API 错误排查
上下文长度超限错误排查
上下文长度超限（context length exceeded）错误排查讲清上下文窗口、输入 Token、输出长度、工具结果、RAG 召回、多轮对话裁剪和 OfApp.cn 接入检查。
context length exceeded 表示一次请求里的输入、历史消息、工具结果、检索片段、 文件内容和预期输出，合计超过了当前模型或接口允许的上下文窗口。它不是“AI 不会回答”，也不一定是模型不可用；更常见的问题是材料塞得太多、对话历史太 长、RAG 召回失控，或输出预算没有给模型留下空间。
排查这类错误，要把“上下文”看成一个有限空间：系统指令、用户问题、文档片 段、代码、日志、工具返回、模型要生成的答案都会占位置。本文示例按 OfApp.cn 的 OpenAI 兼容入口组织；具体模型、上下文长度、端点能力、额度和价格请以 OfApp.cn 控制台或官方文档为准。
| 项目 | 说明 |
|---|---|
| 阅读时间 | 约 7 分钟 |
| 更新时间 | 2026-07-03 |
| 适合读者 | AI 初学者、开发者、产品经理、运营、学生、老师、科研和办公人群 |
| 适合任务 | 长 PDF 总结、会议纪要、代码仓库分析、日志排错、RAG 问答、多轮聊天和自动化办公 |
| 核心方法 | 先缩小输入、历史、工具结果和预期输出，再逐步恢复真实业务上下文 |
| 边界提醒 | 本页不承诺 OfApp.cn 的具体模型、上下文长度、价格、额度、套餐或端点支持范围；请以 OfApp.cn 控制台或官方文档为准 |
上下文长度超限是什么
Section titled “上下文长度超限是什么”上下文窗口是模型一次请求能容纳的总 Token 空间。OpenAI 官方文档说明，上下 文窗口会同时包含输入、输出，以及某些模型用于推理的内部 Token。把长文档、 大量历史消息、工具结果和很长的输出要求放进同一次请求，就可能超过这个空间。
对普通用户来说，可以把它理解成“这次对话包裹太大”。包裹里不仅有你刚发的 问题，也有前面每一轮对话、上传资料、引用片段、表格、日志、代码和你要求 AI 写出的答案长度。
上下文预算拆分表
Section titled “上下文预算拆分表”排查上下文超限时，不要只盯着用户输入。一次请求通常由多个部分共同占用预算， 其中任何一项失控都会把请求推到上限。
| 预算来源 | 常见膨胀原因 | 缩减方式 |
|---|---|---|
| 当前输入 | 粘贴整篇文档、整张表、完整日志 | 只保留本轮问题需要的段落 |
| 历史消息 | 多轮对话原样带入 | 用会话摘要替代旧历史 |
| 系统指令 | 角色、规则和格式重复出现 | 合并成稳定、短小的规则 |
| 工具结果 | 网页正文、大 JSON、数据库多行返回 | 在工具侧过滤字段、分页或截断 |
| RAG 片段 | chunk 过大、topK 过高、相邻段拼太多 | 降低召回数量，保留来源定位 |
| 预期输出 | 一次生成长报告、完整项目或大表格 | 先生成结构，再分段展开 |
| 推理空间 | 复杂任务需要更多内部推理预算 | 缩小任务范围，给输出留余量 |
这张表适合放进产品排查清单、客服工单或开发日志里。只要能判断哪一项在膨胀， 修复就会比“换模型”更可控。
常见触发场景
Section titled “常见触发场景”| 场景 | 典型表现 | 优先处理 |
|---|---|---|
| 长 PDF 或 Word | 上传整份报告后立即失败 | 按章节或页码分段摘要 |
| 会议纪要 | 多份录音转写稿一次总结 | 先提取议题、决议和待办 |
| 代码仓库 | 让 AI 读取整库或完整日志 | 只给相关文件、错误栈和复现步骤 |
| RAG 问答 | 检索结果拼接后超限 | 减少 chunk 数量，压缩片段 |
| 多轮对话 | 前面聊得越多越容易失败 | 摘要旧历史，只保留关键事实 |
| 工具调用 | 工具返回大 JSON、大表格或网页正文 | 工具侧先过滤、分页、提取字段 |
| 输出要求 | 要求一次生成长报告、长表格、完整方案 | 拆成大纲、章节和复核轮次 |
怎么判断是上下文超限
Section titled “怎么判断是上下文超限”先不要急着换模型。把错误和请求拆开看：
| 信号 | 更像上下文超限 | 更像其他问题 |
|---|---|---|
| 错误文本 | 出现 context length exceeded、maximum context length、too many tokens |
出现 401、403、404、rate limit |
| 触发条件 | 输入越长越容易失败 | 短输入也稳定失败 |
| 缩短材料后 | 请求恢复 | 仍然失败 |
| 多轮聊天 | 新会话可用，长会话失败 | 所有会话都失败 |
| RAG 场景 | 减少召回片段后恢复 | 检索前就失败 |
如果短请求能成功，长请求失败，优先按上下文处理。如果短请求也失败，再回到 鉴权、Base URL、模型名、端点路径、权限、限流和服务端错误排查。
最小请求复现
Section titled “最小请求复现”用最小请求确认接口、Key、Base URL 和端点本身可用，再把真实上下文一点点
加回去。OfApp.cn 官方文档展示的 OpenAI 兼容 Base URL 是
https://api.ofapp.cn/v1，并提供 /v1/responses、
/v1/chat/completions、/v1/images/generations 和 /v1/messages
等端点示例。
export OPENAI_BASE_URL="https://api.ofapp.cn/v1"export OPENAI_API_KEY="sk-xxxx"
curl "$OPENAI_BASE_URL/responses" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "请填入控制台可用模型", "input": "用一句话说明上下文窗口是什么。" }'如果最小请求成功，把真实材料按“单份文档、少量历史、少量检索片段、较短输 出”逐步加回。哪一步开始失败，哪一步就是上下文压力的来源。
上下文由哪些部分组成
Section titled “上下文由哪些部分组成”| 部分 | 例子 | 处理建议 |
|---|---|---|
| 系统或开发者指令 | 角色、约束、输出格式 | 保留稳定规则，删除重复描述 |
| 用户输入 | 当前问题、粘贴材料、表格 | 只保留当前任务需要的信息 |
| 历史消息 | 多轮聊天、前几次回答 | 摘要旧历史，不全量带入 |
| 文件内容 | PDF、Word、Excel、代码 | 按章节、表格或文件分段 |
| 工具结果 | 网页抓取、数据库查询、日志 | 工具侧过滤字段和行数 |
| RAG 片段 | chunk、相邻段落、来源 | 控制 topK 和每段长度 |
| 预期输出 | 长报告、长表格、代码生成 | 拆成多个输出步骤 |
| 推理或中间步骤 | 某些模型内部使用的推理空间 | 给输出留余量，避免预算过紧 |
关键点是：不要只看“输入字数”。工具返回、历史对话和输出长度也会把请求推 向上限。
长文档怎么处理
Section titled “长文档怎么处理”长 PDF、论文、合同、会议转写和报告适合走“分段摘要，再合并”的流程。
| 步骤 | 做法 | 保留什么 |
|---|---|---|
| 分段 | 按章节、页码、标题或自然段切开 | 页码、标题、来源 |
| 局部摘要 | 每段提炼结论、证据、数字、待确认点 | 原文定位和不确定性 |
| 合并 | 把局部摘要合成总览 | 冲突、重复、缺口 |
| 追问 | 针对某个结论回到原文段落 | 可追溯材料 |
推荐 Prompt：
你将收到一段长文档的第 3 部分。请只基于本段内容输出：1. 关键结论2. 重要数字和条件3. 需要回看原文的位置4. 与前文可能冲突的地方
不要补充本段没有出现的信息。多轮对话怎么裁剪
Section titled “多轮对话怎么裁剪”多轮聊天最容易把旧内容越带越多。裁剪历史时，不要只保留最近几轮，也不要把 全部历史原样塞回请求。更稳的做法是维护一份“会话状态摘要”。
| 保留 | 可以删除或压缩 |
|---|---|
| 用户目标、约束、已确认事实 | 闲聊、重复解释、已经作废的方案 |
| 关键决策和原因 | 中间试错过程 |
| 文件路径、字段名、接口名 | 完整日志和完整返回体 |
| 待办、风险、开放问题 | 已经解决的错误栈 |
会话摘要可以固定成这种结构：
当前任务：已确认事实：用户偏好：已排除方案：待验证问题：下一步只需要的材料：RAG 和知识库怎么避免超限
Section titled “RAG 和知识库怎么避免超限”RAG 不是把资料全塞给模型，而是把最相关、最短、可追溯的片段放进上下文。
| 控制点 | 常见问题 | 改法 |
|---|---|---|
| chunk 太大 | 一个片段含多个主题 | 按标题、段落、表格边界切分 |
| topK 太高 | 召回很多相似片段 | 先取少量，再按需要扩展 |
| 相邻片段过多 | 为了保留上下文拼接过长 | 只保留命中段前后一小段 |
| 没有重排 | 相关性弱的片段进入上下文 | 加重排或规则过滤 |
| 没有来源 | 输出难以复核 | 每段带标题、页码或 URL |
| 用户问题太宽 | 检索范围过大 | 先让用户缩小问题或拆任务 |
如果你在 OfApp.cn 上接入检索、向量化或文件相关能力，具体端点状态和可用范 围请以 OfApp.cn 控制台或官方文档为准。
输出长度也要控制
Section titled “输出长度也要控制”很多人只压缩输入，却要求一次生成很长的报告。输出也要占上下文空间。OpenAI
Responses API 里可以通过 max_output_tokens 控制输出上限；当输出达到限
制时，响应可能出现 incomplete_details.reason = "max_output_tokens"。
| 任务 | 不推荐 | 推荐 |
|---|---|---|
| 写报告 | 一次生成完整长报告 | 先生成大纲，再逐章生成 |
| 写代码 | 一次生成整个项目 | 先生成文件清单，再逐文件修改 |
| 总结资料 | 一次总结所有材料 | 先分段摘要，再合并 |
| 做 PPT | 一次生成全部页面文案 | 先定结构，再写每页内容 |
生产环境怎么预防
Section titled “生产环境怎么预防”| 位置 | 建议记录 | 注意事项 |
|---|---|---|
| 请求入口 | 文档数量、消息轮数、检索片段数 | 不记录原始敏感内容 |
| 模型调用 | 输入长度估算、输出上限、端点 | 日志里隐藏 API Key |
| RAG 层 | topK、chunk 长度、来源数量 | 支持按来源回放 |
| 工具层 | 返回字段、行数、字节大小 | 工具返回先截断再入模 |
| 用户界面 | 提示用户材料过长 | 给出分段上传和摘要选项 |
| 告警 | 同一任务反复超限 | 引导到分段流程 |
上线前可以做三组压力测试：
| 测试 | 目的 |
|---|---|
| 短输入 | 验证 Base URL、Key、模型和端点 |
| 中等输入 | 验证真实任务的普通规模 |
| 极长输入 | 验证裁剪、摘要、错误提示和兜底路径 |
和其他错误怎么区分
Section titled “和其他错误怎么区分”| 错误 | 核心含义 | 应该先看 |
|---|---|---|
context length exceeded |
单次上下文太大 | 输入、历史、工具结果、输出长度 |
429 Rate Limit |
请求频率或额度限制 | 并发、退避重试、quota |
insufficient quota |
可用额度不足或项目受限 | 控制台、Key 归属、请求成本 |
model not found |
模型名不可用或端点不匹配 | 模型名、模型类型、控制台范围 |
400 Bad Request |
请求体结构或参数错误 | JSON、字段类型、端点要求 |
上下文超限通常不适合盲目重试。更有效的重试条件是：请求已经变小、历史已经 压缩、RAG 片段已经减少，或输出任务已经拆开。
OfApp.cn 接入检查
Section titled “OfApp.cn 接入检查”使用 OfApp.cn 时，可以按这张表检查：
| 检查项 | 建议 |
|---|---|
| Base URL | OpenAI 兼容入口按官方文档使用 https://api.ofapp.cn/v1；如果某个工具会自动拼 /v1，按工具说明调整 |
| API Key | 不要把真实 Key 写进网页、截图、日志、Issue 或公开仓库 |
| 端点 | Chat、Responses、Images、Claude Messages 等端点能力以 OfApp.cn 官方文档和控制台为准 |
| 模型 | 页面示例不要硬编码未确认模型名；生产代码从配置或控制台选择 |
| 长文档 | 先在客户端或服务端分段，再调用 API |
| 错误提示 | 给用户返回“材料过长，请分段或摘要”，不要只显示原始报错 |
自然的工作流是：用 OfApp.cn 跑通最小请求，再把长材料处理、摘要、检索和多 轮状态管理放在你的应用层。
- OpenAI Conversation state：说明上下文窗口包含输入、输出，以及某些模型的推理 Token，并建议使用 tokenizer 工具估算 Token。
- OpenAI Reasoning models：说明输出或推理预算不足时可能出现
incomplete与max_output_tokens。 - OpenAI Responses API Reference：列出
input、instructions、max_output_tokens与incomplete_details等字段。 - OpenAI Compaction：说明长会话可通过压缩上下文保留后续需要的状态。
- OfApp.cn 首页：用于核对 OfApp.cn 当前公开的 OpenAI、Claude、GPT Image、Codex、API Key、Base URL 和天才游乐场入口。
- OfApp.cn API 文档：用于核对 OfApp.cn 公开的
/v1、Bearer 鉴权、Models API、Responses、Chat Completions、Images、Embeddings 和 Messages 示例。 - OfApp.cn 天才游乐场：用于区分网页体验入口和 API Key 接入排查路径；具体模型、上下文长度、能力、额度和价格请以 OfApp.cn 控制台或官方文档为准。
context length exceeded 是什么意思？
Section titled “context length exceeded 是什么意思？”它表示这次请求放入模型的上下文太大。上下文包括当前问题、历史消息、文档、 工具返回、检索片段和输出预算，不只是你刚输入的那句话。
换更大上下文的模型就能解决吗？
Section titled “换更大上下文的模型就能解决吗？”可能缓解，但不能替代上下文管理。长材料仍然需要分段、摘要、检索和来源复核； 模型上下文越大，单次请求也越需要成本、延迟和日志控制。
max tokens 调大可以修复吗？
Section titled “max tokens 调大可以修复吗？”要看是哪一类限制。输出被截断时，适当调大输出上限可能有帮助；输入和历史已 经占满上下文时，调大输出上限反而会让请求更重。先压缩输入，再调整输出。
为什么短问题正常，上传 PDF 就失败？
Section titled “为什么短问题正常，上传 PDF 就失败？”短问题只占很少上下文。PDF、Word、会议转写和长表格会把大量文本放进请求。 更稳的做法是按章节或页码分段摘要，再合并结果。
RAG 已经用了检索，为什么还会超限？
Section titled “RAG 已经用了检索，为什么还会超限？”检索只负责找片段，不自动保证片段足够短。如果 chunk 过大、topK 过高、相邻 片段拼接过多，进入模型的上下文仍然会超限。
Codex 或代码助手遇到这个错误怎么办？
Section titled “Codex 或代码助手遇到这个错误怎么办？”不要让它一次读取整个仓库。提供目标、相关文件、错误命令、最近改动和验证方 法；旧对话用摘要代替，日志只保留关键错误栈和复现步骤。
- AI 基础教程：理解 Token、上下文、Prompt 和 RAG。
- 用 AI 总结 PDF：把长文档拆成可复核的摘要流程。
- 总结 Prompt：为长材料设计分段摘要模板。
- Embeddings 与 RAG 检索示例：理解检索如何减少上下文压力。
- Chat Completions 示例：管理 messages 历史和输出长度。
- Responses API 示例：理解 input、输出、流式和多轮上下文。
- 429 Rate Limit 错误排查：区分限流和上下文超限。
上下文长度超限的本质是上下文预算管理失败。可靠修复不是把全部资料 塞给模型，而是把任务拆小：压缩历史、分段文档、控制 RAG、限制输出、记录用 量，再用最小请求逐步恢复真实场景。使用 OfApp.cn 接入时，接口、模型、能力 和额度以控制台或官方文档为准。