Azure OpenAI 密钥配置与 Python 调用示例

知识分享

2026-10-31 14:00

14 阅读

Azure OpenAI 和直接调用 OpenAI 接口最大的区别在于：请求地址由你的 Azure 资源决定，模型需要先部署，鉴权使用 Azure 密钥而不是组织级 API Key。
如果你已经有一个 Azure 订阅，下一步的步骤可以帮你从零完成资源创建、密钥获取和第一次 Python 调用。

创建资源前需要准备什么

在开始操作之前，确认三件事：

一个可用的 Azure 订阅，并且该订阅已获得 Azure OpenAI 的访问权限。部分订阅类型需要先提交使用申请，审批通过后才能创建资源。
本地或服务器上安装 Python 3.8 及以上版本，并能正常使用 pip 安装第三方库。
清楚自己要调用哪种模型（例如对话模型或嵌入模型），因为后续需要在 Azure 门户中手动部署模型，未部署的模型名无法直接调用。

如果订阅尚未开通 Azure OpenAI 权限，创建资源时会提示不可用，此时需要先在 Azure 门户中提交申请，等待审批后再继续。

在 Azure 门户创建资源并获取密钥

终结点（Endpoint）：形如 https://你的资源名.openai.azure.com/，后续所有请求都发往这个地址。
密钥（Key）：页面会给出 KEY1 和 KEY2，任选一个即可。生产环境建议定期轮换，两个密钥可以交替使用以减少中断。

拿到终结点和密钥后，还需要部署模型。
进入“模型部署”页面，点击“部署模型”，选择模型版本并给部署起一个名字。
这个部署名就是代码中要填的 deployment_name，它不一定等于模型原名，建议起一个容易识别的名字。

用 Python SDK 发起第一次调用

安装官方 SDK：

pip install openai

设置环境变量，避免把密钥直接写进代码：

export AZURE_OPENAI_API_KEY="你的密钥"
export AZURE_OPENAI_ENDPOINT="https://你的资源名.openai.azure.com/"

编写调用脚本：

import os
from openai import AzureOpenAI

client = AzureOpenAI(
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    api_version="2024-02-01",
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"]
)

response = client.chat.completions.create(
    model="你的部署名",
    messages=[
        {"role": "user", "content": "用一句话解释什么是 Azure OpenAI"}
    ]
)

print(response.choices[0].message.content)

注意 model 参数填的是部署名，不是模型原名。api_version 需要与资源支持的版本匹配，不同时期可用的版本可能不同，以门户中显示的为准。

如果不想安装 SDK，也可以用 REST 接口直接请求：

curl "$AZURE_OPENAI_ENDPOINT/openai/deployments/你的部署名/chat/completions?api-version=2024-02-01" \
  -H "Content-Type: application/json" \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -d '{"messages":[{"role":"user","content":"你好"}]}'

请求头使用 api-key，而不是 Authorization: Bearer，这是 Azure OpenAI 与 OpenAI 官方接口的一个明显差异。

常见报错与排查方向

调用失败时，先看 HTTP 状态码，再对照下面的方向排查：

401 Unauthorized：密钥错误或未传递。检查环境变量是否生效，请求头字段是否为 api-key。
404 Not Found：终结点地址或部署名写错。确认 URL 中是否包含 /openai/deployments/部署名/ 这一段，以及部署名是否与门户中完全一致。
429 Too Many Requests：触发速率限制。可以在门户中查看已部署模型的配额，适当降低请求频率或申请提升配额。
400 Bad Request：请求体格式问题，常见于 messages 结构不正确或 api-version 与请求路径不匹配。

排查时建议先用 curl 发一个最小请求，确认密钥和终结点本身可用，再回到代码中检查参数。

调用成功后的验证方式

一次成功的调用会返回 JSON，其中 choices[0].message.content 就是模型输出。
如果返回内容为空，检查请求中的 messages 是否至少包含一条用户消息。
另外，可以在门户的“指标”页面观察请求数和延迟，确认调用确实到达了资源。

对于生产环境，建议把终结点和密钥放在环境变量或密钥管理服务中，不要提交到代码仓库；
同时为部署配置好配额告警，避免流量突增时被限流。

关于模型部署和版本的两个提醒

Azure OpenAI 的模型需要手动部署，且部署名可以自定义，这是新手最容易出错的地方。
另一个容易忽略的点是 api_version：它和模型版本不是一回事，升级 SDK 或更换模型时不需要盲目修改，但如果请求返回版本相关错误，应优先核对请求路径中的版本参数与资源支持的版本是否一致。

Google AI API 怎么调用：密钥申请与 Python 请求示例

AWS Bedrock 调用大模型：API 密钥与 Python 请求示例