Pass-Through 비용 및 사용량 추적

Pass-Through 비용 및 사용량 추적 (Pass-Through Cost & Usage Tracking)

일부 패스 스루 대상은 단일 HTTP 요청을 내부적으로 여러 모델로 확장(fan out)해요. LiteLLM은 응답 본문만으로는 그 요청에 가격을 매길 수 없어서, 이 계약이 생기기 전에는 지출 로그에 비용 0, 토큰 0으로 기록됐어요.

대상이 대신 두 응답 헤더로 전체 요청의 총액을 보고할 수 있어요. LiteLLM은 보고된 값을 재계산하지 않고 그대로 기록해요.

출처: 문서

본문

일부 패스 스루 대상은 단일 HTTP 요청을 내부적으로 여러 모델로 확장해요. LiteLLM은 응답 본문만으로는 그 요청에 가격을 매길 수 없어서, 이 계약이 생기기 전에는 지출 로그에 비용 0, 토큰 0으로 기록됐어요.

대상이 대신 전체 요청의 총액을 두 응답 헤더로 보고할 수 있어요. LiteLLM은 보고된 값을 재계산하지 않고 그대로 기록해요.

헤더

헤더	형식	의미
`x-litellm-response-cost`	소수 문자열, USD	모든 내부 모델 호출에 걸친 이 요청의 총 비용, 예: `0.000415`
`x-litellm-total-tokens`	정수 문자열	모든 내부 모델 호출에 걸친 총 토큰, 예: `1874`

HTTP 요청당 하나의 총액을 보내요. 모델별 분해는 없고, 보고된 값이 권위 있는 값이에요.

빠른 시작 (Quick start)

평소처럼 패스 스루 엔드포인트를 정의해요. 구성에서 이 계약을 선택할 필요는 없어요. 대상이 헤더를 보내면 LiteLLM이 그걸 읽어요.

    general_settings:
      pass_through_endpoints:
        - path: "/internal-api"
          target: "https://internal-api.example.com/v1/answer"
          include_subpath: true
          headers:
            Authorization: "Bearer os.environ/INTERNAL_API_TOKEN"

LiteLLM 키로 프록시를 통해 호출해요:

    curl -i -X POST 'http://localhost:4000/internal-api/summarize' \
      -H "Authorization: Bearer ***" \
      -H 'Content-Type: application/json' \
      -d '{"document_id": "doc-9931"}'

대상이 계산한 총액으로 응답하게 해요:

    HTTP/1.1 200 OK
    content-type: application/json
    x-litellm-response-cost: 0.000415
    x-litellm-total-tokens: 1874

LiteLLM이 0.000415와 1874를 호출 키, 팀, 사용자에 장부로 기록하고, 그 값은 지출 로그와 사용량 대시보드에 그 키의 나머지 트래픽과 함께 표시돼요.

LiteLLM이 기록하는 것

보고된 값은 보낸 그대로 기록돼요. LiteLLM은 파싱하고, 온전성(sanity)을 검사하며, 그 위에 자체 비용을 재계산하지 않아요.

대상이 실제로 보고한 값만 기록돼요. 비용은 보내고 토큰 수는 보내지 않은 대상은 LiteLLM이 자체적으로 파생한 토큰 수를 유지하며 0으로 만들지 않아요. 두 헤더도 보내지 않은 대상은 완전히 내버려 두는데, 이는 Anthropic이나 Vertex AI 같은 provider 패스 스루 라우트의 일반적인 경우로서 LiteLLM이 응답 본문에서 비용을 파생해요.

검증 (Validation)

이 검사 중 하나라도 실패하는 값은 보고되지 않은 것으로 간주하고, 헤더와 문제 값의 이름을 실은 경고가 프록시 로그에 기록돼요.

헤더	수락	거부
`x-litellm-response-cost`	유한하고 음수가 아닌 모든 소수, `0` 포함	파싱 불가 텍스트, 음수, `inf`, `nan`
`x-litellm-total-tokens`	음수가 아닌 모든 정수, `0` 포함	파싱 불가 텍스트, 음수

명시적 0은 실제 값이지 빠진 값이 아니므로, 총액이 0이어도 두 헤더를 모두 보내야 해요.

오류 응답

헤더는 상태 코드와 무관하게 모든 업스트림 응답에서 읽혀요. 실패하기 전에 토큰을 소모한 요청은 4xx나 5xx 상태 때문에 버려지는 대신 실패 줄에 지출을 기록해요. 비용이 여전히 발생했다면 오류 응답에도 헤더를 보내세요.

실패 줄에서 빠지거나 사용할 수 없는 값은 0으로 기록돼요.

`cost_per_request`보다 우선

자체 요청에 가격을 매기는 대상은 항상 엔드포인트에 구성된 고정 cost_per_request 추정보다 우선해요. cost_per_request는 모든 config 정의 엔드포인트에서 기본값 0.0이므로, 이를 존중하면 대상이 방금 보고한 실제 비용이 0으로 잡혀요.

보고된 값을 파싱하지 못한 경우에도 그렇습니다. 대상이 반박한 추정을 청구하는 대신 요청이 0을 기록해요.

레이트 리밋과 예산

보고된 토큰은 호출자의 나머지 트래픽과 같은 TPM 창을 차지하므로, 키나 팀은 패스 스루 트래픽만으로는 공유 토큰 한도를 초과할 수 없어요. 이 계약 이전에는 레이트 리미터가 자신이 모델링하는 응답 형태에서만 사용량을 읽었기 때문에 패스 스루 사용량이 토큰 창에 아예 도달하지 않았어요.

기록된 비용은 다른 요청의 비용과 같은 방식으로 예산에 반영돼요.

스트리밍

응답 헤더가 본문보다 먼저 도착하므로 스트리밍 대상도 동작해요. 스트리밍을 끝낸 후에야 최종 비용을 아는 대상은 이 계약으로 보고할 수 없어요. 그때쯤이면 헤더가 이미 전선(wire)에 있기 때문이에요.

값 다시 읽기

업스트림 응답 헤더는 호출 클라이언트로 중계되므로, 호출자는 일반 API에서 받는 것과 같은 x-litellm-response-cost 형태를 봐요. LiteLLM은 나가는 길에 x-litellm-call-id를 추가하는데, 이 값이 개별 요청을 조정(reconcile)할 때 지출 로그와 맞춰 볼 값이에요.

더 알아보기 (Learn more)

패스 스루 엔드포인트 만들기

Pass-Through 비용 및 사용량 추적