[pydantic-ai] OpenAI prompt_cache_retention 리터럴 타입 오류 수정

PR 링크: pydantic/pydantic-ai#4126 상태: Merged | 변경: +8 / -3

들어가며

OpenAI의 Prompt Caching 기능에서 prompt_cache_retention 파라미터의 리터럴 값에 SDK 타입 스텁과 실제 API 사이의 불일치가 있었습니다. SDK 스텁은 'in-memory'(하이픈)를 정의했지만, 실제 API는 'in_memory'(언더스코어)를 기대합니다. 이 작은 차이가 런타임 오류를 유발할 수 있었습니다.

핵심 코드 분석

리터럴 타입 수정

Before:

openai_prompt_cache_retention: Literal['in-memory', '24h']

After:

openai_prompt_cache_retention: Literal['in_memory', '24h']

Any 타입으로 SDK 타입 에러 우회

Before:

return await self.client.chat.completions.create(
    ...
    prompt_cache_retention=model_settings.get('openai_prompt_cache_retention', OMIT),
    ...
)

After:

# OpenAI SDK type stubs incorrectly use 'in-memory' but API requires 'in_memory',
# so we have to use `Any` to not hit type errors
prompt_cache_retention: Any = model_settings.get('openai_prompt_cache_retention', OMIT)
return await self.client.chat.completions.create(
    ...
    prompt_cache_retention=prompt_cache_retention,
    ...
)

SDK의 타입 체커가 'in_memory'를 허용하지 않으므로, 별도 변수에 Any 타입 어노테이션을 붙여 우회합니다. 이 패턴이 Chat Completions와 Responses API 두 곳에 동일하게 적용되었습니다.

왜 이게 좋은가

SDK 타입과 실제 API 동작의 불일치는 타입 체커를 신뢰하는 개발자에게 특히 위험합니다. 타입 체커가 통과시킨 코드가 런타임에 실패하기 때문입니다. 이 PR은 정확한 API 값을 사용하면서도 주석으로 불일치 원인을 명시하여, SDK가 수정될 때 쉽게 되돌릴 수 있도록 했습니다. 3줄 변경이지만 사용자가 직면할 수 있는 디버깅이 어려운 오류를 예방합니다.

정리

항목	내용
문제	SDK 스텁: 'in-memory' vs API 실제: 'in_memory'
해결	Literal 타입을 'in_memory'로 수정 + Any 우회
적용 범위	Chat Completions API + Responses API

참고 자료

• OpenAI Prompt Caching
• OpenAI SDK GitHub

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