요청 헤더

요청 헤더 (Request Headers)

LiteLLM이 지원하는 특수 헤더들이에요.

출처: 문서

본문

헤더 전달 (Header Forwarding)

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

LiteLLM 헤더

  • x-litellm-timeout — 선택[float]: 요청의 타임아웃(초 단위).
  • x-litellm-stream-timeout — 선택[float]: 응답의 첫 청크를 받기까지의 타임아웃(초, 스트리밍 요청에만 적용). 데모 영상
  • x-litellm-enable-message-redaction — 선택[bool]: 메시지 내용을 로깅 통합에 기록하지 않아요. 지출만 추적해요. 더 알아보기
  • x-litellm-tags — 선택[str]: 쉼표로 구분된 태그 목록(예: tag1,tag2,tag3)으로, 태그 기반 라우팅 또는 지출 추적에 사용해요.
  • x-litellm-num-retries — 선택[int]: 요청의 재시도 횟수. 요청 본문의 num_retries, 배포의 litellm_params, litellm_settings보다 우선해요. 더 알아보기
  • x-litellm-keepalive-seconds — 선택[float]: 스트림 침묵이 이 시간(초)만큼 지속되면 SSE : ping 코멘트 프레임을 보내, 유휴해 보이는 연결을 로드밸런서 타임아웃에서 살려둬요. 배포의 allow_client_keepalive_override 설정에 따르며, 배포가 옵트인하지 않으면 효과가 없어요. 더 알아보기
  • x-litellm-spend-logs-metadata — 선택[str]: 지출 로그에 포함할 커스텀 메타데이터가 담긴 JSON 문자열. 예: {"user_id": "12345", "project_id": "proj_abc", "request_type": "chat_completion"}. 더 알아보기
  • x-litellm-customer-id — 선택[str]: 고객/최종 사용자 ID를 전달하는 표준 헤더. 별도 설정 없이 항상 검사돼요. 더 알아보기
  • x-litellm-end-user-id — 선택[str]: 고객/최종 사용자 ID를 전달하는 표준 헤더. 별도 설정 없이 항상 검사돼요. 더 알아보기
  • x-litellm-trace-id — 선택[str]: 하나의 대화 또는 에이전틱 흐름에 속한 모든 LLM 호출을 연관 짓는 안정적인 ID. 값은 LiteLLM_SpendLogs 테이블의 session_id 컬럼과 요청 메타데이터(trace_id 및 session_id)에 저장되며, 중첩된 MCP 도구 호출과 A2A 에이전트 호출로 전파되어 내부 LLM 호출이 같은 세션 id를 공유해요. 세 헤더 중 최우선 순위예요.
  • x-litellm-session-id — 선택[str]: x-litellm-trace-id와 동일한 동작. x-litellm-trace-id가 없을 때 사용돼요. 두 헤더는 상호 교환 가능하며 같은 체인 id를 설정해요.
  • x-<vendor>-session-id — 선택[str]: 폴백 패턴이에요. x-<vendor>-session-id와 일치하는 헤더(예: x-claude-code-session-id)는 명시적 LiteLLM 헤더가 없으면 세션 id로 자동 감지돼요. 값은 세션 id처럼 보여야 해요: 영숫자, 하이픈 또는 밑줄, 최소 8자.

LiteLLM은 세션 id를 고정된 우선순위로 해석해요: x-litellm-trace-id 먼저, 그다음 x-litellm-session-id, 그다음 어떤 x-<vendor>-session-id 헤더. 첫 번째 일치가 이기고, 해석된 값은 요청과 그 요청이 유발하는 중첩 MCP/A2A 호출에 걸쳐 공유되는 체인 id가 돼요.

세션 연관 예시

같은 x-litellm-trace-id 값으로 두 개의 채팅 완료 요청을 보내 하나의 세션으로 묶을 수 있어요:

curl http://0.0.0.0:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -H "x-litellm-trace-id: my-conversation-123" \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [{"role": "user", "content": "Hello, who won the world cup in 2022?"}]
  }'

curl http://0.0.0.0:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -H "x-litellm-trace-id: my-conversation-123" \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [{"role": "user", "content": "And who was the top scorer?"}]
  }'

그 값을 공유하는 모든 요청은 세션 id로 지출 로그를 조회하거나 Admin UI 로그 페이지의 세션 그룹화를 통해 찾을 수 있어요.

Anthropic 헤더

  • anthropic-version — 선택[str]: 사용할 Anthropic API 버전.

  • anthropic-beta — 선택[str]: 사용할 Anthropic API 베타 버전.

  • /v1/messages 엔드포인트의 경우, 이 헤더는 항상 기본 모델로 전달돼요.

  • /chat/completions 엔드포인트의 경우, 모델이 forward_client_headers_to_llm_api에 설정된 경우에만 전달돼요. 더 알아보기

OpenAI 헤더

  • openai-organization — 선택[str]: OpenAI API에 사용할 조직. (현재 general_settings::forward_openai_org_id: true로 활성화해야 해요)

커스텀 헤더 (Custom Headers)

x-로 시작하는 커스텀 헤더는 모델이 forward_client_headers_to_llm_api에 설정된 경우 LLM 공급자 API로 전달될 수 있어요. 헤더 전달 구성에 대해 더 알아보기.

더 알아보기 (Learn more)