OpenAI Python SDK の HTTPX2 への移行
OpenAI Python SDK は、同期および非同期の HTTP クライアントに HTTPX2 を利用するようになりました。この変更により、近い将来リリース予定の HTTPX 1.0 で予想される破壊的変更を回避し、安定した API に基づいて構築されるようになります。HTTPX2 は openai パッケージと共に自動的にインストールされますが、従来の httpx パッケージはもはや非推奨の依存関係ではなくなっています。
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 リリースに近づくにつれて httpx 依存関係が不安定になり、大幅な破壊的変更が予想されるためです。
HTTPX2 プロジェクトは、既存の API を破壊しないことを約束するフォークであり、より安定した依存関係として構築するのに適しています。
他の開発者は、高性能のニーズに対して Rust ベースの pyqwest などの代替案を提案していますが、SDK の現在の実装は HTTPX2 に標準化されています。
Sources
関連
- プロジェクト
- Dispatch
- Dispatch
- プロジェクト