Agent数据静默丢失？上下文截断排查与防御实战

1. 一次诡异的“数据消失”事件

那天下午，我在调试一个基于 Agent 的数据处理流程。源端数据库里明明躺着 50 条待处理记录，Agent 跑完一圈回来，只处理了 20 条。没有报错，没有异常日志，没有超时提示，就像那 30 条记录从未存在过一样。我盯着屏幕愣了几秒，第一反应是查询条件写错了，第二反应是分页逻辑有 bug，第三反应才意识到——这大概率是上下文截断在作祟。

如果你正在做 Agent 开发、LLM 应用落地，或者任何涉及大模型上下文窗口的工程实践，这个问题你迟早会撞上。它不像接口报错那样直白，也不像超时那样有明确信号，它更像一个“静默杀手”：模型只看到了你喂给它的部分内容，剩下的被悄悄丢掉了，而你和模型都不知道。这篇文章就是把我这次排查的完整过程拆开，从现象到根因，从定位手段到修复方案，再到如何建立防御机制，全部讲清楚。不管你是刚接触 Agent 的新手，还是已经踩过几次坑的老手，都能从这次排查里拿到可以直接复用的思路和代码。

2. 问题现象与初步定位

2.1 源端 50 条，模型只看到 20 条的具体表现

先还原一下现场。我的 Agent 流程大致是这样的：从数据源读取一批记录，每条记录包含若干字段，拼接成一段文本后作为上下文传给 LLM，让模型对每条记录做分类和摘要。源端查询返回了 50 条记录，我甚至在代码里打印了len(records)，确认是 50。但模型最终输出的结果只有 20 条，而且不是随机丢的，是从第 21 条开始全部消失。

这个“从某一条开始连续消失”的特征非常关键。如果是随机丢失，可能是并发写入或者数据竞争；如果是首尾丢失，可能是分页或者切片问题；但连续截断，基本可以锁定是上下文长度超限后触发了某种截断策略。LLM 的上下文窗口是一个硬限制，比如 8K、32K、128K token，当输入超过这个限制时，不同的框架和 API 有不同的处理方式：有的直接报错，有的截断尾部，有的截断中间，有的甚至只保留系统提示词和最后几条消息。

2.2 为什么“静默截断”比报错更危险

报错至少会告诉你“出问题了”，静默截断最可怕的地方在于：它让系统看起来是正常的。你的 Agent 跑完了，返回了结果，日志没有 ERROR，监控没有告警，但结果是不完整的。如果这是一个生产环境的数据处理任务，你可能基于不完整的数据做出错误决策；如果这是一个对话系统，用户会莫名其妙地发现模型“失忆”了。

我后来复盘时发现，这次截断之所以静默，是因为我用的 Agent 框架在拼接上下文时，对超出窗口的部分做了自动截断，但没有抛出任何异常，也没有在返回结果里标记“输入被截断”。这种设计在框架层面可能是为了“优雅降级”，但在业务层面就是灾难。所以第一条经验：任何自动截断都必须有显式日志或返回值标记，否则你永远不知道模型到底看到了多少。

2.3 快速判断是否为上下文截断的三个信号

在深入排查之前，你可以先用这三个信号快速判断问题是否属于上下文截断：

• 信号一：丢失是连续的，不是随机的。比如前 20 条有结果，后 30 条完全没有，而不是第 3、7、15 条丢失。
• 信号二：输入 token 数接近或超过模型窗口上限。你可以用 tokenizer 粗略估算输入长度，如果接近 8K、32K、128K 这些常见阈值，嫌疑就很大。
• 信号三：换一个更长的上下文模型后问题消失。比如从 8K 模型换到 128K 模型，50 条全部处理成功，那基本可以确认是窗口限制导致的截断。

这三个信号我当时全中了。尤其是第三个，我临时换了一个更大窗口的模型跑了一遍，50 条全部返回，问题瞬间定位。

3. 深入根因：上下文窗口与 Token 计算

3.1 LLM 上下文窗口到底是什么

上下文窗口（Context Window）是 LLM 在一次推理中能够“看到”的最大 token 数量。你可以把它想象成模型的工作台面：台面就那么大，你放上去的材料不能超过台面面积，超出的部分要么放不下，要么被挤掉。这个台面包括你输入的提示词、系统指令、历史对话、工具调用结果，以及模型自己生成的输出。

不同模型的窗口大小差异很大。早期模型常见 4K、8K，后来 32K、128K 逐渐普及，现在一些模型已经支持 200K 甚至 1M token。但注意，窗口大不等于不会截断，只是阈值更高。如果你的输入是 500 条记录，即使 128K 窗口也可能不够。而且窗口越大，推理成本和延迟通常越高，所以不能无脑选最大窗口。

