跳轉至

Virtual Key

Virtual Key（虛擬密鑰）是 litellm proxy Server 模式中用於團隊權限與預算控管的核心功能。透過 Virtual Key，管理員可以為不同成員或服務發放「子帳號」型式的 API Key，限制其可存取的模型、月預算上限，並透過管理面板追蹤用量與費用。

背景與價值

在直接使用 openai 等模型服務時，團隊通常共用同一個實體 API Key，容易造成費用失控、無法追蹤個別成員用量。Virtual Key 將單一上游模型 Provider 的憑證封裝在 Proxy 後端，對外提供可獨立控管的存取憑證。

每個 Virtual Key 都掛在 litellm Proxy 之下，實際調用模型時由 Proxy 以 master key 或後端 Provider 金鑰向上游請款，因此 Virtual Key 本身不直接暴露上游金鑰，降低洩漏風險。這類似 hashicorp-vault 或 infisical 這類密鑰管理工具強調的「動態憑證」概念，但 Virtual Key 更聚焦在 API 存取層級。

主要功能

  • 模型白名單：每個 Virtual Key 只能呼叫指定的模型，例如只允許 gpt-4o 與 claude-sonnet。
  • 預算上限：可設定單月或單次的使用額度（例如 USD $50），超額即拒絕請求。
  • 使用追蹤：Proxy 自動記錄每個 Virtual Key 的 Token 用量與費用，管理員可於 Dashboard 查看按用戶、團隊、模型統計的報表。
  • 團隊隔離：不同專案或部門使用不同 Virtual Key，互不影響。

建立 Virtual Key

需先以「master key」啟動 litellm Proxy（參考 litellm-router 設定方式），再呼叫 /key/generate 端點：

curl http://localhost:4000/key/generate \
  -H "Authorization: Bearer sk-master-key" \
  -H "Content-Type: application/json" \
  -d '{
    "max_budget": 50.0,
    "budget_duration": "monthly",
    "models": ["gpt-4o", "claude-sonnet"],
    "metadata": {"user": "developer-01"}
  }'

回應中會取得一組 sk- 開頭的虛擬 Key。將此 Key 交給使用者或應用程式，即可讓它們透過 OpenAI 相容 SDK 呼叫 Proxy：

from openai import OpenAI

client = OpenAI(
    api_key="sk-你的虛擬Key",
    base_url="http://localhost:4000/v1"
)

SDK 模式不支援

需特別注意：litellm Python SDK（litellm.completion()）直接在主程式內呼叫上游 API，這種模式下沒有獨立的 Virtual Key 管理功能。Virtual Key 只在 Proxy Server（獨立網關）模式中提供，因此若團隊需要此功能，應採用 Proxy 架構。

使用場景

Virtual Key 常被用於 ai-agent 或多 Agent 系統中。例如規劃 Agent、執行 Agent、校驗 Agent 各自使用不同的 Virtual Key，管理員可一眼看出哪個 Agent 消耗最多成本，並針對特定 Agent 調降預算。重點是：所有 Agent 仍共用同一組上游模型 Provider 的金鑰，但彼此之間透過 Virtual Key 取得治理邊界。

相關連結

Sources

See Also