OpenAI Python SDK의 HTTPX2로의 마이그레이션
OpenAI Python SDK는 이제 동기 및 비동기 HTTP 클라이언트 모두에 HTTPX2를 사용합니다. 이 변경은 HTTPX 1.0 릴리스 예정 시 breaking changes를 피하기 위해 안정적인 API를 기반으로 SDK를 구축하게 합니다. HTTPX2는 openai 패키지와 함께 자동으로 설치되지만, 이전의 httpx 패키지는 더 이상 전이 종속성(Transitive Dependency)이 아닙니다.
TLS 인증서 검증 및 신뢰 저장소
대부분의 사용자에게 가장 중요한 변경은 TLS 인증서 검증 방식의 전환입니다. HTTPX2는 기본적으로 운영 체제의 신뢰 저장소를 사용하지만, 이전 HTTPX 구현은 certifi CA 번들을 기반으로 했습니다.
다음 환경에서는 인증서 검증 실패가 발생할 수 있습니다:
- 시스템 CA 인증서가 없는 최소한의 컨테이너 이미지.
- 기업용 TLS 검사 프록시를 사용하는 환경.
- 이전에 수정되거나 사용자 정의된
certifi번들을 의존했던 배포.
이러한 문제를 해결하려면 사용자는 OS 신뢰 저장소에 필요한 CA 인증서를 설치하거나 환경 변수를 사용하여 명시적인 인증서 번들을 구성해야 합니다:
SSL_CERT_FILE=/path/to/ca-bundle.pemSSL_CERT_DIR=/path/to/ca-directory
세부 제어를 원하는 경우, DefaultHttpx2Client 또는 DefaultAsyncHttpx2Client를 통해 verify 매개변수를 통해 ssl.SSLContext를 전달할 수 있습니다.
기본 및 사용자 정의 HTTP 클라이언트에 대한 영향
기본 클라이언트 사용
사용자 정의 http_client를 제공하지 않고 OpenAI 또는 AsyncOpenAI 클라이언트를 생성하는 경우, 기존의 API 호출, 스트리밍, 인증 및 타임아웃은 추가 구성 없이도 정상적으로 작동합니다.
사용자 정의 클라이언트 구성
사용자 정의 HTTP 클라이언트를 제공하는 사용자는 이제 HTTPX2 클라이언트와 구성 객체를 사용해야 합니다. SDK는 연결 풀 및 타임아웃에 대한 권장 기본값을 유지하기 위한 헬퍼 클래스를 제공합니다:
DefaultHttpx2Client: 동기 클라이언트용.DefaultAsyncHttpx2Client: 비동기 클라이언트용.
직접 생성된 httpx2.Client 및 httpx2.AsyncClient 인스턴스도 지원됩니다. 이전 이름인 DefaultHttpxClient 및 DefaultAsyncHttpxClient는 여전히 작동하지만, 내부적으로는 이제 HTTPX2 클라이언트를 인스턴스화합니다.
API 매핑 및 객체 대체
사용자 정의 구현을 마이그레이션할 때, 이전의 httpx 객체를 httpx2에 해당하는 객체로 교체하세요:
| 이전 객체 | HTTPX2 객체 |
|---|---|
httpx.Client |
httpx2.Client |
httpx.AsyncClient |
httpx2.AsyncClient |
httpx.Timeout |
httpx2.Timeout |
httpx.URL |
httpx2.URL |
httpx.Limits |
httpx2.Limits |
httpx.HTTPTransport |
httpx2.HTTPTransport |
httpx.AsyncHTTPTransport |
httpx2.AsyncHTTPTransport |
httpx.MockTransport |
httpx2.MockTransport |
원시 응답 및 예외 처리
네이티브 HTTPX2 클라이언트를 사용할 경우, 전송 계층에 대한 객체(예: with_raw_response에서 반환되는 것들)는 httpx2.Response 및 httpx2.Request의 인스턴스입니다.
애플리케이션 코드는 여전히 SDK 수준의 예외(예: openai.APITimeoutError 및 openai.APIConnectionError)를 처리해야 합니다. 그러나 이러한 예외의 기반이 되는 전송 계층 원인은 이제 HTTPX 예외가 아니라 HTTPX2 예외가 됩니다.
테스트 및 요청 모킹
모킹은 이제 HTTPX2 요청을 가로채고 HTTPX2 응답을 반환해야 합니다. 테스트 스위트가 RESPX에 의존하는 경우, HTTPX2 호환 버전으로 업데이트하거나 라이브러리를 포크해야 합니다. 기존 HTTPX만 패치하는 버전은 SDK의 기본 HTTPX2 클라이언트를 가로챌 수 없습니다.
호환성 및 이전 경로
HTTPX 전용 전송 또는 모킹 라이브러리에서 즉시 마이그레이션할 수 없는 애플리케이션을 위해 SDK는 런타임 전용 경로를 제공합니다. 명시적으로 httpx를 설치하고 이전 클라이언트를 주입함으로써 기존 기능을 유지할 수 있습니다:
from typing import Any, cast
import httpx
from openai import OpenAI
client = OpenAI(http_client=cast(Any, httpx.Client()))
이 접근 방식은 정적 타입 체크(mypy, Pyright)에 실패하며 cast(Any, ...) 또는 타입 무시를 필요로 합니다. 이 이전 지원은 일시적인 마이그레이션 보조 도구이며, 향후 중단될 수 있습니다.
커뮤니티 인사이트
업계 동료들은 이 전환이 OpenAI에만 국한되지 않으며, Anthropic도 유사한 변경을 도입했다고 지적했습니다. 주된 동기는 HTTPX가 1.0 릴리스에 접근하면서 안정성이 떨어지고, 이로 인해 중요한 breaking changes가 예상되기 때문입니다.
"httpx2 프로젝트는 기존 API를 깨뜨리지 않겠다는 약속을 하는 포크(fork)이며, 이는 더 안정적인 종속성으로 빌드하는 데 더 적합합니다."
다른 개발자들은 고성능 요구 사항을 위해 Rust 기반의 pyqwest와 같은 대안을 제안했지만, SDK의 현재 구현은 HTTPX2에 표준화되어 있습니다.
Sources
관련
- 프로젝트
- Dispatch
- Dispatch
- 프로젝트