Tự host New API: một endpoint cho OpenAI, Claude, Gemini

Một team dùng AI coding agent thường không thiếu model tốt, mà thiếu một chỗ duy nhất để quản lý việc dùng model đó. Tự host New API gom việc đó về một cổng AI đa model, với điều kiện bạn chấp nhận luôn phần vận hành đi kèm.

Vấn đề: mỗi client một key, mỗi nhà cung cấp một endpoint

Cảnh quen thuộc: một bạn dùng Claude Code với key Anthropic, một bạn dùng Codex với key OpenAI, một bạn khác thử Gemini. Key nằm trong file cấu hình ở máy từng người, có khi trong script dùng tạm rồi quên xóa. Cuối tháng, không ai trả lời chính xác team đã dùng bao nhiêu, và key nào đang nằm ở đâu.

Thu hồi quyền còn khó hơn. Xóa tài khoản nội bộ không đồng nghĩa thu hồi được key upstream từng cấp cho máy của người đó, trừ khi bạn xoay key ở phía nhà cung cấp, mà xoay key chung lại ảnh hưởng tới mọi người khác. Phát key upstream cho từng người cũng không giải quyết được việc này, vì cách đó không có quota theo nhóm, không có log tập trung, và một key bị lộ đồng nghĩa tài khoản và thanh toán ở nhà cung cấp đó bị lộ theo. Điều team cần là một lớp phân phối ở giữa: client chỉ thấy một endpoint và một key do team cấp, còn key upstream thật chỉ nằm ở phía server.

New API là gì

New API là cổng AI tự host, mã nguồn mở AGPL-3.0, tại kho QuantumNous/new-api: một hub hợp nhất để gom, phân phối và quản lý model AI qua một endpoint. Tính tới ngày 28/10/2026, kho này có hơn 50.000 star và 12.304 fork, bản mới nhất là v1.0.0-rc.47 phát hành ngày 25/10/2026. Chữ “rc” rất quan trọng: đây là bản release candidate, chưa phải bản ổn định.

Người dùng cuối chỉ cần một base URL và một key do New API cấp; operator giữ key upstream ở phía server và quyết định key đó được dùng model nào, thuộc nhóm nào, với quota bao nhiêu. Muốn đổi nhà cung cấp phía sau, đổi cấu hình ở New API, không sửa cấu hình ở từng máy client.

Theo mình, New API hợp với sysadmin, DevOps hay SRE vận hành cho team, developer dùng nhiều AI coding agent, và người tự host ở homelab. Ngược lại, nếu bạn chỉ dùng một model, một client, gateway chỉ thêm một tầng vận hành.

New API làm phần routing, mapping model, quota và subscription, log sử dụng, phân quyền theo user, group và key, cùng console quản trị có tiếng Việt. Nó hỗ trợ OpenAI, Anthropic, Gemini, Azure OpenAI, AWS Bedrock, Vertex AI, DeepSeek, Qwen và các dịch vụ tương thích khác. Nhưng nó không thay hợp đồng và thanh toán với nhà cung cấp, và quota trong nó chỉ là kế toán nội bộ, không tự động khóa ví upstream, nên cấu hình sai vẫn có thể làm hóa đơn upstream tăng trước khi bạn kịp phát hiện qua log.

Kiến trúc: một request đi qua New API như thế nào

Bốn khái niệm cần nắm là channel, model mapping, key và quota. Channel đại diện cho một upstream kèm key, danh sách model và nhóm được phép dùng. Model mapping là lớp đổi tên: tên model client gọi không nhất thiết trùng tên model ở upstream, nhờ đó bạn giữ tên model ổn định cho client trong khi đổi nhà cung cấp phía sau. Key do New API cấp gắn với group và model, kèm quota hoặc subscription. Console quản trị là nơi tạo user, group, channel, key, cấu hình giá và xem log.

Luồng một request: client gọi endpoint tương thích OpenAI với key New API; New API xác thực key, kiểm tra group, model và quota; model mapping chọn channel theo độ ưu tiên và trọng số, kèm affinity và retry khi gặp lỗi; request được chuyển đổi giao thức nếu cần rồi gửi tới upstream; response trả về client, đồng thời usage được ghi log để đối soát.

