본문으로 건너뛰기
프롬프트 캐싱

프롬프트 캐싱

자동

호스팅 오픈 웨이트 모델은 반복되는 프롬프트 접두사를 자동으로 캐싱합니다. 요청이 동일한 모델의 최근 요청과 동일한 시스템 프롬프트, 도구 및 이전 메시지로 시작하는 경우, 해당 공유 접두사는 캐시에서 읽어오며 모델 입력 가격의 25%로 청구됩니다. 별도의 설정은 필요 없으며, 캐시 쓰기는 무료입니다.

작동 원리

  • 순서대로 접두사 — 프롬프트는 시스템 프롬프트, 도구 정의, 메시지 순으로 읽힙니다. 캐시는 이 시퀀스의 시작부터 첫 번째로 다른 토큰이 나타나기 전까지 일치하는 부분을 찾습니다.
  • 캐시 히트 기준 — 프롬프트가 최근 요청과 동일한 내용으로 시작하는 경우입니다. 일반적으로 새로운 메시지가 추가된 동일한 대화의 이전 턴이 이에 해당합니다. 일치하는 접두사는 캐시된 입력이며, 그 이후의 모든 내용은 일반 입력입니다.
  • 세분성 — 캐시는 프롬프트를 1,568 토큰 단위의 블록으로 보관하므로 약 1,500 토큰보다 짧은 프롬프트는 캐시되지 않습니다. 응답의 캐시된 토큰 수는 입력 토큰 수에 프롬프트의 캐시된 비율을 곱해 내림한 값입니다. 반드시 블록 크기의 배수인 것은 아닙니다.
  • 히트가 없을 때 — 시작 부분이 캐시에 없는 요청은 일반 입력 요율로 청구됩니다. 캐시된 프롬프트의 유지 기간은 공개되어 있지 않으며 히트는 보장되지 않습니다. 요청이 캐시에서 얼마나 가져왔는지는 usage에서 확인하세요.
  • 스위치 없음 — 요청에서 따로 사용 신청을 하지 않으며, 캐싱을 끄는 필드도 없습니다.
  • 대상 모델 — 모든 호스팅 오픈 웨이트 ID가 해당됩니다. GET /v1/models에서 capabilities.prompt_caching: true 및 pricing.cached_input_per_million_usd 값을 통해 확인할 수 있습니다. Shannon 모델은 단일 정액 요율로 청구됩니다.

응답에서 캐시 히트 확인하기

같은 긴 시스템 프롬프트로 시작하는 요청을 두 번 보내고 각각의 usage를 출력하세요. 첫 번째 숫자는 요청의 입력이고, 두 번째는 그중 캐시에서 읽은 부분입니다.

from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.shannon-ai.com/v1")

handbook = open("handbook.txt").read()  # a long text that stays the same


def ask(question):
    response = client.chat.completions.create(
        model="Kimi-K3-3BIT-REAP",
        messages=[
            {"role": "system", "content": handbook},
            {"role": "user", "content": question},
        ],
    )
    usage = response.usage
    print(usage.prompt_tokens, usage.prompt_tokens_details.cached_tokens)


ask("What is the refund policy?")
ask("Who approves travel?")  # same start: read the second number

가격 책정

캐시된 입력 토큰은 모델 입력 요율의 25%로 청구되며, 1M당 $0.001 단위로 반올림됩니다. 캐시 쓰기 비용은 추가되지 않으며, 출력은 평소와 같이 청구됩니다. 각 ID별 캐시 요율은 '모델 및 가격' 표에 나와 있습니다. 모델 및 가격

호출의 입력은 (입력 − 캐시된 입력) × 입력 요율 + 캐시된 입력 × 캐시 요율로 청구됩니다. 캐시된 토큰 수는 입력 토큰 수보다 클 수 없습니다.

모델 입력 / 1M 캐시된 입력 / 1M
DeepSeek-V4-Pro-0813-3BIT-REAP $1.95 $0.488
GLM-5.2-3BIT-REAP $0.73 $0.183
Kimi-K3-3BIT-REAP $3.83 $0.958
Nemotron3Ultra-3BIT-REAP $0.75 $0.188
MiniMax-M3-3BIT-REAP $0.50 $0.125
DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP $0.50 $0.125
Kimi-K2.6-W4A16-AUTOROUND-REAP $0.78 $0.195
Laguna-S-2.1-W4A16-AUTOROUND-REAP $0.50 $0.125
inkling-W4A16-AUTOROUND-REAP $1.42 $0.355
MiMo-V2.5-Pro-W8A16 $0.50 $0.125
MiMo-V2.5-W8A16 $0.50 $0.125
Hy3-W8A16 $0.50 $0.125

