大模型接口怎样约定减少返工

大模型接口怎样约定减少返工大模型接入早期接口常常长得像模型控制台前端传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能让破坏性变更有出口但接口频繁升级往往是因为最初的语义不清。字段新增是否兼容、枚举值是否允许扩展、空值和缺失是否不同、模型输出无法解析时怎么办都应在首个版本里说明。底层模型切换也不应自动等于降级。备用模型可能不支持同样的语言、工具或结构化输出路由前要检查能力与数据处理要求。如果不能满足合同宁可返回明确失败或排队状态也不要静默给用户一份看似成功、实际不符合约定的结果。减少返工靠的不是把接口做得抽象而是让业务语义、错误处理和演进规则有清楚的边界。模型适配留在服务端客户端依赖稳定合同双方改动才不会总是绑在一起。