# 数据驻留

通过地理位置控制管理模型推理运行的位置和数据存储的位置。

---

<Note>
此功能符合[零数据保留（ZDR）](/docs/en/build-with-claude/api-and-data-retention)资格。当您的组织有 ZDR 安排时，通过此功能发送的数据在 API 响应返回后不会被存储。
</Note>

数据驻留控制让您管理数据处理和存储的位置。两个独立的设置控制此行为：

- **推理地理位置：** 控制模型推理运行的位置，按请求级别设置。通过 `inference_geo` API 参数或作为工作区默认值设置。
- **工作区地理位置：** 控制静态数据存储的位置和端点处理（如图像转码和代码执行）发生的位置。在 [Claude 控制台](https://platform.claude.com)中在工作区级别配置。

<Note>
[Claude 托管智能体](/docs/en/managed-agents/overview)不支持 `inference_geo` 参数，但遵循在控制台中配置的工作区地理位置。使用[自托管沙箱](/docs/en/managed-agents/self-hosted-sandboxes)时，工具执行和沙箱文件系统保留在您控制的基础设施上。
</Note>

## 推理地理位置

`inference_geo` 参数控制特定 API 请求的模型推理运行位置。将其添加到任何 `POST /v1/messages` 调用中。

| 值 | 描述 |
|:------|:------------|
| `"global"` | 默认值。推理可能在任何可用的地理位置运行，以获得最佳性能和可用性。 |
| `"us"` | 仅在美国基础设施上运行推理。 |

### API 用法

<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-opus-4-7",
        "max_tokens": 1024,
        "inference_geo": "us",
        "messages": [{
            "role": "user",
            "content": "Summarize the key points of this document."
        }]
    }'
```

```bash CLI
ant messages create \
  --model claude-opus-4-7 \
  --max-tokens 1024 \
  --inference-geo us \
  --message '{role: user, content: "Summarize the key points of this document."}' \
  --transform '{content.0.text,usage.inference_geo}' --format yaml
```

```python Python hidelines={1..2}
import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    inference_geo="us",
    messages=[
        {"role": "user", "content": "Summarize the key points of this document."}
    ],
)

print(response.content[0].text)
# 检查推理实际运行的位置
print(f"Inference geo: {response.usage.inference_geo}")
```

```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: 1024,
  inference_geo: "us",
  messages: [
    {
      role: "user",
      content: "Summarize the key points of this document."
    }
  ]
});

