클라이언트 헤더를 LLM API로 전달

클라이언트 헤더를 LLM API로 전달 (Forward Client Headers to LLM API)

어떤 모델 그룹이 클라이언트 헤더를 기저 LLM 공급자 API에 전달할 수 있는지 제어해요.

출처: 문서

본문

개요 (Overview)

기본적으로 LiteLLM은 보안상의 이유로 클라이언트 헤더를 LLM 공급자 API에 전달하지 않아요. 하지만 forward_client_headers_to_llm_api 설정으로 특정 모델 그룹에 대한 헤더 전달을 선택적으로 활성화할 수 있어요.

동작 방식 (How it Works)

LiteLLM은 모든 클라이언트 헤더를 LLM 공급자에 전달하지 않아요. 대신 허용 목록 방식을 사용해 특정 규칙과 일치하는 헤더만 전달돼요. 민감한 헤더(예: LiteLLM API 키)는 따라서 절대 실수로 업스트림 공급자에 보내지지 않아요.

헤더 허용 목록 규칙 (Header Allowlist Rules)

다음 규칙이 어떤 헤더가 전달되는지 결정해요 (litellm/proxy/litellm_pre_call_utils.py의 _get_forwardable_headers 참고):

규칙	예시	전달?
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	아니오

추가 헤더 메커니즘 (Additional Header Mechanisms)

메커니즘	설명	참고
x-pass- 접두사	x-pass-가 붙은 헤더는 설정과 무관하게 항상 접두사가 제거된 채 전달됨. 예: x-pass-anthropic-beta: value → anthropic-beta: value. 모든 패스스루 엔드포인트에서 동작.	소스 코드
openai-organization	general_settings에서 forward_openai_org_id: true로 설정될 때만 전달.	Forward OpenAI Org ID
사용자 정보 헤더	add_user_information_to_llm_headers: true일 때 LiteLLM이 x-litellm-user-id, x-litellm-org-id 등을 추가.	User Information Headers
Vertex AI 패스스루	별도의 더 엄격한 허용 목록을 사용: anthropic-beta와 content-type만.	소스 코드

구성 (Configuration)

전역으로 활성화 (Enable Globally)

general_settings:
  forward_client_headers_to_llm_api: true

LLM 공급자 인증 헤더 전달 (Forward LLM Provider Authentication Headers)

v1.82+의 새로운 기능: 기본적으로 LiteLLM은 x-api-key, x-goog-api-key, api-key 같은 인증 헤더를 클라이언트 요청에서 보안을 위해 제거해요 (이들은 보통 프록시 자체 인증에 사용됨). 하지만 클라이언트가 LLM 공급자에 자체 API 키를 보내는 BYOK(Bring Your Own Key) 시나리오를 허용하도록 이 LLM 공급자 인증 헤더 전달을 활성화할 수 있어요.

구성:

general_settings에 forward_llm_provider_auth_headers: true를 추가하세요:

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

어떤 헤더가 전달되는가 (Which Headers Are Forwarded)

forward_llm_provider_auth_headers: true일 때 다음 LLM 공급자 인증 헤더가 보존·전달돼요:

헤더	공급자	예시
x-api-key	Anthropic, Azure AI, Databricks	x-api-key: «redac...»...
x-goog-api-key	Google AI Studio	x-goog-api-key: ***
api-key	Azure OpenAI	api-key: ***
ocp-apim-subscription-key	Azure APIM	ocp-apim-subscription-key: your-key

중요한 보안 참고 (Important Security Note)

프록시의 Authorization 헤더(프록시 인증에 사용)는 이 설정이 활성화되어도 LLM 공급자에 절대 전달되지 않아요. 이는 프록시 인증이 안전하게 유지됨을 보장해요.

사용 사례: 클라이언트 측 API 키 (BYOK)

이 기능은 다음 시나리오를 가능하게 해요:

• 클라이언트가 프록시에 구성된 키 대신 자체 LLM 공급자 API 키를 가져옴
• 각 테넌트가 자체 Anthropic/OpenAI 계정을 가진 멀티 테넌트 애플리케이션
• 개발자가 공유 프록시를 통해 개인 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를 보세요. LiteLLM 키를 전달하려면 ANTHROPIC_CUSTOM_HEADERS="x-litellm-api-key: ***를 사용하세요. 구성된 Anthropic API 키는 x-api-key로 전송되고 위의 forward_llm_provider_auth_headers가 전달하는 데 필요하며, /login은 그 대신 이 설정과 무관하게 LiteLLM이 전달하는 Authorization: Bearer ***로 OAuth 토큰을 보내요.

