觀點 · 資訊分享
Claude 的 Python SDK 升上 1.0：temperature 參數拿掉、最低要 Python 3.10，升級前先看這幾點
Anthropic 的官方 Python SDK 推出 1.0 版，底層改用 httpx2、移除舊的 Text Completions API 與 temperature 等取樣參數，最低支援版本升到 Python 3.10。直接升級可能會讓程式報錯。
- 發布
- 2026-08-21
- 篇幅
- 約 4 分鐘 · 1,797 字
- 結構
- 7 節 + 3 題常見問題
- 標籤
一句話看懂：Claude 官方的 Python SDK 推出 1.0 正式版，一次清掉很多舊寫法；沒鎖版本的專案，一更新就可能報錯。
先用白話講：SDK 升大版本是什麼意思？
SDK 是官方幫你包好的「遙控器」，讓你用幾行 Python 就能呼叫 Claude，不用自己處理連線、重試、錯誤格式。
版本號從 0.x 跳到 1.0，就像遙控器換新款：按鈕更整齊，但有些舊按鈕被拆掉了。習慣按舊按鈕的程式，換上新遙控器後就會「按不下去」，也就是報錯。
發生什麼事
Anthropic 在 Claude API 更新日誌（8 月 20 日）宣布 Python SDK v1.0，GitHub 的發布時間是 8 月 20 日 19:58（UTC，台灣時間 8 月 21 日凌晨）。主要變化：
- 最低支援 Python 3.10（原本是 3.9）
- 底層換成 httpx2：原本用的 httpx 遷移指南形容為不再積極維護，httpx2 是 Pydantic 團隊維護、API 相容的分支
- 移除舊的 Text Completions API：
client.completions.create()不見了，一律用 Messages API - 移除取樣參數：Messages 相關方法不再接受
temperature、top_p、top_k，傳了會丟出TypeError - 非同步原始回應：
.with_raw_response的結果要await response.parse() - Bedrock 要指定區域：
AnthropicBedrock沒設區域會報錯，不再自動用 us-east-1
哪些程式會壞？
| 你的寫法 | 1.0 之後 |
|---|---|
| 只傳模型、訊息、timeout | 大多不用改 |
帶 temperature=0.2 |
報錯，要拿掉或改走 extra_body |
自己傳 httpx.Client 進去 |
建構時就報錯，改用 httpx2 |
| 用 OpenTelemetry、Sentry 追蹤請求 | 不報錯但默默抓不到，最容易漏 |
給開發者的技術細節
升級指令與舊模型的取樣參數寫法：
# pip install --upgrade "anthropic>=1,<2"
# 如果綁定的是仍支援取樣參數的舊模型
client.messages.create(
model="<舊模型名稱>",
max_tokens=1024,
messages=[{"role": "user", "content": "你好"}],
extra_body={"temperature": 0.2},
)
- 遷移指南建議跑一次 pyright 或 mypy，型別檢查器會幾乎把所有要改的地方標出來
- 用 Claude Code 的話，指南提供
/claude-api upgrade python指令讓它幫你改，再自己看 diff - 追蹤與模擬工具（respx、pytest-httpx、vcrpy 等）要在程式最前面呼叫
httpx2.alias_httpx() - 注意：目前 GitHub 上的遷移指南開頭已經在講後續的 v2，看文件時確認自己讀的是「0.x 升 v1」那一段
我的看法
這次最危險的不是會報錯的地方，而是不會報錯的地方。程式拋 TypeError 你一跑就知道；但追蹤工具默默抓不到 API 請求，可能要等到出事要查 log 才發現一片空白。
接案時我會建議：requirements.txt 或 pyproject.toml 一律把 SDK 鎖在明確範圍（例如先寫 anthropic<1 擋住大版本），排一個時間專門升級，升完確認監控面板還看得到請求，再上線。另外，temperature 被拿掉也提醒我們：AI 模型的參數會隨世代改變，程式裡寫死的「調參習慣」要定期檢查。
名詞小辭典
- SDK：官方提供的程式套件，把呼叫 API 的細節包好，讓開發者少寫很多程式碼。
- temperature：控制 AI 回答「隨機程度」的參數，數字越高越有變化。
- httpx：Python 常用的 HTTP 連線套件，SDK 靠它把請求送到伺服器。
- 型別檢查器：在執行前掃描程式碼、找出參數或型別寫錯的工具，例如 pyright、mypy。
資料來源
常見問題
為什麼連 temperature 都拿掉了？
遷移指南說明，目前的模型已經不使用這些取樣參數，所以從 SDK 方法的參數裡移除。如果你綁定的是還支援它們的舊模型，可以改用 extra_body 把參數原樣送出。
我只是用 client.messages.create 簡單呼叫，需要改嗎？
如果只傳一般值（模型、訊息、timeout 這類），而且沒有帶 temperature、top_p、top_k，大多不用改。要改的是自己傳 httpx 物件、用非同步原始回應、或用 Bedrock 沒設區域的程式。
升級後追蹤工具抓不到 API 請求怎麼辦？
OpenTelemetry、Sentry、respx 這類工具是修補 httpx 套件，而 SDK 已改用 httpx2，所以會默默抓不到。官方建議在程式最一開始呼叫 httpx2.alias_httpx()，讓 import httpx 指向 httpx2。
接著讀
全部觀點 →Claude API 推出「使用者檔案」：平台上一個客戶違規，不再拖累整個組織被封Anthropic 推出 Claude API 的 user profiles，讓平台與 API 轉售業者標出每個請求屬於哪個終端客戶。安全處分可以只落在單一客戶身上，不會整個組織一起被限制；同日也推出組織 webhooks（beta）。閱讀 →Claude Haiku 5.5 上線：10 萬 token 以內的請求比上一代便宜 9 成，平均省 75%Anthropic 推出小模型 Claude Haiku 5.5，主打大量、重複、要快的工作。短請求的價格只剩 Haiku 4.5 的一成，電腦操作測驗分數從 15.7% 跳到 72.4%，但舊程式碼直接換模型可能會報錯。閱讀 →Claude Sonnet 5.5 上線：價格不變、快取讀取砍半，官方說每項任務最多省 3 成Anthropic 發布 Claude Sonnet 5.5，輸入、輸出價格維持每百萬 token 2／10 美元，快取讀取降到 0.10 美元。官方說輸出速度快 30% 以上、每項任務最多便宜 30%，但從 Sonnet 5 升級有 5 個不相容變更要先處理。閱讀 →