將用戶端標頭轉送至 LLM API

控制哪些模型群組可以將用戶端標頭轉送至底層 LLM 提供者 API。

概覽

預設情況下，LiteLLM 基於安全考量，不會將用戶端標頭轉送至 LLM 提供者 API。不過，您可以使用 forward_client_headers_to_llm_api 設定，針對特定模型群組選擇性啟用標頭轉送。

運作方式

LiteLLM 不會將所有用戶端標頭轉送到 LLM 提供者。相反地，它採用 allowlist 方法：只有符合特定規則的標頭才會被轉送。因此，敏感標頭（例如您的 LiteLLM API 金鑰）絕不會意外送到上游提供者。

標頭 Allowlist 規則

以下規則決定哪些標頭會被轉送（請參閱 _get_forwardable_headers 於 litellm/proxy/litellm_pre_call_utils.py）：

規則	範例	轉送？
以 `x-` 開頭的標頭	`x-trace-id`, `x-custom-header`, `x-request-source`	是
`anthropic-beta` 標頭	`anthropic-beta: prompt-caching-2024-07-31`	是
以 `x-stainless-*` 開頭的標頭	`x-stainless-lang`, `x-stainless-arch`	否（會造成 OpenAI SDK 問題）
標準 HTTP 標頭	`Authorization`, `Content-Type`, `Host`	否
其他提供者標頭	`Accept`, `User-Agent`	否

其他標頭機制

機制	說明	參考
`x-pass-` 前綴	以 `x-pass-` 為前綴的標頭，無論設定為何，都會一律轉送且會移除前綴。例如：`x-pass-anthropic-beta: value` → `anthropic-beta: value`。適用於所有 pass-through 端點。	原始碼
`openai-organization`	只有在 `forward_openai_org_id: true` 中設定 `general_settings` 時才會轉送。	轉送 OpenAI Org ID
使用者資訊標頭	當 `add_user_information_to_llm_headers: true` 時，LiteLLM 會加入 `x-litellm-user-id`、`x-litellm-org-id` 等。	使用者資訊標頭
Vertex AI pass-through	使用獨立且更嚴格的 allowlist：只有 `anthropic-beta` 與 `content-type`。	原始碼

設定

全域啟用

general_settings:
  forward_client_headers_to_llm_api: true

轉送 LLM 提供者驗證標頭

v1.82+ 新功能：預設情況下，LiteLLM 會基於安全考量，從用戶端請求中移除 x-api-key、x-goog-api-key 和 api-key 等驗證標頭（這些通常用於向 proxy 本身驗證）。不過，您可以啟用這些 LLM 提供者驗證標頭的轉送，以支援 Bring Your Own Key (BYOK) 情境，讓用戶端將自己的 API 金鑰送到 LLM 提供者。

設定

將 forward_llm_provider_auth_headers: true 加入您的 general_settings：

general_settings:
  forward_client_headers_to_llm_api: true
  forward_llm_provider_auth_headers: true  # 👈 Enable BYOK

哪些標頭會被轉送

當 forward_llm_provider_auth_headers: true 時，下列 LLM 提供者驗證標頭會被保留並轉送：

標頭	提供者	範例
`x-api-key`	Anthropic、Azure AI、Databricks	`x-api-key: sk-ant-api03-...`
`x-goog-api-key`	Google AI Studio	`x-goog-api-key: AIza...`
`api-key`	Azure OpenAI	`api-key: your-azure-key`
`ocp-apim-subscription-key`	Azure APIM	`ocp-apim-subscription-key: your-key`

重要安全注意事項

proxy 的 Authorization 標頭（用於 proxy 驗證）絕不會轉送至 LLM 提供者，即使啟用此設定也是如此。這可確保您的 proxy 驗證維持安全。

使用情境：用戶端 API 金鑰（BYOK）

此功能可支援以下情境：

用戶端使用自己的 LLM 提供者 API 金鑰，而非使用在 proxy 中設定的金鑰
多租戶應用程式，每個租戶都有自己的 Anthropic/OpenAI 帳戶
開發環境，開發者透過共用 proxy 使用個人 API 金鑰

範例：Anthropic BYOK

