Microsoft Foundry 与 Azure OpenAI API 接入指南

适用范围与调用前检查

本指南从已获授权的 Azure 订阅、资源和模型部署开始，使用 OpenAI Python SDK 调用 Microsoft 的 v1 聊天接口。它不创建云资源，也不说明每个模型都支持同一功能。先在控制台记录资源名、真实模型版本、部署名、部署类型、配额与网络访问方式；model 填部署名，不是从第三方目录猜出的模型名称。

确认该部署支持 Chat Completions 和示例中的 max_completion_tokens。Responses、工具调用、图像、推理参数与流式能力均要分别核对；模型不支持 Responses 时，不应仅替换路径反复重试。Azure OpenAI 与 Foundry 的非 OpenAI 模型存在能力和授权差异，项目管理端点也不能直接作为模型推理端点。

核对端点与身份权限

v1 的 base_url 采用资源的 /openai/v1/ 路径；官方也支持相应的 services.ai.azure.com 资源域名形式。复制你的资源控制台配置，不能把项目 URL、旧 /deployments/... 路径和 v1 混用。v1 不要求日期式 api-version，这不意味着旧版接口也可删掉版本参数。

处理位置取决于部署类型，Global、Data Zone 与区域部署不能只按资源名称推断。若有数据边界要求，先核对部署方式及适用条件。由有权限的管理员授予推理身份权限：Azure OpenAI 模型可核对 Cognitive Services OpenAI User；Foundry 非 OpenAI 模型按相应文档核对 Cognitive Services User。订阅 Owner 或 Contributor 不自动等于模型调用权限。还应确认服务端的代理、私有端点、DNS和防火墙设置一致。

安装并配置最小请求

python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade openai

以下均为占位值，先换成自己的资源和部署。AZURE_OPENAI_API_KEY 由授权的服务端运行环境安全注入；不要把密钥写进网页、仓库或终端共享记录。

export AZURE_OPENAI_BASE_URL='https://YOUR-RESOURCE.openai.azure.com/openai/v1/'
export AZURE_OPENAI_DEPLOYMENT='YOUR-DEPLOYMENT-NAME'

保存下面代码为 azure_chat.py。只在确认允许模型费用后，用普通测试句运行 python azure_chat.py；128是此例的输出限制，30秒为客户端超时示例，均不是平台配额或支持承诺。SDK自动重试暂设为0，便于先观察原始失败。

import os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ["AZURE_OPENAI_BASE_URL"],
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    timeout=30.0,
    max_retries=0,
)
request = {
    "model": os.environ["AZURE_OPENAI_DEPLOYMENT"],
    "messages": [{"role": "user", "content": "Reply with one short greeting."}],
    "max_completion_tokens": 128,
}
answer = client.chat.completions.create(**request)
if not answer.choices:
    raise RuntimeError("No completion choice returned")
print(answer.choices[0].message.content or "")
print(answer.usage.model_dump() if answer.usage else "usage unavailable")

使用 Entra ID，避免长期静态密钥

服务端生产应用可采用托管身份或其他获批准的 Entra 凭据链。安装依赖后，用下列初始化替换前例的client，保留其余请求逻辑。先完成角色分配，再验证运行身份；不要打印访问令牌。当前官方 v1 示例的 scope 为 https://ai.azure.com/.default。

python -m pip install --upgrade azure-identity

from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)
client = OpenAI(
    base_url=os.environ["AZURE_OPENAI_BASE_URL"],
    api_key=token_provider,
    timeout=30.0,
    max_retries=0,
)

流式解析与错误处理

在确认部署支持流式聊天后，用以下代码替换非流式调用。先检查 choices 再取索引，按增量文本拼接；usage如有返回则单独读取。部分部署需要支持的usage选项才能返回用量，未收到usage不能当作零费用。Responses使用不同事件结构，不能套这个解析器。

usage = None
with client.chat.completions.create(**request, stream=True) as events:
    for part in events:
        if part.usage is not None:
            usage = part.usage
        if not part.choices:
            continue
        text = part.choices[0].delta.content
        if text:
            print(text, end="", flush=True)
