🚀 LLM CPU API - FastAPI với llama-cpp-python

API FastAPI chạy llama-cpp-python (CPU, offline) được đóng gói trong Docker, hỗ trợ các model GGUF và tối ưu cho phân tích đầu tư tiếng Việt.

📁 Cấu trúc thư mục

llm-cpu-api/
├── app/                          # Ứng dụng FastAPI
│   ├── main.py                  # API endpoints chính
│   ├── settings.py              # Cấu hình
│   └── prompts/                 # Prompts và templates
│       ├── system_vi.txt        # System prompt tiếng Việt
│       ├── sample_data.json     # Dữ liệu mẫu để test
│       └── template_vi.txt      # Hướng dẫn sử dụng
├── models/                       # Thư mục chứa model GGUF
│   ├── MyModel-Q4_K_M.gguf     # Model 4-bit (nhanh)
│   └── MyModel-Q8_0.gguf       # Model 8-bit (chất lượng cao)
├── requirements.txt              # Python dependencies
├── Dockerfile                    # Container build
├── docker-compose.yml            # Docker Compose
├── .dockerignore                 # Tối ưu build
├── .env                         # Cấu hình môi trường
├── env.example                  # Cấu hình mẫu
├── Makefile                     # Quản lý lệnh
├── README.md                    # File này
├── benchmark.py                 # Tool benchmark hiệu năng
├── test_api.sh                  # Script test API cơ bản
└── test_investment_analysis.sh  # Script test phân tích đầu tư

✨ Tính năng chính

• ✅ FastAPI với llama-cpp-python
• ✅ CPU-only (không cần GPU)
• ✅ System prompt tiếng Việt cho chuyên gia phân tích đầu tư
• ✅ 2 endpoints: /v1/generate và /v1/chat/completions
• ✅ Docker container tối ưu hiệu năng
• ✅ Health check endpoint /healthz
• ✅ Hỗ trợ model Qwen3 và các model GGUF khác
• ✅ Scripts test tự động
• ✅ Makefile để quản lý dễ dàng

🎯 Mục đích sử dụng

API này được thiết kế đặc biệt cho:

• Phân tích đầu tư với dữ liệu định lượng
• Báo cáo tài chính chuyên nghiệp
• Nghiên cứu thị trường bằng tiếng Việt
• Test và demo các model LLM offline

🛠️ Yêu cầu hệ thống

• Docker và Docker Compose
• File model GGUF (4-bit hoặc 8-bit)
• CPU: 8+ threads (khuyến nghị 16-32)
• RAM: 4-8 GB (tùy model)
• Storage: 1-4 GB cho model

🚀 Cài đặt và chạy

1. Clone và cấu hình

cd llm-cpu-api

# Copy file cấu hình
cp env.example .env

# Chỉnh sửa .env theo nhu cầu
nano .env

2. Cấu hình model

Chỉnh sửa docker-compose.yml:

environment:
  MODEL_PATH: /models/MyModel-Q4_K_M.gguf  # Đường dẫn model
  N_THREADS: 16                             # Số CPU threads
  N_CTX: 4096                               # Context window

3. Build và chạy

# Build Docker image
make build

# Khởi động API
make up

# Kiểm tra trạng thái
make status

🧪 Test API

Test nhanh với Makefile:

make health      # Health check
make test        # Test API cơ bản
make benchmark   # Benchmark hiệu năng

Test thủ công:

# Health check
curl http://localhost:8002/healthz

# Generate text
curl -X POST http://localhost:8002/v1/generate \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Viết về xu hướng thép Việt Nam 2025", "max_tokens": 256}'

# Chat completion
curl -X POST http://localhost:8002/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role":"user","content":"Viết báo cáo 3 phần"}], "max_tokens": 512}'

Test phân tích đầu tư:

./test_investment_analysis.sh

📊 Cấu hình hiệu năng

Biến môi trường chính:

MODEL_PATH=/models/MyModel-Q4_K_M.gguf  # Đường dẫn model
N_THREADS=16                             # Số CPU threads
N_CTX=4096                               # Context window
N_BATCH=256                              # Batch size
TEMPERATURE=0.7                           # Độ sáng tạo
MAX_TOKENS=512                            # Số token tối đa

Tối ưu theo phần cứng:

• CPU 8 cores: N_THREADS=8
• CPU 16 cores: N_THREADS=16
• CPU 32+ cores: N_THREADS=32

🎯 Sử dụng cho phân tích đầu tư

1. System Prompt:

File app/prompts/system_vi.txt định nghĩa vai trò chuyên gia phân tích đầu tư.

2. Dữ liệu mẫu:

File app/prompts/sample_data.json chứa dữ liệu tài chính mẫu.

3. Template:

File app/prompts/template_vi.txt hướng dẫn cách sử dụng.

4. Test chuyên biệt:

./test_investment_analysis.sh

📈 Hiệu năng

Model hiện tại:

• Qwen3 596M (4-bit quantized)
• Tốc độ: ~24 tokens/second trên CPU
• Context: 4096 tokens
• Threads: 8 CPU threads

Benchmark:

python benchmark.py

🛠️ Quản lý với Makefile

make help          # Xem tất cả lệnh
make build         # Build Docker image
make up            # Khởi động API
make down          # Dừng API
make restart       # Restart API
make logs          # Xem logs
make status        # Trạng thái container
make test          # Test API
make benchmark     # Benchmark hiệu năng
make clean         # Dọn dẹp

🔧 Troubleshooting

Model không load được:

• Kiểm tra MODEL_PATH trong .env
• Đảm bảo file GGUF tồn tại trong thư mục models/
• Kiểm tra quyền đọc file

API không trả lời:

• Kiểm tra container status: make status
• Xem logs: make logs
• Kiểm tra port: netstat -tlnp | grep :8002

Hiệu năng chậm:

• Tăng N_THREADS theo số CPU cores
• Giảm N_BATCH xuống 128
• Sử dụng model 4-bit thay vì 8-bit

📚 API Documentation

Sau khi chạy, truy cập:

• Swagger UI: http://localhost:8002/docs
• ReDoc: http://localhost:8002/redoc
• OpenAPI JSON: http://localhost:8002/openapi.json

🎯 Ví dụ sử dụng

Phân tích đầu tư:

import requests

# Dữ liệu công ty
company_data = {
    "name": "ABC Corp",
    "industry": "Technology",
    "pe_ratio": 15.2,
    "roe": 12.5
}

# Gọi API
response = requests.post(
    "http://localhost:8002/v1/chat/completions",
    json={
        "messages": [
            {"role": "system", "content": "Bạn là chuyên gia phân tích đầu tư..."},
            {"role": "user", "content": f"Phân tích công ty: {company_data}"}
        ],
        "max_tokens": 600
    }
)

print(response.json()["text"])

📝 Lưu ý quan trọng

1. Không commit models vào git (file quá lớn)
2. Sử dụng .gitignore để loại trừ *.gguf
3. Backup models quan trọng
4. Test model trước khi deploy production
5. Điều chỉnh cấu hình theo phần cứng thực tế

🤝 Đóng góp

1. Fork repository
2. Tạo feature branch
3. Commit changes
4. Push to branch
5. Tạo Pull Request

📄 License

MIT License - xem file LICENSE để biết thêm chi tiết.

---

Tác giả: LLM CPU API Team
Phiên bản: 1.0.0
Cập nhật: Tháng 8, 2025