3.2 Token 不是字符：中文、英文、代码的 token 差异

很多人第一次做 token 估算时会犯一个错误：用字符数除以 2 或除以 4 来粗略估计 token 数。这个方法在英文纯文本上勉强可用，但在中文、代码、JSON 结构上误差很大。

以中文为例，一个汉字通常对应 1 到 2 个 token，具体取决于 tokenizer。英文单词可能被拆成多个 subword token，比如 “tokenization” 可能变成 “token” + “ization” 两个 token。代码里的缩进、括号、换行符也都会消耗 token。JSON 格式因为有很多引号、冒号、逗号，token 密度更高。

我当时的输入是每条记录拼接成一段 JSON 风格的文本，50 条记录大约产生了 12000 多个 token，而我用的模型窗口是 8K。也就是说，从第 20 条左右开始，后面的内容已经超出了窗口，被框架自动截断了。

3.3 不同框架的截断策略对比

这里我整理了几种常见框架和 API 的截断行为，方便你对照自己用的工具：

从表里可以看出，官方 API 通常更“诚实”，超限直接报错；而一些封装框架为了“用户体验”，会默默截断。这就是为什么我这次遇到的问题没有报错——我用的框架在拼接上下文时做了自动截断，但没有告诉我。

提示：如果你在用封装框架，一定要去读它的上下文拼接源码，确认超限时的行为是报错、截断还是丢弃。不要假设它会报错。

4. 排查过程实录：从日志到代码

4.1 第一步：确认源端数据确实有 50 条

排查任何“数据丢失”问题，第一步永远是确认数据源。我在查询后立刻打印了记录数和前几条内容：

records = fetch_records(query) print(f"源端记录数: {len(records)}") print(f"第一条: {records[0]}") print(f"最后一条: {records[-1]}")

输出确认是 50 条，首尾都在。这一步排除了查询条件、分页、数据库连接等问题。很多人会跳过这一步直接怀疑模型，但我的经验是：先证明输入是完整的，再去怀疑模型和框架。

4.2 第二步：打印实际传给模型的 Prompt

接下来我在调用 LLM 之前，把最终拼接好的 prompt 完整打印出来，并统计字符数和粗略 token 数：

prompt = build_prompt(records) print(f"Prompt 字符数: {len(prompt)}") print(f"Prompt 前 500 字符: {prompt[:500]}") print(f"Prompt 后 500 字符: {prompt[-500:]}")

这一步非常关键。我发现 prompt 的后 500 字符里，最后一条记录只到第 20 条左右，后面的记录根本没有出现在 prompt 里。也就是说，截断发生在 build_prompt 阶段，而不是模型推理阶段。框架在拼接时就已经把超出部分丢掉了。

4.3 第三步：用 Tokenizer 精确计算输入长度

为了确认是不是窗口限制导致的，我用对应模型的 tokenizer 精确计算了完整输入的 token 数：

from transformers import AutoTokenizer tokenizer = AutoTokenizer.from_pretrained("模型对应的tokenizer") full_text = build_full_text(records) # 不截断的完整文本 tokens = tokenizer.encode(full_text) print(f"完整输入 token 数: {len(tokens)}") print(f"模型窗口大小: 8192") print(f"是否超限: {len(tokens) > 8192}")

结果完整输入是 12300 多个 token，远超 8K 窗口。而截断后的 prompt 大约是 7800 token，刚好卡在窗口边缘。这就解释了为什么是 20 条：前 20 条拼接后大约 7800 token，第 21 条开始就超了。

4.4 第四步：定位框架中的截断代码

确认是截断后，我去翻了框架的源码，找到了类似这样的逻辑：

def build_context(messages, max_tokens=8192): total = count_tokens(messages) while total > max_tokens: messages.pop() # 从尾部删除 total = count_tokens(messages) return messages

这段代码从尾部不断弹出消息，直到总 token 数低于上限。它没有日志，没有返回值标记，所以调用方完全不知道发生了截断。这就是“静默截断”的源头。

注意：很多框架的截断策略是“删尾部”或“删中间”，不同策略对结果的影响不同。删尾部会导致后面的数据完全丢失，删中间可能导致上下文不连贯。你需要根据业务场景选择或自定义截断策略。

5. 解决方案：从临时修复到系统防御

5.1 临时方案：分批处理与滑动窗口

最直接的修复是把 50 条记录分批处理，每批控制在窗口限制内。比如每批 15 条，分 4 批跑完，最后合并结果。这就是分批处理（Batching）的思路。

def batch_process(records, batch_size=15): results = [] for i in range(0, len(records), batch_size): batch = records[i:i+batch_size] prompt = build_prompt(batch) result = call_llm(prompt) results.extend(result) return results

