大模型接口怎樣約定減少返工大模型接入早期接口常常長得像模型控制臺前端傳prompt、temperature和模型名服務(wù)端原樣轉(zhuǎn)發(fā)。原型階段很快但它把本應(yīng)由服務(wù)端負(fù)責(zé)的提示詞、權(quán)限和輸出約束散到了多個客戶端。以后想改提示詞、替換供應(yīng)商或統(tǒng)一修正一類錯誤輸出就得同時改 Web、移動端和各個 SDK。接口最好描述用戶想完成的事而不是描述底層模型怎樣工作。比如“為某份已授權(quán)文檔生成簡要摘要”可以包含文檔標(biāo)識、目標(biāo)語言和摘要長度文檔內(nèi)容、系統(tǒng)提示詞、模型路由和采樣參數(shù)由服務(wù)端處理。這樣并不意味著 API 要把所有細(xì)節(jié)藏起來。調(diào)用方仍需要知道輸出的格式、權(quán)限要求、可能的錯誤和資源限制只是這些約定應(yīng)該穩(wěn)定且可測試。先把輸入、輸出和副作用寫清楚設(shè)計接口前先回答幾個樸素的問題請求引用的是哪份數(shù)據(jù)服務(wù)端是否有權(quán)讀取它結(jié)果是臨時展示還是要保存失敗后能否重試。摘要、問答、結(jié)構(gòu)化抽取和代碼生成的風(fēng)險不同沒必要硬塞進(jìn)一個“萬能 chat”接口。以摘要為例調(diào)用方可以提交文檔 ID 和一個受限的展示選項。服務(wù)端讀取文檔時要再次進(jìn)行授權(quán)校驗而不能因為客戶端傳來了 ID 就默認(rèn)可見。輸出若聲明為 JSON就應(yīng)明確字段、未知字段的處理方式以及模型沒能滿足格式時服務(wù)端返回什么。把這些合同寫在 OpenAPI、類型定義和集成測試?yán)锉仍跁h上口頭約定可靠得多。{ document_id: doc_123, length: brief, locale: zh-CN }服務(wù)端可以據(jù)此選擇提示詞和模型但不要把內(nèi)部提示詞當(dāng)作接口合同。提示詞變化后真正要保持的是返回結(jié)構(gòu)、錯誤語義和權(quán)限邊界。流式響應(yīng)要區(qū)分“展示進(jìn)度”和“任務(wù)結(jié)果”SSE 很適合把逐步生成的內(nèi)容送到頁面但網(wǎng)絡(luò)連接不是可靠的任務(wù)存儲。斷線時客戶端需要知道自己訂閱的是哪個生成任務(wù)、已經(jīng)收到哪個事件服務(wù)端則需要判斷任務(wù)是否仍在運行、能否重放以及重連者是否仍有權(quán)限讀取結(jié)果。一個事件可以帶任務(wù) ID、單調(diào)遞增序號和事件類型id: 14 event: delta data: {request_id:req_9f2,text:這一段摘要}這里的id可以配合Last-Event-ID做有限重放但不能憑空保證內(nèi)容永不重復(fù)或絕不丟失。前端應(yīng)按序號去重并能顯示“連接已斷開”后端應(yīng)設(shè)置保留窗口和最大緩沖量。對需要最終結(jié)果的場景更穩(wěn)妥的方式是把任務(wù)狀態(tài)和最終產(chǎn)物保存下來SSE 只負(fù)責(zé)通知進(jìn)度重連后再查詢?nèi)蝿?wù)詳情。錯誤別偽裝成正常文本模型超時、上游限流、內(nèi)容讀取失敗和安全策略拒絕應(yīng)該有能區(qū)分的錯誤碼或事件類型。把“抱歉系統(tǒng)繁忙”混在生成文本中會讓客戶端無法決定是否重試也讓監(jiān)控失去意義。對于可重試的錯誤返回建議等待時間或重試標(biāo)識對于不可重試的權(quán)限錯誤不要泄露文檔是否存在。還要明確取消語義。用戶關(guān)閉頁面不一定代表服務(wù)端必須立刻停止任務(wù)反之也不應(yīng)讓無人消費的長任務(wù)無限運行?？梢杂煽蛻舳孙@式取消由服務(wù)端根據(jù)隊列、預(yù)算和任務(wù)類型決定是否終止并把最終狀態(tài)記錄下來。版本只解決兼容不解決含糊路徑中的/v1能讓破壞性變更有出口但接口頻繁升級往往是因為最初的語義不清。字段新增是否兼容、枚舉值是否允許擴展、空值和缺失是否不同、模型輸出無法解析時怎么辦都應(yīng)在首個版本里說明。底層模型切換也不應(yīng)自動等于降級。備用模型可能不支持同樣的語言、工具或結(jié)構(gòu)化輸出路由前要檢查能力與數(shù)據(jù)處理要求。如果不能滿足合同寧可返回明確失敗或排隊狀態(tài)也不要靜默給用戶一份看似成功、實際不符合約定的結(jié)果。減少返工靠的不是把接口做得抽象而是讓業(yè)務(wù)語義、錯誤處理和演進(jìn)規(guī)則有清楚的邊界。模型適配留在服務(wù)端客戶端依賴穩(wěn)定合同雙方改動才不會總是綁在一起。