源端50条模型只见20条：Agent静默截断排查与修复

源端有 50 条，模型只看到了 20 条：一次 Agent 静默截断排查

先说结论：这次排查到最后，问题出在一个非常不起眼的地方——Agent 框架在把工具返回结果拼进对话消息时，悄悄按最大长度做了截断，而这个截断行为既没有抛异常，也没有显著报错，只在不显眼的位置打了一条 debug 级别日志。模型这边浑然不知，它以为工具只返回了 20 条数据，于是顺着这个残缺结果继续推理，最后给人一个“数据少了 30 条”的假象。

这问题算不上疑难杂症，但特别典型。如果你也在做 Agent 开发，尤其是涉及工具调用、数据量较大的场景，建议花几分钟把这篇文章看完。我会把整个排查过程、每一步的判断依据、最后的根因和修复方案都拆开讲，顺便把这类“静默截断”容易出现的几个隐蔽位置一起盘一遍。

1. 问题现场与环境还原

先说现场。我维护的一个 Agent 应用，核心能力是让模型通过工具调用去读取业务系统里的数据，然后基于这些数据生成分析结论。

有一天同事跑过来说：“模型给出的统计不对。源端明明有 50 条记录，模型在分析里只提到了 20 条，而且它自己说‘根据返回的 20 条数据’——模型并没有意识到数据不完整。”

我之前也处理过类似问题，第一反应是工具接口写错、参数传错或者分页丢了。但这次同事补了一句关键信息：“我手动调那个工具接口，返回是完整的 50 条。”

这就很有意思了。工具是对的，数据是齐的，模型拿到手的却只有 20 条。那问题大概率出在中间环节——也就是 Agent 框架如何把工具返回结果组装成模型消息。

先把环境变量摆出来，方便后面讨论：

• Agent 框架：某开源通用 Agent 框架，支持多轮对话和工具调用
• 模型：开源 32B 指令微调模型，上下文窗口 8K
• 调用链路：用户消息 → Agent 推理 → 触发工具调用 → 工具返回 50 条 JSON → 框架拼回消息 → 再次调用模型 → 模型基于“20 条”做分析

这里要特别强调“静默”两个字。如果模型调用直接报错，或者框架明确告诉你“数据被截断”，那问题早就被发现了。正因为整个过程没有任何显眼错误提示，模型还能正常跑完推理，所以这类问题极具迷惑性。

我一般排这类问题会按一个固定思路走：先确认源端数据，再检查传输过程，最后看模型输入。下面详细展开。

2. 排查链路：从应用日志到模型输入的三层检查

2.1 第一层：确认源端数据确实完整

排查第一步不是翻代码，而是先确认源端真没问题。同事已经手动验证过工具接口能返回 50 条，但我还是坚持自己看了一遍原始数据。原因很简单——很多排查最后白忙一场，就是因为源头数据本身在不同条件下返回结果不一样。

实际操作中，我直接在数据库里跑了源表 COUNT，拿到 50 条，排序字段也没有重复或乱序。又用工具接口带相同参数请求了一次，响应体里 JSON 数组长度是 50。这一步确认源端没问题。

这里有一个小技巧：不要只看“返回了 50 条”这个总数，还要确认数据顺序、ID 连续性。因为在后面的截断场景里，截断往往发生在尾部，如果只看总数，可能漏掉中间丢数的情况。我用业务主键做了一次连续性检查，1 到 50 都在，没有空洞。

2.2 第二层：检查框架日志，定位截断痕迹

源端没问题，接下来就要看数据在传输链路里什么时候“变少了”。

我打开 Agent 服务的应用日志，搜索工具调用相关的记录。日志里能看到框架确实发起了对工具接口的 HTTP 请求，响应码 200，响应体被接收，然后框架执行了一步操作：“将工具结果追加到消息列表”。

日志中有一条比较关键的记录，大意是工具返回结果长度超过预设阈值，框架对结果做了截断处理。问题是这条日志级别是 DEBUG，日常工作环境日志级别默认 INFO，所以它一直没浮出水面。

我把日志级别临时调到 DEBUG，重放了一次完整对话，截断日志稳稳出现。到这一步，其实已经基本锁定根因了——框架的默认行为在作怪。

