기본 통신 라이브러리 교체 및 의존성 변화

동기 및 비동기 HTTP 통신을 처리하는 OpenAI Python SDK의 기본 라이브러리가 HTTPX에서 HTTPX2로 변경됐다. Pydantic이 유지보수를 이어받은 HTTPX2는 기존 HTTPX의 설계를 유지하면서 보안 업데이트와 안정적인 관리를 제공하는 것을 목표로 하는 프로젝트다. HTTP/1.1과 HTTP/2를 모두 지원하며, SDK의 핵심 통신 계층에서 작동한다.

패키지 설치 구조에도 변화가 생겼다. `pip install openai` 명령어로 SDK를 설치하면 이제 HTTPX2가 함께 설치된다. 반면 기존의 `httpx`와 `certifi`는 더 이상 SDK의 기본 의존성 목록에 포함되지 않는다. 만약 애플리케이션의 다른 코드에서 SDK가 설치해 준 `httpx`를 참조해 사용하고 있었다면, 해당 라이브러리를 직접 의존성에 추가하거나 코드를 `httpx2`로 수정해야 한다.

API 유지 사항과 TLS 인증서 검증 메커니즘

기존의 API 호출 방식이나 파싱된 응답 모델, 스트리밍 API는 그대로 유지된다. `OpenAI()` 및 `AsyncOpenAI()` 클라이언트를 생성해 사용하는 기본 방식은 물론, 인증 처리, 재시도 로직, 숫자로 지정하는 타임아웃 설정 등은 이전과 동일하게 동작한다.

가장 주의 깊게 살펴야 할 기술적 변화는 TLS 인증서 검증 방식이다. 기존 HTTPX는 `certifi` 라이브러리가 제공하는 CA 인증서 묶음을 사용해 서버를 검증했다. 하지만 HTTPX2는 운영체제(OS)의 인증서 저장소를 직접 사용한다. 이로 인해 시스템 CA 인증서가 포함되지 않은 최소형 컨테이너 이미지(Minimal Container Image)를 사용하거나, 기업용 TLS 검사 프록시 환경, 혹은 `certifi` 인증서 묶음을 별도로 수정해 사용하던 환경에서는 인증 실패가 발생할 수 있다. 이 경우 필요한 CA 인증서를 운영체제에 직접 설치하거나, `SSL_CERT_FILE` 또는 `SSL_CERT_DIR` 환경 변수를 통해 인증서 경로를 명시해야 한다.

사용자 지정 클라이언트 마이그레이션 및 제약

HTTP 클라이언트를 직접 정의해 사용하는 환경에서는 대응하는 `httpx2` 객체와 인터페이스로 교체 작업이 필요하다. SDK가 제공하는 `DefaultHttpx2Client`와 `DefaultAsyncHttpx2Client`를 사용하면 SDK의 권장 타임아웃, 연결 풀(Connection Pool), 리디렉션 기본값을 그대로 유지할 수 있다. 원시 요청(Raw Request)과 응답 객체를 다루는 코드, 인증 처리기, 이벤트 훅, 실행 추적 및 계측 도구 역시 HTTPX2와의 호환성을 확인해야 한다.

RESPX와 같이 기존 HTTPX 라이브러리를 가로채어 동작하는 테스트 도구는 새 기본 클라이언트의 요청을 캡처하지 못한다. 또한 `openai[aiohttp]` 옵션 사용 시, 외부 `httpx-aiohttp` 어댑터 대신 HTTPX2가 자체적으로 구현한 `aiohttp` 전송 계층을 사용하도록 변경됐다.

당장 라이브러리 교체가 어려운 경우 기존 `httpx`를 직접 설치하고 클라이언트를 주입하는 임시 호환 경로를 사용할 수 있다. 다만 이 방식은 실행 시에만 지원되며 정적 타입 검사 시 우회 처리가 필요하며, 마이그레이션을 돕기 위한 임시 수단이므로 향후 지원이 중단될 수 있다.

기업 내부망이나 폐쇄형 컨테이너 환경에서 SDK를 운영하는 개발자는 OS 수준의 CA 인증서 저장소 상태를 점검하고, 기존 `httpx` 기반의 테스트 훅이나 계측 도구를 `httpx2` 인터페이스로 전환해야 한다.