토큰 카운팅

토큰 카운팅 (Token Counting)

개요

LiteLLM은 프로바이더별 토큰 카운팅 API를 호출해 정확한 토큰 카운팅을 제공합니다. 이는 요청을 보내기 전에 정확한 토큰 수를 얻어 비용 추정과 컨텍스트 창 관리에 도움을 줍니다.

지원 프로바이더

SDK 사용법

기본 사용법

import asyncio
import litellm

async def main():
    # OpenAI
    result = await litellm.acount_tokens(
        model="openai/gpt-5.6-terra",
        messages=[{"role": "user", "content": "Hello, how are you?"}],
    )
    print(f"Token count: {result.total_tokens}")
    print(f"Tokenizer: {result.tokenizer_type}")  # "openai_api"

    # Anthropic
    result = await litellm.acount_tokens(
        model="anthropic/claude-sonnet-5",
        messages=[{"role": "user", "content": "Hello, how are you?"}],
    )
    print(f"Token count: {result.total_tokens}")
    print(f"Tokenizer: {result.tokenizer_type}")  # "anthropic_api"

asyncio.run(main())

도구 및 시스템 메시지와 함께

import asyncio
import litellm

async def main():
    result = await litellm.acount_tokens(
        model="openai/gpt-5.6-terra",
        messages=[{"role": "user", "content": "What's the weather in Paris?"}],
        tools=[{
            "type": "function",
            "function": {
                "name": "get_weather",
                "description": "Get weather for a city",
                "parameters": {
                    "type": "object",
                    "properties": {"city": {"type": "string"}},
                },
            },
        }],
        system="You are a helpful weather assistant.",
    )
    print(f"Token count (with tools): {result.total_tokens}")

asyncio.run(main())

응답 형식

litellm.acount_tokens() 은 TokenCountResponse 를 반환합니다:

TokenCountResponse(
    total_tokens=15,           # Token count
    request_model="openai/gpt-5.6-terra",  # Model requested
    model_used="gpt-5.6-terra",      # Model used for counting
    tokenizer_type="openai_api",    # "openai_api", "anthropic_api", "local_tokenizer"
    original_response={"input_tokens": 15},  # Raw API response
    error=False,               # True if counting failed
    error_message=None,        # Error details if failed
)

폴백 동작

프로바이더가 토큰 카운팅 API를 지원하지 않거나 API 키가 누락되면, acount_tokens() 가 자동으로 로컬 tiktoken 기반 카운팅으로 폴백합니다:

# Unsupported provider → automatic fallback
result = await litellm.acount_tokens(
    model="together_ai/meta-llama/Llama-3-8b-chat-hf",
    messages=[{"role": "user", "content": "Hello"}],
)
print(result.tokenizer_type)  # "local_tokenizer"

프록시에서 로컬 카운팅은 워커 스레드에서 실행되므로 큰 페이로드가 다른 요청을 막지 않아요. 각 워커 프로세스는 한 번에 최대 TOKEN_COUNTER_MAX_CONCURRENT_COUNTS 개(기본 4) 페이로드를 카운트하고 나머지는 큐에 넣어, 대량 카운트 버스트가 차지할 메모리를 제한합니다. TOKEN_COUNTER_MAX_EXACT_CHARS 문자(기본 4,000,000, 대략 백만 토큰)보다 긴 문자열은 총합 그만큼이 되는 16개의 균등 간격 샘플을 토큰화하고 그 결과를 문자열 길이로 스케일링해 추정하므로 가장 큰 페이로드의 비용을 제한합니다.

출처: 문서

본문

Proxy 사용법

OpenAI 형식: /v1/responses/input_tokens

• curl
• Python (httpx)

curl -X POST "http://localhost:4000/v1/responses/input_tokens" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{
    "model": "gpt-5.6-terra",
    "input": "Hello, how are you?"
  }'

import httpx

response = httpx.post(
    "http://localhost:4000/v1/responses/input_tokens",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer sk-<your-litellm-api-key>"
    },
    json={
        "model": "gpt-5.6-terra",
        "input": "Hello, how are you?"
    }
)

print(response.json())
# {"object": "response.input_tokens", "input_tokens": 13}

응답:

{"object": "response.input_tokens", "input_tokens": 13}

Anthropic 형식: /v1/messages/count_tokens

전체 문서는 Anthropic Token Counting 참고.

curl -X POST "http://localhost:4000/v1/messages/count_tokens" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [
      {"role": "user", "content": "Hello, how are you?"}
    ]
  }'

Proxy 구성

model_list:
  - model_name: gpt-5.6-terra
    litellm_params:
      model: openai/gpt-5.6-terra
      api_key: os.environ/OPENAI_API_KEY

  - model_name: claude-sonnet-5
    litellm_params:
      model: anthropic/claude-sonnet-5
      api_key: os.environ/ANTHROPIC_API_KEY

더 알아보기 (Learn more)

• Anthropic Token Counting
• /v1/messages
• Completion Token Usage & Cost