但我不想止步于此，既然截断这么隐蔽，想搞清楚两件事：

1. 框架从哪一步开始截断？是拿到工具结果就截，还是组装最终 prompt 时才截？
2. 截断之后，模型输入到底是什么样？

2.3 第三层：检查实际传给模型的最终消息内容

如果说前两步是“看日志”，这一步就是“抓现场”。我必须看到传给模型的最终消息长什么样。

方法很朴素：在框架调用模型的入口处打一个透传日志，把最终生成的 messages 数组原样打印出来，重点看最后一条工具消息的长度和内容。

重放一次完整流程，打印结果显示，最后一条工具消息里确实只包含 20 条数据。我数了一下，截断位置恰好是第 20 条与第 21 条之间的某个字符处，截断点并不是一条完整的 JSON 记录边界——也就是说框架是按字符数截的，不是按记录条数截的。

这里有个重要发现：截断把 JSON 数组从中间切断，数组的开括号还在，闭括号也被强制补上了，所以从结构上看它仍然是一个“合语法”的 JSON。模型解析这个 JSON 时没报错，解析出来就是 20 条。这就是静默二字最阴险的地方——语法完整，语义残缺。

3. 根因定位：框架的截断策略与模型窗口的隐性关系

3.1 消息级截断：框架默认开启的“保护机制”

根因基本锁定在框架的“消息长度保护”功能上。这个功能的初衷是防止工具返回超大数据把模型上下文窗口撑爆。很多 Agent 框架都有类似机制，英文里通常叫max_tool_response_length或者truncate_message。

默认策略通常是：超过多少字符后，从尾部直接裁剪。有的框架还会在截断后追加一句提示，比如“（内容已截断）”，有的则什么都不加。

我用的这个框架属于“什么都不加”的类型，所以模型完全不知道数据被处理过。

这一点非常关键。如果你的框架会在截断位置补充显式说明，模型至少有机会在推理时意识到“数据不全”。不带任何标记的纯静默截断，是最难排查、对模型误导性最强的一种实现。

3.2 为什么偏偏是 20 条？“隐式截断阈值”的计算过程

模型只看到 20 条，不是因为框架知道“模型需要 20 条”，而是因为工具返回的 50 条数据按 JSON 序列化后，总字符数超过了框架默认阈值，而截断刚好从第 20 条记录的中间位置落下。

我实际量了一下这组数据的长度。50 条 JSON 序列化后大约是 9800 个字符，而框架默认阈值是 4000 个字符。前 20 条完整记录加上第 21 条的前半段，大约凑到 3998 个字符，被硬生生切掉后面 5800 多个字符。

也就是说，这个框架对工具结果的保护阈值是 4000 字符，对应到我们这批数据，恰好约等于 20 条。如果阈值是 8000，我们看到的可能就是 40 条；如果单条记录更长，可能只能看到 10 条。这个数字只是结果，不是原因。

在实际排查中，当你不确定框架是否有类似阈值时，可以用一个简单方法验证：拿同样数据分别用手工构造消息直连模型和走 Agent 框架调用模型，对比两次模型输入的消息体中工具消息的长度差异。一次就能定位截断发生在框架层还是模型层。

3.3 模型侧的表现：它为什么会“信任”这 20 条

模型只看到 20 条数据后，并没有怀疑数据是不完整的，反而直接基于这 20 条做了分析。这背后有一个很容易被忽视的机制：指令微调模型在长时间训练中形成了一种“工具返回什么就信什么”的倾向。

对于大多数主流指令微调模型来说，工具调用格式在训练数据里往往是以“工具返回的 JSON 就是全部事实”的模式出现的。模型很自然地假设工具结果是完整、准确、未经裁剪的。如果你给它一个语法上完整但内容残缺的 JSON，它不会主动去猜“这里是不是被截了”，而是会顺着内容去总结。

这不算模型的“锅”，而是 Agent 框架作为中间层没有尽到告知义务。框架层面的数据完整性问题，模型是无从感知的。

4. 修复方案：如何根治这类“静默截断”

4.1 短期修复：调大阈值或关闭截断

最直接的修复是把框架的截断阈值调大。如果单次工具返回的数据量可控，直接把阈值设到远高于实际最大返回长度就行。例如我们的场景，阈值从 4000 调到 20000，一次性解决问题。

