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 定价。访问定价了解详情。

Note

Foundry 由 C#、Java、PHP、Python 和 TypeScript SDK 支持。Go 和 Ruby SDK 目前不支持 Microsoft Foundry。有关可用的 SDK 平台集成,请参阅客户端 SDK

预览

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

前提条件

在开始之前,请确保您已:

  • 活跃的 Azure 订阅
  • 访问 Foundry
  • 已安装 Azure CLI(可选,用于资源管理)

安装 SDK

Anthropic 的客户端 SDK 通过特定平台的包或客户端类支持 Foundry。

pip install -U "anthropic"
npm install @anthropic-ai/foundry-sdk
dotnet add package Anthropic.Foundry
implementation("com.anthropic:anthropic-java-foundry:2.33.0")
<dependency>
    <groupId>com.anthropic</groupId>
    <artifactId>anthropic-java-foundry</artifactId>
    <version>2.33.0</version>
</dependency>
composer require anthropic-ai/sdk

配置

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

配置 Foundry 资源

创建 Foundry 资源,这是在 Azure 中使用和管理服务所必需的。您可以按照以下说明创建 Foundry 资源。或者,您可以从创建 Foundry 项目开始,这涉及创建 Foundry 资源。

要配置您的资源:

  1. 导航到 Foundry 门户
  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 参数的值。您可以使用不同名称创建同一模型的多个部署,以管理不同的配置或速率限制。

认证

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-keyx-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

resourcebase_url 参数互斥。提供资源名称(SDK 使用它构造 URL 为 https://{resource}.services.ai.azure.com/anthropic/)或直接提供完整的基础 URL。

使用 API 密钥的示例:

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!"}
    ]
  }'
# 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
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)
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);
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)));
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()));
}
<?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;
Note

Anthropic Ruby SDK 目前不支持 Microsoft Foundry。您可以使用标准的 Anthropic::Client 并将自定义 base_url 指向您的 Foundry 端点,但 Azure 特定的认证(Entra ID)未内置。要获得完整的 Foundry 支持,请使用 C#、Java、PHP、Python 或 TypeScript SDK。

Warning

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

Microsoft Entra 认证

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

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

使用 Entra ID 的示例:

# 获取 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!"}
    ]
  }'
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)
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);
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)));
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()));
}
<?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;
Note

Anthropic Ruby SDK 目前不支持 Microsoft Foundry。您可以使用标准的 Anthropic::Client 并将自定义 base_url 指向您的 Foundry 端点,但 Azure 特定的认证(Entra ID)未内置。要获得完整的 Foundry 支持,请使用 C#、Java、PHP、Python 或 TypeScript SDK。

Note

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

关联请求 ID

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

功能支持

Claude in Foundry 支持 Claude 的大多数强大功能。您可以在功能概览中找到当前支持的所有功能。

上下文窗口

Claude Opus 4.7、Claude Opus 4.6 和 Claude Sonnet 4.6 在 Microsoft Foundry 上具有 1M token 上下文窗口。其他 Claude 模型,包括 Sonnet 4.5,具有 200k token 上下文窗口。

不支持的功能

  • Admin API
  • Compliance API
  • Models API
  • Message Batches API

API 响应

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

有关 Foundry 特定的响应头详细信息,请参阅关联请求 ID

API 模型 ID 和部署

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

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

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

Tip

正在升级到更新的 Claude 模型?在 Claude Code 中,运行 /claude-api migrate 以在代码库中应用模型 ID 交换和重大参数更改。该技能检测您的代码目标云平台,并为该平台调整模型 ID 格式和功能更改。请参阅迁移到更新的 Claude 模型

监控和日志

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

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

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

Note

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

故障排除

认证错误

错误: 401 UnauthorizedInvalid 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-limitanthropic-ratelimit-tokens-remaininganthropic-ratelimit-tokens-resetanthropic-ratelimit-input-tokens-limitanthropic-ratelimit-input-tokens-remaininganthropic-ratelimit-input-tokens-resetanthropic-ratelimit-output-tokens-limitanthropic-ratelimit-output-tokens-remaininganthropic-ratelimit-output-tokens-reset)。请改用 Azure 的监控工具管理速率限制。

模型和部署错误

错误: Model not foundDeployment not found

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

错误: Invalid model parameter

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

Claude Mythos Preview 是一个研究预览,面向 Microsoft Foundry 上受邀客户开放。有关更多信息,请参阅 Project Glasswing

其他资源