사용 로그에는 각 호출의 캐시된 입력이 표시됩니다. 청구된 토큰과 비용에는 이미 캐시 요율이 반영되어 있습니다. Keys & usage

사용량 필드

엔드포인트 캐시된 입력 추론
/v1/chat/completions usage.prompt_tokens_details.cached_tokens — prompt_tokens의 일부 usage.completion_tokens_details.reasoning_tokens — completion_tokens의 일부
/v1/responses usage.input_tokens_details.cached_tokens — input_tokens의 일부 usage.output_tokens_details.reasoning_tokens — output_tokens의 일부
/v1/messages usage.cache_read_input_tokens — 별도 보고됨: input_tokens는 캐시되지 않은 부분이며, cache_creation_input_tokens는 항상 0입니다 thinking은 output_tokens에 포함되어 계산됩니다
{
  "usage": {
    "prompt_tokens": 20000,
    "completion_tokens": 812,
    "total_tokens": 20812,
    "prompt_tokens_details": {
      "cached_tokens": 18000
    },
    "completion_tokens_details": {
      "reasoning_tokens": 604
    }
  }
}

스트리밍 응답은 마지막 usage에 같은 필드를 담습니다. 따로 요청할 필요가 없습니다:

엔드포인트 사용량이 도착하는 위치
/v1/chat/completions data: [DONE] 직전 마지막 청크의 usage. 모든 스트림에서 전송됩니다.
/v1/responses response.completed 이벤트의 response.usage.
/v1/messages message_delta 이벤트의 usage. message_start의 usage는 모두 영입니다.

캐시 히트율 높이는 방법

  • 호출 간에 시스템 프롬프트와 도구 정의를 바이트 단위로 동일하게 유지하세요. 타임스탬프나 요청 ID와 같이 호출마다 변하는 값은 시스템 프롬프트가 아닌 최신 메시지의 끝에 배치하세요.
  • 히스토리에 내용을 추가만 하세요. 이전 턴을 수정, 삭제 또는 요약하면 접두사가 변경되어 첫 번째 변경 지점 이후의 모든 내용이 일반 입력으로 청구됩니다.
  • 호출 간에 도구, 메시지 또는 콘텐츠 블록의 순서를 바꾸지 마세요. 또한 JSON(도구 스키마, 도구 인자 및 결과)을 매번 동일한 방식으로 직렬화하세요.
  • 한 대화에서는 하나의 모델 id를 유지하고, 후속 호출은 직전 호출 직후에 보내세요.

API는 다음의 경우에 대화의 시작 부분을 안정적으로 유지합니다:

  • 대화 중간에 보낸 system 또는 developer 메시지는 제자리에 그대로 있습니다. 프롬프트의 시작 부분을 바꾸지 않으므로 그 앞의 턴은 계속 캐시됩니다.
  • 이전 assistant 턴에 있는 도구 호출의 인자는 값으로 비교합니다. 해당 JSON의 키 순서와 공백은 중요하지 않습니다.
  • 세 엔드포인트는 대화를 같은 방식으로 읽습니다. 다른 엔드포인트에서 이어간 대화도 내용이 같으면 공유된 접두사가 유지됩니다.

요청 필드

prompt_cache_key(Chat Completions 및 Responses)와 Messages 콘텐츠 블록의 cache_control이 허용되므로 기존 클라이언트 코드를 그대로 사용할 수 있습니다. 두 필드 모두 필수 사항은 아니며, 캐싱은 자동으로 이루어지며 이들이 없어도 동일하게 작동합니다.

필드 전송 대상 의미
prompt_cache_key /v1/chat/completions, /v1/responses OpenAI API의 캐시 라우팅 키.
cache_control /v1/messages Anthropic API의 콘텐츠 블록, system 블록 또는 메시지에 거는 캐시 브레이크포인트.
stream_options /v1/chat/completions include_usage는 OpenAI API에서 스트림의 사용량을 요청합니다. 여기서는 모든 스트림이 사용량과 함께 끝납니다.

토큰 계산

무료 엔드포인트 두 개, POST /v1/tokenize와 POST /v1/messages/count_tokens가 호스팅 오픈 웨이트 모델에 대해 텍스트 또는 요청 전체의 토큰 수를 보내기 전에 계산해 줍니다. 별도 페이지가 있습니다: 토큰 수 계산