Dựng router lai AI Local và cloud bằng LiteLLM

Model local cho việc thường ngày, đám mây cho lúc cần

Một nhóm Marketing đã chạy Ollama cho việc tóm tắt, viết nháp. Nhưng mỗi ứng dụng lại cấu hình riêng: n8n trỏ thẳng Ollama, công cụ viết bài dùng khoá API đám mây, khi máy local tắt thì mọi thứ dừng, còn hoá đơn API không ai nắm. (Tình huống minh hoạ.)

Router lai giải quyết việc đó: mọi ứng dụng gọi một địa chỉ, router quyết định gửi tới model trên máy hay model đám mây. Phần lý thuyết đã có ở AI Local làm bộ não cho AI Agent; bài này đi từng bước với LiteLLM.

Router lai AI Local và cloud là gì?

Router lai AI Local và cloud là một proxy đứng giữa ứng dụng và các model: ứng dụng gọi một địa chỉ tương thích OpenAI, proxy gửi yêu cầu tới model chạy trên máy và tự chuyển sang model đám mây khi model local lỗi, đồng thời kiểm soát khoá và chi tiêu.

LiteLLM là một proxy như vậy: gọi hơn 100 API model theo chuẩn OpenAI, có theo dõi chi phí, cân bằng tải, ghi log; giấy phép MIT, trừ thư mục enterprise/. Bản ổn định mới nhất trên GitHub là v1.106.0 (18/10/2026).

Nguồn: LiteLLM GitHub · LiteLLM – bản mới nhất

Chuẩn bị

• Ollama đang chạy trên máy, đã tải model chat (cách cài: Windows, Mac, Linux).
• Docker (cách được dùng trong bài). Hoặc chạy bằng dòng lệnh: tài liệu khuyên uv tool install 'litellm[proxy]'; từ bản 1.84.0 cần Python 3.10 trở lên, pip trên Python cũ sẽ âm thầm cài bản 1.83.9.
• Khoá API đám mây của nhà cung cấp bạn chọn, kèm hạn mức chi tiêu đặt ngay trong trang quản trị của họ.
• Quyết định trước loại dữ liệu nào không được rời máy: dữ liệu đó dùng tên model không có dự phòng.

Nguồn: LiteLLM – Quick start

Bước 1: Viết config.yaml

Tệp config.yaml có các khối chính: model_list (danh sách model), litellm_settings, router_settings, general_settings. Mỗi model có model_name là tên ứng dụng gọi, litellm_params.model là model thật. Khoá đọc từ biến môi trường bằng os.environ/…. Tài liệu không có một tệp mẫu gộp đủ Ollama, đám mây và master key, nên mẫu dưới đây ghép từ cú pháp chính thức của trang Ollama, Anthropic, Fallbacks và Budgets; hãy thử trên máy thử trước:

model_list:
  - model_name: local                       # tên ứng dụng sẽ gọi
    litellm_params:
      model: ollama_chat/<tên model Ollama>
      api_base: http://host.docker.internal:11434   # chạy LiteLLM thẳng trên máy: http://localhost:11434
      keep_alive: "8m"                      # giữ model trong bộ nhớ 8 phút
    model_info:
      supports_function_calling: true       # chỉ để true khi model có gọi công cụ (tools)
  - model_name: noi-bo                      # chỉ chạy local, KHÔNG có dự phòng: dùng cho dữ liệu nhạy cảm
    litellm_params:
      model: ollama_chat/<tên model Ollama>
      api_base: http://host.docker.internal:11434
  - model_name: cloud
    litellm_params:
      model: anthropic/<tên model Claude>
      api_key: os.environ/ANTHROPIC_API_KEY   # khoá đọc từ biến môi trường

litellm_settings:
  num_retries: 2              # thử lại trên cùng model trước khi chuyển
  request_timeout: 120        # giây; ví dụ trong docs là 10, model local chậm nên để dài hơn
  fallbacks: [{"local": ["cloud"]}]   # local lỗi thì chuyển sang cloud
  allowed_fails: 3
  cooldown_time: 30           # tạm ngưng model lỗi trong 30 giây

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY

Nguồn: LiteLLM – config.yaml · LiteLLM – Ollama · LiteLLM – Anthropic · LiteLLM – Fallbacks · LiteLLM – Virtual keys

Bước 2: Chạy LiteLLM bằng Docker

Đặt khoá vào tệp .env cạnh config.yaml, không ghi thẳng vào lệnh hay vào config:

# Tạo tệp .env cạnh config.yaml; không gửi tệp này cho ai, không đưa lên Git
LITELLM_MASTER_KEY=sk-<chuỗi ngẫu nhiên dài>
ANTHROPIC_API_KEY=<khoá API đám mây>

Lệnh dưới đây ghép từ lệnh Docker không database của tài liệu LiteLLM cùng cú pháp Docker chung (--env-file, gắn cổng vào 127.0.0.1, --add-host như trang n8n dùng cho Linux). Hãy thử trên máy thử trước:

openssl rand -hex 32          # tạo chuỗi ngẫu nhiên cho master key (thêm sk- ở đầu)

