從 0.x 到 1.0：一次低調但關鍵的版號升級
Anthropic 在 8 月 20 日把 Claude 官方 Python SDK 推上 1.0.0，PyPI 專案頁的發布日期清楚標記了這一天。對一套長年停留在 0.x 版號的 SDK 而言，跨過 1.0 不只是數字變好看：在語意化版號的慣例裡，0.x 意味著介面隨時可能調整，1.0 之後則是對外承諾破壞性變更只發生在大版號跳躍時。這次升級的實際內容，v1.0.0 版本記錄寫得直白：HTTP 層升級到 httpx2，伴隨若干次要的破壞性變更，細節放在 MIGRATION.md。
具體來說，1.0 帶來三件必須留意的事：HTTP 傳輸層從 httpx 換成 httpx2；Python 最低版本提高到 3.10；移除長期棄用的介面，其中最具代表性的就是傳統 Text Completions API。官方發布說明對 HTTP 層的描述是理解整次升級的鑰匙：httpx2 是一個「持續維護、API 相容」的分支版本。SDK 儲存庫的 README 也已加上從 0.x 升級的指引，把使用者直接導向 v1 遷移指南。
換心不換殼：httpx2 遷移為什麼多數人無感
要判斷這次變更會不會打到自己，得先知道 HTTP 層在 SDK 裡做什麼。當你呼叫 client.messages.create()，SDK 要負責建立連線、序列化請求、處理逾時與重試、支援代理伺服器——這些工作不是 SDK 親手做的，而是委託給底下的 HTTP 用戶端函式庫。0.x 時代這個位置放的是 httpx；1.0 之後換成 httpx2。
關鍵在於兩者的關係：httpx2 與 httpx 共用同一組 API 介面，只是實作與維護主體不同。對「拿預設用戶端、呼叫 Messages API」的大多數程式來說，引擎換了、方向盤沒變，程式碼一行都不用改，多數使用者甚至不會察覺底層已經換過一次心臟。真正的差異只會出現在直接觸摸這顆引擎的程式碼上。
三種需要立刻檢查的程式碼
無感的前提是你沒有碰底層。以下三種情況，升級前必須逐一排查。
第一種，自行傳入 http_client 的程式。企業環境很常見這種寫法：強制走內部代理、掛自訂憑證、或注入觀察流量的傳輸層。這類程式碼直接引用 httpx 來建構用戶端再交給 SDK，1.0 之後要跟著換成 httpx2——介面相容，改的往往只是匯入的那一行，但沒改就是直接噴錯。想在本地端實際看看 SDK 送出的請求長什麼樣子，可以參考我們先前用 mitmproxy 攔截 GitHub Copilot 流量的做法，那正是自訂傳輸層的典型場景。
第二種，仍在叫用 client.completions 的舊程式。Text Completions 是 Messages API 出現之前的老介面，這次連 SDK 的介面一起移除，升級後呼叫會直接失效，必須改寫成 client.messages。
第三種，Python 版本低於 3.10 的執行環境。舊版容器映像、內部仍跑 3.8 或 3.9 的服務、鎖舊版基礎映像的 CI，都得先升 Python 再升 SDK，否則連安裝都過不了。完整的變更清單，官方放在儲存庫根目錄的 v1 遷移指南，升級前值得逐條對照，而不是憑印象改。
Text Completions 退場：遲來的介面清理
Text Completions 的棄用不是新聞。自從 Messages API 上線，這條舊路就被標記為淘汰方向，官方文件早已引導開發者遷移，SDK 只是遲遲保留著相容層。這次 1.0 把相容層拿掉，等於正式宣告：還沒搬的程式，現在必須搬。
這種清理對 SDK 的長期健康是必要的。在 0.x 版號下，棄用介面可以無限期地留在原處，代價是程式碼路徑愈積愈多、測試矩陣愈拉愈寬，每個新功能都要多養一條舊路。1.0 的意義之一，就是把介面收斂到一條主幹道上，讓後續維護與功能演進有乾淨的基礎。這也與 Anthropic 今年整體收斂開發者介面的節奏一致——電腦操作、Skills 與 Files API 才剛脫離 beta，平台端正在把「正式版」的界線一條條畫清楚。
httpx2 不是 Anthropic 一家的事：Python 生態的 HTTP 層大搬家
單看發布說明，httpx 換 httpx2 像是一次技術性換料；放進 Python 生態的脈絡，它是更大搬遷潮的一部分。SDK 儲存庫裡早有遷移討論 issue，標題就是「考慮從 httpx 遷移到 httpx2」，討論圍繞 httpx 的維護狀態與供應鏈風險展開：當上游 HTTP 函式庫的維護放緩，依賴它的大量套件等於把命脈掛在一條不確定何時修復的線上，而 httpx2 以 API 相容分支的姿態接手，讓下游能用最小的改動換到持續維護的實作。
Anthropic 的選擇因此有雙重意義。對內，官方 SDK 不再把傳輸層押在維護放緩的依賴上；對外，一家指標型 AI 廠商完成遷移，對整個 Python 生態是可見的示範——httpx2 不再只是社群實驗，而是可以寫進正式版依賴的選項。對使用者的實際影響則是：你的依賴樹未來可能同時存在 httpx 與 httpx2，因為其他尚未遷移的套件仍用前者；兩者可以並存，但在鎖定依賴版本時，值得留意套件管理器的解析行為與重複安裝的體積。
升級策略：現在動、設緩衝期，還是先鎖 0.x
急不急，取決於你屬於哪一種使用者。如果你的程式只用 Messages 系列介面、跑在 Python 3.10 以上、也沒有自訂傳輸層，直接升到 1.0.x 即可，負擔接近零。如果三個踩雷點踩中任何一個，建議的做法是三步：先在依賴檔把 anthropic 鎖在 0.x 最新版，爭取一個明確的緩衝視窗；接著在程式碼裡搜尋三個關鍵字——completions.create、http_client、以及匯入 httpx 的陳述式——把命中處逐一列成清單；最後在暫存環境跑完一輪完整測試再放行。0.x 的最後幾個版本仍然穩定，不會因為 1.0 出現就立刻失效，但官方的修補與新功能重心都會轉向 1.x 線，這是緩衝期不宜拖太長的理由。
官方沒細說的部分與值得追蹤的指標
這次發布也有幾處官方著墨甚少的地方。其一，版本記錄稱破壞性變更「次要」，卻沒有當場逐條列完，真正的清單在 MIGRATION.md，遷移時務必以文件為準而非新聞摘要。其二，httpx2 的維護主體與長期路線圖，官方僅以「持續維護的相容分支」一句帶過，後續治理值得觀察。其三，官方未提及這次替換對效能或連線行為的影響，對延遲敏感的服務建議在升級前後各做一輪實測。其四，Anthropic 的其他官方 SDK（例如 TypeScript 版）是否跟進同樣的 HTTP 層遷移，目前未見對應公告。值得追蹤的指標同樣明確：MIGRATION.md 的後續修訂、1.0.x 修補版本的發布頻率，以及 pydantic-ai、LiteLLM 這類包裹 anthropic 套件的框架的適配進度——它們的時程，往往才是多數團隊真正能夠升級的時間點。
