跳转至

Azure OpenAI SDK 适配详解

记录从标准 OpenAI API 迁移到 Azure OpenAI 的完整适配过程，包括 Python SDK 改造、环境配置和 Codex 集成。

背景

2026-03-10，在 Agentic BI POC 开发中发现： - 初期 Codex 无法使用，缺少 Azure API Key 配置 - 配置 Key 后发现：Azure OpenAI 的 API 格式与标准 OpenAI 不同 - 需要从标准 OpenAI client 切换到 AzureOpenAI client

核心差异

客户端类型

项目 标准 OpenAI Azure OpenAI
Client OpenAI AzureOpenAI
必需参数 api_key api_key, azure_endpoint, api_version
model 语义 模型名 deployment name

环境变量

标准 OpenAI： 

OPENAI_API_KEY=sk-xxx
OPENAI_BASE_URL=https://api.openai.com/v1  # 可选

Azure OpenAI： 

AZURE_OPENAI_API_KEY=xxx
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
AZURE_OPENAI_API_VERSION=2024-02-01
AZURE_OPENAI_DEPLOYMENT=gpt-5-4

Python SDK 适配

标准 OpenAI 写法

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
    base_url=os.environ.get("OPENAI_BASE_URL"),
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
)

Azure OpenAI 写法

from openai import AzureOpenAI

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

response = client.chat.completions.create(
    model=os.environ["AZURE_OPENAI_DEPLOYMENT"],  # deployment name
    messages=[{"role": "user", "content": "Hello"}],
)

兼容层封装

为同时支持两种 Provider：

import os
from openai import OpenAI, AzureOpenAI

def build_client():
    provider = os.environ.get("LLM_PROVIDER", "openai")

    if provider == "azure":
        client = AzureOpenAI(
            api_key=os.environ["AZURE_OPENAI_API_KEY"],
            azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
            api_version=os.environ.get("AZURE_OPENAI_API_VERSION", "2024-02-01"),
        )
        model_name = os.environ["AZURE_OPENAI_DEPLOYMENT"]
    else:
        client = OpenAI(
            api_key=os.environ["OPENAI_API_KEY"],
            base_url=os.environ.get("OPENAI_BASE_URL"),
        )
        model_name = os.environ.get("OPENAI_MODEL", "gpt-4o")

    return client, model_name

# 使用
client, model = build_client()
resp = client.chat.completions.create(
    model=model,
    messages=[{"role": "user", "content": "ping"}],
)

Codex 适配

问题发现

2026-03-13，Agent Portal 开发中发现： - Codex 拿着 Azure OpenAI API Key - 却尝试连接 api.openai.com - 新版 Codex (v0.113.0) 不再自动使用 AZURE_OPENAI_API_KEY

解决方案

在 Codex 配置中显式声明 Azure Provider：

provider = "azure"
model = "gpt-5.4"
reasoning_effort = "high"

验证结果

2026-03-13 23:28：Codex 成功连通 Azure OpenAI
2026-03-13 23:30：确认配置 gpt-5.4 + reasoning_effort = "high"

环境变量治理

问题

2026-03-10 20:31，Codex 反复提示缺少 Azure API Key： - Key 在 ~/.bashrc 中 - 但 exec 环境没有 source

解决方案

将环境变量配置到多个层级：

  1. ~/.bashrc - 交互式 shell
  2. ~/.profile / ~/.zprofile - 登录 shell
  3. systemd 环境 - daemon 进程
  4. 应用配置文件 - OpenClaw/Codex 配置

规则

执行命令必须用 zsh 并加载 ~/.zshrc

zsh -c 'source ~/.zshrc && <command>'

这是整个 AI 自动化系统最关键的运行前提之一。

常见问题

问题 1：直接沿用标准配置

现象：只设置 OPENAI_API_KEY，继续使用 OpenAI() 客户端

解决： - 改用 AzureOpenAI - 增加 azure_endpoint - 增加 api_version

问题 2：model 与 deployment 混淆

现象：传 model="gpt-4o"，但 Azure 返回 404

根因：Azure 下 model 参数需要传 deployment 名称

解决： 

MODEL_NAME = os.environ.get("AZURE_OPENAI_DEPLOYMENT", "gpt-4o-prod")

问题 3：环境变量命名混乱

现象：代码中混用 OPENAI_API_KEY 与 AZURE_OPENAI_API_KEY

解决：增加 provider 分支判断，统一入口

启动校验

建议在应用启动时校验必需配置：

required = [
    "AZURE_OPENAI_API_KEY",
    "AZURE_OPENAI_ENDPOINT",
    "AZURE_OPENAI_API_VERSION",
    "AZURE_OPENAI_DEPLOYMENT",
]
missing = [k for k in required if not os.getenv(k)]
if missing:
    raise RuntimeError(f"Missing Azure OpenAI env: {missing}")

里程碑时间线

时间 事件
2026-03-10 15:43 识别 Azure OpenAI 与标准 OpenAI API 格式差异
2026-03-10 15:43 决定在 Python SDK 中使用 AzureOpenAI
2026-03-10 20:34 完成 Azure API Key 全局环境变量治理
2026-03-13 22:49 确认新版 Codex 不原生适配 Azure OpenAI
2026-03-13 23:28 Codex 成功连通 Azure OpenAI
2026-03-13 23:30 确认模型配置：gpt-5.4 + reasoning_effort = "high"
2026-03-20 23:00 确认当前接入为 Azure OpenAI Sweden

推荐配置模板

.env 文件

LLM_PROVIDER=azure

AZURE_OPENAI_API_KEY=your_key_here
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
AZURE_OPENAI_API_VERSION=2024-02-01
AZURE_OPENAI_DEPLOYMENT=gpt-5-4

Python 统一封装

import os
from openai import AzureOpenAI

client = AzureOpenAI(
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    api_version=os.environ["AZURE_OPENAI_API_VERSION"],
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
)

response = client.chat.completions.create(
    model=os.environ["AZURE_OPENAI_DEPLOYMENT"],
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello"}
    ],
)

总结

Azure OpenAI SDK 适配的核心要点：

  1. 客户端替换：OpenAI → AzureOpenAI
  2. 环境变量：补齐 endpoint、api_version、deployment
  3. 全局配置：确保所有运行环境都能读取配置
  4. 工具链适配：Codex 等工具需要显式配置 Azure provider