Bối cảnh & Lý do LocalAI thay đổi quy trình làm việc của tôi
Khoảng một năm trước, tôi đang chạy một công cụ nội bộ nhỏ gọi API OpenAI để tóm tắt tài liệu. Chẳng có gì phức tạp — nhưng mỗi request đều gửi dữ liệu nội bộ của công ty lên server bên thứ ba. Đội bảo mật phát hiện ra. Pháp lý vào cuộc. Một tính năng tự động hóa đơn giản bỗng trở thành vấn đề tuân thủ quy định.
Đó là lúc tôi bắt đầu tìm hiểu nghiêm túc về LocalAI. Nó không chỉ là một công cụ chạy LLM tự host thông thường. Điểm khác biệt nằm ở API: nó tương thích hoàn toàn với API của OpenAI — cùng endpoint, cùng định dạng request/response. Bất kỳ ứng dụng nào đang gọi tới api.openai.com đều có thể trỏ sang server cục bộ của bạn mà không cần thay đổi một dòng code nào.
Sức mạnh thực sự nằm ở những gì chạy bên dưới. LocalAI tích hợp sẵn llama.cpp, Whisper, diffusers, Bark và Piper làm backend — bao phủ inference LLM, chuyển giọng nói thành văn bản, tạo ảnh và TTS qua một API duy nhất. Tôi đã chạy setup này trên môi trường production suốt vài tháng. Nó ổn định dưới tải đồng thời trên server tầm trung, không crash hay rò rỉ bộ nhớ trong thời gian chạy dài.
Đánh đổi chính là phần cứng. Không có GPU, inference sẽ chậm. Với các công cụ nội bộ, xử lý batch, hoặc môi trường phát triển, inference bằng CPU thường là đủ dùng. Và nếu bạn có GPU, LocalAI sẽ tận dụng nó.
Cài đặt: Chạy LocalAI trên Docker
Yêu cầu trước khi bắt đầu
Trước khi bắt đầu, hãy đảm bảo bạn có:
- Docker Engine 24.0+ và Docker Compose v2
- Ít nhất 8GB RAM (khuyến nghị 16GB+ cho các model 7B)
- 20–50GB dung lượng đĩa trống cho các file model
- Tùy chọn: GPU NVIDIA với driver CUDA đã cài đặt (để tăng tốc bằng GPU)
Cấu trúc thư mục dự án
Tạo thư mục làm việc với thư mục con models/. Cả trọng số model lẫn file cấu hình YAML đều đặt tại đây:
mkdir localai-server && cd localai-server
mkdir -p models
Cấu hình Docker Compose
Đây là file docker-compose.yml cơ bản tôi dùng trong hầu hết các lần deploy. Các biến môi trường đáng đọc kỹ trước khi điều chỉnh:
services:
localai:
image: localai/localai:latest-aio-cpu
# Dùng GPU: thay bằng localai/localai:latest-aio-gpu-nvidia-cuda-12
container_name: localai
ports:
- "8080:8080"
volumes:
- ./models:/build/models
environment:
- THREADS=4 # Số luồng CPU dùng cho inference
- CONTEXT_SIZE=4096 # Kích thước context window tối đa
- DEBUG=false
restart: unless-stopped
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8080/readyz"]
interval: 30s
timeout: 10s
retries: 5
start_period: 60s
Image aio (all-in-one) đóng gói toàn bộ backend trong một container. Nếu bạn chỉ cần inference LLM, dùng localai/localai:latest-cpu thay thế — dung lượng nhỏ hơn đáng kể.
Khởi động:
docker compose up -d
docker compose logs -f
Lần khởi động đầu tiên sẽ tải một số dependency cơ bản. Chờ một hoặc hai phút. Khi bạn thấy LocalAI API is running trong log là đã xong.
Cấu hình: Thiết lập các model
Cách cấu hình model hoạt động
LocalAI dùng các file cấu hình YAML đặt cùng thư mục với trọng số model trong thư mục models/. Mỗi file .yaml định nghĩa một model mà API sẽ expose — backend nào sẽ dùng, file trọng số nào cần tải, và các tham số áp dụng.
Trọng số model — thường là file .gguf cho LLM — đặt trong cùng thư mục đó. Tên file bạn khai báo trong YAML phải khớp chính xác; nếu không, model đơn giản là sẽ không tải được.
Cấu hình LLM (Llama 3.2)
Bắt đầu bằng cách tải model GGUF. Llama 3.2 3B là lựa chọn thực tế cho inference bằng CPU — lượng tử hóa Q4_K_M chiếm khoảng 2GB trên đĩa và xử lý được hầu hết tác vụ văn bản mà không cần GPU:
# Tải về từ Hugging Face (cần huggingface-cli hoặc wget)
wget -O models/llama-3.2-3b-instruct.gguf \
https://huggingface.co/bartowski/Llama-3.2-3B-Instruct-GGUF/resolve/main/Llama-3.2-3B-Instruct-Q4_K_M.gguf
Sau đó tạo file cấu hình model tại models/llama3.yaml:
name: llama3
backend: llama-cpp
parameters:
model: llama-3.2-3b-instruct.gguf
context_size: 4096
threads: 4
f16: true
template:
chat_message: |
{{if eq .RoleName "system"}}{{.Content}}{{end}}
{{if eq .RoleName "user"}}User: {{.Content}}{{end}}
{{if eq .RoleName "assistant"}}Assistant: {{.Content}}{{end}}
Thêm model Text-to-Speech
Piper là backend TTS của LocalAI. Tạo file models/tts.yaml:
name: tts
backend: piper
parameters:
model: en_US-lessac-medium.onnx
Tải model giọng nói Piper:
wget -O models/en_US-lessac-medium.onnx \
https://huggingface.co/rhasspy/piper-voices/resolve/main/en/en_US/lessac/medium/en_US-lessac-medium.onnx
wget -O models/en_US-lessac-medium.onnx.json \
https://huggingface.co/rhasspy/piper-voices/resolve/main/en/en_US/lessac/medium/en_US-lessac-medium.onnx.json
Thêm tính năng tạo ảnh với Stable Diffusion
Tạo ảnh dùng backend diffusers. Tạo file models/stablediffusion.yaml:
name: stable-diffusion
backend: diffusers
parameters:
model: stabilityai/stable-diffusion-2-1
f16: true
diffusers:
pipeline_type: StableDiffusionPipeline
cuda: false
Mọi thay đổi đối với file YAML của model đều cần khởi động lại container để có hiệu lực:
docker compose restart localai
Kiểm tra & Giám sát
Kiểm tra các API Endpoint
Khi LocalAI đang chạy, việc kiểm tra trông y hệt như gọi API OpenAI — chỉ cần đổi base URL.
Bắt đầu bằng cách liệt kê các model mà LocalAI đã tải:
curl http://localhost:8080/v1/models | python3 -m json.tool
Chat completions:
curl http://localhost:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "llama3",
"messages": [
{"role": "user", "content": "Giải thích Docker volume là gì trong một câu."}
],
"temperature": 0.7
}'
TTS dùng cùng pattern API:
curl http://localhost:8080/v1/audio/speech \
-H "Content-Type: application/json" \
-d '{"model": "tts", "input": "Xin chào từ LocalAI"}' \
--output speech.mp3
Tạo ảnh:
curl http://localhost:8080/v1/images/generations \
-H "Content-Type: application/json" \
-d '{
"model": "stable-diffusion",
"prompt": "a server rack in a data center, photorealistic",
"size": "512x512"
}'
Dùng LocalAI từ Python cũng đơn giản không kém — OpenAI SDK hoạt động ngay, chỉ cần một thay đổi duy nhất:
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:8080/v1",
api_key="not-needed" # LocalAI mặc định không yêu cầu key thật
)
response = client.chat.completions.create(
model="llama3",
messages=[{"role": "user", "content": "Kubernetes là gì, giải thích trong một đoạn văn?"}]
)
print(response.choices[0].message.content)
Health Check và theo dõi Log
Endpoint kiểm tra sẵn sàng cho bạn tín hiệu health đơn giản — hữu ích cho load balancer hoặc container orchestration:
curl -s http://localhost:8080/readyz
# Trả về: {"status":"ok"}
Xem log và mức sử dụng tài nguyên:
# Theo dõi log trực tiếp
docker compose logs -f localai
# Chỉ lọc các lỗi
docker compose logs localai 2>&1 | grep -i error
# Kiểm tra mức sử dụng tài nguyên
docker stats localai
Khi một model không chịu tải, hãy đặt DEBUG=true trong file Compose trước. LocalAI ghi log toàn bộ quá trình khởi tạo backend — bạn thấy chính xác nó đang tải gì và thất bại ở đâu. Các file trọng số bị thiếu và khóa YAML cấu hình sai sẽ hiện ra ngay lập tức, thay vì xuất hiện sau dưới dạng lỗi API khó hiểu.
Cần xác thực? Thêm API_KEY=your-secret vào phần environment của Compose. LocalAI áp dụng bearer token auth trên toàn bộ endpoint, dùng cùng định dạng Authorization: Bearer ... như OpenAI. Không cần thay đổi gì khác.
Nếu bạn đang dùng OpenAI SDK ở bất kỳ đâu trong stack của mình, việc chuyển sang LocalAI chỉ là thay đổi một dòng — cập nhật base URL. Đó chính là lý do nó đáng để deploy ngay cả trong môi trường phát triển, không chỉ production. Setup Docker mất chưa đến 10 phút. API surface quen thuộc ngay lập tức. Và từ đó, các request của bạn không còn rời khỏi hệ thống nội bộ nữa.

