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超限行为是否报错是否可配置OpenAI Chat Completions报错context_length_exceeded是需自行截断Anthropic Claude报错prompt is too long是需自行截断LangChain默认截断尾部可配置否可配置max_tokensLlamaIndex默认截断可配置否可配置自研 Agent 框架取决于实现常见静默截断否需自行加日志从表里可以看出官方 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(fPrompt 字符数: {len(prompt)}) print(fPrompt 前 500 字符: {prompt[:500]}) print(fPrompt 后 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_tokens8192): 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_size15): results [] for i in range(0, len(records), batch_size): batch records[i:ibatch_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_tokens8192): 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 或换更大窗口的模型。防御措施实现成本效果显式 token 检查低防止静默截断分批处理中彻底解决超限摘要压缩中高减少 token 消耗Token 预算与监控中长期预防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 常见问题速查表现象可能原因排查方法连续丢失尾部数据上下文超限尾部截断打印 prompt 尾部计算 token随机丢失数据并发问题或数据竞争检查并发写入和锁换大窗口模型仍丢失框架 max_tokens 未调整检查框架配置流式输出中途停止输出 token 超限检查 max_output_tokens多轮对话后期失忆历史累积超限检查历史消息 token 数提示排查这类问题时最有效的习惯是在调用 LLM 前后都打印关键信息输入 token 数、输出 token 数、是否截断、实际使用的模型和窗口大小。这些日志在事后复盘时价值极高。7. 我在这次排查中的几点体会这次排查花了我大半天时间但收获远超预期。最大的体会是不要信任任何“自动”行为。框架自动截断、自动重试、自动降级这些设计在 demo 阶段很友好在生产阶段就是隐患。你必须知道每一层到底做了什么尤其是涉及 token 和上下文的地方。另一个体会是Token 计算要精确不能靠猜。我一开始用字符数除以 4 估算结果低估了 30% 的 token 数导致误判。后来用 tokenizer 精确计算问题立刻清晰。如果你经常做 LLM 应用建议把 token 计算封装成工具函数随时调用。最后分批处理虽然土但真的稳。我现在处理大批量数据时默认就是分批加显式 token 检查不再依赖框架的自动截断。这样虽然多写几行代码但换来的是可预测、可观测、可复现的结果。如果你也在做 Agent 开发不妨从下一次调用开始加上 token 日志和超限告警你会发现很多“玄学问题”其实都有明确的工程解释。