const textBlock = response.content.find(
  (block): block is Anthropic.TextBlock => block.type === "text"
);
console.log(textBlock?.text);
// 检查推理实际运行的位置
console.log(`Inference geo: ${response.usage.inference_geo}`);
```
</CodeGroup>

### 响应

响应 `usage` 对象包含一个 `inference_geo` 字段，指示推理运行的位置：

```json Output
{
  "usage": {
    "input_tokens": 25,
    "output_tokens": 150,
    "inference_geo": "us"
  }
}
```

### 模型可用性

`inference_geo` 参数在 Claude Opus 4.6、Claude Sonnet 4.6 及更高版本模型上受支持。在 Claude Opus 4.5、Claude Sonnet 4.5、Claude Haiku 4.5 或更早版本模型上使用 `inference_geo` 的请求将返回 400 错误。

<Note>
`inference_geo` 参数在 Claude API（第一方）和 [Claude Platform on AWS](/docs/en/build-with-claude/claude-platform-on-aws) 上可用。在 Amazon Bedrock、Vertex AI 和 Microsoft Foundry 上，推理区域由端点 URL 或推理配置文件决定，因此 `inference_geo` 不适用。`inference_geo` 参数也不适用于 [OpenAI SDK 兼容端点](/docs/en/api/openai-sdk)。
</Note>

### 工作区级别限制

工作区设置还支持限制可用的推理地理位置：

- **`allowed_inference_geos`：** 限制工作区可以使用的地理位置。如果请求指定的 `inference_geo` 不在此列表中，API 将返回错误。
- **`default_inference_geo`：** 设置请求中省略 `inference_geo` 时的回退地理位置。单个请求可以通过显式设置 `inference_geo` 来覆盖此设置。

这些设置可以通过控制台或 [Admin API](/docs/en/manage-claude/admin-api) 在 `data_residency` 字段下配置。

## 工作区地理位置

工作区地理位置在创建工作区时设置，之后无法更改。目前，`"us"` 是唯一可用的工作区地理位置。

要设置工作区地理位置，请在[控制台](https://platform.claude.com)中创建新工作区：

1. 转到**设置** > **工作区**。
2. 创建新工作区。
3. 选择工作区地理位置。

<Note>
**Claude Platform on AWS：** 工作区地理位置不可配置。工作区通过 AWS 控制台配置，Claude 控制台的工作区页面为只读。此平台上的 Claude 托管智能体会话以有效的工作区地理位置 `"us"` 运行，这是目前唯一可用的工作区地理位置。有关该平台特定的数据驻留注意事项，请参阅 [Claude Platform on AWS](/docs/en/build-with-claude/claude-platform-on-aws)。
</Note>

## 定价

数据驻留定价因模型世代而异：

- **Claude Opus 4.6、Claude Sonnet 4.6 及更高版本：** 仅美国推理（`inference_geo: "us"`）在所有 token 定价类别（输入 token、输出 token、缓存写入和缓存读取）中按标准费率的 1.1 倍计费。
- **全局路由**（`inference_geo: "global"`）：适用标准定价。
- **较旧模型：** 不支持 `inference_geo`（请参阅[模型可用性](#模型可用性)）；适用标准定价。包含此参数的请求将返回 400 错误。

此定价适用于 Claude API（第一方）和 Claude Platform on AWS。合作伙伴运营的平台（Bedrock 和 Vertex AI）有其自己的区域定价。有关详细信息，请参阅[数据驻留定价](/docs/en/about-claude/pricing#data-residency-pricing)。

<Note>
如果您使用[优先层级](/docs/en/api/service-tiers)，仅美国推理的 1.1 倍乘数也会影响 token 对您优先层级容量的计数方式。使用 `inference_geo: "us"` 消耗的每个 token 从您的承诺 TPM 中扣除 1.1 个 token，与其他定价乘数（如提示缓存）影响消耗速率的方式一致。
</Note>

## 批处理 API 支持

`inference_geo` 参数在[批处理 API](/docs/en/build-with-claude/batch-processing) 上受支持。批处理中的每个请求可以指定自己的 `inference_geo` 值。

## 从旧版选择退出迁移

如果您的组织之前选择退出全局路由以将推理保持在美国，您的工作区已自动配置为 `allowed_inference_geos: ["us"]` 和 `default_inference_geo: "us"`。无需更改代码。您现有的数据驻留要求继续通过新的地理位置控制强制执行。

### 变更内容

旧版选择退出是一个组织级别的设置，将所有请求限制在美国基础设施上。新的数据驻留控制通过两种机制替代了它：

- **按请求控制：** `inference_geo` 参数让您在每个 API 调用上指定 `"us"` 或 `"global"`，为您提供请求级别的灵活性。
- **工作区控制：** 控制台中的 `default_inference_geo` 和 `allowed_inference_geos` 设置让您在工作区中的所有密钥上强制执行地理位置策略。

### 您的工作区发生了什么变化

您的工作区已自动迁移：

| 旧版设置 | 新等效设置 |
|:---------------|:---------------|
| 全局路由选择退出（仅美国） | `allowed_inference_geos: ["us"]`、`default_inference_geo: "us"` |

使用您工作区密钥的所有 API 请求继续在美国基础设施上运行。无需采取任何操作即可维持当前行为。

### 如果您想使用全局路由

如果您的数据驻留要求已更改，并且您想利用全局路由获得更好的性能和可用性，请更新工作区的推理地理位置设置以在允许的地理位置中包含 `"global"`，并将 `default_inference_geo` 设置为 `"global"`。有关详细信息，请参阅[工作区级别限制](#工作区级别限制)。

### 定价影响

旧版模型不受此迁移影响。有关新版本模型的当前定价，请参阅[定价](#定价)。

## 当前限制

- **共享速率限制：** 速率限制在所有地理位置之间共享。
- **推理地理位置：** 仅 `"us"` 和 `"global"` 可用。
- **工作区地理位置：** 目前仅 `"us"` 可用。工作区地理位置在创建工作区后无法更改。

## 后续步骤

<CardGroup>
  <Card title="定价" icon="dollar-sign" href="/docs/en/about-claude/pricing#data-residency-pricing">
    查看数据驻留定价详情。
  </Card>
  <Card title="工作区" icon="building" href="/docs/en/manage-claude/workspaces">
    了解工作区配置。
  </Card>
  <Card title="使用量和成本 API" icon="chart" href="/docs/en/manage-claude/usage-cost-api">
    按数据驻留跟踪使用量和成本。
  </Card>
</CardGroup>