Agent静默截断排查：源端50条数据为何模型只看到20条

做 Agent 的同学应该都有过这种经历你明明在源端准备好了 50 条候选数据模型回答里却只体现出了 20 条的信息。它不报错、不警告、不告诉你少了一半就静悄悄地用剩下那部分内容给你交差。我第一次遇到这个问题是在调一个检索增强型 Agent 的时候当时改完召回逻辑上线线上反馈突然变差我第一反应是召回排序出了问题结果查了半天问题根本不在召回而在 prompt 组装阶段就被框架悄悄截断了。这种不响不叫、把数据偷摸丢掉的情况就是典型的 Agent 静默截断。这个坑最近在社群里被反复问到很多做 Agent 开发的朋友都遇到过类似场景工具返回 50 条记录模型报告里只能数出 20 条RAG 召回 30 个片段模型回答时只引用了其中 8 个。多数人会在检索、排序、Embedding 这些环节反复折腾最后才发现是模型上下文入口那一层出了问题。这篇文章就以源端 50 条、模型看到 20 条这次完整排查为例把静默截断的成因、排查思路、定位技巧和底层原理全部拆开讲。不光是写结论更会把我在这次排查里踩过的坑和验证过的方法一起放出来给正在做 Agent 开发的你做个参考。1. 现象先行50 条进、20 条出到底怪谁1.1 这类事故的共同画风Agent 静默截断最迷惑人的地方在于一切都还正常。你问它问题它能答你给它任务它能跑你检查日志请求成功、响应成功、状态码 200。可一旦让它用到那 50 条完整数据它就像得了选择性失忆只拿其中 20 条当作上下文。我当时遇到的场景是这样的一个文档问答 Agent源端从数据库里查出了 50 条相关片段每条片段大概 100 到 200 个字符。我预期模型可以根据这 50 条片段做归纳但实际测试时让它列出你看到的所有片段标题它只列出来 20 个而且顺序变了。模型并不知道自己被截断它只会基于自己实际看到的内容去回答。所以这种问题从模型输出质量差入手排查往往会被带偏。这类事故有几个共同画风第一数据在某个中间环节被丢弃但没有任何日志提示第二业务层没有对消息条数做过校验丢失无感知第三模型回答本身有一定的自洽性不仔细对比源端数据根本发现不了。我后来复盘发现这类问题在 Agent 项目里出现的概率远比想象中高只要你的上下文组装逻辑里存在任何数量限制或token 预算配置就有可能出现静默丢数据。1.2 为什么静默比报错更危险我们做排查时最怕的不是报错而是不报错。报错至少给了你线索状态码、错误信息、堆栈照着查就行。静默截断则相当于有人在快递分拣中心把你的 50 件包裹扔掉了 30 件还会重新封箱收货人收到的依旧是一个完整箱子只是里面重量不对。有一个容易被忽略的点LLM 服务商返回的错误通常长这样 error report 里面有 message、error code 这些字段Agent 框架也会把显式终止错误比如 agent execution terminated due to error抛出来。但上下文超出限制时很多模型服务商并不会报错而是直接按自己的截断策略处理或者在返回的 usage 字段里让你看到prompt_tokens 被计了多少但不会告诉你哪些内容没被送进去。我用一句话总结静默截断的危险性它把数据缺失伪装成了模型能力不足。一旦你误判方向会花大量时间去调 prompt、换模型、改温度参数结果全部无效。所以排查这件事的核心思路只有一条——不要盯着模型的输出去猜要顺着数据流从源头到模型逐段验证找到真正丢数据的那个节点。1.3 排查前的心理建设与思路主线如果你现在也遇到类似问题先别急着改代码。我建议先想清楚三件事数据是在哪一层丢的是哪一行配置或代码导致的为什么这个环节选择了丢数据而不是报错误对应到排查主线就是一条从源端到模型的链路审计源端查询结果 → 检索/召回层 → prompt 组装层 → 模型请求体 → 模型响应。每一层都需要记录两样东西数据条数和数据体积字符数或 token 数。不要把条数一致当作没问题的证据还要对比内容是否完整。因为有些截断不是整条丢而是每条内容被切断尾部这种情况条数不变但信息量已经缩水了。2. 先摸清作案手法静默截断到底有几种2.1 上下文窗口硬切最直白的断头台第一种最常见的情况就是上下文窗口context window上限。现在的模型虽然把窗口从 4K 扩到了 128K、200K但窗口再大也有上限。Agent 每轮对话会把 system prompt、历史消息、工具返回结果、当前用户问题全拼在一起一旦总 token 数超过模型窗口框架或服务端就必须做出取舍。取舍策略大部分是保头弃尾或保尾弃头。以我遇到的情况来说50 条片段拼进去之后总 token 数已经贴近窗口上限框架默认策略是保留最近的消息、丢弃较早的片段。所以模型看到的内容是当前用户问题 最后拼接的 20 条片段前面的 30 条被悄悄扔掉。你从模型的角度看它确实只看到了 20 条而且它自己毫不知情。这种截断的显著特征是被丢弃的数据往往是 prompt 中比较靠前的部分。如果你发现模型对后面的内容很熟悉对前面的内容毫无反应基本可以锁定这种硬切截断。2.2 Token 计算器与字符数混淆第二种情况出在配置层而且特别坑。很多 Agent 框架在拼接消息前会做一次预算检查判断内容是否超出限制。问题在于这些框架用的计量单位到底是 token 还是字符很多人根本没确认过。字符和 token 的换算关系不是固定的。中文场景下一个汉字大约等于 1 到 2 个 token英文大概 4 个字符等于 1 个 tokenJSON 格式里光引号、括号、逗号这些符号就会额外消耗大量 token。你用字符数不超过 10000去配置一个 token 上限为 8000 的模型结果实际换算下来 token 数已经到 12000就会触发截断逻辑。这个坑的隐蔽之处在于框架不会主动报计量单位不匹配它只会默默执行截断策略。我那次排查时发现配置参数写的明明是max_context_length 20000以为很宽裕后来查了框架源码才发现它这里是把字符数当作 token 数去匹配的实际换算后早就超限了。2.3 max_tokens 输出截断的兄弟问题严格来说max_tokens 截断截的是输出而不是输入但它对排查的干扰程度一点都不低。当模型开始生成回答如果设置了 max_tokens 但设置过小生成到一半就被强制停止这种情况通常会在返回结果的 finish_reason 字段里标成 length。问题在于很多 Agent 框架和业务代码根本不看 finish_reason。它拿到一段不完整的回答照样当成功结果返回给上层。于是你会看到一个更诡异的现象50 条源端数据只看到 20 条而且模型回答连这 20 条都没归纳完写到一半就断了。我第一次排查时把输出截断和输入截断混在了一起白折腾了一个多小时。后来把 finish_reason 打出来看才意识到是两类问题叠加。所以排查时一定要先把输入截断和输出截断分开确认。2.4 Agent 框架内部的轮次与工具返回截断第三种情况藏在 Agent 框架的逻辑里。工具调用返回的内容是动态拼接的框架出于节省 token、防止超长的考虑往往会有一层消息长度限制或历史轮次限制。例如只保留最近 N 轮消息、工具结果只截取前 M 个字符这些都是静默截断的高发区。我记得有次看某个开源 Agent 框架的默认配置它对 tool result 的默认限制是 2000 个字符。一个返回 5000 字符的 JSON 数组传进去后面 3000 字符直接被框架切断而 Agent 以为自己拿到了完整结果。这就是源端数据明明有模型看到的却是残缺版的最典型案例。工具结果截断比上下文硬切更难发现因为条数可能没变每条内容却被砍了一截。对付这种问题必须读一下你正在用的 Agent 框架的源码把 message 历史长度、tool result 长度、上下文预算这几个参数的默认值查清楚。一般都在 configuration 或 constants 文件里花十分钟翻一翻能省下后面几个小时的排查时间。2.5 检索 Top-K 软截断披着设计外衣的数据消失最后一种我要特别提一下检索层的 Top-K 截断。它不叫截断在系统设计里叫召回数量限制。RAG 场景下索引里明明有 50 条相关片段检索器默认只取 Top 20 返回那么后端的模型自然只看到 20 条。这种截断可能是刻意设计的也可能纯粹是配置遗漏。我就见过有人把向量库的 top_k 参数写死为 20忘记调大然后四处排查为什么模型用不到剩下的数据。如果你排查到检索层一定要先问一个问题源端返回 50 条是哪个环节的数据是数据库查出来的 50 条还是检索器过滤后的 50 条这两个数字含义完全不同。数据流的每一个节点输出都要单独打日志才能对得上账。我把这几类截断整理成了一张对照表排查时可以快速定位怀疑方向截断类型典型表现排查入口判断方法上下文窗口硬切靠前的数据全没了prompt 组装层打印完整请求体数消息条数token/字符混淆配置值没超但实际超了框架配置与 tokenizer用真实 tokenizer 换算请求体max_tokens 输出截断回答写到一半就停模型返回的 finish_reason检查是否等于 length框架内部轮次/工具截断条数不变但每条内容残缺Agent 框架源码与配置对比工具原始返回与拼接后内容检索 Top-K 截断源端候选集大于模型所见检索/召回层代码对比数据库查询结果与检索器输出3. 实操过程从源端到模型逐环节打点验证3.1 先复现再冻结现场排查静默截断的第一步不是看代码而是先复现。如果问题不能稳定复现后面所有定位都可能是白费。我当时做的第一件事是把线上出问题的那个用户输入缓存下来然后用完全相同的输入、相同的数据源、相同的模型参数去重放 bug。连续压测三次都能复现才敢确定这不是偶发问题。复现出来后立刻做一次现场冻结把当时的源端数据、检索结果、组装后的 prompt、模型原始响应全部导出来存好。这一步很重要因为后面每做一次改动都需要拿这个固定样本来验证。没有固定样本你无法判断到底是改好了还是数据本身变了。我还建议把 temperature 和随机参数固定住否则模型输出本身的随机性会干扰判断。3.2 三个关键环节入口、出口和嘴替我的排查习惯是在数据流三个关键位置埋点入口打点、出口打点、模型响应打点。先说入口打点。在源端查询函数返回结果之后立即记录数据条数和总字符数。比如查出 50 条、累计 9000 字符这就是源头基线。再说出口打点。在组装完 prompt、发请求之前记录最终 messages 结构里每个 role 的消息数和总字符数。这一步如果能做直接就能发现组装层有没有把 50 条变成 20 条。最后是模型响应打点。记录返回结果里的 finish_reason、usage 里的 prompt_tokens 和 completion_tokens。这三个字段能帮你判断模型到底接收了多少输入、输出有没有被切断。实际操作时不需要开发很复杂的链路追踪在关键函数里加三五行日志就够了。我当时写了个简单的 Python 脚本来做检查def count_messages(messages): total_chars 0 role_count {} for msg in messages: role msg.get(role, unknown) role_count[role] role_count.get(role, 0) 1 content msg.get(content, ) if isinstance(content, list): for block in content: text block.get(text, ) total_chars len(text) else: total_chars len(str(content)) return role_count, total_chars # 调用点示例 role_count, total_chars count_messages(built_messages) print(fdebug: role_count{role_count}, total_chars{total_chars})把这行 debug 输出加在请求发送之前你会立刻看到组装后的消息分布。这个方法工具量小、见效快是我现在所有 Agent 项目的标准配置。3.3 用简化二进制法快速缩小丢失区间如果不想一开始就翻源码我推荐一个非常实用的排查方法把 50 条数据分成几组做递减对比。它有点像二分查找的思路我这里叫它数据区间二分法。第一次请求只放前 5 条看模型是不是能完整看到 5 条第二次放 10 条、第三次放 15 条逐步加量。每次让模型回答你看到几条同时人工检查源端条数。你会发现有一个临界点跨过它之后模型看到的条数不再增长。我当时的测试结果是20 条时全看到25 条时只看到 20 条。这说明截断阈值在 20 到 25 条之间。锁定区间后再看这 25 条到底占了多少 token就能和一个具体的 token 阈值对上账。这个方法最大的优点是不需要借助额外工具用最原始的方式就能把问题范围缩小一大半。缺点是步骤稍慢适合复现稳定的场景。3.4 最关键的一步在请求体里抓到现场有时候框架的封装很重日志打了半天看不到真实请求。这时候不要犹豫直接在请求发出那一刻截获请求体。最简单的方式是用 curl 手动重放同一个请求把完整 messages 打印到本地文件。我那次的做法是把组装后的 messages 序列化成 JSON 存到文件然后数里面的消息条数。结果发现实际发出去的 prompt 里确实只有 20 条片段另外 30 条在组装阶段就没了。这个现场直接锁定了问题层后面再去查框架配置就很快了。如果你用的是某个云厂商的模型并且带了代理网关还可以在网关层记录请求体和响应体。网关是你和模型服务商之间的最后一个观察点在这里能看到最真实的进出流量。有的模型服务商返回的 usage 字段里 prompt_tokens 会大于实际内容量这时你还需要结合模型复述结果来验证——让模型用自己的话列出它看到的内容这是最终确认手段。4. 根因定位与解决80% 是没算清 token 账4.1 把原始 50 条数据换算成一个数字到了根因定位阶段就要开始算账了。把源端 50 条片段全部拿出来统计总 token 数。我当时的 50 条片段每条大概 150 到 220 字符总计约 9500 字符用对应模型 tokenizer 换算后大约是 5200 个 token。再加上 system prompt 的 1200 token、工具定义和用户问题的 600 token整个请求体接近 7000 token。当时我以为用的模型 context window 是 8000应该能装下但忽略了一个关键点窗口里还要预留输出空间。如果 max_tokens 设置成了 2000实际可用于输入的上限就是 8000 - 2000 6000。7000 token 的输入直接超限触发截断也就在所难免了。很多人看到这里会问那为什么框架不报错因为模型服务商把输入超过限制处理成了一种可选行为有的服务商直接报错有的服务商选择丢弃超出的部分。而 Agent 框架更多是宁可截断也不把请求打断它默认丢数据比报错更体面。这就是静默截断的根源——系统设计者把数据完整性让位给了请求可用性。4.2 检查框架的超参默认值算完账以后我直接去翻了正在用的 Agent 框架的源码找到上下文拼接那一段。果然框架在组装 prompt 之前会检查总 token 数超过设定的 max_context_tokens 就会截取消息列表尾部的内容。问题里恰恰有个很隐蔽的参数max_context_tokens 实际上换算错了单位它按字符数计算的而模型服务商按 token 数计算。这里要提醒所有做 Agent 开发的朋友框架默认值不等于合理值。任何一个 agent 框架给你提供的默认参数都需要结合你的真实场景重新校准。常见的需要重点关注的有几个message history 长度限制、tool result 长度限制、context window 上限、max_tokens。把这些参数统一改成按 token 计量并且预留 20% 的安全余量能避开绝大多数静默截断问题。4.3 解决方案复盘配置 代码 观测三件套修这个问题我从三个层面同时下手缺一不可。配置层面把框架的 max_context_tokens 改成 6000同时将 max_tokens 从 2000 调到 1500给输入留出更多空间。再把工具返回结果的单条长度限制从 2000 字符提上去确保单条 JSON 不被砍断。代码层面在源端查询后和 prompt 组装前各加一道显示校验。如果预计算 token 数超过输入预算优先触发显式截断逻辑并返回截断提示给上层而不是让框架内部悄悄丢弃。这样至少保证丢数据这件事变成被记录的事件。观测层面项目里加了 metrics 上报每次请求记录 messages 总数、总 token 估算值、实际 usage.prompt_tokens。设置告警规则当源端条数和请求体条数不一致时直接告警。这条规则不一定能立刻抓到所有问题但至少让静默截断失去了静默这个属性。整个修复上线后的验证也很关键。我重新用最初的固定样本重放模型终于能数出 50 条片段了。再让模型复述每条片段的标题50 条全部对上。从只能说出 20 条到完整 50 条问题彻底解决。5. 常见问题速查表与避坑清单5.1 排查口径速查表在实际排查过程中建议按下面这张表逐项对照可以覆盖 90% 的 Agent 静默截断场景症状优先怀疑环节快速验证方法解决方案模型看不到靠前数据prompt 组装层打印请求体对比消息顺序调整上下文截断策略为保留头部或扩充预算数据条数没变但每条内容残缺工具返回截断对比原始工具结果与框架内对象调大 tool result 长度限制回答写到一半就停max_tokens检查 finish_reason 是否等于 length增大输出预算或精简 prompt模型复述内容比源端少多个环节都可能逐级打点确认哪一层开始少按上文三件套方式修复检索结果多但模型用的少检索 Top-K 配置查检索器配置参数调大 top_k 或改为动态设置这张表的核心是不要猜测用日志和字段数据说话。尤其是 finish_reason、usage.prompt_tokens、role_count 这三个字段建议在日志里固定输出。5.2 日常开发中的防静默截断规范踩过这次坑之后我把几条经验固化成了自己项目的开发规范也分享给你参考。第一条所有 Agent 项目的请求发送前必须记录输入消息条数 估算 token 数。这两条数据能保证出问题时你至少知道模型入口看到的是什么。第二条不要相信字符数所有上下文预算一律按 token 算。项目里保留一个统一的 tokenizer 工具类所有预估都走同一个换算逻辑避免不同模块各算各的。第三条对模型返回的 usage 字段做对账。理想情况下估算 token 和实际 usage.prompt_tokens 的偏差应该在 10% 以内。如果偏差超过 30%说明某个环节的计量方式不对需要检查。第四条截断必须是显式的。任何框架配置的截断行为都要能通过日志看到最好有专门的告警。走一个原则允许丢数据但不能静默地丢。第五条凡是在 prompt 里用了列表序号、编号、标题这类内容建议做一个完整性自检提示。让模型在回答时引用编号而不是笼统概括能显著提高截断问题的暴露率。我在这次排查后还在项目里加了一个小功能把源端数据条数作为一条独立 metric 上报和请求体条数一同展示在监控面板上。有没有问题一眼就能看出来不用等用户反馈模型回答变差了才发现。结尾一点实在体会这次排查到最后一共花了大半天时间真正定位到根因只用了不到一小时剩下时间都在检查检索层和怀疑模型能力上兜圈子。如果把排查顺序反过来先看数据流和请求体可能 20 分钟就能锁死问题。现在我养成了一个习惯任何 Agent 项目上线前先跑一次数据完整性冒烟测试让模型主动汇报自己看到了多少条、哪些编号用最笨的方式验证最基础的事实。这个习惯帮我避开了很多潜在的数据丢失事故。最后再分享一个小技巧排查静默截断时不妨把问题交给模型本身。你可以构造一个请求明确告诉模型请完整列出你收到的所有条目编号不要省略任何一项拿它的输出和你预期对比。模型不会同情你的数据集但它至少能诚实地告诉你它看到了什么。信息时代数据和模型之间的每一次交接都值得多留一双眼睛。