commit 66f2c68b38ca543cf9ca0af9a0fc7916710070ad Author: Tony Tran Date: Sun Apr 19 06:34:10 2026 +0000 first commit diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..1d7940a --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +gemma-4-E2B-it.* diff --git a/README.md b/README.md new file mode 100644 index 0000000..7af7791 --- /dev/null +++ b/README.md @@ -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