# proxy_config.yaml
model_list:
  - model_name: claude-sonnet-5
    litellm_params:
      model: anthropic/claude-sonnet-5
      # No api_key configured! Will use client's key

general_settings:
  forward_client_headers_to_llm_api: true
  forward_llm_provider_auth_headers: true  # Enable BYOK

關於 Claude Code，請參閱 Claude Code BYOK。使用 ANTHROPIC_CUSTOM_HEADERS="x-litellm-api-key: $LITELLM_API_KEY" 傳遞您的 LiteLLM 金鑰。已設定的 Anthropic API 金鑰會以 x-api-key 傳送，且需要上方的 forward_llm_provider_auth_headers 才會被轉送；/login 則會改為將 OAuth token 以 Authorization: Bearer <token> 傳送，而 LiteLLM 無論此設定為何都會轉送該 token。

用戶端請求：

# Authorization: Proxy authentication (stripped)
# x-api-key: Client's Anthropic key (forwarded!)
curl -X POST "http://localhost:4000/v1/messages" \
  -H "Authorization: Bearer sk-proxy-auth-123" \
  -H "x-api-key: sk-ant-api03-YOUR-KEY..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 100
  }'

範例：Google AI Studio BYOK

model_list:
  - model_name: gemini-3.1-pro-preview
    litellm_params:
      model: gemini/gemini-3.1-pro-preview
      # No api_key configured

general_settings:
  forward_client_headers_to_llm_api: true
  forward_llm_provider_auth_headers: true

用戶端請求：

curl -X POST "http://localhost:4000/v1/chat/completions" \
  -H "Authorization: Bearer sk-proxy-auth-123" \
  -H "x-goog-api-key: AIza..." \
  -d '{
    "model": "gemini-3.1-pro-preview",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

範例：自訂 Anthropic 相容的 `api_base`

當模型位於您自己的閘道之後，且該閘道支援 Anthropic Messages API，而每位使用者都持有自己的 token 時，請使用此方式。萬用字元路由會將呼叫端所指定的任何模型傳遞到閘道，因此新可用的模型不需要變更設定。此處只需要 forward_llm_provider_auth_headers

model_list:
  - model_name: "my-gateway/*"
    litellm_params:
      model: "anthropic/*"
      api_base: "https://gateway.example.com/anthropic"
      # No api_key: each request supplies its own

general_settings:
  forward_llm_provider_auth_headers: true

使用 Authorization: Bearer 或 x-litellm-api-key 驗證 LiteLLM，並將使用者的閘道 token 放入 x-api-key：

curl -X POST "http://localhost:4000/v1/chat/completions" \
  -H "Authorization: Bearer $LITELLM_API_KEY" \
  -H "x-api-key: $USER_GATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "my-gateway/claude-sonnet-4-5",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

LiteLLM 會去除 my-gateway/ 前綴，並以 "model": "claude-sonnet-4-5" 和 x-api-key: $USER_GATEWAY_TOKEN 呼叫 https://gateway.example.com/anthropic/v1/messages。對 /v1/messages 和 /v1/chat/completions 的請求都會以這種方式到達閘道。該 token 一律會以 x-api-key 送出，因此閘道必須接受該標頭。若要在 /v1/models 列出閘道的模型，請參閱模型探索

哪個金鑰會到達提供者

轉送的提供者標頭會優先於該部署的 api_key，適用於該次請求。當請求未帶有提供者金鑰時，LiteLLM 會先回退到部署的 api_key，接著回退到 proxy 主機上的提供者環境變數（例如 ANTHROPIC_API_KEY），並以該金鑰執行呼叫，不會發生任何錯誤。若要要求每位呼叫端都提供自己的金鑰，請將兩者都保留為未設定；未提供金鑰的請求會在任何內容送到提供者之前以 Missing Anthropic API Key 失敗。

請勿在 x-api-key 中傳送 LiteLLM 金鑰。LiteLLM 會將其作為 proxy 驗證接受，然後移除，因此不會被轉送，而請求會如上所述回退。

安全性考量

何時使用此功能：

您信任所有用戶端的內部工具
開發／測試環境
具有適當用戶端驗證的多租戶應用程式
希望用戶端使用自己的 API 金鑰的情境

何時不要使用：

