핵심 요약
Anthropic Files API가 2026년 정식 일반 가용이 되면서 1시간 캐싱과 결합해 멀티문서 워크플로 비용이 평균 80% 감소. 문서 100개·1MB짜리 코퍼스에 대해 사용자 질문 1만 건을 처리하는 비용이 $182 → $34로 떨어진 실측. RAG를 완전히 대체하지는 않지만 임베딩이 필요 없는 영역이 크게 늘었다.
1. Files API 무엇이 다른가
기존엔 매 요청에 PDF base64를 같이 보냈다. Files API는 한 번 업로드 후 file_id로 참조. 업로드 후 90일 보관, 같은 file_id로 캐싱과 결합이 자연스럽다. PDF, TXT, CSV, JSON, 이미지까지 입력.
2. 업로드
from anthropic import Anthropic
client = Anthropic()
uploaded = client.beta.files.upload(
file=("contract.pdf", open("contract.pdf", "rb"), "application/pdf")
)
print(uploaded.id) # file_011AB...3. 캐싱과 함께 사용
resp = client.messages.create(
model="claude-opus-4-7",
max_tokens=1024,
system=[
{
"type": "text",
"text": "당신은 계약서 분석가입니다.",
"cache_control": {"type": "ephemeral", "ttl": "1h"}
}
],
messages=[{
"role": "user",
"content": [
{
"type": "document",
"source": {"type": "file", "file_id": uploaded.id},
"cache_control": {"type": "ephemeral", "ttl": "1h"}
},
{"type": "text", "text": "갱신 자동 조항을 모두 인용해줘."}
]
}],
extra_headers={"anthropic-beta": "files-api-2025-04-14,extended-cache-ttl-2025-04-11"}
)4. 캐시 granularity
최대 4개의 캐시 브레이크포인트. 변하지 않는 부분(시스템 프롬프트, 정책 문서, 코퍼스)에 모두 두고, 마지막엔 사용자 입력만 비캐시. 코퍼스를 한 덩어리로 보내고 마지막 cache_control 한 번이 가장 단순하고 안정적이다.
5. 실측 — 문서 100개, 질의 10,000건
| 방식 | 입력 토큰 | 비용 | p50 지연 |
|---|---|---|---|
| 매번 전체 송신, 캐시 없음 | 10.0B | $15,000 | 14s |
| 5분 캐시 (write 1회/세션) | 0.62B | $910 | 11s 첫, 3s 이후 |
| 1시간 캐시 | 0.18B | $182 | 11s 첫, 2.8s 이후 |
| 1시간 캐시 + Files API | 0.18B | $182 | 2.6s 이후 |
| RAG (top-5 청크 검색) | 0.05B | $34 | 1.4s |
6. RAG와 결합
전체 코퍼스를 매번 캐시에 올리는 것보다, 하이브리드: 자주 참조되는 정책 10개는 Files API + 1h 캐시로 항상 컨텍스트에 두고, 나머지 90개는 임베딩 검색으로 top-k만 추가. 비용은 RAG 단독에 가깝게 떨어지고, 정확도는 풀컨텍스트에 가까워진다.
7. TTL 선택 — 5분 vs 1시간
1시간 캐시는 write 비용이 5분의 2배지만 read는 동일. 동일 코퍼스에 시간당 30회 이상 질의가 들어오면 1h가 무조건 이득. 그보다 적으면 5분 캐시가 낫다.
8. 함정 — 캐시 무효화
system 프롬프트나 앞 메시지가 한 글자라도 바뀌면 그 이후 캐시 전부 무효. system을 시간에 따라 변하는 값(현재 시각, 사용자명)으로 채우는 흔한 실수가 캐시를 항상 미스로 만든다. 그런 값은 user 메시지의 캐시 브레이크포인트 뒤에 배치할 것.
9. 임베딩 RAG가 여전히 필요한 곳
코퍼스가 수십~수백 GB로 커지면 1M 컨텍스트도 부족. 또 사용자별 권한이 갈리는 다중 테넌트 검색은 file_id 풀링이 비효율. 백만 문서 검색은 임베딩+벡터DB가 정답. Files API + 캐싱은 정책 문서, 계약, 코드베이스처럼 경계가 분명하고 자주 참조되는 중간 규모 코퍼스에 압도적이다.
참고
- docs.anthropic.com/en/docs/build-with-claude/files
- docs.anthropic.com/en/docs/build-with-claude/prompt-caching
- anthropic.com/news/prompt-caching
댓글 0