print()
print(usage.model_dump() if usage else "usage unavailable")

• 401/403：核对身份来源、资源范围、角色及网络策略，不在日志打印密钥或令牌。
• 404：核对资源域名、v1路径与部署名，避免调用管理端点。
• 400：检查该模型的API、参数与内容限制；删减可选参数定位原因。
• 429：核对配额和并发，结合服务返回的等待提示进行有限退避；超时/5xx不无限重试。

验收、费用与资料边界

保留脱敏的请求编号、模型/部署版本、finish reason、耗时和用量，对照Azure账单；确认截断、拒答与连接中断时的应用行为。输出费用、缓存、部署容量和第三方服务应按实际计费方式分别核对，不能套其他渠道单价。数据保留、内容安全处理与Global部署的处理范围须按实际服务条款审查，应用侧也应控制日志和访问权限。

本示例仅作离线语法检查，没有使用你的订阅、读取密钥或真实调用模型；账户可用性、质量和费用须由获授权的环境实测。

Claude：先核对原生接口与采购资格

Claude 使用独立的 Messages API。用 AnthropicFoundry 连接资源的 https://YOUR-RESOURCE.services.ai.azure.com/anthropic，HTTP Messages 目标路径为 /anthropic/v1/messages。请求中的 model 必须是实际部署名，它可以与目录中的模型 ID 不同。前面的 OpenAI v1 示例只适用于明确支持该 API 的部署。Foundry 项目管理 URL、OpenAI v1 路径和 Claude 原生路径各有用途；进入伙伴模型目录并不代表模型都兼容 OpenAI API。

配置客户端前依次确认：

1. 订阅为符合资格的 Azure 付费订阅，账单国家受支持，并具有购买 Marketplace 产品的权限。微软当前 Claude 文档明确排除 Cloud Solution Provider（CSP）订阅，另有其他订阅限制；拥有 Azure 账户本身不代表可以采购。
2. 从模型卡和部署详情记录模型、托管版本、部署类型及当前支持的部署区域。版本 1 运行在 Anthropic 基础设施，版本 2 托管在 Azure。两者均提供 Global Standard；仅部分 Azure 托管模型版本提供 Data Zone Standard（US）。必须核对精确的模型、版本、类型组合，不能按资源所属国家推断可用性。
3. 复制原生端点与部署名。使用 Entra 推理时，核对 Foundry 资源范围的 Cognitive Services User 角色和实际运行身份。Azure OpenAI 专用角色或资源管理角色不能代替这项检查；网络访问也要单独确认。
4. 核对部署支持的认证方式、Messages 参数、流式能力及配额。部分受限模型只接受 Entra ID。Files、Skills、工具等高级能力会随托管和模型版本变化，不要直接沿用另一个 Claude 部署的参数。

Anthropic 托管的 v1 请求可能在 Azure 及所选 Azure 区域之外处理。Azure 托管的 v2 也要分别核对 Global 或 Data Zone 的处理范围与静态存储位置。两种配置下，Anthropic 都是销售方、运营方，并作为提示词和输出的独立数据处理方。应采用 Claude Marketplace 与数据处理条款；Azure OpenAI 的留存或 SLA 说明不会自动覆盖 Claude。

Claude：独立的 API Key 最小请求

对支持 API Key 的部署，在获授权的服务端安装依赖并配置这些占位项。密钥由安全的服务端环境提供，不要写入浏览器代码或复制示例。将下列 Python 另存为独立 Claude 示例。本次只做离线检查，没有执行依赖安装或云端请求。输出上限和超时是示例控制值，SDK 自动重试已关闭。

下列 API Key 与 Entra 示例都显式设置 base_url。SDK 仍会自动读取 ANTHROPIC_FOUNDRY_RESOURCE，因此配置客户端前应取消该环境变量。另一种选择是用 resource 初始化，不传 base_url，同时取消 SDK 会自动读取的 ANTHROPIC_FOUNDRY_BASE_URL 设置。