您不信任所有用戶端的公開 API
您希望集中式計費／成本控制
您需要在 proxy 層級強制速率限制時

向後相容性

為了向後相容，若您有 forward_client_headers_to_llm_api: true 但沒有明確設定 forward_llm_provider_auth_headers，其行為如下：

預設：LLM 提供者驗證標頭不會被轉送（安全預設）
明確設定 true：LLM 提供者驗證標頭會被轉送（已啟用 BYOK）

# Safe default - auth headers NOT forwarded
general_settings:
  forward_client_headers_to_llm_api: true

# BYOK enabled - auth headers ARE forwarded
general_settings:
  forward_client_headers_to_llm_api: true
  forward_llm_provider_auth_headers: true  # 👈 Opt-in required

對特定模型群組啟用

在您的設定中，於 forward_client_headers_to_llm_api 下新增 model_group_settings 設定：

model_list:
  - model_name: gpt-5.6-luna
    litellm_params:
      model: openai/gpt-5.6-luna
      api_key: "your-api-key"
  - model_name: "wildcard-models/*"
    litellm_params:
      model: "openai/*"
      api_key: "your-api-key"

litellm_settings:
  model_group_settings:
    forward_client_headers_to_llm_api:
      - gpt-5.6-luna
      - wildcard-models/*

支援的模型模式

此設定支援多種模型比對模式：

1. 精確模型名稱

forward_client_headers_to_llm_api:
  - gpt-5.6-luna
  - claude-sonnet-5

2. 萬用字元模式

forward_client_headers_to_llm_api:
  - "openai/*"          # All OpenAI models
  - "anthropic/*"       # All Anthropic models
  - "wildcard-group/*"  # All models in wildcard-group

3. 團隊模型別名

如果您的團隊已設定模型別名，轉送功能對原始模型名稱與別名都可正常運作。

轉送的標頭

當針對模型群組啟用時，LiteLLM 會轉送以下類型的標頭：

自訂標頭（x- 前綴）

任何以 x- 開頭的標頭（除了 x-stainless-*，它可能造成 OpenAI SDK 問題）
範例：x-custom-header、x-request-id、x-trace-id

提供者特定標頭

Anthropic：anthropic-beta 標頭
OpenAI：openai-organization（透過 forward_openai_org_id: true 啟用時）

使用者資訊標頭（選用）

當 add_user_information_to_llm_headers 啟用時，LiteLLM 會加入：

x-litellm-user-id
x-litellm-org-id
其他使用者中繼資料作為 x-litellm-* 標頭

安全性考量

⚠️ 重要安全注意事項：

敏感資料：僅對可信任的模型群組啟用標頭轉送，因為標頭可能包含敏感資訊
API 金鑰：切勿在轉送的標頭中包含 API 金鑰或密鑰
PII：請謹慎轉送可能包含個人識別資訊的標頭
提供者限制：某些提供者對自訂標頭有限制

範例使用情境

1. 請求追蹤

轉送追蹤標頭以追蹤您系統中的請求：

curl -X POST "https://your-proxy.com/v1/chat/completions" \
  -H "Authorization: Bearer your-key" \
  -H "x-trace-id: abc123" \
  -H "x-request-source: mobile-app" \
  -d '{
    "model": "gpt-5.6-luna",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

2. 自訂中繼資料

將自訂中繼資料傳遞給您的 LLM 提供者：

curl -X POST "https://your-proxy.com/v1/chat/completions" \
  -H "Authorization: Bearer your-key" \
  -H "x-customer-id: customer-123" \
  -H "x-environment: production" \
  -d '{
    "model": "gpt-5.6-luna", 
    "messages": [{"role": "user", "content": "Hello"}]
  }'

3. Anthropic Beta 功能

為 Anthropic 模型啟用 beta 功能：

curl -X POST "https://your-proxy.com/v1/chat/completions" \
  -H "Authorization: Bearer your-key" \
  -H "anthropic-beta: tools-2024-04-04" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

完整組態範例

model_list:
  # Fixed model with header forwarding
  - model_name: byok-fixed-gpt-4o-mini
    litellm_params:
      model: openai/gpt-5.6-luna
      api_base: "https://your-openai-endpoint.com"
      api_key: "your-api-key"
      
  # Wildcard model group with header forwarding
  - model_name: "byok-wildcard/*"
    litellm_params:
      model: "openai/*"
      api_base: "https://your-openai-endpoint.com"
      api_key: "your-api-key"
      
  # Standard model without header forwarding
  - model_name: standard-gpt-4o
    litellm_params:
      model: openai/gpt-5.6-terra
      api_key: "your-api-key"

litellm_settings:
  # Enable user info headers globally (optional)
  add_user_information_to_llm_headers: true
  
  model_group_settings:
    forward_client_headers_to_llm_api:
      - byok-fixed-gpt-4o-mini
      - byok-wildcard/*
      # Note: standard-gpt-4o is NOT included, so no headers forwarded

general_settings:
  # Enable OpenAI organization header forwarding (optional)
  forward_openai_org_id: true

測試標頭轉送

若要測試標頭是否正在轉送：

啟用除錯記錄：在您的設定中將 set_verbose: true 設為
檢查提供者記錄：監控您的 LLM 提供者的請求記錄
使用 Webhook 網站：為了測試，您可以將 webhook.site URL 作為 api_base 使用，以查看轉送的標頭

疑難排解

標頭未被轉送

檢查模型名稱：確認您請求中的模型名稱與組態相符
驗證模式比對：萬用字元模式必須完全相符
檢視記錄：啟用詳細記錄以查看標頭處理

提供者錯誤

無效的標頭：某些提供者會拒絕未知標頭
標頭限制：提供者可能對標頭數量／大小有限制
驗證：確保轉送的標頭不會與驗證衝突

請求標頭 - 支援的請求標頭完整清單
回應標頭 - LiteLLM 傳回的標頭
團隊模型別名 - 為團隊設定模型別名
模型存取控制 - 控制哪些使用者可以存取哪些模型

API 參考

標頭轉送由 ModelGroupSettings 組態控制：

class ModelGroupSettings(BaseModel):
    forward_client_headers_to_llm_api: Optional[List[str]] = None

其中清單中的每個字串都可以是：

精確的模型名稱（例如，"gpt-5.6-luna"）
萬用字元模式（例如，"openai/*"）
模型群組名稱（例如，"my-model-group/*"）

概覽​

運作方式​

標頭 Allowlist 規則​

其他標頭機制​

設定​

全域啟用​

轉送 LLM 提供者驗證標頭​

設定​

哪些標頭會被轉送​

使用情境：用戶端 API 金鑰（BYOK）​

範例：Anthropic BYOK​

範例：Google AI Studio BYOK​

範例：自訂 Anthropic 相容的 api_base​

哪個金鑰會到達提供者​

安全性考量​

向後相容性​

對特定模型群組啟用​

支援的模型模式​

1. 精確模型名稱​

2. 萬用字元模式​

3. 團隊模型別名​

轉送的標頭​

自訂標頭（x- 前綴）​

提供者特定標頭​

使用者資訊標頭（選用）​

安全性考量​

範例使用情境​

1. 請求追蹤​

2. 自訂中繼資料​

3. Anthropic Beta 功能​

完整組態範例​

測試標頭轉送​

疑難排解​

標頭未被轉送​

提供者錯誤​

相關功能​

API 參考​

概覽

運作方式

標頭 Allowlist 規則

其他標頭機制

設定

全域啟用

轉送 LLM 提供者驗證標頭

設定

哪些標頭會被轉送

使用情境：用戶端 API 金鑰（BYOK）

範例：Anthropic BYOK

範例：Google AI Studio BYOK

範例：自訂 Anthropic 相容的 `api_base`

哪個金鑰會到達提供者

安全性考量

向後相容性

對特定模型群組啟用

支援的模型模式

1. 精確模型名稱

2. 萬用字元模式

3. 團隊模型別名

轉送的標頭

自訂標頭（x- 前綴）

提供者特定標頭

使用者資訊標頭（選用）

安全性考量

範例使用情境

1. 請求追蹤

2. 自訂中繼資料

3. Anthropic Beta 功能

完整組態範例

測試標頭轉送

疑難排解

標頭未被轉送

提供者錯誤

相關功能

API 參考