觀點 · 資訊分享

OpenAI Python SDK 升 3.0.0：HTTP 底層換成 HTTPX2，TLS 憑證改吃系統信任庫，容器與代理要先測

openai-python 在 8 月 12 日釋出 3.0.0：HTTPX2 成為預設 HTTP 用戶端、httpx 不再自動安裝。預設用法照常，但自訂 HTTP 設定、精簡容器與 TLS 檢查代理可能出問題。

一句話看懂：OpenAI 的 Python 程式庫升到 3.0.0，底層的 HTTP 套件從 httpx 換成 HTTPX2；一般用法不用改，但如果你有自訂 HTTP 設定，或在精簡的容器、公司代理後面跑，升級前要先測。

openai-python 3.0.0 釋出資訊圖卡：HTTP 底層換成 HTTPX2，預設用法照常，憑證信任庫變了

先用白話講：這次換的是什麼？

想像 OpenAI 的 Python 程式庫是一位外送員，負責把你的問題送到 OpenAI、再把答案帶回來。外送員騎的那台車（HTTP 套件）過去是 httpx，這次 3.0.0 版換成了新車 HTTPX2。

多數人只是叫外送員送東西，不在乎他騎哪台車，所以這次升級對一般用法沒有影響。但如果你有改裝過那台車（自訂 HTTP 用戶端、代理、測試用的假傳輸層），新車的零件不通用，就得跟著換。

openai-python 在 8 月 12 日釋出 v3.0.0，這是一個有「破壞性變更」的大版本，只有一項重點：

依官方遷移指南（目前版本）：

你的情況	影響
用 `OpenAI()`、沒自訂 `http_client`	既有的 API 呼叫、串流、驗證、重試與數字型逾時照常運作
程式裡自己 `import httpx`，原本是靠舊 SDK 順便裝的	現在不會再自動裝，要自己加依賴，或改成 `httpx2`
自訂 `http_client`、傳輸層、代理、事件掛鉤	要改成 HTTPX2 的對應物件
測試用 RESPX 攔截請求	要改用相容 HTTPX2 的版本或分支

這點官方特別用粗體提醒：即使你用預設用戶端，也受影響。

可能出狀況的環境，官方列了三種：

解法是把需要的 CA 憑證裝進作業系統信任庫，或用環境變數指定：

export SSL_CERT_FILE=/path/to/ca-bundle.pem
# 或指定一個放 CA 憑證的資料夾
export SSL_CERT_DIR=/path/to/ca-directory

這兩個變數在 trust_env=True（預設值）時有效；若要在自訂用戶端精確控制，可以把 ssl.SSLContext 透過 verify 傳入。

自訂用戶端請改用官方提供的 DefaultHttpx2Client、DefaultAsyncHttpx2Client；舊名稱 DefaultHttpxClient 還能用，但現在建出來的是 HTTPX2 用戶端
httpx.Client → httpx2.Client、httpx.Timeout → httpx2.Timeout，其他物件也是一一對應；數字型逾時與字串網址不變
使用 aiohttp 的人，改裝 openai[aiohttp] 並用 DefaultAioHttpClient()
暫時走回頭路：安裝 httpx 並注入舊版用戶端，但官方說明只在執行期有效、型別檢查會報錯，而且這是「過渡用途，未來可能移除」

接案時最怕這種「看起來只是小套件換掉」的大版本升級，因為出事的地方往往不是程式碼，而是環境：容器映像少了一包憑證、客戶公司的防火牆做了 TLS 檢查，結果上線後第一個請求就憑證驗證失敗。

我的建議是：別讓 pip install -U openai 直接跑在正式環境。先把版本鎖定在 2.x，在測試環境升到 3.0.0，實際跑一次呼叫，重點看憑證驗證、代理設定與逾時行為。如果你的客戶使用公司代理，這一步更不能省。

我只用 OpenAI() 呼叫 API，需要改程式嗎？

依官方遷移指南，沒有提供自訂 http_client 的話，既有的 API 呼叫、串流、驗證、重試與數字型逾時照常運作，pip install openai 就好。但 TLS 憑證信任庫改變仍可能影響你的環境。

升級後出現憑證驗證失敗怎麼辦？

HTTPX2 改用作業系統信任庫，SDK 不再安裝 certifi。可以在系統裝入需要的 CA 憑證，或用環境變數 SSL_CERT_FILE、SSL_CERT_DIR 指定；也可以在自訂用戶端用 ssl.SSLContext 透過 verify 傳入。

我的程式 import httpx，升級後找不到怎麼辦？

新版不再自動安裝 httpx。如果你只是因為舊版 SDK 順便裝了才 import，請自己加上 httpx 依賴，或把這些程式改用 httpx2。

作者

接案做系統開發、網站與主機託管。觀點裡的文章都是我自己寫的,寫的是做專案時第一手遇到的事。