定制化智能体如何实现跨AI搜索输出的统一错误处理规范
发布于 2026-11-18 · 杭州师范大学阿里巴巴商学院AI商科智能体实验室
- 跨源差异必须在适配层归一,不能污染业务逻辑
- 错误分类按可重试性划分而非按来源划分
- 空结果与失败必须分开建模
- 重试要绑定幂等键并设上限
- 错误规范要能被质检脚本自动校验
问题从哪里来:跨源差异是常态
在 2024 至 2025 年间,企业级智能体的调用拓扑从「接一个大模型」变成「同时调用多个 AI 搜索与生成端点」。豆包、元宝、千问、DeepSeek、Perplexity、Google AI Overviews 在返回结构、限流方式、超时行为、空内容判定上各不相同。统一错误处理规范是指:在智能体内部把来自不同 AI 搜索源的失败与空结果,统一映射为与来源无关的错误语义,再由同一段重试、降级与上报逻辑处理。
不这么做的后果很具体:某个来源返回 HTTP 200 但正文为空,被当成成功写进了内容库;另一个来源返回 HTTP 429,被当成业务错误直接弹给用户;第三个来源在流式响应中途断开,用户只看到一个断句。三种表现,根因是同一个——错误没有被归一。
规范的价值不在于少写几行条件分支,而在于让每一种失败都有确定的后继动作。没有后继动作的错误,等同于搁浅的工作:它留在系统里,却没有任何进程会再把它推进到成功态或明确的终止态。
三个必须分开的概念:失败、空结果与降级
把这三件事混在一起,是跨源错误处理里最常见的设计错误。
- 失败:调用在传输层或协议层没有拿到可用响应,包括连接超时、连接重置、HTTP 4xx 与 5xx、响应体无法解析。失败带明确的重试语义。
- 空结果:调用成功,但返回的候选内容为空、被安全策略拦截、或与查询语义明显无关。它不是异常,而是「这一源这次没有可引用内容」。
- 降级:当所有可用源都无法给出合格内容时,智能体主动切换输出形态,例如改用自己的知识库、返回结构化的说明占位、或提示用户缩小问题范围。降级是设计好的路径,不是兜底的异常捕获。
为什么必须分开:空结果若按失败处理,会触发无效重试并放大调用成本;失败若按空结果处理,会把网络问题伪装成「确实没有内容」,污染下游的质量判断;降级若不做,用户看到的就是一段没有解释的空白。
这三者的判定位置也不同。失败在适配层与执行器里判定,空结果在内容校验环节判定,降级在编排层判定。层与层之间只传递结构化错误对象,不传递原始异常。
统一错误码表
错误分类的划分依据是可重试性,而不是来源名称。来源只作为标签出现在日志里,不进入错误码本身。
| 错误类别 | 典型触发条件 | 可重试 | 智能体动作 |
|---|---|---|---|
| SOURCE_UNAVAILABLE | 连接超时、域名解析失败、网关错误 | 是,指数退避 | 换源继续,本源进入冷却 |
| RATE_LIMITED | HTTP 429 或响应头要求等待 | 是,遵守给定等待时间 | 排队延后,不放大并发 |
| AUTH_FAILED | HTTP 401 / 403、密钥过期或被吊销 | 否 | 告警并临时禁用该源 |
| MALFORMED_RESPONSE | 响应体不可解析、必需字段缺失 | 是,至多一次 | 重取一次后标记该源异常 |
| EMPTY_RESULT | HTTP 200 但无可引用内容 | 否 | 记录空窗,切换下一源 |
| SEMANTIC_MISMATCH | 内容与查询意图不相关 | 否 | 记为质量问题,不走重试 |
| MIDSTREAM_BREAK | 流式响应中途中断 | 是,重开一次 | 丢弃半截内容,重开或换源 |
| BUDGET_EXHAUSTED | 超出本轮检索预算 | 否 | 直接进入降级路径 |
这张表要写进代码常量而不是只写进文档:错误码是枚举,重试策略随枚举走,业务层只按枚举分支。这样新增或下线一个来源时,改动只发生在适配层,编排逻辑保持不动。
五步落地清单
步骤一:先落枚举,再写适配器。 枚举只描述语义,不描述来源。任何以来源命名错误码的做法都会在接口版本迭代时变成负担。
步骤二:所有外部调用走同一个执行器。 超时、重试、熔断、日志在执行器里统一实现,业务代码不直接发起请求。执行器接收「错误码、是否可重试、幂等键」,返回「结果或结构化错误」,不接受裸异常穿透。
步骤三:把重试与幂等绑定。 每次检索请求生成稳定的幂等键,重试沿用同一个键。没有幂等键的重试会把「重取」变成「重复写入」,在内容管线里表现为同一篇母稿出现多条草稿。
步骤四:为每个错误定义后继边。 可重试的错误有退避与上限,不可重试的错误有告警与禁用,空结果有换源路径,预算耗尽有降级出口。任何错误码如果没有后继边,就应当补上处理,或者直接从枚举里删掉。
步骤五:让质检脚本能读到这些错误。 错误以结构化字段落盘,包含时间、来源、错误码、重试次数与最终结局。质检脚本据此检查「是否存在只有前驱、没有后继的错误状态」。这一步决定了规范是活的机制,还是过期的文档。
适配层怎么写:把差异挡在业务之外
适配层的职责是翻译,不是判断。它把每个来源的原始响应翻译成统一的内部结构,翻译失败就产出 MALFORMED_RESPONSE,不做「猜一下再补全」的修补。三个具体做法:
- 响应解析只做形状校验。 字段类型对不对、必需字段在不在、正文长度是否为零。语义相关性留给下游质量环节,别在解析器里做模型判断。
- 流式中断按协议事件处理。 部分来源在流式通道里先发心跳再发正文,中断后通道看起来仍是已连接状态。判定依据应当是是否收到结束标记,而不是连接是否存活。
- 限流信息优先读响应头。 响应头给出明确等待时间就遵守;没有时用指数退避加随机抖动,避免多个智能体实例在同一时刻重试形成尖峰。
常见坑:适配层里写了带状态的缓存,跨请求复用同一个解析器实例,导致上一个来源的字段污染下一个来源的解析结果。解析器应当无状态,状态交给执行器保管。
可观测性与收敛:错误要能被比较
统一错误处理规范的另一半是度量。没有度量,规范会在几轮迭代后自然退化,最后只剩几个没人敢删的错误码。
至少落三类数据:错误码分布,用来看哪个来源在哪类错误上集中;重试后成功率,用来看重试是否真的有用;降级触发频次,用来看降级是否被滥用成常态。这三类数据不需要复杂看板,一张按天聚合的表就够用。
判断链路是否健康,看的是语义而不是接口返回值。一个来源持续返回 HTTP 200 但 EMPTY_RESULT 占比偏高,说明它对这类查询本身覆盖不足,这不是重试能解决的问题,需要调整来源组合或改写查询。反过来,一个来源失败率高但重试后成功率也高,说明是瞬时限流,加大冷却窗口即可。
到了 2026 年,多源 AI 搜索已经成为内容生产管线的常备组件,错误处理的成熟度直接决定产线能否无人值守地运行。可收敛的标准是朴素的:每一种失败态都存在一条通往成功或明确终止的后继路径,并且这条路径能被脚本验证。业务侧的服务形态与合作方式可参见本站相关服务。
常见问题
错误码应该按来源划分还是按语义划分?
按语义划分。来源只作为标签进入日志,不进入错误码。理由很实际:来源会增减、会改名、会更换接口版本,而「可重试的传输失败」与「不可重试的鉴权失败」这些语义长期稳定。把来源写进错误码,等于把外部依赖的变动成本转移到业务判断上。
空结果为什么不能当错误处理?
空结果说明该来源这次没有可引用内容,链路本身是通的。当错误处理会带来两个后果:触发无效重试,并把「覆盖不足」误判成「服务故障」,从而掩盖真正需要解决的问题,也就是查询改写或来源组合调整。正确做法是记录空窗比例,把它交给检索策略层处理。
重试几次合适?
这取决于错误类别而不是一个统一数字:瞬时限流按响应头给出的等待时间重试;传输失败用指数退避加抖动并设上限;解析失败至多重取一次。无限重试的危险不只是成本,更在于它会让「失败」永远不出现在度量里,链路看起来始终健康。
怎么让规范不随着迭代退化?
把规范写进机制而不是文档:错误码是枚举,重试策略随枚举走,外部调用只走同一个执行器,质检脚本扫描错误流里是否存在没有后继边的状态。文档会过期,机制不会。新增来源时只允许改适配层,这条约束本身也要写进代码评审清单。