企业知识库问答 API 上线后，最让人头疼的往往不是接不通，而是“能通，但答得不对”。报错和答非所问的排查路径完全不同，混在一起查只会越查越乱。

这篇清单把两类问题拆开讲：一类是接口层的失败，通常有明确状态码可循；另一类是回答质量层的偏差，日志里一切正常，用户却觉得答非所问。前者靠链路定位，后者靠检索质量校验。下面按排查顺序逐层展开，并说明每一步该看什么、怎么记录、以及哪些配置必须以控制台实际显示为准。

一、先分类：接口报错与答非所问是两条排查线

企业知识库问答 API 的完整链路通常是这样：文档解析与切片 → 向量化入库 → 检索（向量或混合）→ 重排 → 拼接提示词 → 调用大模型 → 返回答案。报错多发生在链路两端，也就是鉴权、请求格式和模型调用环节；答非所问则集中在中段，也就是检索、重排和提示词拼装环节。

分类的意义在于节省时间。如果用户反馈“答案不对”，而你先去翻模型供应商的状态页，很可能是白费功夫；如果接口直接返回 401，你也完全不需要去调整切片长度。先问一句“是请求失败，还是请求成功但内容不对”，排查效率会立刻不同。

经验上，超过一半的“答非所问”投诉，本质是检索阶段没有把包含正确答案的片段召回出来，模型只是忠实地根据错误证据作答。

二、接口报错：按状态码和链路顺序定位

1. 高频报错与对应检查点

下面这张表按“排查项—典型表现—常见原因—检查方法”整理，适合直接贴到团队内部的排障文档里。注意不同平台的错误码语义可能略有差异，最终仍以你所接入平台文档中的说明为准。

2. 容易被忽略的三类“非报错异常”

• 流式返回中途截断：常见的 SSE 输出在中间断流，表面没有报错，答案却缺了后半段。检查反向代理的缓冲设置和超时时间。
• 超时被误判为模型慢：很多超时其实发生在检索或重排阶段，尤其是知识库文档量较大时，先看各阶段耗时再下结论。
• 环境不一致：测试环境用一套 Key 和模型名，生产环境换了配置却没同步，导致上线后行为与测试结果不同。

如果团队同时接入了多家模型厂商，配置管理本身就是风险来源。把接口地址、Key、模型名称分散在多个环境变量里，很容易出现串用。像 通联AI中转站 这类 AI 聚合平台提供统一 API Key 管理和一个 Base URL 接入多模型的思路，在需要横向对比不同模型回答质量时，可以减少配置漂移带来的排查干扰。具体支持哪些协议和模型名称，以控制台页面和文档展示的信息为准。

三、答非所问：五步定位法

识别答非所问，第一步不是换模型，而是把中间结果打出来。建议在服务端记录每一次请求的检索片段、相似度分数和最终拼进提示词的内容，这样问题出在哪一层一目了然。

1. 看召回：检索返回的片段里，是否包含能回答问题的原始内容。如果压根没召回，后面再怎么调都无意义。
2. 看排序：正确片段召回了但排在末尾，说明需要重排或调整召回数量。
3. 看切片：片段过长会稀释语义，过短会丢上下文。按文档结构切分通常比按固定字数切分更稳。
4. 看元数据过滤：企业知识库常有版本、部门、生效时间等维度，缺少过滤条件会命中过期文档，答案看起来“很像但不对”。
5. 看提示词与模型：提示词是否明确要求“仅根据给定资料回答，资料不足时说明无法确定”，以及上下文是否在拼接时被截断。

用评测集代替主观感受

“答非所问”是主观判断，团队内部很容易各说各话。更可靠的做法是建一个 50 到 200 条的小型评测集，覆盖高频问题、边界问题和无答案问题，每次调整切片、模型或提示词后跑一遍，对比命中率与答案合格率的变化。这样才能判断改动是真的有效，还是只是把某几个问题修好了。

在需要对比不同模型表现时，可以到 通联AI中转站 的模型广场查看可调用模型并切换测试，让同一套检索链路分别跑不同模型，避免把检索问题和模型能力问题混为一谈。切换时仍需核对控制台给出的模型名称与计费规则。

四、把排查动作固化到上线流程

企业知识库问答 API 的问题很少是一次性的。把下列动作写进上线检查清单，可以显著减少重复踩坑：请求日志必须带 trace id 并记录检索片段快照；客户端必须有重试与退避策略；模型名称、接口地址、Key 一律从配置中心读取而非硬编码；每次改动前先跑评测集；上线后观察错误率与超时率两