操作起来很简单，在框架配置里加一行：

agent_config = { "tools": [...], "max_tool_response_length": 20000, # 按实际最大返回长度估算 "truncate_tool_response": True, # 关闭则设为 False }

但我必须提醒一句：调大阈值不等于根治。如果哪天工具有一次返回了 20 万字符，这个方案就又失效了。更合理的方式是按具体业务场景评估“最大可能返回长度”，留出 1.5 倍余量再设阈值。

如果框架允许直接关闭截断，那就要结合上下文窗口来评估风险。以这个项目的模型为例，上下文窗口 8K tokens，约合 24000 字符左右。单条工具消息设定 20000 字符，再加上系统提示词、历史对话、用户问题，仍然可能超出窗口。所以短期方案虽然立竿见影，但本质上是在“赌数据量不会超过设计上限”。

4.2 中期修复：框架层增加截断标记与统计信息

如果框架支持自定义截断行为，强烈建议在截断后的消息里追加一段显式标记，让模型感知到数据不完整。比如截断后改为：

{"data": [...], "truncated": true, "original_count": 50, "returned_count": 20}

这样模型在做总结时，至少有机会意识到“工具返回的是部分数据”。在实测中，加入这个标记后，模型通常会在回答里明确写出“数据可能存在截断，分析基于前 20 条记录”，比完全静默的版本靠谱得多。

但这里也有一个权衡：如果截断标记本身也让模型分心，比如模型开始纠结数据不完整而拒绝分析，这会带来新的交互问题。我的做法是在系统提示词里加一条规则：当工具结果带有截断标记且用户没有明确要求完整统计时，模型先基于现有数据给出初步结论，并在结论末尾注明数据范围。这样既不阻塞流程，又保留了透明度。

4.3 长期方案：重新设计工具返回策略

真正从根上解决问题，不能只靠“截断时打个招呼”，而是要减少单次工具返回的数据量，从设计上让截断变得不必要。

针对我们这个场景，工具返回 50 条数据给模型本来就不是一个合理的用法。模型拿这 50 条原始记录逐条分析，既消耗大量上下文，又不会带来更深入的理解。更合理的做法是让工具在返回原始数据之前先做一轮聚合分析，比如：

• 返回汇总统计：总数、均值、最大值、最小值、分布
• 返回关键抽样：Top 5、异常样本
• 把数据库层面的聚合交给工具，而不是把原始数据全部塞给模型

重构之后，工具返回给模型的消息从 9800 字符降到了不到 1000 字符，原来的“截断保护”机制基本派不上用场了。这个方向才是长远之道——不是想办法在截断时告诉模型“数据少了”，而是让模型根本不需要面对那么多原始数据。

5. 防止复发：给 Agent 加上“数据完整性护栏”

5.1 建立消息级完整性校验

经过这次事故，我在项目里加了一个强制校验环节：当框架拿到工具返回结果后，处理流程变成三件套——解析 JSON、断言数据集长度与源端一致、再组装进消息。

如果是流式接口或 WebSocket 推送，校验逻辑要放在数据落地端。我的做法是在数据写入缓冲队列时加一个 counter，流结束之后对比声明数量与实际数量，不一致就触发告警，同时把请求链路 ID 打印在日志里。

举个例子，代码层面大致是这样：

def process_tool_response(raw_text: str, expected_count: int | None = None): parsed = json.loads(raw_text) actual_count = len(parsed.get("data", [])) if expected_count is not None and actual_count != expected_count: logger.warning(f"数据量不一致: expected={expected_count}, actual={actual_count}") # 触发告警或标记消息 parsed["_truncation_warning"] = True return parsed

这里expected_count可以来自业务上下文，比如分页接口的 total 字段。没有预期值时，就把解析出来的数组长度作为 baseline，至少能判断 JSON 是否完整解析。如果框架做了截断，这一步往往不会走到——因为截断可能发生在 JSON 解析之前——所以校验放在框架更底层会更保险。

5.2 测试用例里加入“截断回归”场景

这次能快速定位问题，很大程度上是运气好——同事注意到了模型回答里“20 条”这个具体数字。如果模型没有明确说出条数，而是直接基于残缺数据给出错误结论，排查难度会成倍增加。

我在测试集里专门加了一个“超长工具返回”的回归用例：模拟工具返回 80 条记录，断言框架存入消息的每条记录 ID 都在预期集合中，且消息长度不超过窗口限制。只要这个用例不过，发布流水线直接卡住，不再允许“带病上线”。

这类测试在普通单元测试里往往遗漏，很多人只测“返回正常短结果”的路径，罕见的长返回路径反而是最容易出静默 bug 的地方。测试数据本身也要有代表性，比如单条记录偏长、JSON 嵌套偏深、数组位于 JSON 顶层或嵌套多层的情况都覆盖到。

5.3 建立可观测指标：跟踪模型实际接收的数据量

运维层面，我加了一个核心指标：agent_tool_response_char_count和agent_tool_item_count，以及agent_model_input_truncated_ratio。

每次 Agent 调用工具并把结果拼进消息时，统计字符数和条数；模型调用结束后，统计实际发给模型的输入长度与最大窗口长度的比值。当这个比值接近 1 时，意味着上下文使用率即将打满，即使框架没有截断，真实调用模型的 API 也可能在更底层做截断。

有了这三个指标，再做一张简单的仪表盘：折线图横轴是时间，纵轴是每个请求的truncated_ratio，高于安全阈值就标红。这套东西部署后，第二个星期就抓到过一次——某个数据分析工具在某时段返回了异常超大结果集，虽然这次因为阈值调大没有截断，但在日志里能看到延时明显上涨，提示我们该优化工具查询逻辑了。

5.4 日志完整性与审计：Reproducing 必备条件

每次排查这类问题，我最大的感受是：如果日志里缺少关键节点输出，排查就变成盲人摸象。在这次事故里，真正让整个链路清晰起来的，是那把透传日志打开了。建议所有 Agent 项目都确保以下三个节点有可持续观察的日志：

1. 工具调用前：打印入参、预期数据量级
2. 工具返回后：打印原始响应长度、条数、是否发生截断
3. 模型调用前：打印最终消息组装后的总字符数、最后一条消息长度、token 估算值

这三条日志的完整链路，能在一分钟之内判断截断发生在哪一层。如果工具返回后日志显示 50 条，但模型调用前日志显示 20 条，问题一定在框架组装环节。这次事故就是靠这个“三节点对比”法快速锁定的。

6. 踩坑总结与排查速查表

这类“静默截断”在 Agent 开发里其实很常见，表现形式五花八门，但底层原因无非那几类。我把它们整理成一张速查表，以后遇到类似问题可以直接对着查：

第一行说的是工具调用方自身的 HTTP 层。有的 HTTP 客户端为了“安全”，会对响应体做最大读取限制，但连接已正常关闭，不报错。这种问题更难发现，因为源端、服务端、框架日志全都正常，只有内存里的字符串被截了。

模型 API 网关的静默截断在自建或第三方托管服务中也存在，表现为请求体可以发送成功，但服务端拿到的 payload 内容不完整，常见于 API Gateway 对请求体大小有默认限制时。这套速查表的思路核心是：不要轻信任何单一节点的日志输出，必须从源端到模型端做首尾对比。

7. 最后说几句

这个问题的本质不是“模型笨”，也不是“框架烂”，而是 Agent 链路里多了一个容易被忽略的中间层，它的默认行为在特殊数据量下产生了负面效果。

我个人体会最深的一点是：Agent 开发里，任何主动修改数据的隐式逻辑都可能成为定时炸弹。截断、去重、改写、压缩、格式转换，这些功能单看都在解决某个问题，但如果没有显式通知下游消费者，一旦触发，就是一个个静默陷阱。

建议所有做 Agent 的同学翻一下自己框架的默认配置，重点检查有没有类似max_tool_response_length、truncate、max_message_size这样的参数。确认它的值和你业务里的最大数据量是否匹配，同时在测试里专门覆盖异常大返回的场景，别只测正常路径。

如果这篇排查过程的记录，能帮你省掉一个下午的抓耳挠腮，那我的分享就没白写。遇到类似问题，欢迎在评论区交流，特别是那些截断位置不在常规三节点的情况，往往一聊就能碰撞出新的排查思路。