LLM 캐싱

LLM 캐싱 (LLM Caching)

LLM 애플리케이션을 개발·테스트하다 보면 디버깅과 반복 과정에서 같은 요청을 계속 보내게 돼요. Helicone 캐싱은 완전한 응답을 Cloudflare 엣지 네트워크에 저장해서, 중복 API 호출을 없애고 지연 시간과 비용을 함께 줄여 줘요. 완전히 같은 요청은 프로바이더까지 가지 않고 즉시 캐시에서 돌려받는 구조예요.

출처: Helicone 공식 문서 — LLM Caching

프로바이더 서버단에서 캐시하는 프롬프트 캐싱과는 다른 개념이에요. 프롬프트 캐싱은 OpenAI·Anthropic 같은 프로바이더 서버에 캐시를 둬 토큰 비용을 줄이는 방식이고, Helicone 캐싱은 게이트웨이 자체에서 응답 전체를 저장하는 방식이에요.

왜 Helicone 캐싱인가요

비용 절감 — 테스트·디버깅 중 동일 요청에 대한 반복 비용을 피할 수 있어요.
즉시 응답 — LLM 프로바이더를 기다리는 대신 캐시된 응답을 바로 돌려줘요.
트래픽 급증 대응 — 높은 사용량에서도 속도 제한을 피하고 성능을 유지해요.

동작 방식

Helicone 캐싱 시스템은 Cloudflare 엣지 네트워크에 LLM 응답을 저장해서, 전 세계에 분산된 낮은 지연 시간의 캐시 접근을 제공해요.

캐시 키 생성

Helicone은 다음 요소를 해싱해 고유한 캐시 키를 만들어요:

캐시 시드(Cache seed) — 선택적인 네임스페이스 식별자 (지정 시)
요청 URL — 전체 엔드포인트 URL
요청 본문 — 모든 파라미터를 포함한 완전한 요청 페이로드
관련 헤더 — 인증 및 캐시 전용 헤더
버킷 인덱스 — 다중 응답 캐싱용

이 중 하나라도 바뀌면 새 캐시 항목이 생겨요.

// ✅ Cache hit - identical requests
const request1 = { model: "gpt-4o-mini", messages: [{ role: "user", content: "Hello" }] };
const request2 = { model: "gpt-4o-mini", messages: [{ role: "user", content: "Hello" }] };

// ❌ Cache miss - different content  
const request3 = { model: "gpt-4o-mini", messages: [{ role: "user", content: "Hi" }] };

// ❌ Cache miss - different parameters
const request4 = { model: "gpt-4o-mini", messages: [{ role: "user", content: "Hello" }], temperature: 0.5 };

캐시 저장

응답은 Cloudflare Workers KV(key-value store)에 저장돼요.
전 세계 300개 이상의 엣지 위치에 분산돼요.
자동 복제와 폴백을 지원해요.
사용자 인프라에는 영향을 주지 않아요.

시작하기

캐싱 활성화 — 요청에 Helicone-Cache-Enabled 헤더를 추가해요.
```
{
  "Helicone-Cache-Enabled": "true"
}
```

요청 실행 — 첫 호출이 캐시에 저장돼요. baseURL을 https://ai-gateway.helicone.ai로 하고 두 번째 인자 헤더에 캐시 헤더를 실어 보내면 돼요.

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: "user", content: "Hello world" }]
  },
  {
    headers: {
      "Helicone-Cache-Enabled": "true"
    }
  }
);

동작 확인 — 같은 요청을 다시 보내면 캐시에서 즉시 응답이 돌아와요.

설정

헤더	설명
`Helicone-Cache-Enabled`	요청의 캐시 활성화 여부. 예: `"true"`
`Cache-Control`	캐시 유지 시간. 기본 `"max-age=604800"` (7일). 예: `"max-age=3600"` (1시간)
`Helicone-Cache-Bucket-Max-Size`	같은 요청에 저장할 서로 다른 응답 개수. 기본 `"1"`. 예: `"3"`
`Helicone-Cache-Seed`	사용자·컨텍스트별 별도 캐시 네임스페이스. 예: `"user-123"`
`Helicone-Cache-Ignore-Keys`	캐시 키 생성에서 제외할 쉼표로 구분한 JSON 키. 예: `"request_id,timestamp"`