Thành phần chuyển đổi có tên RelayKit, chuyển đổi giữa bốn giao thức text gồm OpenAI Chat Completions, OpenAI Responses, Anthropic Messages và Gemini. Tài liệu của dự án ghi rõ tính năng phụ thuộc vào channel, upstream và đường chuyển đổi, có thể không map chính xác trong mọi trường hợp, nên bạn cần test từng cặp model và client mà team thật sự dùng.

DB chính mặc định là SQLite, hoặc MySQL từ 5.7.8 trở lên, hoặc PostgreSQL từ 9.6 trở lên. Redis tùy chọn ở node đơn, cần thiết khi nhiều node chia sẻ rate limit. Log tách riêng qua LOG_SQL_DSN, có hỗ trợ ClickHouse. Các biến quan trọng là SQL_DSN, LOG_SQL_DSN, REDIS_CONN_STRING, SESSION_SECRET, CRYPTO_SECRET, SESSION_COOKIE_SECURE, SESSION_COOKIE_TRUSTED_URL và TRUSTED_PROXIES. Hệ thống chạy trên Linux amd64 và arm64.

So sánh với lựa chọn cùng phạm vi

So sánh chỉ có ích khi đặt các lựa chọn đúng cùng phạm vi: gateway cho team. New API là lựa chọn tự host có console quản trị đầy đủ, với routing, quota và log tích hợp. Một proxy code-first cùng tầng gateway, ví dụ LiteLLM Proxy, cũng tự host nhưng thiên về cấu hình bằng file và code, phù hợp hơn với team đã quen vận hành bằng Git và config. Gateway hosted, ví dụ OpenRouter hay AI gateway của nhà cung cấp cloud, thì không cần bạn vận hành, nhưng bạn mất quyền kiểm soát dữ liệu, key và log, đồng thời phụ thuộc bảng giá của bên thứ ba.

Một nhầm lẫn cần tránh: công cụ chuyển CLI ở máy cá nhân, ví dụ cc-switch, không phải gateway cho team, vì nó chỉ đổi cấu hình client cục bộ. Theo mình, quy tắc chọn gọn lại như sau: chọn New API khi cần cổng AI đa model tự quản cho nhiều người; chọn hosted khi team nhỏ và không muốn vận hành thêm một service có trạng thái; chọn proxy code-first khi team đã quen vận hành bằng config.

Triển khai: từ chạy nhanh tới production

Lưu ý: các lệnh dưới đây đối chiếu tài liệu chính thức ngày 28/10/2026; phần này mình chưa chạy thử trên VPS thật.

Bạn cần VPS Linux đã có Docker và Docker Compose, cùng domain, reverse proxy và HTTPS nếu mở console ra ngoài. Đừng public console trần. Bạn cũng cần key upstream hợp lệ, tự xin từ từng nhà cung cấp. Hãy quyết định trước: chạy thử bằng SQLite hay production bằng PostgreSQL và Redis, và pin tag image theo trang Releases. Tên image theo tài liệu là calciumion/new-api, dù kho mã nguồn mang tên QuantumNous/new-api.

Cách 1: chạy nhanh bằng Docker với SQLite

Cách này phù hợp để thử nghiệm trên máy cá nhân, không phải cấu hình production cho team.

mkdir -p data
docker run --name new-api -d --restart unless-stopped \
  -p 127.0.0.1:3000:3000 \
  -e TZ=Asia/Shanghai \
  -v "$(pwd)/data:/data" \
  calciumion/new-api:latest

Cổng chỉ bind localhost 127.0.0.1:3000, an toàn cho bản chạy thử. Mở http://localhost:3000, hoàn tất setup wizard để tạo tài khoản admin. Thư mục data giữ SQLite khi thay container. Giới hạn: SQLite không phải kiến trúc production cho team, và không có Redis chung thì nhiều node không chia sẻ được rate limit.

