프롬프트 캐싱

프롬프트 캐싱 (Prompt Caching)

자주 사용하는 컨텍스트(시스템 프롬프트, 예시, 문서)를 매 요청마다 다시 처리하면 토큰 비용과 응답 시간이 계속 쌓여요. 프롬프트 캐싱은 이런 컨텍스트를 프로바이더 서버에 캐시해 여러 요청에서 재사용하게 해 주는데, 대폭 줄어든 비용과 더 빨라진 응답을 얻을 수 있어요. Helicone은 OpenAI 호환 AI 게이트웨이를 통해 여러 프로바이더에서 이 기능을 자동으로 활성화해 줘요.

출처: Helicone 공식 문서 — Prompt Caching

왜 프롬프트 캐싱인가요

• 토큰 비용 절감 — 캐시된 프롬프트는 프로바이더가 크게 할인된 요율로 처리해요 (최대 90% 절감).
• 더 빠른 처리 — 프로바이더가 캐시된 프롬프트 구간을 다시 처리하지 않아 응답이 빨라져요.
• 자동 최적화 — OpenAI 호환 AI 게이트웨이에서 모든 프로바이더에 걸쳐 별도 설정 없이 동작해요.

OpenAI 및 호환 프로바이더

1024 토큰을 넘는 프롬프트에 대해 자동 캐싱이 적용돼요. 캐시 적중률을 더 잘 제어하려면 prompt_cache_key 파라미터를 쓰면 좋아요.

호환 프로바이더: OpenAI, Grok, Groq, Deepseek, Moonshot AI, Azure OpenAI

빠른 시작

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://ai-gateway.helicone.ai",
  apiKey: proces...KEY,
});

const response = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [
    {
      role: "system",
      content: "Very long system prompt that will be automatically cached..." // 1024+ tokens
    },
    {
      role: "user", 
      content: "What is machine learning?"
    }
  ],
  prompt_cache_key: `doc-analysis-${documentId}` // Optional: control caching keys
});

요금

OpenAI는 캐시 쓰기(write)에 표준 요율을, 캐시 읽기(read)에는 큰 할인을 적용해요. 정확한 요율은 모델마다 달라요. 지원 모델과 캐싱 기능은 Helicone 모델 레지스트리에서, 공식 요금 정책은 OpenAI 프롬프트 캐싱 문서에서 확인할 수 있어요.

Anthropic (Claude)

Anthropic은 캐시 제어 브레이크포인트(요청당 최대 4개)와 TTL 제어를 제공하는 고급 캐싱을 지원해요.

OpenAI SDK + Helicone 타입 사용

@helicone/helpers SDK가 OpenAI 타입을 확장해, OpenAI 호환 인터페이스를 통해 Anthropic의 캐시 제어를 지원해요.

npm install @helicone/helpers

import OpenAI from "openai";
import { HeliconeChatCreateParams } from "@helicone/helpers";

const client = new OpenAI({
  baseURL: "https://ai-gateway.helicone.ai",
  apiKey: proces...KEY,
});

const response = await client.chat.completions.create({
  model: "claude-3.5-haiku",
  messages: [
    {
      role: "system",
      content: "You are a helpful assistant...",
      cache_control: {
        type: "ephemeral",
        ttl: "1h"
      }
    },
    {
        role: "assistant",
        content: "Example assistant message.",
        cache_control: { type: "ephemeral" }
    },
    {
      role: "user",
      content: [
        {
          type: "text",
          text: "This content will be cached.",
          cache_control: {
            type: "ephemeral",
            ttl: "5m"
          }
        },
        {
          type: "image_url",
          image_url: {
            url: "https://example.com/image.jpg",
            detail: "low"
          },
          cache_control: { type: "ephemeral" }
        }
      ]
    }
  ],
  temperature: 0.7
} as HeliconeChatCreateParams);

메시지에 cache_control: { type: "ephemeral" }를 붙이면 그 메시지를 캐시 대상으로 표시해요. TTL은 브레이크포인트 단위로 지정할 수 있어요.

캐시 키 매핑

Anthropic은 서버에서 user_id를 캐시 키로 사용해요. OpenAI 호환 AI 게이트웨이를 쓰면 다음 파라미터가 Anthropic의 user_id로 자동 매핑돼요:

• prompt_cache_key
• safety_identifier
• user

따라서 prompt_cache_key: "doc-analysis-v1"처럼 지정하면 Anthropic 쪽 캐시 키로 사용돼요. 현재 한계는 Anthropic 캐시 제어가 메시지 캐싱에서만 활성화되어 있다는 점이에요 — 도구(tools) 캐싱 지원은 곧 추가될 예정이에요.

요금 구조

Anthropic은 프롬프트 캐싱에 배수(multiplier) 기반 요금 모델을 써요.

핵심 사항

• TTL 옵션: 5분 또는 1시간
• 프로바이더: Anthropic API, Vertex AI, AWS Bedrock에서 사용 가능
• 한계: Vertex AI와 Bedrock은 5분 캐싱만 지원
• 최소: 대부분의 모델에서 1024 토큰부터

계산 예시

Base input price: $3/MTok
5-min cache write: $3 × 1.25 = $3.75/MTok
1-hour cache write: $3 × 2.0 = $6.00/MTok
Cache read: $3 × 0.1 = $0.30/MTok

Google Gemini

Google은 컨텍스트 캐싱에 배수 + 저장 비용 모델을 사용해요.

저장 요율:

• Gemini 2.5 Pro: $4.50/MTok/hour
• Gemini 2.5 Flash: $1.00/MTok/hour
• Gemini 2.5 Flash-Lite: $1.00/MTok/hour

핵심 사항

• TTL: 5분만 지원
• 캐시 유형: 암시적(자동) 및 명시적(수동)
• 최소: 1024 토큰(Flash), 2048 토큰(Pro)
• 할인: 캐시 읽기 입력 비용 75% 할인

계산 예시 (Gemini 2.5 Pro, ≤200K 토큰)

Base input price: $1.25/MTok
Storage rate: $4.50/MTok/hour

Cache write (5 min):
- Input cost: $1.25 × 1.0 = $1.25
- Storage cost: $4.50 × (5/60) = $0.375
- Total: $1.625/MTok

Cache read: $1.25 × 0.25 = $0.31/MTok

계층형 요금

Gemini 2.5 Pro는 컨텍스트 크기에 따라 요율이 달라져요.

더 알아보기

• LLM 캐싱 — 게이트웨이 레벨 응답 캐싱
• Anthropic 프롬프트 캐싱 문서
• Helicone 모델 레지스트리 — 모델별 캐싱 지원 확인