# 迁移指南

从先前版本的 Claude 迁移到 Claude Opus 4.7 和 Claude 4.6 模型的指南

---

<Note>
本指南涵盖 [Messages API](/docs/en/build-with-claude/working-with-messages) 代码的迁移。如果您使用 [Claude 托管代理](/docs/en/managed-agents/overview)，除更新模型名称外无需其他更改。
</Note>

## 迁移到 Claude Opus 4.7

Claude Opus 4.7 是 Anthropic 迄今为止功能最强大的通用模型。它具有高度自主性，在长周期代理任务、知识工作、视觉任务和记忆任务方面表现出色。

Claude Opus 4.7 在现有的 Claude Opus 4.6 提示词和评估上应具有出色的开箱即用性能，定价相同为每百万 token $5 / $25，但在迁移过程中有一些行为和 API 变更值得了解。它支持与 Claude Opus 4.6 相同的功能集，包括：

- [1M token 上下文窗口](/docs/en/build-with-claude/context-windows)，标准 API 定价，无长上下文附加费用
- [128k 最大输出 token](/docs/en/about-claude/models/overview)
- [自适应思维](/docs/en/build-with-claude/adaptive-thinking)
- [提示缓存](/docs/en/build-with-claude/prompt-caching)
- [批处理](/docs/en/build-with-claude/batch-processing)
- [文件 API](/docs/en/build-with-claude/files)
- [PDF 支持](/docs/en/build-with-claude/pdf-support)
- [视觉](/docs/en/build-with-claude/vision)
- 完整的服务器端和客户端[工具](/docs/en/agents-and-tools/tool-use/overview)集（[bash](/docs/en/agents-and-tools/tool-use/bash-tool)、[代码执行](/docs/en/agents-and-tools/tool-use/code-execution-tool)、[计算机使用](/docs/en/agents-and-tools/tool-use/computer-use-tool)、[文本编辑器](/docs/en/agents-and-tools/tool-use/text-editor-tool)、[网络搜索](/docs/en/agents-and-tools/tool-use/web-search-tool)、[网页抓取](/docs/en/agents-and-tools/tool-use/web-fetch-tool)、[MCP 连接器](/docs/en/agents-and-tools/mcp-connector)、[记忆](/docs/en/agents-and-tools/tool-use/memory-tool)）

