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