Cách 2: triển khai production bằng Docker Compose

File Compose trong kho mặc định chạy New API cùng PostgreSQL và Redis.

git clone https://github.com/QuantumNous/new-api.git
cd new-api
docker compose up -d
docker compose logs -f new-api

Trước khi chạy up, hãy thay mọi mật khẩu ví dụ ở cả service và connection string, vì chỉ đổi một phía sẽ làm Compose không khởi động được. Tạo SESSION_SECRET ngẫu nhiên và bền vững, ví dụ bằng openssl rand -hex 32, rồi giữ nó ổn định, vì đổi secret sẽ làm session cũ mất hiệu lực. Nếu đã có Dockge để quản lý stack Compose hay Coolify để triển khai ứng dụng, bạn có thể đặt New API làm một stack hoặc một ứng dụng trong đó: Dockge và Coolify thuộc tầng triển khai, New API thuộc tầng cổng AI. Với console sau reverse proxy và HTTPS, đặt SESSION_COOKIE_SECURE=true, SESSION_COOKIE_TRUSTED_URL đúng origin HTTPS công khai, và TRUSTED_PROXIES nếu cần.

Cấu hình tối thiểu và kiểm chứng

Trình tự tối thiểu gồm bốn bước: tạo channel với upstream key, danh sách model, gán group, rồi chạy channel test; cấu hình giá cho model và bảo đảm user có quota hoặc subscription hợp lệ; tạo API key trong console, gắn đúng group và model; trỏ client tương thích OpenAI về base URL http://localhost:3000/v1 khi chạy local, đổi host khi chạy production, và dùng key do New API cấp.

Kiểm tra danh sách model mà key được phép dùng:

curl --fail-with-body http://localhost:3000/v1/models \
  -H "Authorization: Bearer ${NEW_API_KEY}"

Kết quả mong đợi là danh sách model mà key đó được phép dùng, không phải lỗi 401 hay lỗi quota. Nếu nhận lỗi 401, hãy kiểm tra group và model gắn với key trước khi kết luận upstream hỏng. Kiểm tra một request responses, thay your-enabled-model bằng tên model đã bật:

curl --fail-with-body http://localhost:3000/v1/responses \
  -H "Authorization: Bearer ${NEW_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"model":"your-enabled-model","input":"Hello!"}'

Kết quả mong đợi là response có nội dung từ model và log xuất hiện trong console đúng user và key đó. Sau đó, kiểm tra ở client thật với một prompt ngắn và đối chiếu log, quota tăng đúng chỗ; nếu không, đừng vội phát key cho cả team.

Quản trị hàng ngày và bảo mật

Khi gateway đã chạy, công việc hàng ngày là chia quota, đối soát chi phí và giữ quyền ở mức tối thiểu. Gán user vào group, key theo group và model, đặt quota và subscription, dùng pricing theo biểu thức cho từng tier. Khi một người rời team, chỉ cần vô hiệu hóa user và key ngay trong console, không cần thu hồi key upstream.

Về chi phí, dùng usage log trong New API để phân bổ nội bộ theo user, key và model, nhưng vì quota nội bộ không khóa ví upstream, bạn vẫn cần đối soát định kỳ với hóa đơn upstream.

Về bảo mật, đừng public console mà không có HTTPS và xác thực. Bật 2FA, passkey và OAuth hoặc OIDC nếu có sẵn, tách tài khoản admin khỏi tài khoản dùng hàng ngày. Upstream key chỉ nhập ở server, không commit vào repo hay dán vào chat, log, và xoay ngay khi nghi ngờ bị lộ.

Đánh giá, sao lưu và rollback

Ưu điểm rõ nhất là một endpoint cho nhiều nhà cung cấp, và việc đổi upstream không cần sửa client nhờ model mapping. Quản lý API key cho team trở nên tập trung: phân quyền, quota, log và thu hồi nhanh. Vì tự host nên dữ liệu request, log và key nằm trong hạ tầng của mình, và console có tiếng Việt.