<Tip>
  **使用 Claude API 技能自动化此迁移。** 在 Claude Code 中，运行 `/claude-api migrate` 以调用内置的 [Claude API 技能](/docs/en/agents-and-tools/agent-skills/claude-api-skill#migrating-to-a-newer-claude-model)：

  ```text
  /claude-api migrate this project to claude-opus-4-7
  ```

  该技能会在您的代码库中应用模型 ID 替换、破坏性参数更改、预填充替换和以下所述的努力度校准，然后生成需要手动验证的清单。在编辑任何文件之前，它会要求您确认迁移范围（整个工作目录、子目录或特定文件列表）。该技能还能检测 Amazon Bedrock、Vertex AI、Claude Platform on AWS 和 Microsoft Foundry 客户端，并为每个平台调整模型 ID 格式和功能变更。
</Tip>

### 更新模型名称

```python
# Opus 迁移
model = "claude-opus-4-6"  # 之前
model = "claude-opus-4-7"  # 之后
```

### 破坏性变更

1. **扩展思维已移除：** `thinking: {type: "enabled", budget_tokens: N}` 在 Claude Opus 4.7 及更高版本模型上不再支持，将返回 400 错误。请切换到[自适应思维](/docs/en/build-with-claude/adaptive-thinking)（`thinking: {type: "adaptive"}`），并使用[努力度参数](/docs/en/build-with-claude/effort)控制思维深度。自适应思维在 Claude Opus 4.7 上**默认关闭**：不包含 `thinking` 字段的请求将在无思维模式下运行，与 Opus 4.6 行为一致。请显式设置 `thinking: {type: "adaptive"}` 以启用。

    之前（Claude Opus 4.6）：

    ```python
    client.messages.create(
        model="claude-opus-4-6",
        max_tokens=16000,
        thinking={"type": "enabled", "budget_tokens": 10000},
        messages=[{"role": "user", "content": "..."}],
    )
    ```

    之后（Claude Opus 4.7）：

    ```python
    client.messages.create(
        model="claude-opus-4-7",
        max_tokens=16000,
        thinking={"type": "adaptive"},
        output_config={"effort": "high"},  # 或 "max", "xhigh", "medium", "low"
        messages=[{"role": "user", "content": "..."}],
    )
    ```

    自适应思维可通过提示词进行引导。关于模型思维过多或不足时的调整指导，请参阅[校准努力度和思维深度](/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#calibrating-effort-and-thinking-depth)。

2. **采样参数已移除：** 在 Claude Opus 4.7 上将 `temperature`、`top_p` 或 `top_k` 设置为任何非默认值将返回 400 错误。最安全的迁移路径是从请求载荷中完全省略这些参数。提示是在 Claude Opus 4.7 上引导模型行为的推荐方式。如果您之前使用 `temperature = 0` 来实现确定性，请注意它从未在先前模型上保证过相同的输出。

3. **思维内容默认省略：** 思维块仍会出现在 Claude Opus 4.7 的响应流中，但除非您显式选择加入，否则其 `thinking` 字段为空。这是与 Claude Opus 4.6 相比的静默变更，后者默认返回摘要化的思维文本。要在 Claude Opus 4.7 上恢复摘要化的思维内容，请将 `thinking.display` 设置为 `"summarized"`：

    ```python
    thinking = {
        "type": "adaptive",
        "display": "summarized",
    }
    ```

    在 Claude Opus 4.7 上默认为 `"omitted"`。如果您的产品向用户流式传输推理过程，新默认值会在输出开始前显示长时间暂停；设置 `display: "summarized"` 以在思维过程中恢复可见的进度。详情请参阅[扩展思维](/docs/en/build-with-claude/extended-thinking#controlling-thinking-display)。

4. **更新的 token 计数：** Claude Opus 4.7 使用新的分词器，这有助于提升其在各种任务上的性能。新分词器在处理文本时可能使用大约 1x 到 1.35x 的 token 数量（与先前模型相比最多增加约 35%，因内容而异）。

    [`/v1/messages/count_tokens`](/docs/en/build-with-claude/token-counting) 将为 Claude Opus 4.7 返回与 Claude Opus 4.6 不同的 token 数量。token 效率因工作负载模式而异。

    提示干预、`task_budget` 和 `effort` 可以帮助控制成本并确保适当的 token 使用。这些控制可能会牺牲模型智能。更新您的 `max_tokens` 参数以留出额外空间，包括压缩触发器。Claude Opus 4.7 以标准 API 定价提供 1M 上下文窗口，无长上下文附加费用。

5. **预填充移除（从 Opus 4.6 延续）：** 在 Claude Opus 4.7 上预填充助手消息将返回 400 错误。请改用[结构化输出](/docs/en/build-with-claude/structured-outputs)、系统提示指令或 `output_config.format`。

### 选择努力度级别

[努力度参数](/docs/en/build-with-claude/effort)允许您调整 Claude 的智能与 token 消耗之间的权衡，以更快的速度和更低的成本换取能力。对于编程和代理用例，从新的 `xhigh` 努力度级别开始，对于大多数对智能敏感的用例，至少使用 `high` 努力度。尝试其他努力度级别以进一步调整 token 使用和智能：

- **`max`：** 最大努力度可以在某些用例中带来性能提升，但由于 token 使用增加可能会出现收益递减。此设置有时也可能导致过度思考。对于需要高度智能的任务测试最大努力度。
- **`xhigh`（新）：** 超高努力度是大多数编程和代理用例的最佳设置。
- **`high`：** 此设置在 token 使用和智能之间取得平衡。对于大多数对智能敏感的用例，至少使用 `high` 努力度。
- **`medium`：** 适合需要在降低 token 使用的同时牺牲智能的成本敏感型用例。
- **`low`：** 保留用于范围较小的短任务和对延迟敏感但对智能不敏感的工作负载。

努力度对这个模型比对任何先前的 Opus 模型都更重要。升级时请积极地进行实验。

### 行为变更

Claude Opus 4.7 与 Claude Opus 4.6 有几个行为差异，这些不是 API 破坏性变更，但可能需要更新提示词或移除脚手架代码。

1. **响应长度因用例而异：** Claude Opus 4.7 根据其判断的任务复杂度来校准响应长度，而不是默认使用固定的详细程度。这通常意味着简单查询的答案更短，开放式分析的答案更长。

    如果您的产品依赖于特定的输出风格或详细程度，您可能需要调整提示词。例如，要减少详细程度，可以添加："提供简洁、聚焦的回复。跳过非必要的上下文，保持示例最少。"如果您发现特定类型的过度解释，请在提示词中添加针对性指令来防止。

    展示 Claude 如何以适当简洁度沟通的正面示例，往往比告诉模型不要做什么的负面示例或指令更有效。

2. **更字面化的指令遵循：** Claude Opus 4.7 比 Claude Opus 4.6 更字面化和显式地解释提示词，尤其是在较低努力度级别下。它不会将指令从一个项目静默泛化到另一个项目，也不会推断您没有提出的请求。这种字面化的好处是精确性和更少的反复调整。它通常在使用精心调优的提示词、结构化提取和需要可预测行为的流水线的 API 用例中表现更好。提示词和脚手架审查对于迁移到 Claude Opus 4.7 可能特别有帮助。

3. **更直接的语气：** 与任何新模型一样，长篇写作的散文风格可能会有所变化。Claude Opus 4.7 更直接和有主见，比 Claude Opus 4.6 更温暖的风格更少使用肯定性措辞和表情符号。如果您的产品依赖于特定的声音，请根据新基线重新评估风格提示词。

4. **代理跟踪中的内置进度更新：** Claude Opus 4.7 在长时间代理跟踪中向用户提供更规律、更高质量的更新。如果您已添加脚手架来强制生成中间状态消息（"每 3 次工具调用后总结进度"），请尝试移除它。如果您发现 Claude Opus 4.7 面向用户的更新长度或内容与您的用例不太匹配，请在提示词中明确描述这些更新应是什么样子并提供示例。

5. **默认生成更少的子代理：** Claude Opus 4.7 默认倾向于生成更少的子代理。但是，此行为可通过提示词引导；给 Claude Opus 4.7 关于何时需要子代理的明确指导。

6. **更严格的努力度校准：** 与 Claude Opus 4.6 有显著不同，Claude Opus 4.7 严格遵守[努力度级别](/docs/en/build-with-claude/effort)，尤其是在低端。在 `low` 和 `medium` 下，模型将其工作范围限定在所要求的内容上，而不是额外发挥。

    这对延迟和成本有利，但在 `low` 努力度下运行中等复杂任务时存在思维不足的风险。如果您在复杂问题上观察到浅层推理，请将努力度提高到 `high` 或 `xhigh`，而不是通过提示词来绕过。

    如果您因延迟原因需要保持 `low` 努力度，请添加针对性指导："此任务涉及多步推理。在回复前仔细思考问题。"请参阅[Claude Opus 4.7 推荐努力度级别](/docs/en/build-with-claude/effort#recommended-effort-levels-for-claude-opus-4-7)。

7. **默认更少的工具调用：** Claude Opus 4.7 倾向于比 Claude Opus 4.6 更少使用工具，更多使用推理。这在大多数情况下产生更好的结果。

    要增加工具使用，请提高努力度设置。`high` 或 `xhigh` 努力度设置在代理搜索和编程中显示明显更多的工具使用。您还可以调整提示词以显式指示模型何时以及如何正确使用其工具。

8. **实时网络安全保障：** 在 Claude Opus 4.7 中新增，涉及禁止或高风险主题的请求可能会导致拒绝。对于合法的安全工作，如渗透测试、漏洞研究或红队测试，请申请[网络验证计划](https://claude.com/form/cyber-use-case)以请求降低限制。详情请参阅[保障、警告和申诉](https://support.claude.com/en/articles/8241253-safeguards-warnings-and-appeals)。

9. **高分辨率图像支持：** Claude Opus 4.7 是首个支持高分辨率图像的 Claude 模型。最大图像分辨率为长边 2576 像素，高于先前模型的 1568 像素。这为视觉密集型工作负载带来了收益提升，对计算机使用、屏幕截图理解和文档分析尤为有价值。

    高分辨率支持是自动的，无需 beta 头或客户端选择加入。需要规划两件事：

    - 全分辨率图像可能比先前模型使用大约 3 倍多的图像 token（每张图像最多 4,784 token，而之前每张图像上限约为 1,600 token）。为图像密集型工作负载重新预算 `max_tokens` 和成本预期，或者在发送前降采样（如果不需要额外的保真度）。
    - Claude Opus 4.7 返回的指向和边界框坐标与实际图像像素为 1:1，因此无需缩放因子转换。

    详情请参阅[Claude Opus 4.7 高分辨率图像支持](/docs/en/build-with-claude/vision#high-resolution-image-support-on-claude-opus-4-7)。

### 推荐更改

这些不是必需的，但会改善您的体验：

1. **重新评估 `max_tokens`：** 因为相同文本在 Claude Opus 4.7 上产生更高的 token 计数，请更新您的 `max_tokens` 参数以留出额外空间，包括压缩触发器。提示干预、[`task_budget`](/docs/en/build-with-claude/task-budgets) 和 [`effort`](/docs/en/build-with-claude/effort) 可以帮助控制成本并确保适当的 token 使用。

2. **审核 token 计数预期：** 任何在客户端估算 token 或假设固定 token 与字符比率的代码路径应针对 Claude Opus 4.7 重新测试。使用 [Token 计数端点](/docs/en/build-with-claude/token-counting)进行验证。

3. **采用[任务预算](/docs/en/build-with-claude/task-budgets)（beta）：** Claude Opus 4.7 引入了任务预算。这些预算让您告知 Claude 在完整的代理循环中可用的 token 数量，包括思维、工具调用、工具结果和最终输出。模型会看到一个倒计时，并在预算消耗时使用它来优先处理工作并优雅地完成任务。要使用，请设置 beta 头 `task-budgets-2026-03-13` 并在输出配置中添加以下内容：

    ```python
    output_config = {
        "effort": "high",
        "task_budget": {"type": "tokens", "total": 128000},
    }
    ```

    您可能需要针对您的用例尝试不同的任务预算。如果给予模型的任务预算过于严格，它可能会以预算为约束条件，不太彻底地完成任务。

    对于质量比速度更重要的开放式代理任务，不要设置任务预算。将任务预算保留用于需要模型将其工作范围限定在 token 配额内的工作负载。任务预算的最小值为 20k token。

    任务预算不是硬性限制；它是模型意识到的建议。它与 `max_tokens` 不同：

    - **`task_budget`：** 跨整个代理循环的建议性上限。模型看到它并使用它来调节自己的节奏。
    - **`max_tokens`：** 每个请求生成 token 的硬性上限。它不会传递给模型，因此模型不知道它。

    当您希望模型自我调节时使用 `task_budget`，将 `max_tokens` 作为限制使用的硬性上限。

4. **在 `max` 或 `xhigh` 努力度下设置较大的 `max_tokens`：** 如果您以 `max` 或 `xhigh` 努力度运行 Claude Opus 4.7，请设置较大的最大输出 token 预算，以便模型有空间在其子代理和工具调用中进行思考和行动。从 64k token 开始并从中调优。

5. **如果不需要高分辨率则降采样图像：** Claude Opus 4.7 支持最大 2576px / 3.75MP 的图像。高分辨率图像使用更多 token。如果不需要额外的图像保真度，请在发送到 Claude 前降采样图像以避免 token 使用增加。请参阅[图像和视觉](/docs/en/build-with-claude/vision)。

### 迁移清单

- [ ] 将模型名称从 `claude-opus-4-6` 更新为 `claude-opus-4-7`（或更新别名）。
- [ ] 从请求载荷中移除 `temperature`、`top_p` 和 `top_k`。
- [ ] 将 `thinking: {type: "enabled", budget_tokens: N}` 替换为 `thinking: {type: "adaptive"}` 加上[努力度参数](/docs/en/build-with-claude/effort)。
- [ ] 移除任何助手消息预填充。
- [ ] 如果您的 UI 显示思维内容，请显式选择加入思维摘要化。
- [ ] 在更新的分词下重新基准测试端到端成本和延迟。
- [ ] 重新调优 `max_tokens` 以适应更新的分词。
- [ ] 重新测试任何客户端 token 计数估算。
- [ ] 如果您的应用发送图像，请为[高分辨率图像支持](/docs/en/build-with-claude/vision#high-resolution-image-support-on-claude-opus-4-7)重新预算（每张全分辨率图像最多约 3 倍图像 token）。如果不需要额外保真度，请在发送前降采样。
- [ ] 如果您从模型获取指向或边界框坐标，请移除任何缩放因子转换；Claude Opus 4.7 的坐标与实际图像像素为 1:1。
- [ ] 审查提示词以适应上述行为变更（响应长度、字面化、语气、进度更新、子代理、努力度校准、工具触发、网络安全保障、高分辨率图像处理）。
- [ ] 在移除现有长度控制提示词后重新基线化响应长度，然后显式调优。
- [ ] 如果使用 `xhigh` 或 `max` 努力度，请将 `max_tokens` 提高到至少 64k 作为起点。
- [ ] 考虑为代理工作流采用任务预算（beta）。
- [ ] 如果您的产品从事合法的安全工作，请申请[网络验证计划](https://claude.com/form/cyber-use-case)以获取降低网络内容限制的权限。

## 从 Opus 4.5 或更早版本迁移到 Claude Opus 4.7

如果您从 Claude Opus 4.5、Opus 4.1 或更早模型直接迁移到 Claude Opus 4.7，请应用**上方[Opus 4.7 的所有变更](#迁移到-claude-opus-4-7)**以及本节中在 Opus 4.5 和 Opus 4.7 之间生效的累积变更。如果您从 Opus 4.6 迁移，只需要上方的 [Opus 4.7 章节](#迁移到-claude-opus-4-7)。

### 更新模型名称

```python
# Opus 迁移
model = "claude-opus-4-5"  # 之前
model = "claude-opus-4-7"  # 之后
```

### 破坏性变更

1. **预填充移除**已在上方的 [Opus 4.7 破坏性变更](#破坏性变更)中涵盖。

2. **工具参数引号：** Claude Opus 4.6 及更高版本模型可能在工具调用参数中产生略有不同的 JSON 字符串转义（例如，Unicode 转义或正斜杠转义的不同处理）。如果您将工具调用 `input` 作为原始字符串解析而不是使用 JSON 解析器，请验证您的解析逻辑。标准 JSON 解析器（如 `json.loads()` 或 `JSON.parse()`）会自动处理这些差异。

### 推荐更改

这些更改改善您在 Opus 4.7 上的体验。标记为 **（在 Opus 4.7 上必需）** 的项目在 Opus 4.6 发布时是可选建议，但现在是强制性的；其余项目仍然是推荐的。

1. **迁移到自适应思维（在 Opus 4.7 上必需）：** `thinking: {type: "enabled", budget_tokens: N}` 在 Claude Opus 4.7 上返回 400 错误。切换到 `thinking: {type: "adaptive"}` 并使用[努力度参数](/docs/en/build-with-claude/effort)控制思维深度。请参阅[自适应思维](/docs/en/build-with-claude/adaptive-thinking)。

   <CodeGroup>
   ```bash cURL
   curl -sS https://api.anthropic.com/v1/messages \
     -H "content-type: application/json" \
     -H "x-api-key: $ANTHROPIC_API_KEY" \
     -H "anthropic-version: 2023-06-01" \
     -d '{
       "model": "claude-opus-4-7",
       "max_tokens": 16000,
       "thinking": {"type": "adaptive"},
       "output_config": {"effort": "high"},
       "messages": [{"role": "user", "content": "Your prompt here"}]
     }'
   ```

   ```python Before hidelines={1..3}
   import anthropic

   client = anthropic.Anthropic()
   response = client.beta.messages.create(
       model="claude-opus-4-5",
       max_tokens=16000,
       thinking={"type": "enabled", "budget_tokens": 32000},
       betas=["interleaved-thinking-2025-05-14"],
       messages=[{"role": "user", "content": "Your prompt here"}],
   )
   ```

   ```python After
   response = client.messages.create(
       model="claude-opus-4-7",
       max_tokens=16000,
       thinking={"type": "adaptive"},
       output_config={"effort": "high"},
       messages=[{"role": "user", "content": "Your prompt here"}],
   )
   ```

   ```bash CLI
   ant messages create <<'YAML'
   model: claude-opus-4-7
   max_tokens: 16000
   thinking:
     type: adaptive
   output_config:
     effort: high
   messages:
     - role: user
       content: Your prompt here
   YAML
   ```

   ```typescript TypeScript hidelines={1..2}
   import Anthropic from "@anthropic-ai/sdk";

   const client = new Anthropic();

   const response = await client.messages.create({
     model: "claude-opus-4-7",
     max_tokens: 16000,
     thinking: { type: "adaptive" },
     output_config: { effort: "high" },
     messages: [{ role: "user", content: "Your prompt here" }]
   });
   ```

   ```csharp C#
   using Anthropic;
   using Anthropic.Models.Messages;

   AnthropicClient client = new();

   var parameters = new MessageCreateParams
   {
       Model = Model.ClaudeOpus4_7,
       MaxTokens = 16000,
       Thinking = new ThinkingConfigAdaptive(),
       OutputConfig = new OutputConfig { Effort = Effort.High },
       Messages = [new() { Role = Role.User, Content = "Your prompt here" }]
   };

   var response = await client.Messages.Create(parameters);
   Console.WriteLine(response);
   ```

   ```go Go hidelines={1..11,-1}
   package main

   import (
   	"context"
   	"fmt"
   	"log"

   	"github.com/anthropics/anthropic-sdk-go"
   )

   func main() {
   	client := anthropic.NewClient()

   	response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
   		Model:     anthropic.ModelClaudeOpus4_7,
   		MaxTokens: 16000,
   		Thinking: anthropic.ThinkingConfigParamUnion{
   			OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{},
   		},
   		OutputConfig: anthropic.OutputConfigParam{
   			Effort: anthropic.OutputConfigEffortHigh,
   		},
   		Messages: []anthropic.MessageParam{
   			anthropic.NewUserMessage(anthropic.NewTextBlock("Your prompt here")),
   		},
   	})
   	if err != nil {
   		log.Fatal(err)
   	}
   	fmt.Println(response)
   }
   ```

   ```java Java hidelines={1..5,8..10,-2..}
   import com.anthropic.client.AnthropicClient;
   import com.anthropic.client.okhttp.AnthropicOkHttpClient;
   import com.anthropic.models.messages.MessageCreateParams;
   import com.anthropic.models.messages.Message;
   import com.anthropic.models.messages.Model;
   import com.anthropic.models.messages.OutputConfig;
   import com.anthropic.models.messages.ThinkingConfigAdaptive;

   public class AdaptiveThinkingExample {
       public static void main(String[] args) {
           AnthropicClient client = AnthropicOkHttpClient.fromEnv();

           MessageCreateParams params = MessageCreateParams.builder()
               .model(Model.CLAUDE_OPUS_4_7)
               .maxTokens(16000L)
               .thinking(ThinkingConfigAdaptive.builder().build())
               .outputConfig(OutputConfig.builder()
                   .effort(OutputConfig.Effort.HIGH)
                   .build())
               .addUserMessage("Your prompt here")
               .build();

           Message response = client.messages().create(params);
           System.out.println(response);
       }
   }
   ```

   ```php PHP hidelines={1..4}
   <?php

   use Anthropic\Client;

   $client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));

   $response = $client->messages->create(
       maxTokens: 16000,
       messages: [['role' => 'user', 'content' => 'Your prompt here']],
       model: 'claude-opus-4-7',
       thinking: ['type' => 'adaptive'],
       outputConfig: ['effort' => 'high'],
   );
   ```

   ```ruby Ruby hidelines={1..2}
   require "anthropic"

   client = Anthropic::Client.new

   response = client.messages.create(
     model: "claude-opus-4-7",
     max_tokens: 16000,
     thinking: { type: "adaptive" },
     output_config: { effort: "high" },
     messages: [{ role: "user", content: "Your prompt here" }]
   )
   ```
   </CodeGroup>

   请注意，迁移还从 `client.beta.messages.create` 移动到 `client.messages.create`。自适应思维和努力度是正式版功能，不需要 beta SDK 命名空间或任何 beta 头。

2. **移除努力度 beta 头：** 努力度参数现已正式发布。从您的请求中移除 `betas=["effort-2025-11-24"]`。

3. **移除细粒度工具流式传输 beta 头：** 细粒度工具流式传输现已正式发布。从您的请求中移除 `betas=["fine-grained-tool-streaming-2025-05-14"]`。

4. **移除交错思维 beta 头：** 自适应思维在 Claude Opus 4.7、Opus 4.6 和 Sonnet 4.6 上自动启用交错思维。从您的请求中移除 `betas=["interleaved-thinking-2025-05-14"]`。该头在 Sonnet 4.6 上使用手动扩展思维时仍然有效，但手动模式已弃用。

5. **迁移到 output_config.format：** 如果使用结构化输出，请将 `output_format={...}` 更新为 `output_config={"format": {...}}`。旧参数仍然有效但已弃用，将在未来的模型版本中移除。

### 从 Claude 4.1 或更早版本迁移

如果您从 Opus 4.1、Sonnet 4（已弃用）或更早模型直接迁移到 Claude Opus 4.7，请应用本指南顶部的 Claude Opus 4.7 变更和上方的累积变更以及本节中的附加变更。

```python
# 从 Opus 4.1
model = "claude-opus-4-1-20250805"  # 之前
model = "claude-opus-4-7"  # 之后

# 从 Sonnet 4
model = "claude-sonnet-4-20250514"  # 之前
model = "claude-opus-4-7"  # 之后

# 从 Sonnet 3.7
model = "claude-3-7-sonnet-20250219"  # 之前
model = "claude-opus-4-7"  # 之后
```

#### 附加破坏性变更

1. **移除采样参数**

   <Warning>
   从 Claude 3.x 模型迁移时，这是一项破坏性变更。
   </Warning>

   从 Claude Opus 4.7 开始，将 `temperature`、`top_p` 或 `top_k` 设置为任何非默认值将返回 400 错误。最安全的迁移路径是从请求中完全省略这些参数，并使用提示来引导模型的行为。如果您之前使用 `temperature = 0` 来实现确定性，请注意它从未保证过相同的输出。

   
   ```python Python nocheck
   # 之前 - 这在 Claude 4+ 模型上会报错
   response = client.messages.create(
       model="claude-3-7-sonnet-20250219",
       temperature=0.7,
       top_p=0.9,  # 非默认采样参数在 Opus 4.7 上返回 400
       # ...
   )

   # 之后
   response = client.messages.create(
       model="claude-opus-4-7",
       # ...
   )
   ```

2. **更新工具版本**

   <Warning>
   从 Claude 3.x 模型迁移时，这是一项破坏性变更。
   </Warning>

   更新到最新工具版本。移除任何使用 `undo_edit` 命令的代码。

   ```python
   # 之前
   tools = [{"type": "text_editor_20250124", "name": "str_replace_editor"}]

   # 之后
   tools = [{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}]
   ```

   - **文本编辑器：** 使用 `text_editor_20250728` 和 `str_replace_based_edit_tool`。详情请参阅[文本编辑器工具文档](/docs/en/agents-and-tools/tool-use/text-editor-tool)。
   - **代码执行：** 升级到 `code_execution_20250825`。请参阅[代码执行工具文档](/docs/en/agents-and-tools/tool-use/code-execution-tool#upgrade-to-latest-tool-version)获取迁移说明。

3. **处理 `refusal` 停止原因**

   更新您的应用以[处理 `refusal` 停止原因](/docs/en/test-and-evaluate/strengthen-guardrails/handle-streaming-refusals)：

   
   ```python Python nocheck
   response = client.messages.create(...)

   if response.stop_reason == "refusal":
       # 适当地处理拒绝
       pass
   ```

4. **处理 `model_context_window_exceeded` 停止原因**

   Claude 4.5+ 模型在生成因达到上下文窗口限制而停止时返回 `model_context_window_exceeded` 停止原因，而不是请求的 `max_tokens` 限制。更新您的应用以处理此新的停止原因：

   
   ```python Python nocheck
   response = client.messages.create(...)

   if response.stop_reason == "model_context_window_exceeded":
       # 适当地处理上下文窗口限制
       pass
   ```

5. **验证工具参数处理（尾部换行符）**

   Claude 4.5+ 模型保留了先前被剥离的工具调用字符串参数中的尾部换行符。如果您的工具依赖于对工具调用参数的精确字符串匹配，请验证您的逻辑是否正确处理尾部换行符。

6. **为行为变更更新提示词**

   Claude 4+ 模型具有更简洁、直接的沟通风格，需要明确的指导。请查阅[提示最佳实践](/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices)获取优化指导。

#### 附加推荐更改

- **移除旧版 beta 头：** 移除 `token-efficient-tools-2025-02-19` 和 `output-128k-2025-02-19`。所有 Claude 4+ 模型都内置了 token 高效工具使用，这些头没有任何效果。

### 迁移清单（从 Opus 4.5 或更早版本）

- [ ] 将模型 ID 更新为 `claude-opus-4-7`
- [ ] 应用所有 [Opus 4.7 破坏性变更](#迁移到-claude-opus-4-7)（扩展思维已移除、采样参数已移除、思维显示默认省略、更新的分词）
- [ ] **破坏性：** 移除助手消息预填充（返回 400 错误）；改用结构化输出或 `output_config.format`
- [ ] **在 Opus 4.7 上破坏性：** 将 `thinking: {type: "enabled", budget_tokens: N}` 替换为 `thinking: {type: "adaptive"}` 加上[努力度参数](/docs/en/build-with-claude/effort)（在 Opus 4.7 上返回 400）
- [ ] 验证工具调用 JSON 解析使用标准 JSON 解析器
- [ ] 移除 `effort-2025-11-24` beta 头（努力度现已正式发布）
- [ ] 移除 `fine-grained-tool-streaming-2025-05-14` beta 头
- [ ] 移除 `interleaved-thinking-2025-05-14` beta 头（自适应思维自动启用交错思维）
- [ ] 将 `output_format` 迁移到 `output_config.format`（如适用）
- [ ] 如果从 Claude 4.1 或更早版本迁移：移除 `temperature`、`top_p` 和 `top_k`（非默认值在 Opus 4.7 上返回 400）
- [ ] 如果从 Claude 4.1 或更早版本迁移：更新工具版本（`text_editor_20250728`、`code_execution_20250825`）
- [ ] 如果从 Claude 4.1 或更早版本迁移：处理 `refusal` 停止原因
- [ ] 如果从 Claude 4.1 或更早版本迁移：处理 `model_context_window_exceeded` 停止原因
- [ ] 如果从 Claude 4.1 或更早版本迁移：验证工具字符串参数的尾部换行符处理
- [ ] 如果从 Claude 4.1 或更早版本迁移：移除旧版 beta 头（`token-efficient-tools-2025-02-19`、`output-128k-2025-02-19`）
- [ ] 按照[提示最佳实践](/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices)审查和更新提示词
- [ ] 在生产部署前在开发环境中测试

---

## 迁移到 Claude Sonnet 4.6

Claude Sonnet 4.6 结合了强大的智能和快速的性能，具有改进的代理搜索能力，并在与网络搜索或网页抓取一起使用时提供免费的代码执行。它非常适合日常编程、分析和内容任务。

有关功能的完整概述，请参阅[模型概述](/docs/en/about-claude/models/overview)。

<Note>
Sonnet 4.6 定价为每百万输入 token $3，每百万输出 token $15。详情请参阅 [Claude 定价](/docs/en/about-claude/pricing)。
</Note>

**更新模型名称：**

```python
# 从 Sonnet 4.5
model = "claude-sonnet-4-5"  # 之前
model = "claude-sonnet-4-6"  # 之后

# 从 Sonnet 4
model = "claude-sonnet-4-20250514"  # 之前
model = "claude-sonnet-4-6"  # 之后
```

### 破坏性变更

#### 从 Sonnet 4.5 迁移时

1. **不再支持预填充助手消息**

   <Warning>
   从 Sonnet 4.5 或更早版本迁移时，这是一项破坏性变更。
   </Warning>

   在 Sonnet 4.6 上预填充助手消息将返回 `400` 错误。请改用[结构化输出](/docs/en/build-with-claude/structured-outputs)、系统提示指令或 `output_config.format`。

   **常见的预填充用例及迁移方式：**

   - **控制输出格式**（强制 JSON/YAML 输出）：使用[结构化输出](/docs/en/build-with-claude/structured-outputs)或带有枚举字段的工具进行分类任务。

   - **消除前言**（移除"Here is..."等短语）：在系统提示中添加直接指令："直接回复，不要前言。不要以'Here is...'、'Based on...'等短语开头。"

   - **避免不当拒绝：** Claude 现在在适当拒绝方面做得更好。在用户消息中使用清晰的提示而无需预填充应该足够了。

   - **续接**（恢复中断的响应）：将续接内容移到用户消息中："您之前的响应被中断，以 `[previous_response]` 结尾。请从中断处继续。"

   - **上下文注入 / 角色一致性**（在长对话中刷新上下文）：将之前预填充的助手提醒注入到用户轮次中。

2. **工具参数 JSON 转义可能不同**

   <Warning>
   从 Sonnet 4.5 或更早版本迁移时，这是一项破坏性变更。
   </Warning>

   工具参数中的 JSON 字符串转义可能与先前模型不同。标准 JSON 解析器会自动处理，但基于自定义字符串的解析可能需要更新。

#### 从 Claude 3.x 迁移时

3. **更新采样参数**

   <Warning>
   从 Claude 3.x 模型迁移时，这是一项破坏性变更。
   </Warning>

   仅使用 `temperature` 或 `top_p`，不要同时使用两者。

4. **更新工具版本**

   <Warning>
   从 Claude 3.x 模型迁移时，这是一项破坏性变更。
   </Warning>

   更新到最新工具版本（`text_editor_20250728`、`code_execution_20250825`）。移除任何使用 `undo_edit` 命令的代码。

5. **处理 `refusal` 停止原因**

   更新您的应用以[处理 `refusal` 停止原因](/docs/en/test-and-evaluate/strengthen-guardrails/handle-streaming-refusals)。

6. **为行为变更更新提示词**

   Claude 4 模型具有更简洁、直接的沟通风格。请查阅[提示最佳实践](/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices)获取优化指导。

### 推荐更改

1. **移除 `fine-grained-tool-streaming-2025-05-14` beta 头：** 细粒度工具流式传输在 Sonnet 4.6 上现已正式发布，不再需要 beta 头。
2. **将 `output_format` 迁移到 `output_config.format`：** `output_format` 参数已弃用。请改用 `output_config.format`。

### 从 Sonnet 4.5 迁移

考虑从 Sonnet 4.5 迁移到 Sonnet 4.6，后者以相同的价格提供更强的智能。

<Warning>
Sonnet 4.6 默认努力度级别为 `high`，这与没有努力度参数的 Sonnet 4.5 不同。在从 Sonnet 4.5 迁移到 Sonnet 4.6 时，考虑调整努力度参数。如果未显式设置，您可能会因默认努力度级别而遇到更高的延迟。
</Warning>

#### 如果您未使用扩展思维

如果您在 Sonnet 4.5 上未使用扩展思维，可以在 Sonnet 4.6 上继续不使用。您应该显式设置适合您用例的努力度级别。在 `low` 努力度且禁用思维的情况下，您可以预期相对于 Sonnet 4.5 无扩展思维时相似或更好的性能。

<CodeGroup>
```bash cURL
curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-sonnet-4-6",
    "max_tokens": 8192,
    "output_config": {
        "effort": "low"
    },
    "messages": [
        {
            "role": "user",
            "content": "Your prompt here"
        }
    ]
}'
```

```bash CLI
ant messages create <<'YAML'
model: claude-sonnet-4-6
max_tokens: 8192
output_config:
  effort: low
messages:
  - role: user
    content: Your prompt here
YAML
```

```python Python
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=8192,
    output_config={"effort": "low"},
    messages=[{"role": "user", "content": "Your prompt here"}],
)
```

```typescript TypeScript
const response = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 8192,
  output_config: { effort: "low" },
  messages: [{ role: "user", content: "Your prompt here" }]
});
```

```csharp C#
using Anthropic;
using Anthropic.Models.Messages;

AnthropicClient client = new();

var parameters = new MessageCreateParams
{
    Model = Model.ClaudeSonnet4_6,
    MaxTokens = 8192,
    OutputConfig = new OutputConfig
    {
        Effort = Effort.Low
    },
    Messages = [new() { Role = Role.User, Content = "Your prompt here" }]
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message);
```

```go Go hidelines={1..11,-1}
package main

import (
	"context"
	"fmt"
	"log"

	"github.com/anthropics/anthropic-sdk-go"
)

func main() {
	client := anthropic.NewClient()

	response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
		Model:     anthropic.Model("claude-sonnet-4-6"),
		MaxTokens: 8192,
		OutputConfig: anthropic.OutputConfigParam{
			Effort: anthropic.OutputConfigEffortLow,
		},
		Messages: []anthropic.MessageParam{
			anthropic.NewUserMessage(anthropic.NewTextBlock("Your prompt here")),
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response.Content[0].Text)
}
```

```java Java hidelines={1..5,7..9,-2..}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.Model;
import com.anthropic.models.messages.OutputConfig;

public class Main {
    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        MessageCreateParams params = MessageCreateParams.builder()
            .model(Model.CLAUDE_SONNET_4_6)
            .maxTokens(8192L)
            .outputConfig(OutputConfig.builder()
                .effort(OutputConfig.Effort.LOW)
                .build())
            .addUserMessage("Your prompt here")
            .build();

        Message response = client.messages().create(params);
        response.content().stream()
            .flatMap(block -> block.text().stream())
            .forEach(textBlock -> System.out.println(textBlock.text()));
    }
}
```

```php PHP hidelines={1..4}
<?php

use Anthropic\Client;

$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));

$message = $client->messages->create(
    maxTokens: 8192,
    messages: [['role' => 'user', 'content' => 'Your prompt here']],
    model: 'claude-sonnet-4-6',
    outputConfig: ['effort' => 'low'],
);
echo $message->content[0]->text;
```

```ruby Ruby hidelines={1..2}
require "anthropic"

client = Anthropic::Client.new

message = client.messages.create(
  model: "claude-sonnet-4-6",
  max_tokens: 8192,
  output_config: {
    effort: "low"
  },
  messages: [
    { role: "user", content: "Your prompt here" }
  ]
)
puts message.content.first.text
```
</CodeGroup>

#### 如果您正在使用扩展思维

如果您在 Sonnet 4.5 上使用带有 `budget_tokens` 的扩展思维，它在 Sonnet 4.6 上仍然可用但已弃用。请迁移到带有[努力度参数](/docs/en/build-with-claude/effort)的[自适应思维](/docs/en/build-with-claude/adaptive-thinking)。

##### 迁移到自适应思维

[自适应思维](/docs/en/build-with-claude/adaptive-thinking)是 Sonnet 4.6 上 `budget_tokens` 的推荐替代方案。它特别适合以下工作负载模式：

- **自主多步代理：** 将需求转化为可工作软件的编码代理、数据分析流水线和模型在多个步骤中独立运行的漏洞发现。自适应思维让模型可以在每个步骤中校准其推理，在较长的轨迹上保持正轨。对于这些工作负载，从 `high` 努力度开始。如果延迟或 token 使用是问题，请降低到 `medium`。
- **计算机使用代理：** Sonnet 4.6 使用自适应模式在计算机使用评估中达到了一流的准确性。
- **双模式工作负载：** 混合了简单和困难任务的工作负载，其中自适应模式跳过简单查询的思考并在复杂查询上进行深入推理。

使用自适应思维时，在您的任务上评估 `medium` 和 `high` 努力度。正确的级别取决于您的工作负载在质量、延迟和 token 使用之间的权衡。

<CodeGroup>
```bash cURL
curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-sonnet-4-6",
    "max_tokens": 64000,
    "thinking": {
        "type": "adaptive"
    },
    "output_config": {
        "effort": "medium"
    },
    "messages": [
        {
            "role": "user",
            "content": "Your prompt here"
        }
    ]
}'
```

```bash CLI nocheck
ant messages create <<'YAML'
model: claude-sonnet-4-6
max_tokens: 64000
thinking:
  type: adaptive
output_config:
  effort: medium
messages:
  - role: user
    content: Your prompt here
YAML
```

```python Python nocheck
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=64000,
    thinking={"type": "adaptive"},
    output_config={"effort": "medium"},
    messages=[{"role": "user", "content": "Your prompt here"}],
)
```

```typescript TypeScript nocheck
const response = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 64000,
  thinking: { type: "adaptive" },
  output_config: { effort: "medium" },
  messages: [{ role: "user", content: "Your prompt here" }]
});
```

```csharp C# nocheck
using Anthropic;
using Anthropic.Models.Messages;

AnthropicClient client = new();

var parameters = new MessageCreateParams
{
    Model = Model.ClaudeSonnet4_6,
    MaxTokens = 64000,
    Thinking = new ThinkingConfigAdaptive(),
    OutputConfig = new OutputConfig { Effort = Effort.Medium },
    Messages = [new() { Role = Role.User, Content = "Your prompt here" }]
};

var message = await client.Messages.Create(parameters);
Console.WriteLine(message);
```

```go Go nocheck hidelines={1..11,-1}
package main

import (
	"context"
	"fmt"
	"log"

	"github.com/anthropics/anthropic-sdk-go"
)

func main() {
	client := anthropic.NewClient()

	response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
		Model:     "claude-sonnet-4-6",
		MaxTokens: 64000,
		Thinking: anthropic.ThinkingConfigParamUnion{
			OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{},
		},
		OutputConfig: anthropic.OutputConfigParam{
			Effort: anthropic.OutputConfigEffortMedium,
		},
		Messages: []anthropic.MessageParam{
			anthropic.NewUserMessage(anthropic.NewTextBlock("Your prompt here")),
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}
```

```java Java nocheck hidelines={1..5,8..10,-2..}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.Model;
import com.anthropic.models.messages.OutputConfig;
import com.anthropic.models.messages.ThinkingConfigAdaptive;

public class Main {
    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        MessageCreateParams params = MessageCreateParams.builder()
            .model(Model.CLAUDE_SONNET_4_6)
            .maxTokens(64000L)
            .thinking(ThinkingConfigAdaptive.builder().build())
            .outputConfig(OutputConfig.builder()
                .effort(OutputConfig.Effort.MEDIUM)
                .build())
            .addUserMessage("Your prompt here")
            .build();

        Message response = client.messages().create(params);
        System.out.println(response);
    }
}
```

```php PHP hidelines={1..4} nocheck
<?php

use Anthropic\Client;

$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));

$message = $client->messages->create(
    maxTokens: 64000,
    messages: [['role' => 'user', 'content' => 'Your prompt here']],
    model: 'claude-sonnet-4-6',
    thinking: ['type' => 'adaptive'],
    outputConfig: ['effort' => 'medium'],
);

echo array_find($message->content, fn($block) => $block->type === 'text')->text;
```

```ruby Ruby nocheck hidelines={1..2}
require "anthropic"

client = Anthropic::Client.new

message = client.messages.create(
  model: "claude-sonnet-4-6",
  max_tokens: 64000,
  thinking: {
    type: "adaptive"
  },
  output_config: {
    effort: "medium"
  },
  messages: [
    { role: "user", content: "Your prompt here" }
  ]
)
puts message.content.find { |block| block.type == :text }.text
```
</CodeGroup>

<Note>
如果您在使用自适应思维时遇到不一致的行为或质量下降，请尝试降低[努力度](/docs/en/build-with-claude/effort)设置或先使用 `max_tokens` 作为硬性限制。带有 `budget_tokens` 的扩展思维在 Sonnet 4.6 上仍然可用但已弃用，不再推荐。
</Note>

##### 在迁移期间保留 budget_tokens

如果您在迁移期间需要临时保留 `budget_tokens`，约 16k token 的预算可以为较难的问题提供空间，而不会有 token 使用失控的风险。此配置已弃用，将在未来的模型版本中移除。

###### 编程和代理用例

对于代理编程、前端设计、工具密集型工作流和复杂的企业工作流，从 `medium` 努力度开始。如果延迟过高，考虑降低到 `low` 努力度。如果需要更高的智能，考虑增加到 `high` 努力度或迁移到 Opus 4.7。

<CodeGroup>
```bash cURL
curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "anthropic-beta: interleaved-thinking-2025-05-14" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-sonnet-4-6",
    "max_tokens": 16384,
    "thinking": {
        "type": "enabled",
        "budget_tokens": 16384
    },
    "output_config": {
        "effort": "medium"
    },
    "messages": [
        {
            "role": "user",
            "content": "Your prompt here"
        }
    ]
}'
```

```bash CLI
ant beta:messages create --beta interleaved-thinking-2025-05-14 <<'YAML'
model: claude-sonnet-4-6
max_tokens: 16384
thinking:
  type: enabled
  budget_tokens: 16384
output_config:
  effort: medium
messages:
  - role: user
    content: Your prompt here
YAML
```

```python Python
response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=16384,
    thinking={"type": "enabled", "budget_tokens": 16384},
    output_config={"effort": "medium"},
    betas=["interleaved-thinking-2025-05-14"],
    messages=[{"role": "user", "content": "Your prompt here"}],
)
```

```typescript TypeScript
const response = await client.beta.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 16384,
  thinking: { type: "enabled", budget_tokens: 16384 },
  output_config: { effort: "medium" },
  betas: ["interleaved-thinking-2025-05-14"],
  messages: [{ role: "user", content: "Your prompt here" }]
});
```

```csharp C#
using Anthropic;
using Anthropic.Models.Beta;
using Anthropic.Models.Beta.Messages;

AnthropicClient client = new();

var parameters = new MessageCreateParams
{
    Model = "claude-sonnet-4-6",
    MaxTokens = 16384,
    Thinking = new BetaThinkingConfigEnabled { BudgetTokens = 16384 },
    OutputConfig = new BetaOutputConfig
    {
        Effort = Effort.Medium
    },
    Betas = [AnthropicBeta.InterleavedThinking2025_05_14],
    Messages = [new() { Role = Role.User, Content = "Your prompt here" }]
};

var message = await client.Beta.Messages.Create(parameters);
Console.WriteLine(message);
```

```go Go hidelines={1..11,-1}
package main

import (
	"context"
	"fmt"
	"log"

	"github.com/anthropics/anthropic-sdk-go"
)

func main() {
	client := anthropic.NewClient()

	response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
		Model:     "claude-sonnet-4-6",
		MaxTokens: 16384,
		Thinking:  anthropic.BetaThinkingConfigParamOfEnabled(16384),
		OutputConfig: anthropic.BetaOutputConfigParam{
			Effort: anthropic.BetaOutputConfigEffortMedium,
		},
		Messages: []anthropic.BetaMessageParam{
			anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Your prompt here")),
		},
		Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaInterleavedThinking2025_05_14},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}
```

```java Java hidelines={1..6,9..11,-2..}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.messages.MessageCreateParams;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.messages.Model;
import com.anthropic.models.beta.AnthropicBeta;
import com.anthropic.models.beta.messages.BetaThinkingConfigEnabled;
import com.anthropic.models.beta.messages.BetaOutputConfig;

public class Main {
    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        MessageCreateParams params = MessageCreateParams.builder()
            .model(Model.CLAUDE_SONNET_4_6)
            .maxTokens(16384L)
            .thinking(BetaThinkingConfigEnabled.builder()
                .budgetTokens(16384L)
                .build())
            .outputConfig(BetaOutputConfig.builder()
                .effort(BetaOutputConfig.Effort.MEDIUM)
                .build())
            .addBeta(AnthropicBeta.INTERLEAVED_THINKING_2025_05_14)
            .addUserMessage("Your prompt here")
            .build();

        BetaMessage response = client.beta().messages().create(params);
        System.out.println(response);
    }
}
```

```php PHP hidelines={1..4}
<?php

use Anthropic\Client;

$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));

$message = $client->beta->messages->create(
    maxTokens: 16384,
    messages: [['role' => 'user', 'content' => 'Your prompt here']],
    model: 'claude-sonnet-4-6',
    thinking: ['type' => 'enabled', 'budget_tokens' => 16384],
    outputConfig: ['effort' => 'medium'],
    betas: ['interleaved-thinking-2025-05-14'],
);

echo array_find($message->content, fn($block) => $block->type === 'text')->text;
```

```ruby Ruby hidelines={1..2}
require "anthropic"

client = Anthropic::Client.new

message = client.beta.messages.create(
  model: "claude-sonnet-4-6",
  max_tokens: 16384,
  thinking: {
    type: "enabled",
    budget_tokens: 16384
  },
  output_config: {
    effort: "medium"
  },
  betas: ["interleaved-thinking-2025-05-14"],
  messages: [
    { role: "user", content: "Your prompt here" }
  ]
)
puts message.content.find { |block| block.type == :text }.text
```
</CodeGroup>

###### 聊天和非编程用例

对于聊天、内容生成、搜索、分类和其他非编程任务，从带扩展思维的 `low` 努力度开始。如果需要更多深度，将努力度增加到 `medium`。

<CodeGroup>
```bash cURL
curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "anthropic-beta: interleaved-thinking-2025-05-14" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-sonnet-4-6",
    "max_tokens": 8192,
    "thinking": {
        "type": "enabled",
        "budget_tokens": 16384
    },
    "output_config": {
        "effort": "low"
    },
    "messages": [
        {
            "role": "user",
            "content": "Your prompt here"
        }
    ]
}'
```

```bash CLI
ant beta:messages create --beta interleaved-thinking-2025-05-14 <<'YAML'
model: claude-sonnet-4-6
max_tokens: 8192
thinking:
  type: enabled
  budget_tokens: 16384
output_config:
  effort: low
messages:
  - role: user
    content: Your prompt here
YAML
```

```python Python
response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=8192,
    thinking={"type": "enabled", "budget_tokens": 16384},
    output_config={"effort": "low"},
    betas=["interleaved-thinking-2025-05-14"],
    messages=[{"role": "user", "content": "Your prompt here"}],
)
```

```typescript TypeScript
const response = await client.beta.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 8192,
  thinking: { type: "enabled", budget_tokens: 16384 },
  output_config: { effort: "low" },
  betas: ["interleaved-thinking-2025-05-14"],
  messages: [{ role: "user", content: "Your prompt here" }]
});
```

```csharp C#
using Anthropic;
using Anthropic.Models.Beta;
using Anthropic.Models.Beta.Messages;

AnthropicClient client = new();

var parameters = new MessageCreateParams
{
    Model = "claude-sonnet-4-6",
    MaxTokens = 8192,
    Thinking = new BetaThinkingConfigEnabled { BudgetTokens = 16384 },
    OutputConfig = new BetaOutputConfig
    {
        Effort = Effort.Low
    },
    Betas = [AnthropicBeta.InterleavedThinking2025_05_14],
    Messages = [new() { Role = Role.User, Content = "Your prompt here" }]
};

var message = await client.Beta.Messages.Create(parameters);
Console.WriteLine(message);
```

```go Go hidelines={1..11,-1}
package main

import (
	"context"
	"fmt"
	"log"

	"github.com/anthropics/anthropic-sdk-go"
)

func main() {
	client := anthropic.NewClient()

	response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
		Model:     "claude-sonnet-4-6",
		MaxTokens: 8192,
		Thinking:  anthropic.BetaThinkingConfigParamOfEnabled(16384),
		OutputConfig: anthropic.BetaOutputConfigParam{
			Effort: anthropic.BetaOutputConfigEffortLow,
		},
		Messages: []anthropic.BetaMessageParam{
			anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Your prompt here")),
		},
		Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaInterleavedThinking2025_05_14},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}
```

```java Java hidelines={1..6,9..11,-2..}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.messages.MessageCreateParams;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.messages.Model;
import com.anthropic.models.beta.AnthropicBeta;
import com.anthropic.models.beta.messages.BetaThinkingConfigEnabled;
import com.anthropic.models.beta.messages.BetaOutputConfig;

public class Main {
    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        MessageCreateParams params = MessageCreateParams.builder()
            .model(Model.CLAUDE_SONNET_4_6)
            .maxTokens(8192L)
            .thinking(BetaThinkingConfigEnabled.builder()
                .budgetTokens(16384L)
                .build())
            .outputConfig(BetaOutputConfig.builder()
                .effort(BetaOutputConfig.Effort.LOW)
                .build())
            .addBeta(AnthropicBeta.INTERLEAVED_THINKING_2025_05_14)
            .addUserMessage("Your prompt here")
            .build();

        BetaMessage response = client.beta().messages().create(params);
        System.out.println(response);
    }
}
```

```php PHP hidelines={1..4}
<?php

use Anthropic\Client;

$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));

$message = $client->beta->messages->create(
    maxTokens: 8192,
    messages: [['role' => 'user', 'content' => 'Your prompt here']],
    model: 'claude-sonnet-4-6',
    thinking: ['type' => 'enabled', 'budget_tokens' => 16384],
    outputConfig: ['effort' => 'low'],
    betas: ['interleaved-thinking-2025-05-14'],
);

echo array_find($message->content, fn($block) => $block->type === 'text')->text;
```

```ruby Ruby hidelines={1..2}
require "anthropic"

client = Anthropic::Client.new

message = client.beta.messages.create(
  model: "claude-sonnet-4-6",
  max_tokens: 8192,
  thinking: {
    type: "enabled",
    budget_tokens: 16384
  },
  output_config: {
    effort: "low"
  },
  betas: ["interleaved-thinking-2025-05-14"],
  messages: [
    { role: "user", content: "Your prompt here" }
  ]
)
puts message.content.find { |block| block.type == :text }.text
```
</CodeGroup>

### Sonnet 4.6 迁移清单

- [ ] 将模型 ID 更新为 `claude-sonnet-4-6`
- [ ] **破坏性：** 移除助手消息预填充；改用结构化输出或 `output_config.format`
- [ ] **破坏性：** 验证工具参数 JSON 解析处理转义差异
- [ ] **破坏性：** 将工具版本更新为最新（`text_editor_20250728`、`code_execution_20250825`）；不支持旧版本（如果从 3.x 迁移）
- [ ] **破坏性：** 移除任何使用 `undo_edit` 命令的代码（如适用）
- [ ] **破坏性：** 更新采样参数以仅使用 `temperature` 或 `top_p`，不要同时使用两者（如果从 3.x 迁移）
- [ ] 在您的应用中处理新的 `refusal` 停止原因
- [ ] 移除 `fine-grained-tool-streaming-2025-05-14` beta 头（现已正式发布）
- [ ] 将 `output_format` 迁移到 `output_config.format`
- [ ] 按照[提示最佳实践](/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices)审查和更新提示词
- [ ] **推荐：** 将 `thinking: {type: "enabled", budget_tokens: N}` 迁移到带有[努力度参数](/docs/en/build-with-claude/effort)的 `thinking: {type: "adaptive"}`（`budget_tokens` 已弃用，将在未来版本中移除）
- [ ] 在生产部署前在开发环境中测试

---

## 迁移到 Claude Sonnet 4.5

Claude Sonnet 4.5 结合了强大的智能和快速的性能，非常适合日常编程、分析和内容任务。

有关功能的完整概述，请参阅[模型概述](/docs/en/about-claude/models/overview)。

<Note>
Sonnet 4.5 定价为每百万输入 token $3，每百万输出 token $15。详情请参阅 [Claude 定价](/docs/en/about-claude/pricing)。
</Note>

**更新模型名称：**

```python
# 从 Sonnet 4
model = "claude-sonnet-4-20250514"  # 之前
model = "claude-sonnet-4-5-20250929"  # 之后

# 从 Sonnet 3.7
model = "claude-3-7-sonnet-20250219"  # 之前
model = "claude-sonnet-4-5-20250929"  # 之后
```

### 破坏性变更

这些破坏性变更适用于从 Claude 3.x Sonnet 模型迁移时。

1. **更新采样参数**

   <Warning>
   从 Claude 3.x 模型迁移时，这是一项破坏性变更。
   </Warning>

   仅使用 `temperature` 或 `top_p`，不要同时使用两者。

2. **更新工具版本**

   <Warning>
   从 Claude 3.x 模型迁移时，这是一项破坏性变更。
   </Warning>

   更新到最新工具版本（`text_editor_20250728`、`code_execution_20250825`）。移除任何使用 `undo_edit` 命令的代码。

3. **处理 `refusal` 停止原因**

   更新您的应用以[处理 `refusal` 停止原因](/docs/en/test-and-evaluate/strengthen-guardrails/handle-streaming-refusals)。

4. **为行为变更更新提示词**

   Claude 4 模型具有更简洁、直接的沟通风格。请查阅[提示最佳实践](/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices)获取优化指导。

### Sonnet 4.5 迁移清单

- [ ] 将模型 ID 更新为 `claude-sonnet-4-5-20250929`
- [ ] **破坏性：** 将工具版本更新为最新（`text_editor_20250728`、`code_execution_20250825`）；不支持旧版本（如果从 3.x 迁移）
- [ ] **破坏性：** 移除任何使用 `undo_edit` 命令的代码（如适用）
- [ ] **破坏性：** 更新采样参数以仅使用 `temperature` 或 `top_p`，不要同时使用两者（如果从 3.x 迁移）
- [ ] 在您的应用中处理新的 `refusal` 停止原因
- [ ] 按照[提示最佳实践](/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices)审查和更新提示词
- [ ] 考虑为复杂推理任务启用扩展思维
- [ ] 在生产部署前在开发环境中测试

---

## 迁移到 Claude Haiku 4.5

Claude Haiku 4.5 是最快、最智能的 Haiku 模型，具有接近前沿的性能，为交互式应用和大批量处理提供优质模型质量。

有关功能的完整概述，请参阅[模型概述](/docs/en/about-claude/models/overview)。

<Note>
Haiku 4.5 定价为每百万输入 token $1，每百万输出 token $5。详情请参阅 [Claude 定价](/docs/en/about-claude/pricing)。
</Note>

**更新模型名称：**

```python
# 从 Haiku 3.5
model = "claude-3-5-haiku-20241022"  # 之前
model = "claude-haiku-4-5-20251001"  # 之后
```

**查看新的速率限制：** Haiku 4.5 的速率限制与 Haiku 3.5 分开。详情请参阅[速率限制文档](/docs/en/api/rate-limits)。

<Tip>
要在编程和推理任务上获得显著的性能提升，考虑启用带有 `thinking: {type: "enabled", budget_tokens: N}` 的扩展思维。
</Tip>

<Note>
扩展思维会影响[提示缓存](/docs/en/build-with-claude/prompt-caching#caching-with-thinking-blocks)效率。

扩展思维在 Claude 4.6 模型中已弃用，在 Claude Opus 4.7 中已移除。如果使用较新的模型，请改用[自适应思维](/docs/en/build-with-claude/adaptive-thinking)。
</Note>

**探索新功能：** 有关上下文感知、增加的输出能力（64k token）、更高的智能和改进的速度的详情，请参阅[模型概述](/docs/en/about-claude/models/overview)。

### 破坏性变更

这些破坏性变更适用于从 Claude 3.x Haiku 模型迁移时。

1. **更新采样参数**

   <Warning>
   从 Claude 3.x 模型迁移时，这是一项破坏性变更。
   </Warning>

   仅使用 `temperature` 或 `top_p`，不要同时使用两者。

2. **更新工具版本**

   <Warning>
   从 Claude 3.x 模型迁移时，这是一项破坏性变更。
   </Warning>

   更新到最新工具版本（`text_editor_20250728`、`code_execution_20250825`）。移除任何使用 `undo_edit` 命令的代码。

3. **处理 `refusal` 停止原因**

   更新您的应用以[处理 `refusal` 停止原因](/docs/en/test-and-evaluate/strengthen-guardrails/handle-streaming-refusals)。

4. **为行为变更更新提示词**

   Claude 4 模型具有更简洁、直接的沟通风格。请查阅[提示最佳实践](/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices)获取优化指导。

### Haiku 4.5 迁移清单

- [ ] 将模型 ID 更新为 `claude-haiku-4-5-20251001`
- [ ] **破坏性：** 将工具版本更新为最新（`text_editor_20250728`、`code_execution_20250825`）；不支持旧版本
- [ ] **破坏性：** 移除任何使用 `undo_edit` 命令的代码（如适用）
- [ ] **破坏性：** 更新采样参数以仅使用 `temperature` 或 `top_p`，不要同时使用两者
- [ ] 在您的应用中处理新的 `refusal` 停止原因
- [ ] 审查并适应新的速率限制（与 Haiku 3.5 分开）
- [ ] 按照[提示最佳实践](/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices)审查和更新提示词
- [ ] 考虑为复杂推理任务启用扩展思维
- [ ] 在生产部署前在开发环境中测试

---

## 获取帮助

- 查阅 [API 文档](/docs/en/api/overview)获取详细规格说明
- 查阅[模型功能](/docs/en/about-claude/models/overview)了解性能对比
- 查阅 [API 发布说明](/docs/en/release-notes/api)了解 API 更新
- 如果在迁移过程中遇到任何问题，请联系支持