症状
API 返回错误信息提示输入长度超过模型的最大上下文窗口（如 context_length_exceeded 或 maximum context length）。具体表现为：
- 长文档处理或多轮对话在积累到一定长度后突然失败。
- 错误信息中通常包含当前 Token 数与模型上限的具体数值对比。
- 同一请求在缩短输入后可以正常完成。
常见原因
- 会话历史无截断：多轮对话中持续追加历史消息，Token 总量逐轮累积最终超限。
- 系统提示词过长：包含大量背景信息或规则的系统提示词占据了过多上下文空间。
- RAG 注入过量：检索增强生成流程中一次注入了过多的参考文档片段。
- Token 计算偏差：客户端使用的 Token 计数器与服务端实际使用的 tokenizer 版本不一致。
排查步骤
- 使用供应商官方的 Token 计数工具（如
tiktoken）精确计算请求中各部分的 Token 数，定位哪个部分占比最大。 - 检查会话管理逻辑，确认是否实现了滑动窗口或摘要压缩策略，将历史消息保持在上下文窗口的 70% 以内。
- 审查 RAG 流程的 Top-K 设置，减少单次注入的文档片段数量，或对检索结果进行二次排序后仅保留最相关的片段。
- 对比客户端 Token 估算值与 API 错误信息中的实际 Token 数，校准本地计数器的准确性。
- 如业务确实需要处理超长输入，评估是否可切换到支持更大上下文窗口的模型版本。
预防
- 在发送请求前实现 Token 预检逻辑，超限时自动触发截断或摘要压缩。
- 为系统提示词设定 Token 上限预算，定期审查并精简冗余内容。
- 实现分层上下文管理：将历史对话中的关键信息提取为摘要，替代原始消息。
- 在 RAG 流程中加入文档片段的 Token 计数，控制注入的总量不超过预设阈值。