Nhược điểm cũng cần nói thẳng. Bạn đang thêm một service có trạng thái phải vận hành: backup, nâng cấp bản RC, giám sát, xoay secret. Đây không phải loại công cụ “cài xong quên”. Tính năng không đồng đều giữa các upstream do chuyển đổi giao thức, nên bạn phải test từng model và client trước khi hứa với team. Mức hoàn thiện của bản dịch tiếng Việt là điểm mình chưa kiểm chứng.

Bài này không đưa benchmark, vì tài liệu đã kiểm tra không có số liệu chính thức; hãy đo thực tế trên workload của team, vì rate limit và latency của nhà cung cấp vẫn là trần cuối cùng.

Trước khi nâng cấp, hãy backup volume data nếu dùng SQLite, hoặc dump PostgreSQL kèm backup cấu hình Compose và file env, và ghi lại tag image đang chạy tốt. Nâng cấp bằng cách pin tag mới, đọc upgrade notes, thử ở môi trường thử trước nếu có, rồi mới nâng production. Nếu bản mới gặp lỗi, hãy dừng bản mới, chạy lại tag cũ với cơ sở dữ liệu đã backup, giữ nguyên key upstream và SESSION_SECRET, rồi kiểm tra lại bằng lệnh /v1/models trước khi mở lại cho team. Khôi phục cơ sở dữ liệu cũ sau khi bản mới đã ghi dữ liệu mới có thể làm mất log và quota phát sinh, nên hãy nâng cấp lúc ít traffic và thông báo trước cho team.

Lỗi thường gặp và trường hợp sử dụng

Lỗi 401 thường không phải do upstream hỏng. Hãy kiểm tra key có đúng không, key có gắn nhầm group không, và model đó có bật cho group đó không. Hết quota thì kiểm tra quota và pricing của user. Mất session sau khi đổi SESSION_SECRET là hành vi có thể dự đoán: secret mới làm session cũ mất hiệu lực, bạn chỉ cần đăng nhập lại, rồi giữ secret ổn định trong secret manager. Console chạy nhưng client không nối được thường do container chỉ bind localhost: kiểm tra bind, port và reverse proxy.

Với team phần mềm, New API cho cả team dùng Claude Code, Codex và các client tương thích OpenAI qua một cổng, chia quota theo dự án và thu hồi quyền khi nhân sự thay đổi. Với homelab, nó gom các model đang dùng về một endpoint. Với DevOps và SRE, giá trị nằm ở log, quota và cảnh báo chi phí tập trung, cùng retry để giảm ảnh hưởng khi upstream chập chờn, nhưng hãy test retry cẩn thận vì retry không đúng chỗ có thể gây request trùng.

Kết luận

New API hợp với team từ vài người trở lên, dùng nhiều model và client, cần chia quota, phân quyền và log tập trung, và chấp nhận vận hành thêm một service có trạng thái. Nó không hợp với cá nhân chỉ dùng một model, và không hợp với team không muốn tự vận hành service có trạng thái.

Theo mình, điểm mấu chốt là New API tách tên model và key mà client nhìn thấy khỏi upstream thật. Sự tách rời đó cho bạn quyền kiểm soát, nhưng cũng đặt toàn bộ niềm tin vào một điểm tập trung duy nhất.

Bước tiếp theo trong 30 phút: một, chạy bản Docker SQLite ở localhost, tạo admin, thêm một channel và test bằng curl. Hai, nếu dùng cho team, chuyển sang Compose với PostgreSQL và Redis, pin tag, đặt SESSION_SECRET, bật HTTPS và backup cơ sở dữ liệu. Ba, chỉ sau đó mới phát key cho team theo từng group, và đối soát log với hóa đơn upstream sau tuần đầu tiên.

Tham khảo

• Kho chính thức QuantumNous/new-api: https://github.com/QuantumNous/new-api
• Tài liệu chính thức: https://docs.newapi.ai/en/docs
• Bài liên quan trên phamnam.me về tầng triển khai: Tự host Dockge: quản lý Docker Compose stack và Tự host Coolify: PaaS mã nguồn mở