OpenAI官方文檔確認(rèn)Assistants API將在2026年8月26日關(guān)閉。遷移并不是把threads.runs.create替換成responses.create就結(jié)束Assistant配置、Threads與Messages、Runs與Run steps、工具調(diào)用、文件資源以及權(quán)限和數(shù)據(jù)保留都需要逐項(xiàng)核對。本文給出對象映射、Python代碼對照和一套先切新會話、再按需回填歷史的上線方案。核驗(yàn)日期2026年8月24日。接口、SDK和遷移時(shí)間線可能繼續(xù)調(diào)整實(shí)施前請?jiān)俅尾榭碠penAI官方文檔。OpenAI已經(jīng)在官方遷移指南中明確Assistants API完成棄用并將在2026年8月26日關(guān)閉新集成應(yīng)轉(zhuǎn)向Responses API。如果項(xiàng)目中仍然出現(xiàn)下面這些調(diào)用現(xiàn)在需要處理的不是“以后有空再升級”而是確認(rèn)生產(chǎn)請求是否仍經(jīng)過舊接口client.beta.assistants.create(...)client.beta.threads.create(...)client.beta.threads.messages.create(...)client.beta.threads.runs.create(...)client.beta.threads.runs.retrieve(...)先澄清一個(gè)容易誤解的地方這次關(guān)閉針對開發(fā)者使用的Assistants API不等于ChatGPT網(wǎng)頁、普通聊天或ChatGPT Plus訂閱在8月26日關(guān)閉。一、為什么不能只替換一個(gè)接口名稱舊Assistants API把多種職責(zé)拆成了持久化對象Assistant保存模型、instructions和工具Thread保存會話Message保存消息Run在Thread上執(zhí)行AssistantRun step記錄執(zhí)行步驟文件、Vector Store和工具資源掛在Assistant或Thread周圍。Responses API的心智模型不同。官方遷移表給出的主要變化是舊對象新對象遷移時(shí)真正要處理的內(nèi)容AssistantsPrompts應(yīng)用配置模型、instructions、工具Schema、輸出格式和版本ThreadsConversations會話ID、用戶歸屬、metadata和歷史項(xiàng)目MessagesConversation items文本、圖片、工具調(diào)用與工具輸出的類型轉(zhuǎn)換RunsResponses請求執(zhí)行、狀態(tài)、錯(cuò)誤、輸出和用量Run stepsItems消息、工具調(diào)用、工具輸出不再只看Run step工具與文件重新配置File Search、函數(shù)調(diào)用、文件ID、Vector Store和權(quán)限所以真正的遷移對象不是一行代碼而是一整套狀態(tài)、配置、工具和權(quán)限模型。二、第一類先盤點(diǎn)Assistant里的配置每一個(gè)生產(chǎn)Assistant至少要導(dǎo)出或記錄這些字段assistant_id model instructions tools tool_resources response_format temperature / top_p metadata官方遷移指南將Assistants映射到Prompts可以在控制臺把Assistant配置創(chuàng)建為Prompt并通過Prompt ID在Responses請求中引用。但這里不能機(jī)械操作。當(dāng)前官方頁面同時(shí)提示可復(fù)用Prompt對象也有自己的棄用時(shí)間線。長期項(xiàng)目在采用Prompt ID前應(yīng)再次核對該時(shí)間線如果選擇由應(yīng)用代碼管理配置也要做好版本、審查和回滾不能只把一大段instructions散落在環(huán)境變量里。建議建立配置清單Assistant ID業(yè)務(wù)用途模型工具配置負(fù)責(zé)人新配置版本asst_xxx客服問答環(huán)境變量指定file_search、function后端Aprompt_xxx或Git版本遷移前先回答三個(gè)問題哪些Assistant仍有生產(chǎn)流量哪些只是測試對象可以直接停用哪些工具Schema和instructions已經(jīng)與線上代碼不一致三、第二類Threads和Messages不能自動整體搬家官方遷移指南明確說明不會提供把Threads自動遷移為Conversations的工具。推薦做法是讓新會話進(jìn)入Conversations舊Thread僅在確有需要時(shí)回填。這意味著數(shù)據(jù)庫至少需要暫時(shí)保留一張映射user_id / session_id old_thread_id new_conversation_id migration_status last_active_at不要在截止日前對所有歷史Thread做一次無差別全量搬遷。更穩(wěn)妥的順序是新建會話全部寫入Conversations最近仍活躍的用戶在首次訪問時(shí)按需回填長期不活躍歷史只保留必要索引和合規(guī)策略無業(yè)務(wù)價(jià)值或不應(yīng)繼續(xù)保存的數(shù)據(jù)按既定刪除規(guī)則處理。官方示例的核心轉(zhuǎn)換邏輯是按時(shí)間順序讀取舊Thread的Messages再轉(zhuǎn)換成Conversation items用戶文本映射為input_text助手文本映射為output_text圖片等內(nèi)容則按對應(yīng)item類型處理。遷移時(shí)最容易漏掉的不是純文本而是Message中的圖片與文件附件annotation和文件引用metadata工具調(diào)用及工具輸出一條消息中包含的多種content類型。如果代碼只復(fù)制message.content[0].text.value歷史會話很可能被截?cái)嗷騺G失結(jié)構(gòu)。四、第三類Runs和Run steps要改成Response與Items思維舊代碼通常是創(chuàng)建Run然后不斷輪詢importtime runclient.beta.threads.runs.create(thread_idthread_id,assistant_idassistant_id,)whilerun.statusin(queued,in_progress):time.sleep(1)runclient.beta.threads.runs.retrieve(thread_idthread_id,run_idrun.id,)Responses API可以直接接收輸入并把輸出作為items返回。下面是按照官方遷移示例壓縮后的基本結(jié)構(gòu)importosfromopenaiimportOpenAI clientOpenAI()conversationclient.conversations.create(items[{role:user,content:請檢查這段部署日志中的失敗原因,}],metadata{user_id:user_123},)responseclient.responses.create(modelos.environ[OPENAI_MODEL],conversationconversation.id,input[{role:user,content:請給出排查順序,}],)print(response.output_text)實(shí)際項(xiàng)目不能只確認(rèn)output_text能打印。還要覆蓋成功、失敗、不完整和取消狀態(tài)流式輸出與斷線重連超時(shí)與重試是否造成重復(fù)執(zhí)行token用量和請求ID是否繼續(xù)記錄原來依賴Run step的審計(jì)頁面如何改讀Items后臺任務(wù)是否需要background、webhook或其他異步機(jī)制。五、第四類函數(shù)調(diào)用的工具循環(huán)要由應(yīng)用顯式驗(yàn)收官方遷移指南強(qiáng)調(diào)Responses中的工具調(diào)用循環(huán)需要顯式管理。舊系統(tǒng)里如果只等待Run進(jìn)入requires_action再提交工具輸出遷移后必須重新檢查完整循環(huán)模型請求工具 → 應(yīng)用校驗(yàn)工具名和參數(shù) → 執(zhí)行業(yè)務(wù)函數(shù) → 保存冪等鍵和執(zhí)行結(jié)果 → 把工具輸出交回模型 → 獲取最終Response重點(diǎn)檢查四件事工具參數(shù)是否仍經(jīng)過Schema和業(yè)務(wù)權(quán)限校驗(yàn)同一個(gè)調(diào)用重試時(shí)會不會重復(fù)扣款、發(fā)消息或創(chuàng)建訂單工具輸出是否與正確的call ID關(guān)聯(lián)工具失敗時(shí)模型能否拿到明確、可恢復(fù)的錯(cuò)誤而不是無限重試。不要因?yàn)镽esponses API代碼更短就把原有的權(quán)限判斷、冪等控制和審計(jì)日志一起刪掉。六、第五類文件與Vector Store要單獨(dú)核對文件相關(guān)功能最容易被“聊天已經(jīng)通了”掩蓋。至少核對當(dāng)前項(xiàng)目中有哪些File ID和Vector Store ID哪些文件掛在Assistant哪些掛在Thread或工具資源新請求是否仍能檢索到相同資料文件引用和citation能否回到正確來源不同用戶能否錯(cuò)誤讀取彼此的文件歷史文件是否還需要保留。不要假設(shè)Thread遷成Conversation后所有附件和檢索資源會自動跟著遷移。先選一組包含PDF、圖片和多輪引用的真實(shí)樣本逐條驗(yàn)證召回內(nèi)容與引用位置。七、第六類權(quán)限、對象歸屬和數(shù)據(jù)保留要重新檢查OpenAI官方數(shù)據(jù)訪問說明提醒Assistants、Threads、Messages和Vector Stores按Project劃分擁有該P(yáng)roject API key的人可能讀取或修改其中對象。因此應(yīng)用仍應(yīng)在自己的數(shù)據(jù)庫中維護(hù)“哪個(gè)終端用戶可以訪問哪個(gè)對象ID”不能把拿到thread_id或conversation_id等同于已經(jīng)授權(quán)。遷移時(shí)至少檢查API key和Project成員是否最小權(quán)限用戶、Thread和Conversation的歸屬映射管理后臺是否可能越權(quán)查看其他用戶內(nèi)容日志中是否打印完整文件內(nèi)容、密鑰或隱私數(shù)據(jù)刪除流程是否同時(shí)覆蓋應(yīng)用數(shù)據(jù)庫和OpenAI對象。數(shù)據(jù)保留規(guī)則也不能沿用想象。OpenAI當(dāng)前數(shù)據(jù)控制文檔顯示Responses API的應(yīng)用狀態(tài)默認(rèn)有30天保留期Assistants相關(guān)對象如果沒有通過API或控制臺刪除可能持續(xù)保留Assistants相關(guān)對象刪除后官方說明為30天后從服務(wù)器刪除。是否使用store、后臺模式或特定數(shù)據(jù)控制方案會影響實(shí)際行為。遷移上線前應(yīng)按組織當(dāng)前配置再次核對不能把“接口關(guān)閉”誤解成“歷史對象會自動立即清空”。八、推薦的上線順序先切新會話再遷活躍歷史在只剩兩天的情況下優(yōu)先級應(yīng)是降低生產(chǎn)中斷而不是一次完成所有歷史清理。階段1當(dāng)天完成清點(diǎn)搜索代碼中的beta.assistants、beta.threads和runs列出生產(chǎn)Assistant、工具、文件資源和負(fù)責(zé)人確認(rèn)哪些入口仍在創(chuàng)建新Thread為舊ID到新ID建立映射字段。階段2讓新會話進(jìn)入Responses新用戶和新會話走ConversationsResponses舊路徑保留短期回退開關(guān)但不再擴(kuò)展功能同一組輸入同時(shí)跑舊、新路徑比較答案、工具調(diào)用和用量。階段3按需回填活躍歷史優(yōu)先遷移最近活躍且確實(shí)依賴歷史的Thread轉(zhuǎn)換所有content類型而不是只復(fù)制第一段文本記錄回填狀態(tài)失敗可重試且不能重復(fù)插入。階段4驗(yàn)收與收尾關(guān)閉舊接口入口保留可審計(jì)的遷移清單按數(shù)據(jù)政策刪除不再需要的舊對象在8月26日前做一次生產(chǎn)流量和錯(cuò)誤率確認(rèn)。九、上線前最小驗(yàn)收表檢查項(xiàng)通過標(biāo)準(zhǔn)新會話不再創(chuàng)建Thread能夠持續(xù)寫入Conversation普通回復(fù)文本、結(jié)構(gòu)化輸出和流式結(jié)果正常工具調(diào)用參數(shù)校驗(yàn)、權(quán)限、冪等和失敗回傳正常文件檢索召回內(nèi)容、文件引用和用戶隔離正確歷史會話活躍Thread能按需回填順序與角色不亂監(jiān)控錯(cuò)誤率、延遲、用量、請求ID和工具失敗可追蹤回退新路徑異常時(shí)有受控回退不產(chǎn)生雙寫臟數(shù)據(jù)數(shù)據(jù)保留、刪除、日志脫敏和對象授權(quán)符合現(xiàn)有政策十、幾個(gè)常見問題1. 8月26日后ChatGPT Plus還能正常使用嗎這次通知針對Assistants API。不要把開發(fā)者接口關(guān)閉擴(kuò)寫成ChatGPT網(wǎng)頁或Plus訂閱關(guān)閉。2. 只使用Chat Completions API需要遷移嗎本次關(guān)閉對象是Assistants API。如果代碼沒有創(chuàng)建Assistant、Thread或Run不能僅憑這則通知判斷必須遷移但新Agent類集成可以單獨(dú)評估Responses API。3. Threads會自動變成Conversations嗎不會。官方遷移指南明確表示不會提供自動遷移工具建議新會話先切換舊會話按需回填。4. 舊Thread里的文件會自動進(jìn)入Conversation嗎不要這樣假設(shè)。消息內(nèi)容、附件、文件資源和檢索配置需要分別清點(diǎn)和驗(yàn)證。5. 遷移后還需要輪詢嗎不能簡單回答“完全不需要”。普通Response可以直接返回結(jié)果但流式、后臺任務(wù)、工具循環(huán)和長任務(wù)仍要按實(shí)際模式設(shè)計(jì)狀態(tài)、重試和通知機(jī)制。結(jié)語Assistants API遷移最危險(xiǎn)的誤區(qū)是把它當(dāng)成一次SDK方法改名。真正需要核對的是六類對象Assistant配置、Threads與Messages、Runs與Run steps、工具調(diào)用、文件資源、權(quán)限與數(shù)據(jù)保留。距離8月26日只剩很短時(shí)間時(shí)最穩(wěn)妥的策略不是全量搬歷史而是先讓新會話切到ConversationsResponses再按業(yè)務(wù)價(jià)值遷移活躍歷史最后清理舊對象。這樣既能先降低停機(jī)風(fēng)險(xiǎn)也能避免在倉促全量遷移中丟失消息結(jié)構(gòu)、工具記錄和用戶權(quán)限。官方資料OpenAIAssistants API遷移指南OpenAIAssistants API deep diveOpenAI數(shù)據(jù)控制與端點(diǎn)保留規(guī)則