配置 OpenAI Azure 端点时需要修改哪些 SDK 参数？

配置 Azure OpenAI 端点时，SDK 需修改 base_url 为 Azure 资源地址，api_key 替换为 Azure 密钥或 Entra ID 令牌，并显式指定 api_version 查询参数。同时需将模型名称映射为 Azure 部署 ID，否则请求会被拒绝。

先说结论：核心差异在于终结点结构、身份验证方式和版本控制，直接沿用 OpenAI 默认配置会导致连接失败。

适合：使用 Python openai 库、.NET、Java 或 REST 直接调用 Azure 服务的场景。
先准备：Azure 资源名称、部署 ID、API 密钥或 Entra ID 权限、有效的 API 版本号。
验收：通过 SDK 发起聊天补全请求，确认返回状态码 200 且无认证错误。

命令速用版

以下 Python 代码展示了使用 openai SDK 连接 Azure 时的关键参数修改，重点在于 azure_endpoint 和 api_version 的显式声明。

from openai import AzureOpenAI

client = AzureOpenAI(
    azure_endpoint="https://{your-resource-name}.openai.azure.com/",
    api_key="{your-api-key}",
    api_version="2024-10-21"
)

response = client.chat.completions.create(
    model="{your-deployment-id}",
    messages=[{"role": "user", "content": "Hello"}]
)

为什么会这样

Azure OpenAI 服务本质由服务资源和模型部署两个独立但强耦合的组件构成，导致请求路径与原生 OpenAI 不同。

原生 OpenAI 直接使用模型名作为路径标识，而 Azure 需要在终结点中嵌入资源名称，并在请求中指定部署 ID。此外，Azure 要求通过查询参数明确 API 版本，以支持不同版本的接口特性，如响应 API 或批处理功能。

分步处理

按顺序检查以下四个配置项，确保每一项都与 Azure 控制台显示一致。

1. 修改 Base URL
将默认地址替换为 Azure 资源终结点，格式通常为 https://{your-resource-name}.openai.azure.com/openai/v1 或包含 deployments 路径。

2. 替换认证凭证
使用 Azure Portal 生成的 Key 1 或 Key 2，若企业环境要求更高安全级别，可配置 Microsoft Entra ID 令牌进行认证。

3. 指定 API 版本
在 SDK 初始化或请求参数中加入 api_version，例如 2024-10-21 或 2023-07-01-preview，版本过旧可能导致功能不可用。

4. 映射部署名称
请求中的 model 参数必须填写 Azure 中创建的部署 ID，而非基础模型名称，否则返回 404 错误。

怎么验证是否生效

运行一个简单的补全请求，检查返回对象中是否包含 usage 信息且无异常抛出。

若使用 REST 工具，观察 HTTP 状态码是否为 200，响应体中 choices 字段是否有内容。若返回 401，检查密钥是否复制完整；若返回 404，检查部署 ID 是否与区域匹配。

常见坑

1. 免费层限制
默认创建的 Free Tier 资源组可能不支持自定义模型或与虚拟网络集成，生产环境建议跳过图形化向导直接使用模板。

2. 区域支持差异
并非所有区域都支持最新的响应 API 或特定模型版本，部署前需确认资源区域是否在支持列表中。

3. 密钥与权限
本地测试能通但 CI/CD 报错 401，通常是因为环境变量未正确注入密钥，或缺少 Cognitive Services User 角色权限。

常见问题

如何不使用 API 密钥而用 Entra ID 认证？

推荐使用 DefaultAzureCredential 获取令牌，并在请求头中设置 Authorization: Bearer {token}，避免硬编码密钥。

API 版本号应该选最新的吗？

建议选择稳定版版本号，如 2024-10-21，预览版版本可能随时间变更导致接口不兼容。

为什么模型名填了 gpt-4 还是报错？

Azure 中必须填写自定义的部署 ID，例如 my-gpt4-deployment，直接填基础模型名无法识别。

参考来源

Azure OpenAI in Microsoft Foundry Models REST API 参考
Azure OpenAI 生产级部署实操指南：从零到可用的 7 步落地-CSDN 博客
使用 Azure OpenAI 响应 API
Microsoft Foundry SDK 和终结点
【企业级 AI 部署必看】:MCP+Azure OpenAI 配置优化的 8 个黄金法则