分批的优点是实现简单，缺点是批次之间没有上下文关联，如果任务需要跨记录推理，效果会打折扣。另一个变体是滑动窗口：每次处理一部分，但保留上一批的部分内容作为上下文，适合需要连续性的场景。

5.2 进阶方案：摘要压缩与分层上下文

如果业务要求必须一次性看到所有记录，可以考虑摘要压缩：先用一个模型对每条记录生成简短摘要，再把摘要拼接起来传给主模型。这样 token 数会大幅下降。

def summarize_records(records): summaries = [] for record in records: summary = call_llm(f"用一句话总结: {record}") summaries.append(summary) return summaries summaries = summarize_records(records) final_prompt = build_prompt(summaries) # 摘要后的 token 数远小于原始

这种方案适合“记录内容长但关键信息少”的场景。如果每条记录本身就很短，摘要压缩的收益不大，反而增加了一次模型调用成本。

5.3 根本方案：显式截断检测与告警

无论用哪种处理策略，显式检测和告警都是必须的。我在修复时加了一个装饰器，在每次调用 LLM 前检查 token 数，超限就记录日志并抛出异常：

def check_context_limit(prompt, max_tokens=8192): token_count = count_tokens(prompt) if token_count > max_tokens: logger.warning(f"上下文超限: {token_count}/{max_tokens}, 将被截断") raise ContextLimitExceeded(f"输入 {token_count} token 超过限制 {max_tokens}") return prompt

这样至少不会静默失败。更进一步，可以在返回结果里附带truncated: true标记，让上层业务知道结果可能不完整。

5.4 工程化防御：Token 预算与监控

在工程层面，我建议给每个 Agent 流程设置token 预算：预估输入、输出、工具调用各占多少 token，留出安全余量。比如窗口 8K，输入预算 5K，输出预算 2K，留 1K 给系统提示和意外情况。

同时加监控：记录每次调用的输入 token 数、输出 token 数、是否接近上限。如果发现某类请求经常接近上限，就要考虑优化 prompt 或换更大窗口的模型。

6. 常见问题与避坑指南

6.1 为什么换了更大窗口的模型还是丢数据

有一次我以为换成 128K 窗口就万事大吉，结果 500 条记录还是只处理了 300 条。原因是：窗口大了，但框架的默认 max_tokens 没改。很多框架有一个独立的max_tokens参数，默认值可能还是 8K 或 16K，不会自动跟随模型窗口。你需要手动把这个参数调到和模型窗口匹配的值。

6.2 系统提示词和工具定义也占 token

排查时容易忽略的是：系统提示词、工具定义、few-shot 示例、历史对话，这些都会占用 token。我那次 12300 token 里，大约有 1500 token 是系统提示和工具定义。所以计算可用空间时，要用窗口大小 - 系统开销 - 输出预留，剩下的才是给业务数据的。

6.3 流式输出下的截断更难发现

如果用的是流式输出（streaming），截断可能表现为“输出到一半突然停止”。用户看到的是不完整的回答，但 API 可能返回了正常的结束标记。这种情况下，你需要在客户端检查输出是否完整，比如看最后一个 token 是否是结束符，或者对比预期输出长度。

6.4 多轮对话中的上下文累积

多轮对话场景下，每一轮都会把历史消息拼进去，token 数会不断累积。如果不做清理，几轮之后就会超限。常见做法是保留最近 N 轮，或者对历史做摘要。我一般会设置一个“历史 token 上限”，超过就从最旧的消息开始删。

6.5 常见问题速查表

提示：排查这类问题时，最有效的习惯是在调用 LLM 前后都打印关键信息：输入 token 数、输出 token 数、是否截断、实际使用的模型和窗口大小。这些日志在事后复盘时价值极高。

7. 我在这次排查中的几点体会

这次排查花了我大半天时间，但收获远超预期。最大的体会是：不要信任任何“自动”行为。框架自动截断、自动重试、自动降级，这些设计在 demo 阶段很友好，在生产阶段就是隐患。你必须知道每一层到底做了什么，尤其是涉及 token 和上下文的地方。

另一个体会是：Token 计算要精确，不能靠猜。我一开始用字符数除以 4 估算，结果低估了 30% 的 token 数，导致误判。后来用 tokenizer 精确计算，问题立刻清晰。如果你经常做 LLM 应用，建议把 token 计算封装成工具函数，随时调用。

最后，分批处理虽然土，但真的稳。我现在处理大批量数据时，默认就是分批加显式 token 检查，不再依赖框架的自动截断。这样虽然多写几行代码，但换来的是可预测、可观测、可复现的结果。如果你也在做 Agent 开发，不妨从下一次调用开始，加上 token 日志和超限告警，你会发现很多“玄学问题”其实都有明确的工程解释。