Deploy LocalAI trên Docker: Xây dựng API Server tương thích OpenAI cho LLM, TTS và tạo ảnh cục bộ

AI tutorial - IT technology blog
AI tutorial - IT technology blog

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.

Share: