--- schemaVersion: 1 slug: mp-303-20260528-openai-gpt-5-5-api-migration-checklist ticketId: MP-303 lang: zh-tw title: GPT-5.5 不是換 model slug 就好：OpenAI 把 migration 清單藏在 API 文件裡 summary: OpenAI 的 GPT-5.5 latest-model 文件把重點從 prompt 寫法推到整個 API orchestration：reasoning effort、verbosity、image detail、phase replay、prompt caching、tool search 和 compaction 都要重調。GP-189 已經拆過 prompting，這篇補上工程端的 migration checklist。 originalDate: 2026-05-28 translatedDate: 2026-05-28 source: OpenAI Developers sourceUrl: https://developers.openai.com/api/docs/guides/latest-model author: null authorshipNote: null canonicalUrl: https://gu-log.vercel.app/posts/mp-303-20260528-openai-gpt-5-5-api-migration-checklist status: published replacementTicketId: null replacementUrl: null --- # GPT-5.5 不是換 model slug 就好：OpenAI 把 migration 清單藏在 API 文件裡 > **來源:** [OpenAI Developers](https://developers.openai.com/api/docs/guides/latest-model) 工程團隊最容易低估的模型升級，不是 benchmark 多幾分，而是「只改一行 model slug」之後整套產品行為開始歪掉。 OpenAI 的 GPT-5.5 最新模型文件表面上像版本說明，實際上是一張遷移清單：prompt 要重寫，API 參數要重調，工具描述要整理，長任務的狀態重播也要檢查。這不是換引擎，是整台車的油門、方向盤、煞車手感都換了。 [GP-189](https://gu-log.vercel.app/posts/gp-189-20260430-openai-gpt-5-5-prompting-guide/) 已經拆過 GPT-5.5 prompting 的主線：描述目的地，不要畫地圖。這份新文件補上的，是更工程端的版本：光會寫 prompt 不夠，整個編排層也要跟著升級。 > **Mogu 內心戲：** > > 「換 model slug」聽起來像把手機商店的更新按下去。實際比較像把手排車換成電動車，方向盤還在、輪胎還在，但油門一踩下去的反應完全不同。工程師如果只確認 API 沒噴 500，就宣布遷移成功，那跟開出停車場才發現煞車踏板位置不一樣差不多 (¬‿¬) --- ## 第一個坑：推理力道預設變成 `medium` GPT-5.5 的 `reasoning.effort` 預設是 `medium`。OpenAI 把它定義成品質、可靠度、延遲、成本之間的平衡點。 這句話看起來溫和，對 production 來說很硬：以前某些 workflow 可能靠預設值剛好跑得快，升到 GPT-5.5 後，預設 reasoning 力道變成中等，延遲跟 token 消耗都可能改變。 OpenAI 給的建議也很明確： - `low`：有效率的推理，很多工作負載其實夠用 - `medium`：預設平衡點 - `high`：複雜 agent 任務，延遲比較不敏感時使用 - `xhigh`：最難的非同步 agent 任務或智力邊界測試 - `none`：只留給真正延遲極敏感、又不需要多步推理的任務 最重要的是那句反直覺提醒：更高推理力道不一定更好。如果任務本身有衝突指令、停止條件不清楚、工具權限太開，推理力道拉高只會讓模型更認真地繞遠路。 --- ## 第二個坑：省 token 不是靠更笨，是靠更會收手 OpenAI 說 GPT-5.5 在同樣推理力道下，用更少推理 token 就能達到強結果。這對工具密集流程很重要，因為每一輪工具呼叫、省下的不是一點點文字，而是整段規劃、搜尋、重試的成本。 但省 token 的前提不是把模型調笨，而是讓系統講清楚「什麼時候該收手」。文件反覆提到成功條件、允許的副作用、證據規則、輸出形狀、停止規則。這些東西不是 prompt 裝飾，是 agent 的煞車皮。 沒有煞車皮的高 reasoning agent，很容易變成勤奮版迷路。它不是懶，它是在錯誤的迷宮裡全力奔跑。 > **Mogu 碎碎念：** > > 這裡跟 GP-189 的「不要畫地圖」不是矛盾，而是上下半場。不要畫每一步路線，但要告訴模型目的地、邊界、什麼狀況算到站。少了目的地叫放生，少了邊界叫災難，少了 stopping condition 叫帳單爆炸。 --- ## 第三個坑：多模態跟工具層也一起變了 這份文件最像檢查清單的地方，是它把一堆容易被忽略的 API 旋鈕排在一起。 `image_detail=auto` 的預設行為變了。GPT-5.5 會保留更多視覺細節，用來改善圖片輸入和電腦操作表現；`low` 則更積極壓縮到 512 像素維度上限。也就是說，同一張截圖在不同細節設定下，成本和可見細節都會不同。 `text.verbosity` 也要重新評估。GPT-5.5 預設更直接、更任務導向，客服或對話產品可能需要明確補個性、溫度、理由；工具型產品反而可能該把 輸出詳略程度壓到 `low`，避免狀態更新變成小作文。 還有 Responses API 的老朋友：`phase`、preamble、assistant item replay。OpenAI 特別提醒，如果應用端不用 `previous_response_id`，而是手動把 assistant output items 傳回下一輪，`phase` 必須原封不動保留。漏掉這個欄位，模型可能把中間進度當最終答案，或把最終答案當成還沒講完。 這些東西加起來，結論很殘酷：GPT-5.5 migration 不是 prompt engineer 一個人的工作。產品、後端、agent harness、UX 都有份。 --- ## 第四個坑：工具清單不是越大越威，是越準越威 GPT-5.5 繼續支援 GPT-5.4 的工具呼叫模式，但 OpenAI 建議把大部分工具規則放進工具描述：工具做什麼、什麼時候用、需要哪些輸入、有什麼副作用、能不能重試、常見錯誤是什麼。 這跟 gu-log 一直在講的 agent 整理原則是同一件事。System prompt 不該變成工具說明書垃圾場。工具本身要像好用的電器標籤：插頭在哪、按鈕幹嘛、危險區在哪，寫在機器旁邊，不要貼在冰箱門上。 OpenAI 也順手推了託管工具和 tool search。大型工具目錄不要一次全部塞進 context，能延後載入就延後載入；適合 OpenAI 託管工具的場景，就用網頁搜尋、檔案搜尋、程式碼直譯器、圖片生成、電腦操作這些內建能力，少維護一層自製膠水。 最後一個很實用的小點：prompt 快取要把穩定前綴放前面、動態使用者 context 放後面；大量相似流量用 `prompt_cache_key` 穩定路由，並追蹤 `usage.prompt_tokens_details.cached_tokens`。這不是寫作技巧，是帳單工程。 --- ## 結語 GP-189 的結論是：GPT-5.5 逼 prompt 從「流程清單」改成「結果契約」。這份最新模型文件補上的後半句是：結果契約寫完，API 編排也要跟著對齊。 真正的 GPT-5.5 遷移清單不是「model 改成 `gpt-5.5`」。比較像：推理力道有沒有重測、輸出詳略程度有沒有重配、圖片細節有沒有算成本、phase 重播有沒有保住、工具描述有沒有清乾淨、快取前綴有沒有穩定、長時間 agent 有沒有壓縮狀態。 模型升級越來越不像換一顆腦，越來越像換一個同事。履歷更漂亮，但新人訓練文件還是要重寫。