Agent链路静默截断排查：模型只收到20条数据的真相

先别急着怀疑模型。“源端有 50 条模型只看到了 20 条” 这个故障我排查了整整一个下午最后发现和模型本身一点关系都没有。问题出在一个特别容易被忽略的环节Agent 链路里的静默截断。这类问题的可怕之处在于系统不报错、日志全绿、接口全部返回成功你甚至能看到源端查出了 50 条数据但模型在推理时实际拿到的上下文里只剩 20 条。中间那 30 条去哪儿了没人知情。你要是光盯着模型调 prompt、调温度、调 max_tokens调一晚上也白搭。这篇文章就把我这次排查的完整过程写出来从现象确认、分层取证、根因定位到修复方案和防复发手段。对正在做 Agent 开发、RAG 应用、或者自己手搓智能体的工程师来说这是一次很典型的“假性正常”故障值得从头到尾捋一遍。1. 事故现场一切正常但答案残缺1.1 表象复盘源端 50 条模型只拿到 20 条先说业务背景。我这边在做一个基于 Agent 的知识问答系统核心链路是用户提问后Agent 会调用一个检索工具从知识库的向量索引里取回匹配片段然后把这些片段作为工具结果组装进上下文再交给模型做最终回答。那天运营反馈说某类问题的回答质量突然下降答案经常漏掉关键信息。我先在后台看工具调用日志检索工具正常返回了 50 条候选片段每条都带 score 和元数据耗时也正常。再看模型侧记录发现最后请求体里只有 20 条片段。当时第一反应是“模型拒答了”或者“prompt 太长被吞了”但仔细一看请求体里根本没有出现另外 30 条的任何信息既没有截断标记也没有异常字段干干净净。这种事最难查因为链路里每个节点都在“忠实”地工作没有节点觉得自己错了。我后来打趣说这就像网购快递物流信息显示“已签收”你拆开箱子发现里面只有两件衣服另一件压根没发。你想找快递公司理论但单号、包装、签收记录全是完整的——问题一定出在某个你觉得不会出问题的“包装”环节。这个案例适合所有人参考不管你是用 LangChain、LlamaIndex 这类现成框架还是自己基于 OpenAI SDK 封装 Agent都可能遇到。只要链路上存在“先检索、再组装、后截断”的环节就一定有类似的坑等着你。1.2 为什么“静默截断”是最难查的故障类型我在群里问了几个做 Agent 的同行发现很多人遇到过类似问题但真正定位到原因的没几个。大家普遍卡在同一个地方所有环节的返回值都是成功的没有 exception没有 timeout因此无从下手。传统后端系统里数据丢失往往伴随超时、内存溢出、序列化异常等错误信号。但 Agent 链路的特殊性在于它天然包含“裁剪”和“压缩”这类操作。为了控制上下文长度、降低 token 成本很多框架默认就有截断逻辑。问题是这些逻辑常常在“看起来 OK”的默认参数后面不会主动告诉你“我截断了”或者“我丢了 30 条”。更麻烦的是这类截断往往嵌套多层。工具出参可能有一层限制上下文管理器有一层裁剪策略模型 API 还有最大 token 限制每一层都只处理自己那一段每一层都觉得“我已经处理好了”于是错误就被一层层“合规”地掩盖了。整个过程没有节点红脸模型也只是安静地基于残缺的输入作答。要是模型在回答里说一句“我没有找到相关数据”你可能还会误以为是检索质量差。这就是静默截断的真正危险——它伪装成系统正常运行的一部分。所以排查这类问题必须有一个意识不要相信任何中间层的“成功”只相信请求体里实际发给模型的内容。一切从模型真正看到的输入开始倒推。2. 从链路下游往上游摸排五层过滤逐一取证2.1 先确认“模型实际收到了什么”我这一次的排查顺序不是从源端往下查而是从模型端往上查。为什么因为最接近模型的那一层才是一切问题的“终局”。源端查了 50 条认证过了不代表后面每一层都放行了。首先做的动作很直接把实际发给模型 API 的完整请求体 dump 下来。如果是本地开发环境直接在调用模型的那个函数里加一个打印打印出messages里每条消息的角色、内容长度、消息条数。不要打完整内容先打印摘要比如def build_messages_with_debug(*args, **kwargs): messages build_messages(*args, **kwargs) for i, msg in enumerate(messages): if isinstance(msg.get(content), str): print(f[DEBUG] msg[{i}] role{msg[role]} chars{len(msg[content])}) elif isinstance(msg.get(content), list): total_chars 0 item_count len(msg[content]) for item in msg[content]: if item.get(type) text: total_chars len(item.get(text, )) elif item.get(type) tool_result: total_chars len(str(item.get(content, ))) print(f[DEBUG] msg[{i}] role{msg[role]} item_count{item_count} total_chars{total_chars}) return messages这一步的目的只有一个确定“模型看到的到底是 20 条还是 30 条”。如果模型收到 50 条但 API 返回错误那是另一类问题如果模型收到 20 条而链路毫无异常那截断必然发生在这之前。我当时 dump 出来确认tool_result消息里确实只有 20 个条目于是立刻把怀疑范围收缩到请求体组装之前的所有环节。注意这里有一条重要经验打印摘要行而不是完整内容。Agent 上下文动不动就几千上万字符打印完整内容会让你淹没在数据里反而看不清条数和长度这样的结构化信息。摘要行能让你在日志里一眼看出消息数、字符数这几个关键指标。2.2 工具层出参被限流还是被序列化“弄丢”了确认模型侧只收到 20 条之后我开始往上游查。第一站是工具调用层也就是那个返回 50 条结果的检索工具本身。这里有两个常见嫌疑。第一个是框架对工具出参的隐式限制。很多 Agent 框架在定义工具时可以在返回结果上加max_output_tokens、max_items之类的参数或者在 schema 里写了maxItems约束。如果你用的是现成框架尤其要检查工具装饰器上的默认参数。我这次用的检索工具在函数定义上写了挺多自定义元数据但当时并没有显式设置输出条数限制。我直接写了一个干净的单测去调那个工具结果一次返回 50 条没有截断。第二个嫌疑是序列化环节。工具返回的是一个 Python 列表里面嵌套了字典。在组装进消息之前通常要经过 JSON 序列化或者自定义的to_string()转换。如果这段转换逻辑里用了replace()、filter()、limit()这类操作就可能悄悄丢掉一部分字段。我当时把工具原始返回的 JSON 字符串和最终写入上下文的字符串做了一次 diff结果也正常50 条都在序列化字符串里。到这里工具层基本洗清嫌疑。但这里有一个容易漏的点如果工具结果是通过多次并行调用返回的还要检查合并逻辑。比如用 Agent 框架的并行工具调用时每个分支各返回一部分结果合并时如果只取了前 N 条也会造成静默丢失。我这次是单次调用所以排除了这种可能。2.3 上下文管理器最常背锅也最常真凶的一层工具层干净了接下来看上下文管理器。这是我最怀疑的一层事实证明确实如此。所谓上下文管理器就是负责把系统提示词、用户问题、历史对话、工具结果组装成最终messages数组的组件。在很多 Agent 框架里这一步会内置各种“保护策略”比如上下文长度超过阈值时自动丢历史消息比如每条消息内容超过 N 个字符时自动截断字符串比如按“最近优先”规则丢弃较早的消息。我这次的问题就出在这里。框架的上下文管理器里有一段逻辑如果工具结果序列化后超过某个长度就按“前缀截断”只保留前一部分内容。更坑的是它截断的单位不是 token也不是消息条数而是“字符长度”。它会循环读取消息直到累计字符数达到上限为止。每读完一条就把它保留下来一旦超过阈值后面的直接丢弃。在我这次场景里50 条工具结果序列化后长度很大而上下文管理器的默认字符上限是 16000 字符。它按消息顺序读读到第 30 条时超过阈值于是后面 20 条被丢掉了。等等按这个说法应该是保留前 30 条丢后 20 条但现象是保留 20 条。实际跑起来还有另一个因素系统提示词和用户问题占了很大一部分字符工具结果消息本身还没读到一半预算就用完了。所以最终保留 20 条。这就是“静默截断”的典型实现框架认为自己在做合理的上下文压缩但压缩策略完全不适合业务场景。它不会告诉你丢了什么因为它觉得这是正常优化。查到这一步我基本锁定了根因方向。但这里我想提醒一点不是所有上下文管理器都默认开启这种截断你需要看框架文档里关于上下文压缩、消息裁减、token 估算的配置项。很多时候不是框架没做而是默认开启了“保护机制”。2.4 Token 计算与模型窗口最后一道物理闸门工具层和上下文管理器检查完还有一个不得不查的环节模型 API 层面的 token 上限。即使上下文管理器组装了完整的 50 条发送给模型 API 时API 本身也有max_tokens上限或请求体长度限制。如果组装后的消息总长度超过模型的上下文窗口比如 Claude 的 200K、GPT 的 128KAPI 可能返回 400 错误也可能在某些网关层被截断。但正规模型 API 一般不会默默悄悄截断多数会报错。真正要留意的是那些“中转层”和自建的代理网关。我这次用的模型 API 上下文窗口是 128K50 条工具结果加上其他消息大约 20K远没到上限。所以这个环节可以排除。但排查时不能跳过它否则你改了一堆上下文管理器配置最后发现是网关卡住了。为了保险我还做了一个最小化验证把 50 条结果全部作为唯一内容发给模型没有系统提示词、没有历史对话结果模型能收到全部 50 条。这就彻底排除了模型窗口因素。到这一步完整链路五层已经查了四层焦点集中在上下文管理器的字符截断逻辑上。排查顺序总结一下模型输入 → 工具出参 → 序列化 → 上下文组装 → Token 窗口。自上而下逐层自证。哪个环节的数据和上游不一致哪个环节就是问题所在。3. 根因确认字符数截断遇上中文检索结果3.1 复现实验同一输入三份快照对比确认根因之前我做了个复现实验确保不是偶发现象。做法很简单写一个独立脚本构造同样的 50 条工具结果走一遍完整的消息组装流程然后在三个关键节点分别打点记录节点 A工具返回的原始数据记录条数和字符数。节点 B序列化并加入消息数组后记录字符数和条数。节点 C最终请求体里的工具结果消息记录字符数和条数。三个节点全部打印摘要不打印内容。跑了一遍数据是这样的节点条数字符数说明A工具原始返回509321全部字段完整B序列化入消息509321无丢失C最终请求体2015983多了其他消息且被截断注意看节点 C 的字符数是 15983明显超过了我设的 16000 阈值。而且节点 C 的“条数”只有 20但“字符数”反而更高因为里面还塞了系统提示词、用户问题、历史对话等其他消息。这个实验非常有说服力如果只看条数你会以为是在工具层丢的如果只看字符数你会以为只是正常压缩。但把条数和字符数放在一起看就知道是上下文管理器的“字符阈值 消息遍历顺序”共同作用导致的结果。我随后去翻了框架源码找到了那段截断代码逻辑大致是这样MAX_CONTEXT_CHARS 16000 def trim_messages(messages: list[dict]) - list[dict]: total_chars 0 kept [] for msg in messages: content msg.get(content, ) content_str content if isinstance(content, str) else json.dumps(content, ensure_asciiFalse) total_chars len(content_str) if total_chars MAX_CONTEXT_CHARS: break kept.append(msg) return kept这个函数有几个致命缺陷。第一它按字符数累计而 1 个 token 在中文场景下大概对应 1~2 个汉字但英文和代码符号可能对应更多字符所以字符数根本不能准确反映 token 消耗。第二它在累计超限后直接break而不是丢弃一部分保留另一部分导致后面的消息整段消失。第三它没有任何日志截断发生了调用方毫无感知。更糟糕的是消息数组的顺序是系统提示词 → 用户问题 → 历史对话 → 工具结果。工具结果排在最后。遍历时先累加系统提示词和用户问题等轮到工具结果时预算已经消耗了一部分。我这次工具结果刚读完 20 条就超了阈值后面 30 条连被“考虑”的机会都没有。3.2 修复一截断逻辑从字符维度改成 Token 维度定位到根因后我第一件事就是改掉这段截断逻辑核心思路就一句话用 token 数而不是字符数做预算并且给工具结果单独的预算池。具体的修复方案分三步。第一步用模型的 tokenizer 把每条消息的文本转成 token 数再做累计而不是用len()算字符数。如果你用的是 OpenAI可以用tiktoken如果用的是开源模型可以用transformers的 tokenizer。我这里直接用了模型同款 tokenizerimport tiktoken encoding tiktoken.encoding_for_model(gpt-4o) def estimate_tokens(text: str) - int: if not text: return 0 return len(encoding.encode(text))第二步给“工具结果”单独分配预算比例。比如整个上下文预算假设是 120K token其中固定 30K 留给系统提示词和对话剩下的 90K 优先保证工具结果完整。如果工具结果超过 90K再做摘要而不是简单截断。第三步把遍历逻辑从“遍历到超限就 break”改成“遍历全部消息优先保留工具结果其次保留最近对话”。也就是说真有必要截断时先丢最旧的对话历史而不是丢工具结果。因为对于知识问答场景来说工具结果就是模型回答的依据丢了它等于让模型瞎猜。修复后的伪代码大致如下TOKEN_BUDGETS { system: 5000, conversation: 30000, tool_result: 90000, } def build_messages_with_budget(system_prompt, conversation_history, tool_result): system_tokens estimate_tokens(system_prompt) conv_tokens sum(estimate_tokens(m[content]) for m in conversation_history) tool_tokens estimate_tokens(tool_result) messages [{role: system, content: system_prompt}] messages.extend(conversation_history) # 工具结果超预算时优先保留完整消息而不是丢弃后面的 if tool_tokens TOKEN_BUDGETS[tool_result]: tool_result summarize_tool_result(tool_result, max_tokensTOKEN_BUDGETS[tool_result]) messages.append({role: user, content: tool_result}) return messages这个方案改完同样 50 条工具结果模型侧终于能收到完整数据了。改完那一刻我反而有点后怕如果当时没做三节点快照对比只靠肉眼翻日志这种问题再查三天也未必能定位。3.3 修复二给截断行为加上“审计日志”光改截断逻辑还不够因为下一次如果出现别的截断场景依然可能悄无声息。所以第二件事是给所有可能丢失数据的位置加审计日志。具体做法是在上下文管理器里维护一个TruncationReport记录每次发生截断时的时间、被丢弃的消息条数、丢弃内容的 token 估算值、触发截断的阈值等信息然后统一输出到日志系统。这样以后任何一次裁剪和丢弃都会留下痕迹系统再也不会有“无痕丢数据”的情况。实现的思路很轻量不用引入额外组件只要在原来的trim_messages里把静默的break改成记录再丢class TruncationReporter: def __init__(self): self.events [] def record(self, reason: str, dropped_items: int, dropped_chars: int, dropped_tokens: int): self.events.append({ reason: reason, dropped_items: dropped_items, dropped_chars: dropped_chars, dropped_tokens: dropped_tokens, ts: time.time(), }) def log(self): for ev in self.events: logger.warning(f[TRUNCATION] {ev[reason]} dropped{ev[dropped_items]} items, fchars{ev[dropped_chars]}, tokens{ev[dropped_tokens]})我第一次在日志里看到[TRUNCATION] dropped30 items的时候才知道之前的静默有多离谱。如果这个告警能提前一周存在那次线上问题根本不会发生。3.4 修复三让模型自己报告“看不全”除了在代码层面做防护我还加了一道人防措施在系统提示词里加一句话让模型在发现输入不完整时主动反馈。这句话的大意是“工具返回的知识片段可能不完整。如果你发现当前上下文中的相关片段数量少于预期、或者明显缺少回答问题的必要信息请明确说明‘我没有获得完整信息’而不是强行作答。”这个技巧听上去有点简单但在实际场景里非常有效。模型本身对自己收到的内容有没有感知没有它不知道源端是 50 条还是 20 条。但你可以让它对“信息不足”保持敏感把“部分信息缺失”从静默变成显性反馈。比如这次修复后如果未来再出现工具结果被意外截断模型可能会在回答里明确说“我只收到了部分片段无法确认完整答案。” 这样至少运营同事能快速发现问题而不是带着残缺答案上线一整天。当然这是一个兜底不是根治。根治靠的还是上下文管理器的预算分配和审计日志。提示词防御只是让问题更容易暴露相当于在系统里加了一个“烟雾报警器”。4. 常见截断场景速查一张表定位问题环节4.1 高频静默截断场景定位表排查完这一次我把 Agent 链路里常见的静默截断场景整理成了一张速查表后面再遇到类似问题先按表定位效率高很多场景表面现象最可能环节验证方法修复方向检索结果条数不符源端 50 条模型只见 20 条上下文管理器按字符/token 预算丢弃dump 请求体打印条数和字符数单独给工具结果设预算优先保留工具结果历史对话丢失模型想不起几分钟前说过的话上下文管理器按“最近优先”丢弃早期消息查看 messages 数组里历史消息条数提高历史预算或对早期对话做摘要压缩工具出参字段缺失某字段一直没有值但工具明明返回了工具 schema 或序列化逻辑对比工具原始返回和请求体中的内容检查工具定义的返回值限制和序列化代码中文内容被截断英文数据正常中文数据乱码或缺失截断逻辑使用字符数而非 token 数复现一条长中文输入观察截断位置替换为 tokenizer 估算不用字符数模型回复“信息不足”答案残缺但链路无异常可能是源端检索质量低也可能是截断用最小化实验单独发给模型区分是检索问题还是链路问题这张表不是万能药但排查时对照一下能少走不少弯路。大多数静默截断问题都逃不出这几个场景条数限制、字符限制、预算分配顺序、序列化丢字段、并行调用合并丢失。排查时我还有一个刻在脑子里的原则先把模型实际收到的内容打出来再往前推。只要确认了“模型收到了什么”上游每一步都有据可查。最怕从一开始就怀疑模型能力调 prompt 调一整天最后发现连数据都没送进去。4.2 我踩过的坑与一条经验法则严格说这次排查最大的坑不是技术而是心态。一开始我盯着“模型只看到了 20 条”这个结果潜意识里默认“模型收到 50 条但推理能力不行”于是浪费了大半天调 prompt、加 few-shot。直到 dump 请求体发现真的只有 20 条才把思路掰回来。这个教训比任何技术方案都值钱在 Agent 场景里很多“模型变笨”的假象本质是喂给模型的上下文变了。第二个坑是字符数和 token 数的概念混淆。以前我总觉得 len() 算一下长度差不多得了但中文场景下差距巨大。一段 500 字的纯中文用 GPT 系 tokenizer 算可能只有 300~400 token同样长度的英文混代码符号可能要到 800 token。如果截断代码按字符数算等于实际 token 预算完全失控。这次问题之所以到了 16000 字符才触发阈值却只保住了 20 条就是因为中文字符在 tokenizer 里“值钱”程度和 len() 算出来的完全不同。第三个值得说的坑是永远不要在 Agent 链路里写“万能异常吞掉”逻辑。我们的工具调用代码外层有个大try/except异常会被记录成 warning 而不是抛出。这个设计本意是防止单个工具失败导致整个 Agent 崩溃但它也为静默问题提供了温床。排查时你会发现部分warning级别的日志根本不会引起人警觉。后来我改了一条策略与数据完整性相关的异常必须升级为error级别并在日志里输出上下文快照。宁可多报警不能漏数据。还有一条经验法则我觉得对所有人都有用新写一个 Agent 链路时先写一个“数据账本”。每次进入下一步骤前打印当前这条消息里包含的条目数、字符数、token 估算值。刚开始会觉得这是额外工作但等到线上出问题那一天你会感谢这些日志让你 5 分钟定位而不是 5 小时抓瞎。我现在所有 Agent 项目的 message 构建函数里都默认带一个 debug 模式专门输出这种摘要行。最后再分享一个小技巧如果你用的是现成 Agent 框架排查这类问题时先别改业务代码先看框架的配置项里有没有这几个关键词max_message_chars、max_context_tokens、trim_strategy、summarization_threshold、max_output_items。这些配置项往往藏在框架默认参数里是最容易被忽略的“隐形手”。我这次就差点在框架配置文档里翻到max_context_chars这个参数只是因为数值默认太大没人会主动去改它。Agent 开发里这类“假性正常”的问题以后只会越来越多。链路过长、环节过多、每个环节都做一点“优化”最后模型拿到的上下文早就不是你想要的样子了。希望这次排查过程能给同样踩坑的同学一点参考遇到模型表现突然下降先别急着调模型把请求体打开看看数据有没有完整送到比什么 prompt 技巧都管用。