python -m pip install --upgrade anthropic azure-identity
# Explicit base_url must not be combined with the SDK resource-name fallback.
unset ANTHROPIC_FOUNDRY_RESOURCE
# Copy both values from your actual Foundry deployment in the console.
export FOUNDRY_CLAUDE_BASE_URL='https://YOUR-RESOURCE.services.ai.azure.com/anthropic'
export FOUNDRY_CLAUDE_DEPLOYMENT='YOUR-CLAUDE-DEPLOYMENT-NAME'
# Supply FOUNDRY_CLAUDE_API_KEY through the approved server secret environment.

import os
from anthropic import AnthropicFoundry

client = AnthropicFoundry(
    base_url=os.environ["FOUNDRY_CLAUDE_BASE_URL"],
    api_key=os.environ["FOUNDRY_CLAUDE_API_KEY"],
    timeout=30.0,
    max_retries=0,
)
message = client.messages.create(
    model=os.environ["FOUNDRY_CLAUDE_DEPLOYMENT"],
    max_tokens=128,
    messages=[{"role": "user", "content": "Reply with one short greeting."}],
)
for block in message.content:
    if block.type == "text":
        print(block.text)
print(message.stop_reason)
print(message.usage.model_dump())

响应返回带类型的 content 内容块，只输出文本块，并检查 stop_reason 和 usage 后再验收。原生 HTTP 使用 x-api-key 和 anthropic-version: 2023-06-01，响应不是 OpenAI 的 choices 结构。先确认部署支持的组合，再加入 thinking 或工具参数。

Claude：用 Entra ID 替换密钥

保留前例的 import os、AnthropicFoundry 和 Messages 请求，只用下列代码替换客户端初始化。采用获批准的凭据链，优先使用应用的托管身份，并先核对资源角色。azure_ad_token_provider 获取 scope 为 https://ai.azure.com/.default 的令牌，原生 HTTP 对应 Authorization: Bearer ...。每次只配置一种认证；使用此 provider 时，移除显式 API Key 及 SDK 会自动读取的 ANTHROPIC_FOUNDRY_API_KEY 设置，不要打印令牌。

from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)
client = AnthropicFoundry(
    base_url=os.environ["FOUNDRY_CLAUDE_BASE_URL"],
    azure_ad_token_provider=token_provider,
    timeout=30.0,
    max_retries=0,
)

Claude：流式、故障与验收

支持流式的部署可在 Messages 中设置 stream=True，接收 SSE。原生事件流程为 message_start，按索引传输的 content_block_start / content_block_delta / content_block_stop，再到 message_delta 和 message_stop。文本增量的 delta.type == "text_delta"；工具与 thinking 使用其他内容块类型。分别处理 ping、未知事件和错误，保留最终用量及停止信息，完成前断开的流应标为不完整。OpenAI 的 choices[].delta 或 Responses 事件解析器不能用于此协议。HTTP 状态成功并不保证流会完整结束。

Claude 的 401/403 应核对所选认证方式、令牌 scope 和资源角色；404 应核对 /anthropic 及准确部署名。400 可能来自不支持的参数或特定模型的数据留存要求，后者应按适用条款复核。采购或区域错误应检查订阅资格及模型版本可用性。遇到 429，应检查订阅、模型、版本对应的配额并限制重试；换区域新建资源仍可能共享同一个 Global 配额池。按实际 Marketplace Claude Consumption Unit（CCU）计量、输入输出和缓存用量核对账单，不要沿用前面 OpenAI 部署的价格。在获授权环境中分别测试无敏感内容的正常输出、截断和流中断，再验收集成。

官方依据

核验日期：2026-10-17。使用前复核当前文档与控制台。

• Microsoft v1 API与版本
• Foundry模型端点与部署名
• Entra身份与角色
• 部署类型与处理范围
• Claude 部署、原生端点与认证
• Claude 托管版本、采购与处理边界
• Claude 模型能力与部署类型
• Claude 配额与速率限制
• Claude 数据处理
• Claude Consumption Unit 计费
• Anthropic 原生 Messages 流式事件
• AnthropicFoundry SDK 客户端选项