消息上下文管理

上下文窗口

此功能符合零数据保留（ZDR）的条件。当您的组织签订了 ZDR 协议时，通过此功能发送的数据在 API 响应返回后不会被存储。

随着对话的增长，您最终会接近上下文窗口的限制。本指南解释了上下文窗口的工作原理，并介绍了有效管理上下文窗口的策略。

对于长时间运行的对话和智能体工作流，服务器端压缩是上下文管理的主要策略。对于更专业的需求，上下文编辑提供了额外的策略，例如工具结果清除和思考块清除。

理解上下文窗口

"Context window"（上下文窗口）是指语言模型在生成响应时可以参考的所有文本，包括响应本身。这与语言模型训练所用的大型数据语料库不同，而是代表模型的"工作记忆"。较大的上下文窗口允许模型处理更复杂和冗长的提示，但更多的上下文并不自动意味着更好。随着令牌数量的增长，准确性和召回率会下降，这种现象被称为上下文腐化（context rot）。这使得精心管理上下文中的内容与可用空间的大小同样重要。

Claude 在 MRCR 和 GraphWalks 等长上下文检索基准测试中取得了最先进的结果，但这些成果取决于上下文中的内容，而不仅仅是能容纳多少内容。

如需深入了解长上下文为何会退化以及如何围绕这一问题进行工程设计，请参阅 Effective context engineering（有效的上下文工程）。

下图展示了 API 请求的标准上下文窗口行为¹：

上下文窗口示意图

¹对于聊天界面（例如 claude.ai），上下文窗口也可以设置为滚动的"先进先出"系统。

渐进式令牌累积： 随着对话轮次的推进，每条用户消息和助手响应都会在上下文窗口中累积。之前的轮次会被完整保留。
线性增长模式： 上下文使用量随每个轮次线性增长，之前的轮次会被完整保留。
上下文窗口容量： 总可用上下文窗口（最多 100 万个令牌）代表存储对话历史和生成 Claude 新输出的最大容量。
输入-输出流程： 每个轮次包括：
- 输入阶段： 包含所有先前的对话历史以及当前用户消息
- 输出阶段： 生成文本响应，该响应将成为未来输入的一部分

使用扩展思考时的上下文窗口

使用扩展思考时，所有输入和输出令牌（包括用于思考的令牌）都会计入上下文窗口限制，但在多轮对话场景中存在一些细微差别。

思考预算令牌是 max_tokens 参数的子集，按输出令牌计费，并计入速率限制。使用自适应思考时，Claude 会动态决定其思考分配，因此每个请求的实际思考令牌使用量可能有所不同。

然而，之前的思考块会被 Claude API 自动从上下文窗口计算中剥离，并且不属于模型在后续轮次中"看到"的对话历史的一部分，从而为实际对话内容保留令牌容量。

下图展示了启用扩展思考时的专门令牌管理：

使用扩展思考的上下文窗口示意图

剥离扩展思考： 扩展思考块（以深灰色显示）在每个轮次的输出阶段生成，但不会作为后续轮次的输入令牌向前传递。您无需自行剥离思考块。如果您将它们传回，Claude API 会自动为您执行此操作。
技术实现细节：
- 当您将之前轮次的思考块作为对话历史的一部分传回时，API 会自动排除这些思考块。
- 扩展思考令牌仅在生成时作为输出令牌计费一次。
- 有效上下文窗口计算变为：context_window = (input_tokens - previous_thinking_tokens) + current_turn_tokens。
- 思考令牌包括 thinking 块。

这种架构具有令牌效率，允许进行大量推理而不浪费令牌，因为思考块的长度可能相当可观。

您可以在扩展思考指南中阅读有关上下文窗口和扩展思考的更多信息。

结合扩展思考和工具使用时的上下文窗口

下图展示了结合扩展思考与工具使用时的上下文窗口令牌管理：

使用扩展思考和工具使用的上下文窗口示意图

第一轮架构
- 输入组件： 工具配置和用户消息
- 输出组件： 扩展思考 + 文本响应 + 工具使用请求
- 令牌计算： 所有输入和输出组件都计入上下文窗口，所有输出组件都按输出令牌计费。
工具结果处理（第 2 轮）
- 输入组件： 第一轮中的每个块以及 tool_result。扩展思考块必须与相应的工具结果一起返回。这是您必须返回思考块的唯一情况。
- 输出组件： 在工具结果传回给 Claude 后，Claude 仅以文本响应（在下一条 user 消息之前不会有额外的扩展思考，除非启用了交错思考）。
- 令牌计算： 所有输入和输出组件都计入上下文窗口，所有输出组件都按输出令牌计费。
新的用户轮次（第 3 轮）
- 输入组件： 上一轮的所有输入和输出都会向前传递，但思考块除外，因为 Claude 已完成整个工具使用周期，此时可以丢弃思考块。如果您将其传回，API 会自动为您剥离思考块，或者您也可以在此阶段自行剥离。这也是您添加下一个 user 轮次的位置。
- 输出组件： 由于在工具使用周期之外有一个新的 user 轮次，Claude 会生成一个新的扩展思考块并从那里继续。
- 令牌计算： 之前的思考令牌会自动从上下文窗口计算中剥离。所有其他先前的块仍计入令牌窗口，当前 assistant 轮次中的思考块也计入上下文窗口。

