Microsoft Foundry 中的 Claude

本指南将引导您完成在 Microsoft Foundry 中设置并使用 Anthropic 的客户端 SDK 或直接 HTTP 请求调用 Claude API 的过程。当您在 Microsoft Foundry 中访问 Claude 时，Claude 的使用费用将通过 Azure Marketplace 计费，使您能够在通过 Azure 订阅管理成本的同时访问 Claude 的最新功能。

Claude 在 Foundry 资源中以 Global Standard 和 US Data Zone Standard 部署类型提供，通过 Azure Marketplace 以 Claude Consumption Units（Claude 消费单位）计费。请访问定价了解详情。



托管选项

Microsoft Foundry 中的 Claude 模型提供两种托管选项。您可以在配置部署时选择托管选项。



前提条件

在开始之前，请确保您具备以下条件：

• 有效的 Azure 订阅
• 可访问 Foundry
• 已安装 Azure CLI（可选，用于资源管理）



安装 SDK

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



配置

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



配置 Foundry 资源

创建一个 Foundry 资源，这是在 Azure 中使用和管理服务所必需的。您可以按照这些说明创建 Foundry 资源。或者，您也可以从创建 Foundry 项目开始，该过程包含创建 Foundry 资源。

要配置您的资源：

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



创建 Foundry 部署

创建资源后，部署一个 Claude 模型以使其可用于 API 调用。以下步骤描述的是新版 Foundry 门户（New Foundry 开关处于开启状态）：

1. 登录 Foundry 门户。在门户主页上，选择右上角导航中的 Discover，然后在左侧窗格中选择 Models 以打开模型目录。
2. 搜索并选择一个 Claude 模型（例如 claude-opus-4-8）。无论模型支持多少种托管选项，每个模型在目录中只出现一次。
3. 在模型卡片上，选择 Deploy，然后选择 Custom settings 以打开部署设置窗格。如果您选择 Default settings，对于同时支持两种托管选项的模型，部署将自动配置为托管于 Azure。
4. 首次部署 Claude 时，请查看 Azure Marketplace 条款，选择一个行业，然后选择 Agree and Proceed 以接受条款并订阅 Azure Marketplace 产品。
5. 配置部署：
   • Deployment name（部署名称）： 默认为模型 ID，但您可以自定义（例如 my-claude-deployment）。部署名称在创建后无法更改。
   • Region scope（区域范围）： 选择 Global，或者对于托管于 Azure 的模型，选择 Data Zone。选择 Data Zone 会创建 US Data Zone Standard 部署，将推理限制在美国境内，等同于在 Claude API 上设置 inference_geo: "us"。
   • Model version（模型版本）： 展开 Model version settings 并从 Model version 下拉菜单中选择一个版本。每个托管选项都作为单独的模型版本列出，并标注其托管选项（例如，版本 1 为托管于 Anthropic，版本 2 为托管于 Azure）。
6. 选择 Deploy 并等待配置完成。
7. 部署完成后，选择右上角导航中的 Build，然后在左侧窗格中选择 Models，并打开您的部署。Details 选项卡显示 Target URI（您的端点 URL）和 Key（您的 API 密钥）。



身份验证

Microsoft Foundry 中的 Claude 支持两种身份验证方法：API 密钥和 Entra ID 令牌。两种方法都使用格式为 https://{resource}.services.ai.azure.com/anthropic/v1/* 的 Azure 托管端点。



API 密钥身份验证

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

1. 在 Foundry 门户中，选择右上角导航中的 Build，然后在左侧窗格中选择 Models。
2. 打开您的 Claude 部署并选择 Details 选项卡。
3. 复制 Key 值（并记下 Target URI 作为您的端点）。
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/）

使用 API 密钥的示例：



Microsoft Entra 身份验证

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

1. 为您的 Foundry 资源启用 Entra 身份验证
2. 从 Entra ID 获取访问令牌
3. 在 Authorization: Bearer {TOKEN} 标头中使用该令牌

