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