응답 헤더

응답 헤더 (Response Headers)

프록시에 요청을 보내면, 프록시는 다음과 같은 헤더를 반환해요.

레이트 리밋 헤더

OpenAI 호환 헤더:

헤더 타입 설명
x-ratelimit-remaining-requests Optional[int] 레이트 리밋이 소진되기 전에 허용된 남은 요청 수
x-ratelimit-remaining-tokens Optional[int] 레이트 리밋이 소진되기 전에 허용된 남은 토큰 수
x-ratelimit-limit-requests Optional[int] 레이트 리밋이 소진되기 전에 허용된 최대 요청 수
x-ratelimit-limit-tokens Optional[int] 레이트 리밋이 소진되기 전에 허용된 최대 토큰 수
x-ratelimit-reset-requests Optional[int] 레이트 리밋이 리셋되는 시점
x-ratelimit-reset-tokens Optional[int] 레이트 리밋이 리셋되는 시점

레이트 리밋 헤더 동작 방식

키에 레이트 리밋이 설정된 경우

프록시는 그 키의 남은 레이트 리밋을 반환해요.

키에 레이트 리밋이 설정되지 않은 경우

프록시는 백엔드 제공자가 반환하는 남은 요청/토큰을 반환해요. (LiteLLM은 백엔드 제공자의 응답 헤더를 OpenAI 형식에 맞게 표준화해요.)

백엔드 제공자가 이 헤더들을 반환하지 않으면 값은 None이 돼요.

이 헤더들은 클라이언트가 현재 레이트 리밋 상태를 이해하고 요청 속도를 그에 맞게 조절하는 데 유용해요.

레이턴시 헤더

헤더 타입 설명
x-litellm-response-duration-ms float 요청이 LiteLLM Proxy에 도달한 순간부터 클라이언트에 반환되는 순간까지의 총 시간
x-litellm-overhead-duration-ms float LiteLLM 처리 오버헤드(밀리초)

재시도, 폴백 헤더

헤더 타입 설명
x-litellm-attempted-retries int 시도된 재시도 횟수
x-litellm-attempted-fallbacks int 시도된 폴백 횟수
x-litellm-max-fallbacks int 허용된 최대 폴백 횟수

비용 추적 헤더

헤더 타입 설명 Pass-Through 엔드포인트에서 사용 가능
x-litellm-response-cost float API 호출 비용
x-litellm-response-cost-input float 캐시되지 않은 입력 비용 구성 요소
x-litellm-response-cost-output float 출력 비용 구성 요소(추론 포함)
x-litellm-response-cost-cache-read float 프롬프트 캐시 읽기 비용 구성 요소
x-litellm-response-cost-cache-creation float 프롬프트 캐시 쓰기 비용 구성 요소
x-litellm-response-cost-reasoning float 추론 비용, 출력 구성 요소의 일부
x-litellm-response-cost-tool-usage float 내장 도구 비용 구성 요소
x-litellm-key-spend float API 키의 총 지출 ✅

구성 요소 헤더들의 합은 총액과 같아요: input + cache read + cache creation + output + tool usage = x-litellm-response-cost. 추론(reasoning)은 이미 출력 안에 있으므로 합계에서 제외해요. 캐시와 추론 헤더는 해당 비용이 0이 아닐 때만 나타나고, 구성 요소 헤더는 비스트리밍 응답에서만 나타나요.

LiteLLM 전용 헤더

헤더 타입 설명 Pass-Through 엔드포인트에서 사용 가능
x-litellm-call-id string 이 요청의 Id. general_settings.include_call_id_in_error_body: true면 JSON 오류 본문 안에도 litellm_call_id로 포함됨 (세부 사항) ✅
x-litellm-model-id string 배포 id (model_info.id)
x-litellm-model-api-base string API base URL ✅
x-litellm-version string LiteLLM 버전
x-litellm-model-group string 라우팅된 model_list[].model_name (클라이언트 model)

예시

    model_list:  
      - model_name: my-chat-model          # clients call this  
        litellm_params:  
          model: gpt-5.6-luna               # LiteLLM calls this upstream  
        model_info:  
          id: "7c9f2a1b3d8e4f0a2c6b5d9e1f3a7b8c"   # optional; auto-generated if omitted