클라이언트 요청:

# Authorization: Proxy *** (stripped)
# x-api-key: *** Anthropic key (forwarded!)
curl -X POST "http://localhost:4000/v1/messages" \
  -H "Authorization: Bearer ***" \
  -H "x-api-key: «redac......" \
  -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 ***" \
  -H "x-goog-api-key: ***" \
  -d '{
    "model": "gemini-3.1-pro-preview",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

보안 고려사항 (Security Considerations)

이 기능을 사용할 때:

• 모든 클라이언트를 신뢰하는 내부 도구
• 개발/테스트 환경
• 적절한 클라이언트 인증이 있는 멀티 테넌트 앱
• 클라이언트가 자체 API 키를 사용하게 하려는 시나리오

사용하지 말아야 할 때:

• 모든 클라이언트를 신뢰하지 않는 공개 API
• 중앙 집중식 청구/비용 제어를 원할 때
• 프록시 수준에서 요율 제한을 강제해야 할 때

하위 호환성 (Backward Compatibility)

하위 호환성을 위해 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

모델 그룹에 대해 활성화 (Enable for a Model Group)

구성의 model_group_settings 아래에 forward_client_headers_to_llm_api 설정을 추가하세요:

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/*

지원되는 모델 패턴 (Supported Model Patterns)

구성은 다양한 모델 매칭 패턴을 지원해요:

1. 정확한 모델 이름: gpt-5.6-luna, claude-sonnet-5
2. 와일드카드 패턴: "openai/*" (모든 OpenAI 모델), "anthropic/*" (모든 Anthropic 모델), "wildcard-group/*"
3. 팀 모델 별칭: 팀에 모델 별칭이 구성되어 있으면 원래 모델 이름과 별칭 모두에서 전달이 동작해요.

전달되는 헤더 (Forwarded Headers)

모델 그룹에 대해 활성화되면 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-* 헤더로 추가

보안 고려사항 (Security Considerations)

⚠️ 중요한 보안 참고:

• 민감한 데이터: 헤더가 민감한 정보를 포함할 수 있으므로 신뢰하는 모델 그룹에 대해서만 헤더 전달을 활성화하세요.
• API 키: 전달되는 헤더에 API 키나 시크릿을 절대 포함하지 마세요.
• PII: 개인 식별 정보를 포함할 수 있는 헤더 전달에 주의하세요.
• 공급자 한도: 일부 공급자는 커스텀 헤더에 제한이 있어요.

예시 사용 사례 (Example Use Cases)

1. 요청 추적 (Request Tracing): 시스템 전반에서 추적 헤더를 전달해 요청을 추적:

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

3. Anthropic 베타 기능: Anthropic 모델의 베타 기능 활성화:

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

완전한 구성 예시 (Complete Configuration Example)

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

헤더 전달 테스트 (Testing Header Forwarding)

헤더가 전달되는지 테스트하려면:

1. 콘피그에서 set_verbose: true로 디버그 로깅 활성화
2. 공급자 로그 확인: LLM 공급자의 요청 로그 모니터링
3. 웹훅 사이트 사용: 테스트용으로 webhook.site URL을 api_base로 사용해 전달된 헤더 확인

문제 해결 (Troubleshooting)

헤더가 전달되지 않음 (Headers Not Being Forwarded):

• 모델 이름 확인: 요청의 모델 이름이 구성과 일치하는지 확인
• 패턴 매칭 검증: 와일드카드 패턴이 정확히 일치해야 함
• 로그 검토: 헤더 처리를 보려면 상세 로깅 활성화

공급자 오류 (Provider Errors):

• 잘못된 헤더: 일부 공급자가 알 수 없는 헤더를 거부
• 헤더 한도: 공급자가 헤더 수/크기에 제한이 있을 수 있음
• 인증: 전달된 헤더가 인증과 충돌하지 않는지 확인

관련 기능 (Related Features)

• Request Headers - 지원되는 요청 헤더의 전체 목록
• Response Headers - LiteLLM이 반환하는 헤더
• Team Model Aliases - 팀용 모델 별칭 구성
• Model Access Control - 어떤 사용자가 어떤 모델에 액세스할 수 있는지 제어

API 참조 (API Reference)

헤더 전달은 ModelGroupSettings 구성이 제어해요:

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

목록의 각 문자열은:

• 정확한 모델 이름 (예: "gpt-5.6-luna")
• 와일드카드 패턴 (예: "openai/*")
• 모델 그룹 이름 (예: "my-model-group/*")