MiniMax 프롬프트 캐시 (Prompt Caching)

같은 시스템 프롬프트나 대화 이력을 반복해서 보내는 애플리케이션에서는 비용과 지연이 쉽게 늘어나요. MiniMax의 프롬프트 캐시는 반복되는 입력을 자동으로 캐시해서, 같은 요청을 다시 보낼 때 더 싸고 빠르게 처리해 줘요. 이 문서에서는 캐시 동작 원리와 지원 모델, 그리고 비용 계산을 정리해 드릴게요.

출처: MiniMax 공식 문서 - Prompt 캐시

기능 특성

자동 캐시 (수동 방식): 반복되는 컨텍스트를 자동으로 인식해서, 호출 방식을 바꾸지 않아도 돼요. (이에 반해 Anthropic API에서 파라미터를 명시적으로 설정하는 방식은 '능동 캐시'라고 불러요.)
비용 절감: 캐시에 적중한 입력 token은 더 낮은 가격으로 계산돼요.
속도 향상: 반복 내용 처리 시간을 줄여 모델 응답이 빨라져요.

이 방식은 이런 시나리오에 특히 유용해요.

시스템 프롬프트 재사용: 다중 턴 대화에서 시스템 프롬프트는 대개 그대로 유지돼요.
고정된 도구 목록: 특정 작업에서 쓰는 도구는 거의 고정돼요.
다중 턴 대화 이력: 복잡한 대화에서 이력 메시지는 중복 정보가 많아요.

코드 예시

Anthropic SDK

import anthropic

client = anthropic.Anthropic()

response1 = client.messages.create(
    model="MiniMax-M3",
    system="You are an AI assistant tasked with analyzing literary works.",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "<the entire contents of 'Pride and Prejudice'>"
                }
            ]
        },
    ],
    max_tokens=10240,
)

print(f"입력 Token: {response1.usage.input_tokens}")
print(f"출력 Token: {response1.usage.output_tokens}")
print(f"캐시 적중 Token: {response1.usage.cache_read_input_tokens}")

같은 내용의 두 번째 요청에서 cache_read_input_tokens가 커지면 캐시가 적중했다는 뜻이에요. Anthropic 호환 응답의 usage는 input_tokens·output_tokens·cache_creation_input_tokens·cache_read_input_tokens로 구성돼요.

OpenAI SDK

from openai import OpenAI

client = OpenAI()

response1 = client.chat.completions.create(
    model="MiniMax-M3",
    messages=[
        {"role": "system", "content": "You are an AI assistant tasked with analyzing literary works."},
        {"role": "user", "content": "<the entire contents of 'Pride and Prejudice'>"},
    ],
    extra_body={"reasoning_split": True},
)

print(f"캐시 Token: {response1.usage.prompt_tokens_details.cached_tokens if hasattr(response1.usage, 'prompt_tokens_details') else 0}")

OpenAI 호환 응답의 usage.prompt_tokens_details.cached_tokens로 캐시 적중을 확인할 수 있어요.

주의사항

캐시는 입력 token이 512개 이상인 API 호출에 적용돼요.
캐시는 접두사(prefix) 매칭 방식으로, '도구 정의 → 시스템 프롬프트 → 역사 대화 내용' 순서로 구성돼요. 어떤 모듈 내용이 바뀌어도 캐시 효과에 영향을 줄 수 있어요.

베스트 프랙티스

대화 앞부분에 정적·반복 내용(도구 정의, 시스템 프롬프트, 이력)을 두고, 동적인 사용자 정보는 대화 끝부분에 둬서 캐시를 최대한 활용하세요.
API가 반환하는 usage token 수로 캐시 성능을 모니터링하고, 정기적으로 분석해서 사용 전략을 최적화하세요.

계상 설명

프롬프트 캐시는 차별화된 가격 정책을 써요.

캐시 적중 token: 할인 가격으로 계산
신규 입력 token: 표준 입력 가격
출력 token: 표준 출력 가격

계상 예시(MiniMax-M3, 입력 ≤512k 표준 가격이라 가정, 대략적인 가격):

입력 4.20원/1M tokens, 출력 16.80원/1M tokens, 캐시 적중 0.84원/1M tokens

한 번의 요청에서 총 입력 50,000 token 중 캐시 적중 45,000, 신규 입력 5,000, 출력 1,000 token이라고 하면:

신규 입력: 5000 × 4.20 / 1000000 = 0.021원
캐시: 45000 × 0.84 / 1000000 = 0.0378원
출력: 1000 × 16.80 / 1000000 = 0.0168원
총: 0.0756원

캐시가 없었다면 (50000 × 4.20/1000000 + 1000 × 16.80/1000000 = 0.2268원)이므로 약 66.7%를 절약할 수 있어요.

M3의 경우 요청 입력 token이 512k를 넘으면 장기 컨텍스트 가격이 적용되고, 입력 token에는 캐시 적중 token이 포함돼요.

캐시 비교

항목	Prompt 캐시 (수동/자동 캐시)	Anthropic 능동 캐시
사용 방식	반복 내용 자동 인식 후 캐시	API에 `cache_control` 명시적으로 설정
계상 방식	적중 token 할인, 캐시 기록은 추가 비용 없음	적중 token 할인, 첫 캐시 기록 token은 추가 비용
캐시 만료	시스템 부하에 따라 만료 시간 자동 조정	5분 만료, 지속 사용 시 자동 갱신
지원 모델	M3, M2.7 시리즈, M2.5 시리즈, M2.1 시리즈	M2.7 시리즈, M2.5 시리즈, M2.1 시리즈, M2 시리즈

MiniMax 프롬프트 캐시 (Prompt Caching)