# Claude in Microsoft Foundry

通过 Microsoft Foundry 使用 Azure 原生端点和认证访问 Claude 模型。

---

本指南将引导您使用 Anthropic 的客户端 SDK 或直接 HTTP 请求设置和向 Foundry 中的 Claude 发起 API 调用。当您可以访问 Foundry 中的 Claude 时，您将在 Microsoft Marketplace 中为 Claude 使用付费，允许您访问 Claude 的最新功能，同时通过 Azure 订阅管理成本。

区域可用性：在发布时，Claude 在 Foundry 资源中作为全局标准部署类型可用。Microsoft Marketplace 中 Claude 的定价使用 Anthropic 的标准 API 定价。访问[定价](https://claude.com/pricing#api)了解详情。

<Note>
Foundry 由 C#、Java、PHP、Python 和 TypeScript SDK 支持。Go 和 Ruby SDK 目前不支持 Microsoft Foundry。有关可用的 SDK 平台集成，请参阅[客户端 SDK](/docs/en/api/client-sdks)。
</Note>

## 预览

在此预览平台集成中，Claude 模型运行在 Anthropic 的基础设施上。这是一个通过 Azure 进行计费和访问的商业集成。作为 Microsoft 的独立处理者，通过 Microsoft Foundry 使用 Claude 的客户受 Anthropic 数据使用条款的约束。Anthropic 继续提供其行业领先的安全和数据承诺，包括零数据保留可用性。

## 前提条件

在开始之前，请确保您已：

- 活跃的 Azure 订阅
- 访问 [Foundry](https://ai.azure.com/)
- 已安装 [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli)（可选，用于资源管理）

## 安装 SDK

Anthropic 的[客户端 SDK](/docs/en/api/client-sdks) 通过特定平台的包或客户端类支持 Foundry。

<Tabs>
<Tab title="Python">
```bash
pip install -U "anthropic"
```
</Tab>

<Tab title="TypeScript">
```bash
npm install @anthropic-ai/foundry-sdk
```
</Tab>

<Tab title="C#">
```bash
dotnet add package Anthropic.Foundry
```
</Tab>

<Tab title="Java">
<Tabs>
<Tab title="Gradle">
```kotlin
implementation("com.anthropic:anthropic-java-foundry:2.33.0")
```
</Tab>
<Tab title="Maven">
```xml
<dependency>
    <groupId>com.anthropic</groupId>
    <artifactId>anthropic-java-foundry</artifactId>
    <version>2.33.0</version>
</dependency>
```
</Tab>
</Tabs>
</Tab>

<Tab title="PHP">
```bash
composer require anthropic-ai/sdk
```
</Tab>
</Tabs>

## 配置

Foundry 使用两级层次结构：**资源**包含您的安全和计费配置，而**部署**是您通过 API 调用的模型实例。您将首先创建一个 Foundry 资源，然后在其中创建一个或多个 Claude 部署。

### 配置 Foundry 资源

创建 Foundry 资源，这是在 Azure 中使用和管理服务所必需的。您可以按照以下说明创建 [Foundry 资源](https://learn.microsoft.com/en-us/azure/ai-services/multi-service-resource?pivots=azportal#create-a-new-azure-ai-foundry-resource)。或者，您可以从创建 [Foundry 项目](https://learn.microsoft.com/en-us/azure/ai-foundry/how-to/create-projects?tabs=ai-foundry)开始，这涉及创建 Foundry 资源。

要配置您的资源：

1. 导航到 [Foundry 门户](https://ai.azure.com/)
2. 创建新的 Foundry 资源或选择现有资源
3. 使用 Azure 颁发的 API 密钥或 Entra ID（前身为 Azure Active Directory）配置访问管理以进行基于角色的访问控制
4. 可选择将资源配置为私有网络（Azure Virtual Network）的一部分以增强安全性
5. 记下您的资源名称。您将在 API 端点中将其用作 `{resource}`（例如 `https://{resource}.services.ai.azure.com/anthropic/v1/*`）

### 创建 Foundry 部署

创建资源后，部署 Claude 模型以使其可用于 API 调用：

1. 在 Foundry 门户中，导航到您的资源
2. 转到**模型 + 端点**并选择 **+ 部署模型** > **部署基础模型**
3. 搜索并选择 Claude 模型（例如 `claude-sonnet-4-6`）
4. 配置部署设置：
   - **部署名称：** 默认为模型 ID，但您可以自定义（例如 `my-claude-deployment`）。部署名称创建后无法更改。
   - **部署类型：** 选择全局标准（推荐用于 Claude）
5. 选择**部署**并等待配置完成
6. 部署后，您可以在**密钥和端点**下找到端点 URL 和密钥

<Note>
  您选择的部署名称将成为 API 请求中 `model` 参数的值。您可以使用不同名称创建同一模型的多个部署，以管理不同的配置或速率限制。
</Note>

## 认证

Claude in Foundry 支持两种认证方法：API 密钥和 Entra ID token。两种方法都使用格式为 `https://{resource}.services.ai.azure.com/anthropic/v1/*` 的 Azure 托管端点。

### API 密钥认证

配置 Foundry Claude 资源后，您可以从 Foundry 门户获取 API 密钥：

1. 在 Foundry 门户中导航到您的资源
2. 转到**密钥和端点**部分
3. 复制提供的 API 密钥之一
4. 在请求中使用 `api-key` 或 `x-api-key` 头，或将其提供给 SDK

Foundry SDK 需要 API 密钥以及资源名称或基础 URL。C#、Java、PHP、Python 和 TypeScript SDK 在定义时会自动从以下环境变量中读取：

- `ANTHROPIC_FOUNDRY_API_KEY` - 您的 API 密钥
- `ANTHROPIC_FOUNDRY_RESOURCE` - 您的资源名称（例如 `example-resource`）
- `ANTHROPIC_FOUNDRY_BASE_URL` - 资源名称的替代方案；完整的基础 URL（例如 `https://example-resource.services.ai.azure.com/anthropic/`）

<Note>
`resource` 和 `base_url` 参数互斥。提供资源名称（SDK 使用它构造 URL 为 `https://{resource}.services.ai.azure.com/anthropic/`）或直接提供完整的基础 URL。
</Note>

**使用 API 密钥的示例：**

<Tabs>
<Tab title="cURL">

```bash cURL nocheck
curl https://{resource}.services.ai.azure.com/anthropic/v1/messages \
  -H "content-type: application/json" \
  -H "api-key: YOUR_AZURE_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-7",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'
```
</Tab>

<Tab title="CLI">

```bash CLI nocheck
# ant 读取 ANTHROPIC_API_KEY 并将其作为 x-api-key 发送，Foundry 接受
export ANTHROPIC_API_KEY="YOUR_AZURE_API_KEY"

ant messages create \
  --base-url https://example-resource.services.ai.azure.com/anthropic \
  --model claude-opus-4-7 \
  --max-tokens 1024 \
  --message '{role: user, content: "Hello!"}' \
  --transform content
```
</Tab>

<Tab title="Python">

```python nocheck
import os
from anthropic import AnthropicFoundry

client = AnthropicFoundry(
    api_key=os.environ.get("ANTHROPIC_FOUNDRY_API_KEY"),
    resource="example-resource",  # 您的资源名称
)

message = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
)
print(message.content)
```
</Tab>

<Tab title="TypeScript">

```typescript nocheck
import AnthropicFoundry from "@anthropic-ai/foundry-sdk";

const client = new AnthropicFoundry({
  apiKey: process.env.ANTHROPIC_FOUNDRY_API_KEY,
  resource: "example-resource" // 您的资源名称
});

const message = await client.messages.create({
  model: "claude-opus-4-7",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello!" }]
});
console.log(message.content);
```
</Tab>

<Tab title="C#">

```csharp nocheck
using Anthropic.Foundry;
using Anthropic.Models.Messages;

var client = new AnthropicFoundryClient(
    new AnthropicFoundryApiKeyCredentials(
        Environment.GetEnvironmentVariable("ANTHROPIC_FOUNDRY_API_KEY")!,
        "example-resource"
    )
);

var response = await client.Messages.Create(new MessageCreateParams
{
    Model = "claude-opus-4-7",
    MaxTokens = 1024,
    Messages = [new() { Role = Role.User, Content = "Hello!" }],
});

Console.WriteLine(
    string.Join("", response.Content
        .Select(block => block.Value)
        .OfType<TextBlock>()
        .Select(textBlock => textBlock.Text)));
```
</Tab>

<Tab title="Java">

```java Java nocheck
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.foundry.backends.FoundryBackend;
import com.anthropic.models.messages.MessageCreateParams;

void main() {
    // 需要环境变量：ANTHROPIC_FOUNDRY_API_KEY、ANTHROPIC_FOUNDRY_RESOURCE
    AnthropicClient client = AnthropicOkHttpClient.builder()
        .backend(FoundryBackend.fromEnv())
        .build();

    MessageCreateParams params = MessageCreateParams.builder()
        .model("claude-opus-4-7")
        .maxTokens(1024)
        .addUserMessage("Hello!")
        .build();

    client.messages().create(params).content().stream()
        .flatMap(block -> block.text().stream())
        .forEach(textBlock -> System.out.println(textBlock.text()));
}
```
</Tab>

<Tab title="PHP">

```php PHP nocheck
<?php

use Anthropic\Foundry;

$client = Foundry\Client::withCredentials(
    apiKey: getenv('ANTHROPIC_FOUNDRY_API_KEY'),
    baseUrl: 'https://example-resource.services.ai.azure.com/anthropic/v1',
);

$message = $client->messages->create(
    maxTokens: 1024,
    messages: [
        ['role' => 'user', 'content' => 'Hello!']
    ],
    model: 'claude-opus-4-7',
);
echo $message->content[0]->text;
```
</Tab>

<Tab title="Ruby">
<Note>
Anthropic Ruby SDK 目前不支持 Microsoft Foundry。您可以使用标准的 `Anthropic::Client` 并将自定义 `base_url` 指向您的 Foundry 端点，但 Azure 特定的认证（Entra ID）未内置。要获得完整的 Foundry 支持，请使用 C#、Java、PHP、Python 或 TypeScript SDK。
</Note>
</Tab>
</Tabs>

<Warning>
确保您的 API 密钥安全。切勿将它们提交到版本控制或公开共享。任何可以访问您 API 密钥的人都可以通过您的 Foundry 资源向 Claude 发起请求。
</Warning>

### Microsoft Entra 认证

为了增强安全性和集中访问管理，您可以使用 Entra ID token：

1. 为您的 Foundry 资源启用 Entra 认证
2. 从 Entra ID 获取访问 token
3. 在 `Authorization: Bearer {TOKEN}` 头中使用 token

**使用 Entra ID 的示例：**

<Tabs>
<Tab title="cURL">

```bash cURL nocheck
# 获取 Microsoft Entra ID token
ACCESS_TOKEN=$(az account get-access-token --resource https://cognitiveservices.azure.com --query accessToken -o tsv)

# 使用 token 发起请求。将 {resource} 替换为您的资源名称
curl https://{resource}.services.ai.azure.com/anthropic/v1/messages \
  -H "content-type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-7",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'
```
</Tab>

<Tab title="Python">

```python nocheck
import os
from anthropic import AnthropicFoundry
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

# 使用 token 提供者模式获取 Microsoft Entra ID token
token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default"
)

# 使用 Entra ID 认证创建客户端
client = AnthropicFoundry(
    resource="example-resource",  # 您的资源名称
    azure_ad_token_provider=token_provider,  # 使用 token 提供者进行 Entra ID 认证
)

# 发起请求
message = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
)
print(message.content)
```
</Tab>

<Tab title="TypeScript">

```typescript nocheck
import AnthropicFoundry from "@anthropic-ai/foundry-sdk";
import { DefaultAzureCredential, getBearerTokenProvider } from "@azure/identity";

// 使用 token 提供者模式获取 Entra ID token
const credential = new DefaultAzureCredential();
const tokenProvider = getBearerTokenProvider(
  credential,
  "https://cognitiveservices.azure.com/.default"
);

// 使用 Entra ID 认证创建客户端
const client = new AnthropicFoundry({
  resource: "example-resource", // 您的资源名称
  azureADTokenProvider: tokenProvider // 使用 token 提供者进行 Entra ID 认证
});

// 发起请求
const message = await client.messages.create({
  model: "claude-opus-4-7",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello!" }]
});
console.log(message.content);
```
</Tab>

<Tab title="C#">

```csharp nocheck
using Anthropic.Foundry;
using Anthropic.Models.Messages;
using Azure.Identity;

var client = new AnthropicFoundryClient(
    new AnthropicFoundryIdentityTokenCredentials(
        new DefaultAzureCredential(),
        "example-resource"
    )
);

var response = await client.Messages.Create(new MessageCreateParams
{
    Model = "claude-opus-4-7",
    MaxTokens = 1024,
    Messages = [new() { Role = Role.User, Content = "Hello!" }],
});

Console.WriteLine(
    string.Join("", response.Content
        .Select(block => block.Value)
        .OfType<TextBlock>()
        .Select(textBlock => textBlock.Text)));
```
</Tab>

<Tab title="Java">

```java Java nocheck hidelines={1..2,4,8}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.foundry.backends.FoundryBackend;
import com.anthropic.models.messages.MessageCreateParams;
import com.azure.identity.AuthenticationUtil;
import com.azure.identity.DefaultAzureCredentialBuilder;
import java.util.function.Supplier;

void main() {
    Supplier<String> bearerTokenSupplier = AuthenticationUtil.getBearerTokenSupplier(
        new DefaultAzureCredentialBuilder().build(),
        "https://cognitiveservices.azure.com/.default"
    );

    AnthropicClient client = AnthropicOkHttpClient.builder()
        .backend(FoundryBackend.builder()
            .bearerTokenSupplier(bearerTokenSupplier)
            .resource("example-resource")
            .build())
        .build();

    MessageCreateParams params = MessageCreateParams.builder()
        .model("claude-opus-4-7")
        .maxTokens(1024)
        .addUserMessage("Hello!")
        .build();

    client.messages().create(params).content().stream()
        .flatMap(block -> block.text().stream())
        .forEach(textBlock -> System.out.println(textBlock.text()));
}
```
</Tab>

<Tab title="PHP">

```php PHP nocheck
<?php

use Anthropic\Foundry;

// 获取 Entra ID 访问 token，例如通过 Azure CLI：
//   az account get-access-token --resource https://cognitiveservices.azure.com \
//     --query accessToken -o tsv
$token = getenv('AZURE_ACCESS_TOKEN');

$client = Foundry\Client::withCredentials(
    authToken: $token,
    baseUrl: 'https://example-resource.services.ai.azure.com/anthropic/v1',
);

$message = $client->messages->create(
    maxTokens: 1024,
    messages: [
        ['role' => 'user', 'content' => 'Hello!']
    ],
    model: 'claude-opus-4-7',
);
echo $message->content[0]->text;
```
</Tab>

<Tab title="Ruby">
<Note>
Anthropic Ruby SDK 目前不支持 Microsoft Foundry。您可以使用标准的 `Anthropic::Client` 并将自定义 `base_url` 指向您的 Foundry 端点，但 Azure 特定的认证（Entra ID）未内置。要获得完整的 Foundry 支持，请使用 C#、Java、PHP、Python 或 TypeScript SDK。
</Note>
</Tab>
</Tabs>

<Note>
Microsoft Entra ID 认证允许您使用 Azure RBAC 管理访问，与组织的身份管理集成，并避免手动管理 API 密钥。
</Note>

## 关联请求 ID

Foundry 在 HTTP 响应头中包含请求标识符，用于调试和跟踪。联系支持时，请同时提供 `request-id` 和 `apim-request-id` 值，以帮助团队在 Anthropic 和 Azure 系统中快速定位和调查您的请求。

## 功能支持

Claude in Foundry 支持 Claude 的大多数强大功能。您可以在[功能概览](/docs/en/build-with-claude/overview)中找到当前支持的所有功能。

### 上下文窗口

Claude Opus 4.7、Claude Opus 4.6 和 Claude Sonnet 4.6 在 Microsoft Foundry 上具有 [1M token 上下文窗口](/docs/en/build-with-claude/context-windows)。其他 Claude 模型，包括 Sonnet 4.5，具有 200k token 上下文窗口。

### 不支持的功能

- Admin API
- Compliance API
- Models API
- Message Batches API

## API 响应

来自 Claude in Foundry 的 API 响应遵循标准的 [Claude API 响应格式](/docs/en/api/messages/create)。这包括响应体中的 `usage` 对象，它为您的请求提供详细的 token 消耗信息。`usage` 对象在所有平台（Claude API、Foundry、Claude Platform on AWS、Amazon Bedrock 和 Vertex AI）上是一致的。

有关 Foundry 特定的响应头详细信息，请参阅[关联请求 ID](#关联请求-id)。

## API 模型 ID 和部署

以下 Claude 模型可通过 Foundry 使用。最新一代模型（Opus 4.7、Opus 4.6、Sonnet 4.6 和 Haiku 4.5）提供最先进的功能：

| 模型             | 默认部署名称     |
| :---------------- | :-------------------------- |
| Claude Opus 4.7   | `claude-opus-4-7`           |
| Claude Opus 4.6   | `claude-opus-4-6`           |
| Claude Opus 4.5   | `claude-opus-4-5`           |
| Claude Opus 4.1   | `claude-opus-4-1`           |
| Claude Sonnet 4.6 | `claude-sonnet-4-6`         |
| Claude Sonnet 4.5 | `claude-sonnet-4-5`         |
| Claude Haiku 4.5  | `claude-haiku-4-5`          |

默认情况下，部署名称与上表中显示的模型 ID 匹配。但是，您可以在 Foundry 门户中创建具有不同名称的自定义部署，以管理不同的配置、版本或速率限制。在 API 请求中使用部署名称（不一定是模型 ID）。

<Tip>
正在升级到更新的 Claude 模型？在 Claude Code 中，运行 `/claude-api migrate` 以在代码库中应用模型 ID 交换和重大参数更改。该技能检测您的代码目标云平台，并为该平台调整模型 ID 格式和功能更改。请参阅[迁移到更新的 Claude 模型](/docs/en/agents-and-tools/agent-skills/claude-api-skill#migrating-to-a-newer-claude-model)。
</Tip>

## 监控和日志

Azure 通过标准 Azure 模式为您的 Claude 使用提供全面的监控和日志功能：

- **Azure Monitor：** 跟踪 API 使用情况、延迟和错误率
- **Azure Log Analytics：** 查询和分析请求/响应日志
- **成本管理：** 监控和预测与 Claude 使用相关的成本

Anthropic 建议至少保留 30 天的滚动活动日志，以了解使用模式并调查任何潜在问题。

<Note>
Azure 的日志服务在您的 Azure 订阅中配置。启用日志不会让 Microsoft 或 Anthropic 访问您的内容，超出计费和服务运营所需的内容。
</Note>

## 故障排除

### 认证错误

**错误：** `401 Unauthorized` 或 `Invalid API key`

- **解决方案：** 验证您的 API 密钥是否正确。您可以从 Foundry 门户中您的 Foundry 资源的**密钥和端点**下获取新的 API 密钥。
- **解决方案：** 如果使用 Microsoft Entra ID，请确保您的访问 token 有效且未过期。token 通常在 1 小时后过期。

**错误：** `403 Forbidden`

- **解决方案：** 您的 Azure 账户可能缺少必要的权限。确保您已分配适当的 Azure RBAC 角色（例如"Cognitive Services OpenAI User"）。

### 速率限制

**错误：** `429 Too Many Requests`

- **解决方案：** 您已超出速率限制。在应用程序中实现指数退避和重试逻辑。
- **解决方案：** 考虑通过 Azure 门户或 Azure 支持请求速率限制增加。

#### 速率限制头

Foundry 不在响应中包含 Anthropic 的标准速率限制头（`anthropic-ratelimit-tokens-limit`、`anthropic-ratelimit-tokens-remaining`、`anthropic-ratelimit-tokens-reset`、`anthropic-ratelimit-input-tokens-limit`、`anthropic-ratelimit-input-tokens-remaining`、`anthropic-ratelimit-input-tokens-reset`、`anthropic-ratelimit-output-tokens-limit`、`anthropic-ratelimit-output-tokens-remaining` 和 `anthropic-ratelimit-output-tokens-reset`）。请改用 Azure 的监控工具管理速率限制。

### 模型和部署错误

**错误：** `Model not found` 或 `Deployment not found`

- **解决方案：** 验证您使用的是正确的部署名称。如果您尚未创建自定义部署，请使用默认模型 ID（例如 `claude-sonnet-4-6`）。
- **解决方案：** 确保模型/部署在您的 Azure 区域中可用。

**错误：** `Invalid model parameter`

- **解决方案：** model 参数应包含您的部署名称，该名称可在 Foundry 门户中自定义。验证部署是否存在并正确配置。

<Info>
[Claude Mythos Preview](https://anthropic.com/glasswing) 是一个研究预览，面向 Microsoft Foundry 上受邀客户开放。有关更多信息，请参阅 [Project Glasswing](https://anthropic.com/glasswing)。
</Info>

## 其他资源

- **Foundry 文档：** [ai.azure.com/catalog](https://ai.azure.com/catalog/publishers/anthropic)
- **Azure 定价：** [azure.microsoft.com/en-us/pricing/details/ai-foundry](https://azure.microsoft.com/en-us/pricing/details/ai-foundry/#pricing)
- **Anthropic 定价详情：** [模型定价](/docs/en/about-claude/pricing#model-pricing)
- **认证指南：** 参见[认证](#认证)
- **Azure 门户：** [portal.azure.com](https://portal.azure.com/)