使用 Entra ID 的示例：



关联请求 ID

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



功能支持

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



上下文窗口

Claude Fable 5、Claude Opus 4.8、Claude Opus 4.7、Claude Opus 4.6、Claude Sonnet 5 和 Claude Sonnet 4.6 在 Microsoft Foundry 上拥有 100 万令牌的上下文窗口。其他 Claude 模型（包括 Claude Sonnet 4.5）拥有 20 万令牌的上下文窗口。



Microsoft Foundry 中的 Claude 不支持的 Claude 功能

• Admin API
• Advisor 工具
• Claude Managed Agents
• Compliance API
• Models API
• Message Batches API
• 服务器端回退（fallbacks 参数；请改用客户端回退模式）



托管于 Azure 时不支持的其他功能

以下功能适用于托管于 Anthropic 的部署，但不支持托管于 Azure 的部署：

• 结构化输出
• 服务器端工具（网络搜索、网络获取、代码执行和工具搜索）
• MCP 连接器
• Agent Skills
• 编程式工具调用
• Files API

针对托管于 Azure 的部署使用这些功能的请求会按设计返回 400 Bad Request 错误。Claude Code 会检测托管于 Azure 的部署并自动调整其功能集。



API 响应

Microsoft Foundry 中 Claude 的 API 响应遵循标准的 Claude API 响应格式。这包括响应正文中的 usage 对象，该对象提供您请求的详细令牌消耗信息。usage 对象在所有平台（Claude API、Foundry、AWS 上的 Claude Platform、Amazon Bedrock 和 Google Cloud）上保持一致。

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



API 模型 ID 和部署

生命周期术语（已弃用、已停用）在模型弃用中定义。Microsoft Foundry 遵循 Claude API 的生命周期计划。

以下 Claude 模型可通过 Foundry 使用：

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



计费

Microsoft Foundry 中的 Claude 通过 Azure Marketplace 计费。使用量以 Claude Consumption Units（CCU，Claude 消费单位）计量，按小时计量，并按月后付费计入您的 Azure 账单。CCU 不是预付费额度；没有 CCU 余额或承诺。

有关 CCU 价格、换算机制和每个模型的令牌费率，请参阅 Microsoft Foundry 中的 Claude 定价。



在托管选项之间迁移

要将现有部署从一种托管选项迁移到另一种：

1. 创建该模型另一个托管版本（托管于 Azure 或托管于 Anthropic）的新部署。这可以在同一个 Foundry 资源中，也可以在新资源中。
2. 更新您的应用程序，在 model 参数中传递新的部署名称。
3. 流量迁移完成后，删除旧部署。

如果新部署位于同一个 Foundry 资源中，您的端点 URL 和身份验证保持不变。如果您创建了新资源，请更新应用程序的端点和凭据以指向新资源。



监控和日志记录

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

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

Anthropic 建议至少以 30 天滚动方式记录您的活动，以了解使用模式并调查任何潜在问题。



故障排除



身份验证错误

错误： 401 Unauthorized 或 Invalid API key

• 解决方案： 验证您的 API 密钥是否正确。您可以在 Foundry 门户中部署的 Details 选项卡（位于 Build > Models 下）找到它。
• 解决方案： 如果使用 Microsoft Entra ID，请确保您的访问令牌有效且未过期。令牌通常在 1 小时后过期。

错误： 403 Forbidden

• 解决方案： 您的 Azure 账户可能缺少必要的权限。请确保您已分配适当的 Azure RBAC 角色（例如 Foundry User（原 Azure AI User）或 Cognitive Services 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 门户中自定义。请验证部署是否存在且配置正确。



其他资源

• Foundry 文档： ai.azure.com/catalog
• Azure 定价： azure.microsoft.com/en-us/pricing/details/ai-foundry
• Anthropic 定价详情： 模型定价
• 身份验证指南： 请参阅身份验证
• Azure 门户： portal.azure.com