[pydantic-ai] CachePoint에 TTL 옵션 추가 — Anthropic 1시간 캐시 지원

PR 링크: pydantic/pydantic-ai#3450 상태: Merged | 변경: +75 / -21

들어가며

Anthropic는 prompt caching에 기본 5분 TTL 외에 1시간 TTL 옵션을 제공합니다. 기존 Pydantic AI는 항상 기본 TTL만 사용했기 때문에, 도구 정의나 시스템 프롬프트처럼 변경 빈도가 낮은 콘텐츠에 더 긴 캐시를 적용할 방법이 없었습니다. 이 PR은 CachePoint와 AnthropicModelSettings에 TTL 설정을 추가합니다.

핵심 코드 분석

1. CachePoint에 ttl 필드 추가

Before (messages.py):

class CachePoint:
    kind: Literal['cache-point'] = 'cache-point'

After:

class CachePoint:
    kind: Literal['cache-point'] = 'cache-point'
    ttl: Literal['5m', '1h'] = '5m'

CachePoint에 ttl 필드를 추가하되 기본값을 '5m'으로 설정하여 기존 코드의 동작을 유지합니다.

2. 모델 설정 타입 확장

Before (anthropic.py):

anthropic_cache_tool_definitions: bool
anthropic_cache_instructions: bool

After:

anthropic_cache_tool_definitions: bool | Literal['5m', '1h']
anthropic_cache_instructions: bool | Literal['5m', '1h']

True를 전달하면 기본 5분 TTL, '1h'를 직접 지정하면 1시간 TTL이 적용됩니다. Union 타입을 활용하여 하위 호환성을 유지합니다.

3. TTL 값을 API 파라미터에 전달

Before:

last_tool['cache_control'] = BetaCacheControlEphemeralParam(type='ephemeral')

After:

ttl: Literal['5m', '1h'] = '5m' if cache_tool_defs is True else cache_tool_defs
last_tool['cache_control'] = BetaCacheControlEphemeralParam(type='ephemeral', ttl=ttl)

True인 경우 '5m'으로 변환하고, 문자열 값이면 그대로 전달합니다. 동일한 패턴이 system prompt, user message cache point 모두에 일관되게 적용됩니다.

왜 이게 좋은가

• 도구 정의, 시스템 프롬프트처럼 거의 변하지 않는 콘텐츠에 1시간 캐시를 적용하면 cache write 비용을 대폭 줄일 수 있습니다.
• bool | Literal['5m', '1h'] 타입 설계로 기존 True/False 사용자에게 영향 없이 새 기능을 추가했습니다.
• TTL 변환 로직이 '5m' if value is True else value 한 줄로 단순합니다.

정리

• 설정 확장 시 Union 타입으로 하위 호환성을 보장하라: bool에서 bool | Literal[...]로 확장하면 기존 코드가 그대로 동작합니다.
• 기본값을 명시적으로 설정하라: TTL 기본값 '5m'을 생략하지 않고 명시하여, API 기본값 변경에 의존하지 않습니다.

참고 자료

• pydantic/pydantic-ai#3450 — PR 전체 diff
• Anthropic 1시간 캐시 문서 — 1시간 TTL 지원 설명

⚠️ 알림: 이 분석은 AI가 실제 코드 diff를 기반으로 작성했습니다.