first commit

2026-04-19 06:34:10 +00:00
commit 66f2c68b38
2 changed files with 261 additions and 0 deletions
@@ -0,0 +1,260 @@
+# 🤖 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](https://github.com/google-ai-edge/litert-lm) với giao diện REST API và Web UI.
+
+---
+
+## 📋 Yêu cầu
+
+- Python 3.10+
+- [`litert-lm`](https://github.com/google-ai-edge/litert-lm) đã cài và hoạt động
+- Model file: `gemma-4-E2B-it.litertlm` (hoặc model `.litertlm` khác)
+- Thư viện Python:
+
+```bash
+pip install fastapi uvicorn pydantic
+```
+
+---
+
+## 📁 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
+
+```bash
+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.
+
+```bash
+curl -X POST http://localhost:8000/generate \
+  -H "Content-Type: application/json" \
+  -d '{"prompt": "Bạn là ai?"}'
+```
+
+**Response:**
+
+```json
+{
+  "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
+
+```bash
+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ẻ.
+
+```bash
+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.
+
+```bash
+curl -X POST http://localhost:8000/chat/new
+```
+
+**Response:**
+
+```json
+{
+  "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 đó.
+
+```bash
+curl -X POST http://localhost:8000/chat/a3f2c1d4-... \
+  -H "Content-Type: application/json" \
+  -d '{"prompt": "Kể thêm về điều đó đi"}'
+```
+
+**Response:**
+
+```json
+{
+  "session_id": "a3f2c1d4-...",
+  "response": "..."
+}
+```
+
+---
+
+#### `DELETE /chat/{session_id}`
+Xóa session và giải phóng bộ nhớ.
+
+```bash
+curl -X DELETE http://localhost:8000/chat/a3f2c1d4-...
+```
+
+**Response:**
+
+```json
+{
+  "status": "cleared",
+  "session_id": "a3f2c1d4-..."
+}
+```
+
+---
+
+#### `GET /chat/sessions/list`
+Liệt kê tất cả session đang hoạt động.
+
+```bash
+curl http://localhost:8000/chat/sessions/list
+```
+
+**Response:**
+
+```json
+{
+  "sessions": ["a3f2c1d4-...", "b7e9f2a1-..."],
+  "count": 2
+}
+```
+
+---
+
+## 💡 Ví dụ: Multi-turn conversation qua curl
+
+```bash
+# 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ợ):
+
+```python
+engine = litert_lm.Engine(MODEL_PATH, backend=litert_lm.Backend.GPU)
+```
+
+---
+
+## 🧪 Test nhanh
+
+```bash
+# 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