自架 LiteLLM 模型閘道：虛擬金鑰、預算控制，以及與 New API、Magpie 的選型比較

開發 AI 應用或帶團隊使用大型語言模型時，把上游服務商的主 API Key 直接放進各個用戶端或程式碼儲存庫裡，既無法限制單一專案能花多少錢，換金鑰時還要到處改設定。LiteLLM 是目前 Python 與 AI 工程生態裡最常使用的開源模型代理（LLM Proxy）：它把 100 多家模型服務商統一成標準 OpenAI API，內建 /ui 管理後台、虛擬金鑰（Virtual Keys）、預算上限（Budgets）與每次呼叫的費用日誌。

本文用 Zenavo 的 LiteLLM 範本，把 LiteLLM 連同 PostgreSQL 資料庫一起部署到你自己的伺服器上，並比較它與 New API、Magpie 的選型差異。伺服器、Zenavo 平台與上游模型 API 分別計費。

1. 部署 LiteLLM 與 PostgreSQL

先在 Zenavo 中連接一台 Linux 伺服器（建議預留 1 GB 以上記憶體），再開啟 LiteLLM 範本，選擇伺服器並部署。

部署後專案裡有兩項服務，透過專案私有網路自動連通：

服務 / 變數	值或用途
litellm	映像檔 ghcr.io/berriai/litellm:v1.109.1，HTTP 連接埠 4000
postgresql	映像檔 postgres:16，資料庫 litellm，持久化磁碟區 /var/lib/postgresql/data
LITELLM_MASTER_KEY	自動產生的 sk-... 主金鑰，用於登入 /ui 後台與管理 API
LITELLM_SALT_KEY	自動產生的加密鹽值，用於加密存入資料庫的上游服務商 API Key
STORE_MODEL_IN_DB	True，允許直接在網頁後台增刪模型並持久化至 PostgreSQL

切勿修改 LITELLM_SALT_KEY：在你往後台新增任何上游模型憑證之後，絕對不要改動 LITELLM_SALT_KEY。LiteLLM 用它加密和解密資料庫裡的 API Key；一旦改動，已儲存的上游金鑰將全部無法解密。部署完請立刻把 LITELLM_MASTER_KEY 和 LITELLM_SALT_KEY 複製到密碼管理器（如自架的 Vaultwarden）中備份。

2. 綁定網域並登入 /ui 管理後台

1. 在 litellm 服務的 網路（Networking） 頁為 4000 連接埠綁定自訂網域，例如 llm.example.com，並在 DNS 新增指向伺服器的 A 記錄。詳見網域與 HTTPS。
2. 在 litellm 服務的 變數（Variable） 頁查看並複製 LITELLM_MASTER_KEY。
3. 造訪 https://llm.example.com/ui，使用管理員使用者名稱（預設填 admin）和 LITELLM_MASTER_KEY 登入管理面板。

postgresql 只走專案內網供 litellm 存取，不需要開啟公開存取。

3. 新增模型與發放虛擬金鑰

新增上游模型

範本已開啟 STORE_MODEL_IN_DB="True"，無需手動修改 YAML 設定檔：

1. 在 /ui 後台開啟 Models → Add Model。
2. 選擇服務商（如 OpenAI、Anthropic、DeepSeek、Gemini、Azure、Bedrock 等），填寫對外公開的模型別名（如 claude-sonnet 或 gpt-4o）與上游 API Key。
3. 儲存後在 Test Key / Playground 發送一則測試請求，確認回傳正常。

發放有預算上限的虛擬金鑰（Virtual Keys）

日常呼叫不要直接使用 LITELLM_MASTER_KEY。開啟 Virtual Keys → Create New Key：

• 為每個應用、隊友或工具單獨建一把金鑰（如 nextjs-prod、open-webui、claude-code-alex）；
• 限制這把金鑰允許呼叫的模型清單；
• 設定預算上限（Max Budget，例如 $20）與重設週期（按日 / 按月），以及速率限制（TPM / RPM）。

4. 串接用戶端與程式碼

任何支援自訂 OpenAI Base URL 的 SDK 或工具都能直接連上 LiteLLM：