헤더 예시 참고
x-litellm-model-group my-chat-model model_name / 요청 model; litellm_params.model가 아님
x-litellm-model-id 7c9f2a1b3d8e4f0a2c6b5d9e1f3a7b8c 어느 배포 행인지; /v1/model/info?litellm_model_id=...와 함께 사용
응답 본문 model 종종 my-chat-model 클라이언트에 맞게 자주 다시 찍힘; 업스트림 id는 config에 남음

자동 라우팅 요청

자동 라우터에 대한 요청에서는 본문 model이 클라이언트가 호출한 라우터 별칭이고, 위 헤더들은 여전히 응답한 배포를 가리켜요. 스트리밍 소비자를 포함해 응답 헤더를 읽지 못하는 클라이언트는 라우터에 return_raw_model_name을 설정해서 본문 model 필드에서 선택된 티어를 대신 받을 수 있어요. 응답에서 선택된 모델 읽기를 참고하세요.

컴플렉시티 자동 라우터도 기록된 라우팅 결정을 응답 헤더로 반환해요:

헤더 타입 설명
x-litellm-complexity-router-tier string 선택된 컴플렉시티 티어
x-litellm-complexity-router-cause string 티어를 선택한 라우팅 메커니즘(예: heuristic_scorer, heuristic_v2, llm_classifier, 또는 키워드 규칙)
x-litellm-complexity-router-score float 기록된 휴리스틱 점수
x-litellm-complexity-router-reasoning-effort string 선택된 티어에 구성된 reasoning_effort

각 헤더는 성공한 시도의 기록된 라우팅 결정에 해당 값이 있을 때만 나타나요. 키워드 및 LLM-분류기 결정을 포함해 점수를 기록하지 않는 경로에서는 점수가 없어요. reasoning-effort 헤더는 선택된 티어의 구성된 오버라이드를 보고해요. 모델의 기본 effort나 분류기 모델의 reasoning effort를 보고하지는 않아요. 유효하지 않거나 비-ASCII 텍스트 값은 생략돼요. 원시 휴리스틱 신호, 매칭된 키워드, 전체 티어 파라미터 맵은 노출되지 않아요.

이 헤더들은 /v1/chat/completions, /v1/responses, /v1/messages에 대한 스트리밍·비스트리밍 요청에서 사용 가능해요. 일반 모델 그룹으로 폴백된 후에는 없어져요. 스트림이 커밋된 후에는 HTTP 헤더를 바꿀 수 없어요.

추가 예시 (예시용)

헤더 예시 의미
x-litellm-response-cost 0.000214 이 호출 (USD)
x-litellm-key-spend 12.847 이 호출 후 키 총액
x-litellm-response-duration-ms 842.3 프록시 종단 간 (ms)
x-litellm-overhead-duration-ms 15.1 LiteLLM 오버헤드 (ms)
x-litellm-attempted-retries 0 재시도
x-litellm-attempted-fallbacks 1 다른 배포로의 폴백
x-litellm-call-id 019b2c4d-e5f6-7890-abcd-ef1234567890 로그 / 추적
x-litellm-version 1.55.3 버전
x-litellm-model-api-base https://api.openai.com/v1 제공자 base (쿼리 문자열 없음)

LLM 제공자의 응답 헤더

LiteLLM은 또한 LLM 제공자의 원래 응답 헤더를 반환해요. 이 헤더들은 LiteLLM의 헤더와 구분되도록 llm_provider- 접두사가 붙어요.

응답 헤더 예시:

    llm_provider-openai-processing-ms: 256  
    llm_provider-openai-version: 2020-10-01  
    llm_provider-x-ratelimit-limit-requests: 30000  
    llm_provider-x-ratelimit-limit-tokens: 150000000

출처: 문서

더 알아보기 (Learn more)

  • 레이트 리밋 헤더 동작과 병렬 요청 리미터 원리 이해하기
  • 자동 라우터에서 선택된 모델을 응답으로 읽는 방법 확인하기