docker run -d --name litellm \
  -v $(pwd)/config.yaml:/app/config.yaml \
  --env-file .env \
  --add-host host.docker.internal:host-gateway \
  -p 127.0.0.1:4000:4000 \
  ghcr.io/berriai/litellm:<tag phiên bản trên trang Releases> \
  --config /app/config.yaml

• Ghim phiên bản: tài liệu khuyên dùng tag cụ thể thay cho latest; tag main-stable đã bỏ từ bản 1.84.0. Image chính thức ở ghcr.io/berriai, bản sao ở docker.litellm.ai/berriai.
• Linux: LiteLLM trong container gọi Ollama trên máy qua host.docker.internal thì Ollama phải nghe ngoài 127.0.0.1 (đặt OLLAMA_HOST, kèm tường lửa), cách làm ở bài n8n và Ollama.
• Không dùng Docker: litellm --config config.yaml, thêm --detailed_debug để xem log; proxy chạy ở cổng 4000, api_base đổi thành http://localhost:11434.

Nguồn: LiteLLM – Docker quick start · LiteLLM – Deploy · LiteLLM – Release cycle · n8n – host.docker.internal trên Linux

Bước 3: Gọi thử và kiểm tra đã chạy đúng

curl http://localhost:4000/health/liveliness          # không cần khoá, trả "I'm alive!"

curl -X POST 'http://localhost:4000/chat/completions' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $LITELLM_API_KEY" \
  -d '{"model": "local", "messages": [{"role": "user", "content": "Chào bạn, bạn là model nào?"}]}'

• /health/liveliness trả "I'm alive!"; /health/readiness (không cần khoá) báo cả tình trạng database.
• Gọi model local nhận câu trả lời; trên máy Ollama, ollama ps thấy model đang chạy.
• Thử dự phòng: tạm dừng Ollama rồi gọi lại local, câu trả lời phải đến từ model đám mây; gọi noi-bo phải báo lỗi. Bật lại Ollama sau khi thử.
• Gọi không kèm khoá hoặc khoá sai phải bị từ chối.
• Ứng dụng khác dùng SDK OpenAI: base_url="http://localhost:4000", api_key là virtual key.

Nguồn: LiteLLM – Health · LiteLLM – gọi thử · LiteLLM – SDK OpenAI

Bước 4: Ngân sách và khoá riêng cho từng ứng dụng (cần database)

Điểm dễ nhầm nhất: không có database thì max_budget không có tác dụng, proxy vẫn phục vụ khi đã vượt. Virtual key (khoá con cấp cho từng ứng dụng) cũng cần Postgres và master key. Tài liệu có sẵn bộ Docker Compose gồm LiteLLM và Postgres:

curl -sSLO https://github.com/BerriAI/litellm/raw/main/docker/docker-compose.quickstart.yml
printf 'LITELLM_MASTER_KEY=sk-%s\nLITELLM_SALT_KEY=sk-%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
echo 'LITELLM_BIND=127.0.0.1:' >> .env      # chỉ nghe trên chính máy (biến có trong tệp compose)
docker compose -f docker-compose.quickstart.yml up -d

1. Giữ nguyên tệp .env: LITELLM_SALT_KEY không được đổi sau khi đã thêm model, đổi đi thì thông tin đăng nhập đã lưu không đọc được nữa.
2. Bộ compose này không gắn config.yaml; model lưu trong database. Mở http://localhost:4000/ui, đăng nhập user admin, mật khẩu là master key nếu chưa đặt UI_PASSWORD, rồi thêm model local và model đám mây. Trên Linux, nếu container không gọi được host.docker.internal, cần thêm ánh xạ host-gateway tương tự --add-host (cú pháp Docker chung, thử trên máy thử trước).
3. Tạo virtual key có ngân sách cho từng ứng dụng bằng lệnh dưới. Vượt ngân sách, yêu cầu bị từ chối với lỗi ExceededTokenBudget; không đặt budget_duration thì ngân sách không bao giờ đặt lại.

curl 'http://localhost:4000/key/generate' \
--header 'Authorization: Bearer <master key>' \
--header 'Content-Type: application/json' \
--data-raw '{"max_budget": 10, "budget_duration": "30d"}'   # 10 USD mỗi 30 ngày (ví dụ minh hoạ)

Ngân sách chung cho cả proxy đặt trong litellm_settings bằng max_budget và budget_duration (ví dụ 30d) của config.yaml; cách này cũng chỉ có tác dụng khi proxy có database, và bộ compose ở trên không gắn sẵn config.yaml. Ngân sách riêng theo từng model là tính năng Enterprise.

Nguồn: LiteLLM – Docker có Postgres · Tệp compose quickstart · LiteLLM – Budgets · LiteLLM – Admin UI · LiteLLM – Salt key

Chia việc giữa local và đám mây

Ứng dụng chỉ cần đổi tên model để đổi cách xử lý, không phải sửa khoá hay địa chỉ. Chọn việc nào đi đâu: 40 việc AI Local làm được.

Lỗi thường gặp

Nguồn: LiteLLM – Quick start · LiteLLM – Release cycle · LiteLLM – Health

Cập nhật và gỡ cài đặt