• 應用程式碼（OpenAI SDK / LangChain / Vercel AI SDK）：Base URL 填 https://llm.example.com/v1，API Key 填虛擬金鑰。如果應用也部署在同一個 Zenavo 專案裡（例如 Next.js 全端應用），直接走內網 http://litellm.zenavo.internal:4000/v1，延遲更低且不走公網。
• Claude Code 與 Codex CLI：LiteLLM 同樣支援 /v1/messages 與 /v1/responses 路由，可依 New API 教學中的環境變數設定串接；如果想在 Claude Code 裡透過 MCP 管理 Zenavo 服務，可參考用 Claude Code 部署和除錯 Zenavo 專案。
• 聊天介面與智慧體：在自架的 Open WebUI、LobeHub 或 OpenClaw 中，把 OpenAI 代理位址設為 https://llm.example.com/v1（同專案內網為 http://litellm.zenavo.internal:4000/v1）即可。

5. LiteLLM vs New API vs Magpie：三個閘道怎麼選？

Zenavo 範本庫提供了三款定位不同的開源模型閘道，你可以依使用場景挑選最合適的一款（甚至組合使用）：

閘道範本	核心定位	持久層	最合適的場景
LiteLLM	面向工程與 SDK 的 OpenAI 代理，附虛擬金鑰、預算控制、護欄（Guardrails）與 Langfuse 等可觀測性串接	PostgreSQL 16	自研 AI 應用後端、Python/TypeScript 工程團隊依專案/服務控管預算與呼叫日誌
New API	多租戶模型分發與記帳中心，內建使用者註冊/登入、令牌管理、渠道權重與額度面板	預設 SQLite（/data）	給團隊多位成員依人發放帳號或令牌，統一串接 Open WebUI、LobeHub、Claude Code 與 Codex
Magpie	輕量單容器多協定閘道，支援在 Anthropic Messages、OpenAI Responses/Chat 與 Gemini 之間互轉，支援 API Key 與訂閱帳號故障切換	/config 磁碟區	個人開發者或小團隊用 Claude Code、Codex CLI 寫程式，想跨協定呼叫 DeepSeek/Gemini 並提供 /me 自助看板

6. 備份與升級

LiteLLM 的所有模型設定、虛擬金鑰和消費紀錄都保存在 postgresql 服務中：

1. 開啟 postgresql 服務的 備份與還原（Backup & Restore） 頁，建立資料庫備份並下載留存，還可以開啟排程自動備份。詳見備份與還原文件。
2. 務必同時保管好 litellm 服務變數裡的 LITELLM_SALT_KEY——只有備份的資料庫加上原來的 LITELLM_SALT_KEY，還原後才能解開裡面儲存的上游 API Key。
3. 升級時先備份 PostgreSQL，再於 litellm 服務的 設定 → 來源 中把映像檔標籤（預設 v1.109.1）更新到新的穩定版本。

常見問題

為什麼剛部署完造訪 /ui 回報 502？ LiteLLM 啟動時需要連線 PostgreSQL 並執行 Prisma 資料庫遷移，範本設定了 40 秒的啟動健康檢查寬限期（start_period: 40）。等服務狀態變為 Running 後再開啟網頁即可；若啟動異常，可呼出控制台右側的 Zenavo Agent 一鍵診斷日誌。

在 /ui 裡新增模型時提示無法寫入資料庫？ 確認 litellm 服務的環境變數中保留了 STORE_MODEL_IN_DB="True"，且 postgresql 服務處於 Running 狀態。

虛擬金鑰回報 BudgetExceededError？ 代表該虛擬金鑰的累計費用已達到你設定的 Max Budget。可以在 /ui 的 Virtual Keys 頁面調高預算、重設消費額度，或為它設定按月自動重設。

LiteLLM 可以和 New API 一起用嗎？ 可以。不少團隊用 New API 管理上游渠道池，再把 LiteLLM 放在應用後端前面做依微服務的預算切分與可觀測性追蹤；兩者放在同一個 Zenavo 專案裡走 .zenavo.internal 內網呼叫即可。

開啟 LiteLLM 範本，幾分鐘就能在自己的伺服器上架好附 PostgreSQL 的模型代理，把散落在各處的 API Key 收攏到受預算保護的虛擬金鑰後面。