OpenAI Python SDK 遷移至 HTTPX2
OpenAI Python SDK 現在針對同步與非同步 HTTP 用戶端皆使用 HTTPX2。此變更可確保 SDK 是基於穩定的 API 構建，以避免即將發布的 HTTPX 1.0 版本中預期的破壞性變更。雖然 openai 套件會自動安裝 HTTPX2，但舊有的 httpx 套件不再是傳遞依賴項。
TLS 憑證驗證與信任儲存庫
對大多數使用者而言，最關鍵的變更在於 TLS 憑證驗證方式的轉變。HTTPX2 預設使用作業系統的信任儲存庫，而先前的 HTTPX 實作則是依賴 certifi CA 束。
此轉變可能會在以下環境中導致憑證驗證失敗：
- 缺乏系統 CA 憑證的精簡容器映像檔。
- 使用企業 TLS 檢查代理伺服器的環境。
- 先前依賴於修改過或自定義
certifi束的部署環境。
若要解決這些問題，使用者應將所需的 CA 憑證安裝到作業系統的信任儲存庫中，或使用環境變數配置明確的憑證束：
SSL_CERT_FILE=/path/to/ca-bundle.pemSSL_CERT_DIR=/path/to/ca-directory
若需進行細粒度控制，可以透過 DefaultHttpx2Client 或 DefaultAsyncHttpx2Client 使用 verify 參數傳遞 ssl.SSLContext。
對預設與自定義 HTTP 用戶端之影響
預設用戶端使用方式
對於在建構 OpenAI 或 AsyncOpenAI 用戶端時未提供自定義 http_client 的使用者，現有的 API 呼叫、串流、身分驗證與逾時設定仍可正常運作，無需額外配置。
自定義用戶端配置
提供自定義 HTTP 用戶端的的使用者現在必須使用 HTTPX2 用戶端與配置物件。SDK 提供輔助類別以維持連接池與逾時設定的建議預設值：
DefaultHttpx2Client: 用於同步用戶端。DefaultAsyncHttpx2Client: 用於非同步用戶端。
也支援直接建構的 httpx2.Client 與 httpx2.AsyncClient 實例。雖然舊有的名稱 DefaultHttpxClient 與 DefaultAsyncHttpxClient 仍可運作，但它們現在底層實作的是 HTTPX2 用戶端。
API 對應與物件替換
在進行自定義實作遷移時，請將舊有的 httpx 物件替換為對應的 httpx2 等效物：
| Previous Object | HTTPX2 Object |
|---|---|
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）。然而，這些異常底層的傳輸層原因現在將會是 HTTPX2 異常而非 HTTPX 異常。
測試與請求模擬 (Mocking)
模擬工具現在必須攔截 HTTPX2 請求並回傳 HTTPX2 回應。如果測試套件依賴於 RESPX，使用者必須更新至與 HTTPX2 相容的版本或分支 (fork) 該函式庫，因為僅修補舊有 HTTPX 的版本無法攔截 SDK 預設的 HTTPX2 用戶端。
相容性與舊有方案的逃生艙
對於無法立即從僅限 HTTPX 的傳輸層或模擬函式庫遷移的應用程式，SDK 提供了一個僅限執行時 (runtime-only) 的逃生艙。透過明確安裝 httpx 並注入一個舊有的用戶端，使用者可以維持現有功能：
from typing import Any, cast
import httpx
from openai import OpenAI
client = OpenAI(http_client=cast(Any, httpx.Client()))
請注意，此方法會導致靜態型別檢查（mypy, Pyright）失敗，且需要使用 cast(Any, ...) 或 type-ignores。此舊有支援是暫時性的遷移輔助工具，未來可能會停止支援。
社群洞察
業界同儕已指出，此轉變並非 OpenAI 獨有；Anthropic 也實作了類似的變更。主要的驅動力是 httpx 依賴項在接近 1.0 版本發布時的不穩定性，因為預期會引入顯著的破壞性變更。
The httpx2 project is essentially a fork that promises not to break the existing API, which makes it a more stable dependency to build against.
其他開發者也針對高效能需求提出了替代方案，例如基於 Rust 的 pyqwest，儘管 SDK 目前的實作是標準化於 HTTPX2。
Sources
相關
- 專案
- Dispatch
- Dispatch
- 專案