扩展思考与工具使用的注意事项：
- 发布工具结果时，必须包含伴随该特定工具请求的完整未修改的思考块（包括签名部分）。
- 扩展思考与工具使用的有效上下文窗口计算变为：context_window = input_tokens + current_turn_tokens。
- 系统使用加密签名来验证思考块的真实性。在工具使用期间未能保留思考块可能会破坏 Claude 的推理连续性。因此，如果您修改思考块，API 会返回错误。

Claude 4 模型支持交错思考，这使 Claude 能够在工具调用之间进行思考，并在收到工具结果后进行更复杂的推理。

有关将工具与扩展思考结合使用的更多信息，请参阅扩展思考指南。

Claude 的工具选择设计为在处理大型输入文档时依然稳定，即使对话包含超过 10 万个非工具上下文令牌，也能选择正确的工具（或正确地不使用工具）。如需减少工具本身消耗的上下文，请参阅管理工具上下文，或使用工具搜索工具延迟工具定义。

Claude Opus 4.8、Claude Mythos Preview、Claude Opus 4.7、Claude Opus 4.6 和 Claude Sonnet 4.6 在 Claude API、Amazon Bedrock 和 Vertex AI 上拥有 100 万令牌的上下文窗口。在 Microsoft Foundry 上，Claude Opus 4.8 拥有 20 万令牌的上下文窗口。其他 Claude 模型（包括 Claude Sonnet 4.5）拥有 20 万令牌的上下文窗口。

Claude Fable 5 和 Claude Mythos 5（claude-fable-5 和 claude-mythos-5）在 Claude API 上拥有 100 万令牌的上下文窗口。100 万的最大值也是默认值，单个请求最多可生成 12.8 万个输出令牌（max_tokens）。

单个请求最多可包含 600 张图片或 PDF 页面（对于拥有 20 万令牌上下文窗口的模型，上限为 100）。发送大量图片或大型文档时，您可能会在达到令牌限制之前先接近请求大小限制。

Claude Sonnet 4.6、Sonnet 4.5 和 Haiku 4.5 中的上下文感知

Claude Sonnet 4.6、Claude Sonnet 4.5 和 Claude Haiku 4.5 具备上下文感知功能。此功能使这些模型能够在整个对话过程中跟踪其剩余的上下文窗口（即"令牌预算"）。这使 Claude 能够通过了解其可用的工作空间来更有效地执行任务和管理上下文。Claude 经过训练可以精确使用此上下文，坚持执行任务直到最后，而不是猜测剩余多少令牌。对于模型而言，缺乏上下文感知就像在没有时钟的情况下参加烹饪比赛。上下文感知模型通过明确接收有关剩余上下文的信息改变了这一点，因此它们可以最大限度地利用可用令牌。

工作原理：

在对话开始时，Claude 会收到有关其总上下文窗口的信息：

<budget:token_budget>1000000</budget:token_budget>

预算设置为 100 万个令牌（对于上下文窗口较小的模型为 20 万个）。

每次工具调用后，Claude 会收到有关剩余容量的更新：

<system_warning>Token usage: 35000/1000000; 965000 remaining</system_warning>

这种感知能力帮助 Claude 确定剩余多少工作容量，并能够更有效地执行长时间运行的任务。图片令牌也包含在这些预算中。

优势：

上下文感知对以下场景特别有价值：

需要持续专注的长时间运行的智能体会话
状态转换很重要的多上下文窗口工作流
需要仔细管理令牌的复杂任务

对于跨多个会话的智能体，请设计您的状态工件，以便在新会话开始时能够快速恢复上下文。内存工具的多会话模式详细介绍了一种具体方法。另请参阅 Effective harnesses for long-running agents（长时间运行智能体的有效框架）。

有关利用上下文感知的提示指导，请参阅提示最佳实践指南。

使用压缩管理上下文

如果您的对话经常接近上下文窗口限制，服务器端压缩是推荐的方法。压缩提供服务器端摘要功能，可自动压缩对话的早期部分，从而以最少的集成工作实现超出上下文限制的长时间运行对话。该功能在 Claude Fable 5、Claude Mythos 5、Claude Opus 4.8、Claude Mythos Preview、Claude Opus 4.7、Claude Opus 4.6 和 Claude Sonnet 4.6 中以测试版形式提供。

对于更专业的需求，上下文编辑提供了额外的策略：

工具结果清除 - 在智能体工作流中清除旧的工具结果
思考块清除 - 使用扩展思考时管理思考块