跳至主要內容

限制模型存取

依 Virtual Key 限制模型​

使用 models 參數為金鑰設定允許的模型

models 清單同時會將模型從 GET /v1/models 中隱藏，並阻擋對該模型的呼叫。若要在不阻擋呼叫的情況下，將模型從列出端點中隱藏，請改為在該模型上設定 model_info.discoverable: false（將模型從 /v1/models 中隱藏）

curl 'http://0.0.0.0:4000/key/generate' \
--header 'Authorization: Bearer <your-master-key>' \
--header 'Content-Type: application/json' \
--data-raw '{"models": ["gpt-5.6-luna", "gpt-5.6-terra"]}'
資訊

此金鑰只能對 models 發出 gpt-5.6-luna 或 gpt-5.6-terra 的請求

請透過以下方式確認設定正確

curl -i http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LITELLM_API_KEY" \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [
      {"role": "user", "content": "Hello"}
    ]
  }'

API 參考​

依 team_id 限制模型​

litellm-dev 只能存取 azure-gpt-3.5

1. 透過 /team/new 建立團隊

curl --location 'http://localhost:4000/team/new' \
--header 'Authorization: Bearer <your-master-key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "team_alias": "litellm-dev",
  "models": ["azure-gpt-3.5"]
}' 

# returns {...,"team_id": "my-unique-id"}

2. 為團隊建立金鑰

curl --location 'http://localhost:4000/key/generate' \
--header "Authorization: Bearer $LITELLM_API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{"team_id": "my-unique-id"}'

3. 測試

curl --location 'http://0.0.0.0:4000/chat/completions' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer sk-qo992IjKOC2CHKZGRoJIGA' \
    --data '{
        "model": "BEDROCK_GROUP",
        "messages": [
            {
                "role": "user",
                "content": "hi"
            }
        ]
    }'
{"error":{"message":"Invalid model for team litellm-dev: BEDROCK_GROUP.  Valid models for team are: ['azure-gpt-3.5']\n\n\nTraceback (most recent call last):\n  File \"/Users/ishaanjaffer/Github/litellm/litellm/proxy/proxy_server.py\", line 2298, in chat_completion\n    _is_valid_team_configs(\n  File \"/Users/ishaanjaffer/Github/litellm/litellm/proxy/utils.py\", line 1296, in _is_valid_team_configs\n    raise Exception(\nException: Invalid model for team litellm-dev: BEDROCK_GROUP.  Valid models for team are: ['azure-gpt-3.5']\n\n","type":"None","param":"None","code":500}}%

API 參考​

檢視可用的備援模型​

使用 /v1/models 端點來探索給定模型可用的備援模型。這有助於您了解當主要模型無法使用或受到限制時，可用哪些備援模型。

擴充點

include_metadata 參數可作為未來公開其他模型中繼資料的擴充點。目前重點在備援模型，但此作法將擴充以納入其他模型中繼資料，例如定價資訊、功能、速率限制等。

基本用法​

取得所有可用模型：

curl -X GET 'http://localhost:4000/v1/models' \
  -H 'Authorization: Bearer <your-api-key>'

取得含中繼資料的備援模型​

加入中繼資料以查看備援模型資訊：

curl -X GET 'http://localhost:4000/v1/models?include_metadata=true' \
  -H 'Authorization: Bearer <your-api-key>'

取得特定類型的備援​

您可以指定想查看的備援類型：

curl -X GET 'http://localhost:4000/v1/models?include_metadata=true&fallback_type=general' \
  -H 'Authorization: Bearer <your-api-key>'

一般備援是可處理相同類型請求的替代模型。

範例回應​

當指定 include_metadata=true 時，每個模型都會帶有一個 metadata.fallbacks 清單，且只對單一備援類型生效，也就是 fallback_type 所指定的類型（若省略則為 general）。若要查看全部三種型別，請針對每個 fallback_type 各送出一個請求：

{
  "data": [
    {
      "id": "gpt-5.6-terra",
      "object": "model",
      "created": 1677610602,
      "owned_by": "openai",
      "metadata": {
        "fallbacks": ["gpt-5.6-luna", "claude-sonnet-5"]
      }
    }
  ]
}

使用案例​

  • 高可用性：找出備援模型以確保服務持續性
  • 成本最佳化：在主要模型價格較高時尋找更便宜的替代方案
  • 內容篩選：探索具有不同內容政策的模型
  • 上下文長度：尋找可處理更大輸入的模型
  • 負載平衡：將請求分散到多個相容模型

API 參數​

參數型別說明
include_metadataboolean包含額外的模型中繼資料，包括備援
fallback_typestring要在 metadata.fallbacks 中回傳哪一種備援：general（預設）、context_window，或 content_policy。任何其他值都會回傳 400

在時間區間內為團隊保留部署​

在部署上設定 model_info.access_windows，即可在每日的本地時間區間內將其保留給特定團隊。當區間啟用時，路由器只會將該部署提供給其金鑰屬於所列團隊之一的請求；來自其他團隊的請求，以及來自沒有團隊的金鑰（包含 master key）的請求，會路由到同一模型群組中的其他部署，或在所有候選項都已保留時以 400 拒絕。區間之外，路由維持不變。部署會一直列在 /v1/models 和 /model/info 中。

model_list:
  - model_name: gpt-4o-ptu
    litellm_params:
      model: azure/gpt-4o-ptu
      api_base: os.environ/AZURE_PTU_BASE
      api_key: os.environ/AZURE_PTU_KEY
    model_info:
      access_windows:
        - start: "22:00"
          end: "06:00"
          timezone: "America/New_York"
          team_ids: ["team-nightly-batch"]

start 和 end 是指定 IANA timezone 中的 HH:MM 牆鐘時間（會自動套用日光節約時間）。start 為包含，end 為不包含；晚於 end 的 start 表示區間會跨越午夜。部署可以列出多個區間；只要其中任何一個啟用，就視為已保留。當某個區間具有無效時間、未知時區、空的 team_ids，或相同的 start 與 end 時，proxy 會拒絕啟動。

被拒絕的請求如下所示：

{"error":{"message":"litellm.BadRequestError: Deployment gpt-4o-ptu is reserved for another team until 06:00 America/New_York","type":"invalid_request_error","param":null,"code":"400"}}

進階：模型存取群組​

對於進階使用案例，請使用 模型存取群組 動態分組多個模型，並在不重新啟動 proxy 的情況下管理存取。

基於角色的存取控制（RBAC）​

LiteLLM Enterprise
為正式環境打造的 SSO/SAML、稽核記錄、支出追蹤、多團隊管理與防護欄。
深入瞭解 →