跳到主要内容

第 1.3.3 节：用模型适配层统一请求、响应和错误处理

模型适配层统一请求、响应和错误只有拆成可执行步骤，才容易复核、排错和交接。完成本节后，你应该能够按顺序说明模型适配层统一请求、响应和错误的触发、处理、复核、记录和兜底步骤。

实现步骤或决策流程​

客服工作台模型底座如何落地​

客服工作台里的模型底座可以按“输入、上下文、调用、输出、日志、兜底”六件事落地。

环节落地动作为什么重要
输入标准化用户问题、会话编号、用户身份和业务入口后续才能判断权限、上下文和追踪链路。
上下文只放当前任务需要的会话摘要、知识片段和工具结果摘要控制 Token（文本计量单位）、成本和回答稳定性。
调用通过模型适配层选择 Mock（模拟）或真实供应商学习、测试和交付环境可以分开。
输出校验文本、结构化结果或工具意图防止无效输出进入业务动作。
日志记录 trace_id（追踪编号）、耗时、Token（文本计量单位）、模型名和错误方便成本复盘、故障排查和面试说明。
兜底超时、限流、格式错误、无依据时进入重试、降级或人工用户不会看到模型编造的业务结果。

这套落地方式会贯穿后续章节。第 1.4 章会把输出变成字段契约，第 1.5 章会把模型调用放进第一个 Agent（智能体），第 1.6 章会把工具结果重新送回模型解释。

Responses API（响应接口）、Chat Completions（聊天补全接口）和 Agents SDK（智能体软件开发工具包）​

新项目要理解三个层次：

层次定位适合场景
Chat Completions（聊天补全接口）对话消息生成接口兼容旧项目、简单聊天
Responses API（响应接口）面向多模态、工具和状态化交互的统一接口新项目的模型调用底座
Agents SDK（智能体软件开发工具包）构建 Agent 应用的 SDK（软件开发工具包）工具、上下文、Handoff（任务转交）、Tracing（调用链追踪）等

本书后续会优先使用新项目更适合的方式讲解，但也会说明旧项目迁移和多模型适配的边界。

模型调用的最小流程​

这个流程里，模型只是系统的一部分。真正的工程质量来自应用后端对上下文、工具、错误和日志的控制。

读图重点：模型与工具之间没有直连，所有上下文、执行、校验和展示责任都由应用后端掌握。

Mock（模拟）模式和 Real Provider（真实模型供应商）模式​

配套项目先以制作说明呈现，但从设计上必须保留两种运行模式。

Mock（模拟）模式​

Mock（模拟）模式不调用真实模型。它可以根据固定规则返回结果。

适合：

  • 学习者无 API Key（接口密钥）时运行流程。
  • 自动化测试。
  • CI（持续集成）检查。
  • 演示系统结构。

Real Provider（真实模型供应商）模式​

Real Provider（真实模型供应商）模式读取环境变量，调用 OpenAI（模型服务商）、DeepSeek（深度求索模型）、Qwen（通义千问模型）、智谱、Claude（模型产品）、Gemini（模型产品）或本地模型服务。

适合：

  • 真实效果验证。
  • 客户试点。
  • 性能和成本评估。
  • 商业部署。

为什么必须同时支持​

如果只有 Real Provider（真实模型供应商）模式，学习者可能因为网络、额度、模型更新或 Key（密钥）配置失败而跑不通。如果只有 Mock（模拟）模式，又无法验证真实效果。

所以本书的项目设计统一采用：

配置项含义示例口径
APP_MODE（应用运行模式）决定使用 Mock（模拟）模式还是真实模型模式mock 或 real
MODEL_PROVIDER（模型供应商）指定模型服务来源openai、deepseek、qwen 等
MODEL_NAME（模型名称）指定具体模型只写名称，不写密钥

真实值放在 .env，模板放在 .env.example。

最小模型适配层​

商业项目不要把业务代码写死在某一家 SDK（软件开发工具包）上。可以先设计一个很薄的模型适配层。

模型适配契约说明​

本节只说明制作方法，不展开代码语法。进入真实项目开发时，要把本节的输入、输出、日志和验收规则落实到项目结构中。

环节需要明确的内容验收方式
请求进入用户问题、身份、业务对象和会话编号能复现同一次请求
智能体处理角色、提示词、工具、资料范围和停止条件典型任务能稳定走完
工具调用工具名称、权限、输入字段和失败处理高风险工具需人工确认
结果返回答案、依据、风险、下一步动作和拒答原因前端和业务人员能理解
运行记录追踪编号、耗时、模型调用、工具结果和人工确认问题能追溯和复盘

这个例子不追求完整，只表达一个原则：业务代码依赖自己的接口，具体模型供应商放在适配层里。

项目实现说明可以把文本生成、结构化输出、工具调用和流式响应拆得更细。

推荐技术流：模型调用从可跑到可交付​

步骤做什么为什么
1定义模型调用场景不同场景的成本、延迟和质量要求不同。
2设计输入上下文防止把无关历史和过期资料塞进模型。
3估算 Token（文本计量单位）预算让成本和延迟在可控范围内。
4设计 Mock（模拟）模式让学习、测试和演示不依赖真实密钥。
5设计真实供应商配置让系统可以接 OpenAI（模型服务商）、DeepSeek（深度求索模型）或其他供应商。
6封装模型适配层业务代码不直接依赖某一家 SDK（软件开发工具包）。
7校验输出和错误不把异常模型结果直接交给业务流程。
8记录调用日志方便追踪成本、耗时、错误和质量问题。
9设置降级策略供应商异常时能提示、重试或切换模式。
10用验收样例验证证明典型客服问题能稳定处理。

这条技术流的核心理由是：模型调用不是一次性请求，而是一个外部服务接入工程。

模型请求与响应字段契约​

字段说明客服工作台示例风险控制
trace_id（追踪编号）串联一次模型调用和业务处理一次售后咨询的唯一编号日志必须保留，便于复盘。
user_message（用户消息）用户原始问题我的订单为什么还没发货？需要过滤明显恶意输入。
task_type（任务类型）本次调用目的意图识别、答案生成、工具结果总结不同任务使用不同 Prompt（提示词）。
context_pack（上下文包）进入模型的资料集合售后政策片段、会话摘要、工具结果摘要控制长度和权限。
model_profile（模型配置）供应商、模型、模式和温度等选择mock、openai、qwen 等不暴露密钥。
output_contract（输出契约）期望模型返回的字段意图、风险等级、是否需要工具、回复草稿失败时进入重试或降级。
usage_record（用量记录）Token（文本计量单位）、耗时、错误输入 1500，输出 300，耗时 2 秒用于成本和性能分析。

版本与资料来源​

具体 API（应用程序接口）参数和 SDK（软件开发工具包）用法以后续章节及官方文档为准。

主要资料入口：

过时风险：模型名称、上下文窗口、价格和 API 参数变化较快。写作和发布前应再次核对官方文档。

继续学习​