litert-lm-orangepi/README.md

🤖 LiteRT-LM Web Server

Chạy mô hình Gemma 4 trên thiết bị nhúng (Orange Pi 5, Raspberry Pi, v.v.) thông qua LiteRT-LM với giao diện REST API và Web UI.

---

📋 Yêu cầu

• Python 3.10+
• litert-lm đã cài và hoạt động

pip install litert-lm

• Thư viện Python:

pip install -r requirements.txt

• Models

• https://huggingface.co/litert-community/gemma-4-E2B-it-litert-lm

• https://huggingface.co/litert-community/gemma-4-E4B-it-litert-lm

---

📁 Cấu trúc

.
├── app.py         # REST API đơn giản, single-turn
├── server.py      # REST API đầy đủ + Web UI, multi-turn sessions
└── README.md

---

🚀 Hướng dẫn sử dụng

Bước 1 — Đặt model vào cùng thư mục

gemma-4-E2B-it.litertlm   ← model file
app.py
server.py

Nếu model ở chỗ khác, sửa biến MODEL_PATH ở đầu mỗi file.

---

📄 app.py — REST API đơn giản

File cơ bản, phù hợp để tích hợp nhanh hoặc test.

Chạy

python app.py

Server khởi động tại http://0.0.0.0:8000

Endpoint

POST /generate

Gửi một prompt, nhận phản hồi. Mỗi request là độc lập, không có bộ nhớ giữa các lần gọi.

curl -X POST http://localhost:8000/generate \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Bạn là ai?"}'

Response:

{
  "response": "Tôi là Gemma 4, một Mô hình Ngôn ngữ Lớn..."
}

---

🖥️ server.py — REST API đầy đủ + Web UI

Phiên bản đầy đủ với hỗ trợ multi-turn conversation, quản lý session và giao diện chat trên trình duyệt.

Chạy

python server.py

Server khởi động tại http://0.0.0.0:8000

---

🌐 Web UI

Mở trình duyệt và truy cập:

http://<địa-chỉ-ip>:8000

Tính năng:

• Giao diện chat trực quan, hỗ trợ tiếng Việt
• Tự động tạo session khi mở trang
• Nhớ ngữ cảnh hội thoại trong cùng một session
• Nút New để bắt đầu cuộc trò chuyện mới
• Nút Clear để xóa lịch sử và tạo session mới
• Enter để gửi, Shift + Enter để xuống dòng

---

🔌 REST API

POST /generate

Single-turn, không nhớ context. Dùng khi chỉ cần hỏi đáp đơn lẻ.

curl -X POST http://localhost:8000/generate \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Thủ đô của Việt Nam là gì?"}'

---

POST /chat/new

Tạo một session mới. Trả về session_id dùng cho các request tiếp theo.

curl -X POST http://localhost:8000/chat/new

Response:

{
  "session_id": "a3f2c1d4-..."
}

---

POST /chat/{session_id}

Gửi tin nhắn trong một session. Model nhớ toàn bộ lịch sử hội thoại trong session đó.

curl -X POST http://localhost:8000/chat/a3f2c1d4-... \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Kể thêm về điều đó đi"}'

Response:

{
  "session_id": "a3f2c1d4-...",
  "response": "..."
}

---

DELETE /chat/{session_id}

Xóa session và giải phóng bộ nhớ.

curl -X DELETE http://localhost:8000/chat/a3f2c1d4-...

Response:

{
  "status": "cleared",
  "session_id": "a3f2c1d4-..."
}

---

GET /chat/sessions/list

Liệt kê tất cả session đang hoạt động.

curl http://localhost:8000/chat/sessions/list

Response:

{
  "sessions": ["a3f2c1d4-...", "b7e9f2a1-..."],
  "count": 2
}

---

💡 Ví dụ: Multi-turn conversation qua curl

# 1. Tạo session
SESSION=$(curl -s -X POST http://localhost:8000/chat/new | python3 -c "import sys,json; print(json.load(sys.stdin)['session_id'])")

# 2. Gửi tin nhắn đầu tiên
curl -s -X POST http://localhost:8000/chat/$SESSION \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Tên tôi là Nam"}' | python3 -m json.tool

# 3. Model nhớ context
curl -s -X POST http://localhost:8000/chat/$SESSION \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Tên tôi là gì?"}' | python3 -m json.tool

# 4. Xóa session khi xong
curl -X DELETE http://localhost:8000/chat/$SESSION

---

⚙️ Cấu hình

Các tham số có thể chỉnh trong đầu mỗi file:

Biến	Mô tả	Mặc định
MODEL_PATH	Đường dẫn đến file model	gemma-4-E2B-it.litertlm
backend	Backend inference	litert_lm.Backend.CPU
host	Địa chỉ lắng nghe	0.0.0.0
port	Cổng	8000

Để đổi backend sang GPU (nếu thiết bị hỗ trợ):

engine = litert_lm.Engine(MODEL_PATH, backend=litert_lm.Backend.GPU)

---

🧪 Test nhanh

# Kiểm tra server đang chạy
curl http://localhost:8000/generate \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Hello!"}'

---

📝 Ghi chú

• Mỗi session giữ toàn bộ lịch sử hội thoại trong RAM. Nên xóa session khi không dùng nữa.
• Warning mel_filterbank khi khởi động là bình thường — liên quan đến audio encoder của Gemma 4 multimodal, không ảnh hưởng đến text generation.
• Tốc độ generate phụ thuộc vào phần cứng. Trên Orange Pi 5 với CPU, khoảng 5–15 token/giây.

---

📜 License

MIT