• Cập nhật: đọc ghi chú phát hành trên GitHub, đổi tag phiên bản trong lệnh hoặc tệp compose, kéo image mới, chạy lại. Sao lưu tệp .env và database trước khi nâng bản.
• Gỡ bản Docker không database (theo Docker): docker rm -f litellm.
• Gỡ bộ compose (theo Docker): docker compose -f docker-compose.quickstart.yml down. Xoá thêm volume database là mất vĩnh viễn virtual key và nhật ký chi tiêu.
• Thu hồi khoá: vô hiệu khoá API đám mây cũ trong trang quản trị nhà cung cấp nếu không dùng nữa.

Nguồn: LiteLLM releases · LiteLLM – Deploy

An toàn

• Không để cổng 4000 ra Internet khi chưa có master key; nên gắn cổng vào 127.0.0.1 và gọi từ xa qua mạng riêng như Tailscale.
• Master key, salt key, khoá đám mây chỉ nằm trong .env hoặc trình quản lý bí mật; tài liệu production khuyên giữ master key trong secret manager. Không gửi qua chat, không dán vào prompt, không đưa lên Git.
• Mỗi ứng dụng một virtual key có ngân sách, để khoá lộ thì thu hồi riêng mà không ảnh hưởng ứng dụng khác.
• Nhớ rằng dự phòng là gửi dữ liệu ra ngoài: tên model có fallbacks sang đám mây không dành cho dữ liệu nhạy cảm.
• Ollama vẫn giữ ở chế độ chỉ nghe nội bộ; LiteLLM là cửa duy nhất có khoá.

Danh sách kiểm tra đầy đủ: Chi phí thật và bảo mật khi dùng AI Local.

Nguồn: LiteLLM – Production

Bắt đầu từ đâu?

1. Hôm nay: chạy LiteLLM không database với hai model local và cloud, gọi thử, thử tắt Ollama.
2. Tuần này: chuyển một ứng dụng (vd workflow n8n) sang gọi qua LiteLLM, thêm tên noi-bo cho việc nhạy cảm.
3. Khi nhiều ứng dụng, nhiều người: chạy bản có Postgres, cấp virtual key có ngân sách cho từng ứng dụng.

Bài tiếp theo: truy cập AI Local từ xa an toàn qua Tailscale. Muốn được tư vấn hoặc cài đặt AI Local theo nhu cầu riêng, bạn có thể đăng ký Tư vấn 1-1 hoặc Coaching 1-1 cho doanh nghiệp; chi phí báo sau buổi tư vấn.

Đọc tiếp: Truy cập từ xa qua Tailscale →

Câu hỏi thường gặp

Tài liệu liên quan

• AI Local · AI AgentAI Local là gì? Chạy AI ngay trên máy tính, không tốn phí APIAI Local là gì: chạy model AI mở ngay trên máy tính của bạn, không trả phí API theo lượt, dữ liệu ở lại máy. Lợi ích, giới hạn, so sánh với AI đám mây.
• AI Local · AI AgentCài Ollama trên Windows có card NVIDIA từng bướcCài Ollama trên Windows có card NVIDIA: kiểm tra driver, cài đặt, dời thư mục model sang ổ khác, đặt biến môi trường, xác nhận chạy GPU, sửa lỗi, cập nhật, gỡ.
• AI Local · AI AgentCấu hình máy tính chạy AI Local: RAM, VRAM, Mac hay PC NVIDIACấu hình máy tính chạy AI Local: RAM, VRAM quyết định model nào chạy được, cách ước tính dung lượng theo Q4/Q8, Mac hay PC NVIDIA, ổ cứng, mua máy hay thuê GPU.
• AI Local · AI AgentCài AI Local trên Mac: Ollama và LM StudioCài AI Local trên Mac từng bước: xác định chip Apple hay Intel, cài Ollama và LM Studio, dời thư mục model, tắt tự chạy, kiểm tra, sửa lỗi, cập nhật, gỡ.

Xem tất cả tài liệu hướng dẫn →

Bước tiếp theo

Đăng ký Tư vấn 1-1 về AI Local

Chuyên gia Aduca cùng bạn xem nhu cầu, máy đang có và dữ liệu cần bảo vệ, rồi đề xuất nên chạy AI Local, dùng đám mây hay kết hợp. Dịch vụ cài AI Local nằm trong gói Tư vấn 1-1 hoặc Coaching 1-1; chi phí báo sau buổi tư vấn.

Đăng ký Tư vấn 1-1 về AI LocalXem thư viện tài liệu

Nguồn tham khảo

• LiteLLM – GitHub (README, giấy phép)
• LiteLLM Docs – Proxy quick start
• LiteLLM Docs – Docker quick start
• LiteLLM Docs – config.yaml
• LiteLLM Docs – Ollama
• LiteLLM Docs – Anthropic
• LiteLLM Docs – Fallbacks, retries
• LiteLLM Docs – Budgets
• LiteLLM Docs – Virtual keys
• LiteLLM Docs – Health checks

Lịch sử cập nhật

• 21/10/2026 — Bản đầu.

Miễn trừ trách nhiệm