先别急着怀疑模型。“源端有 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 的 128K，API 可能返回 400 错误，也可能在某些网关层被截断。但正规模型 API 一般不会默默悄悄截断，多数会报错。真正要留意的是那些“中转层”和自建的代理网关。

我这次用的模型 API 上下文窗口是 128K，50 条工具结果加上其他消息大约 20K，远没到上限。所以这个环节可以排除。但排查时不能跳过它，否则你改了一堆上下文管理器配置，最后发现是网关卡住了。

为了保险，我还做了一个最小化验证：把 50 条结果全部作为唯一内容发给模型，没有系统提示词、没有历史对话，结果模型能收到全部 50 条。这就彻底排除了模型窗口因素。

到这一步，完整链路五层已经查了四层，焦点集中在上下文管理器的字符截断逻辑上。排查顺序总结一下：模型输入 → 工具出参 → 序列化 → 上下文组装 → Token 窗口。自上而下，逐层自证。哪个环节的数据和上游不一致，哪个环节就是问题所在。

3. 根因确认：字符数截断遇上中文检索结果

3.1 复现实验：同一输入三份快照对比

确认根因之前，我做了个复现实验，确保不是偶发现象。做法很简单：写一个独立脚本，构造同样的 50 条工具结果，走一遍完整的消息组装流程，然后在三个关键节点分别打点记录：

• 节点 A：工具返回的原始数据，记录条数和字符数。
• 节点 B：序列化并加入消息数组后，记录字符数和条数。
• 节点 C：最终请求体里的工具结果消息，记录字符数和条数。

三个节点全部打印摘要，不打印内容。跑了一遍，数据是这样的：

注意看，节点 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_ascii=False) 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。我这里直接用了模型同款 tokenizer：

import 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_tokens=TOKEN_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, " f"chars={ev['dropped_chars']}, tokens={ev['dropped_tokens']}")

我第一次在日志里看到[TRUNCATION] dropped=30 items的时候，才知道之前的静默有多离谱。如果这个告警能提前一周存在，那次线上问题根本不会发生。

3.4 修复三：让模型自己报告“看不全”

除了在代码层面做防护，我还加了一道人防措施：在系统提示词里加一句话，让模型在发现输入不完整时主动反馈。

这句话的大意是：“工具返回的知识片段可能不完整。如果你发现当前上下文中的相关片段数量少于预期、或者明显缺少回答问题的必要信息，请明确说明‘我没有获得完整信息’，而不是强行作答。”

这个技巧听上去有点简单，但在实际场景里非常有效。模型本身对自己收到的内容有没有感知？没有，它不知道源端是 50 条还是 20 条。但你可以让它对“信息不足”保持敏感，把“部分信息缺失”从静默变成显性反馈。

比如这次修复后，如果未来再出现工具结果被意外截断，模型可能会在回答里明确说：“我只收到了部分片段，无法确认完整答案。” 这样至少运营同事能快速发现问题，而不是带着残缺答案上线一整天。

当然这是一个兜底，不是根治。根治靠的还是上下文管理器的预算分配和审计日志。提示词防御只是让问题更容易暴露，相当于在系统里加了一个“烟雾报警器”。

4. 常见截断场景速查：一张表定位问题环节

4.1 高频静默截断场景定位表

排查完这一次，我把 Agent 链路里常见的静默截断场景整理成了一张速查表，后面再遇到类似问题，先按表定位，效率高很多：

这张表不是万能药，但排查时对照一下，能少走不少弯路。大多数静默截断问题都逃不出这几个场景：条数限制、字符限制、预算分配顺序、序列化丢字段、并行调用合并丢失。

排查时我还有一个刻在脑子里的原则：先把模型实际收到的内容打出来，再往前推。只要确认了“模型收到了什么”，上游每一步都有据可查。最怕从一开始就怀疑模型能力，调 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 技巧都管用。