모든 헤더 값은 문자열이어야 해요. 예를 들어 "Helicone-Cache-Bucket-Max-Size": "10"처럼 따옴표로 묶어야 해요.

조합 예시

프로바이더 캐싱과 병행 — 프로바이더 전용 키를 무시하도록 Helicone-Cache-Ignore-Keys: "prompt_cache_key"를 쓰면 두 캐싱을 함께 쓸 수 있어요. 같은 메시지를 보내되 prompt_cache_key가 다른 요청들이 Helicone 캐시를 공유하면서도, OpenAI 프롬프트 캐싱은 각각 활용해 양쪽에서 성능과 비용을 최적화해요.

개발 테스트 — 개발 중 하루 단위 캐시(Cache-Control: max-age=86400)로 반복 청구를 피해요. 어떤 모델이든 게이트웨이를 통해 동작해요.

사용자별 캐시 — Helicone-Cache-Seed에 사용자 ID를 넣으면 사용자마다 별도의 캐시 응답을 유지해요.

캐시 상태 확인

응답 헤더로 캐시 상태를 확인할 수 있어요:

Helicone-Cache 헤더가 HIT 또는 MISS 값을 줘요.
Helicone-Cache-Bucket-Idx 헤더가 사용된 캐시 응답의 버킷 인덱스를 알려줘요.

캐시 유지 시간

Cache-Control 헤더로 응답이 캐시에 머무는 시간을 정해요.

1시간: max-age=3600
1일: max-age=86400
7일: max-age=604800 (기본)
30일: max-age=2592000

최대 캐시 기간은 365일(max-age=31536000)이에요.

캐시 버킷

Helicone-Cache-Bucket-Max-Size로 같은 요청에 서로 다른 응답을 몇 개까지 저장할지 정해요. 크기가 1이면(기본) 같은 요청은 항상 같은 캐시 응답을 돌려줘서 결정적이고, 크기가 1보다 크면 같은 요청이 버킷 안에서 무작위로 다른 응답을 돌려줘요(창의적 프롬프트에 유용). 예를 들어 "임의의 숫자를 줘" 같은 비결정적 프롬프트에서 버킷 크기 3이면 "42", "47", "17" 중 하나가 캐시 적중으로 반환돼요. 버킷 최대 크기는 20이고, 엔터프라이즈 플랜에서 더 큰 버킷을 지원해요.

캐시 시드

Helicone-Cache-Seed로 별도의 캐시 네임스페이스를 만들어요. 사용자 A와 사용자 B가 서로 영향을 주지 않도록 분리하고 싶을 때 유용해요. 내부적으로 시드 "user-123"은 자기만의 캐시 상태를 유지하므로, 시드가 다르면 같은 호출도 다른 결과를 냅니다. 시드 값을 바꾸면 테스트용으로 캐시를 사실상 비우는 효과도 있어요.

무시 키

Helicone-Cache-Ignore-Keys로 캐시 키 생성에서 특정 JSON 필드를 제외해요. 예를 들어 "request_id,timestamp"를 무시하면 이 값들이 달라도 같은 캐시 항목을 사용해요. 응답에 영향을 주지 않는 추적 ID나 타임스탬프를 무시하거나, 공유 콘텐츠를 캐시할 때 세션·사용자 메타데이터를 빼는 데 써요. 이 기능은 JSON 요청 본문에서만 동작하고, 비-JSON 본문은 원본 텍스트로 캐시 키를 만들어요.

캐시 제한

최대 기간: 365일
최대 버킷 크기: 20 (엔터프라이즈는 더 허용)
캐시 키 민감도: 어떤 파라미터든 바뀌면 새 캐시 항목 생성
저장 위치: Cloudflare Workers KV(엣지 분산) — 사용자 인프라가 아님

더 알아보기

프롬프트 캐싱 — 프로바이더 서버에서 토큰 비용 절감
커스텀 프로퍼티 — 캐시된 요청에 메타데이터 부여
속도 제한 — 요청 빈도 제어와 캐싱 병행