Azure OpenAI 配置

相关源文件

• src/openai/_utils/_logs.py
• src/openai/lib/azure.py
• src/openai/resources/beta/realtime/realtime.py
• tests/lib/test_azure.py
• tests/test_utils/test_logging.py

本文档涵盖了 OpenAI Python 库中 Azure OpenAI 客户端的配置和设置。它详细介绍了 Azure 特有的认证方法、端点配置、部署管理以及实时 WebSocket 连接等专业功能。

有关通用客户端配置和 HTTP 基础，请参阅HTTP 客户端基础。有关实时 API 使用模式，请参阅流式传输和实时 API。

客户端架构

Azure OpenAI 实现通过一个专门的继承层次结构，扩展了基础 OpenAI 客户端，增加了 Azure 特有的功能。

BaseAzureClient 类提供 Azure 特定的 URL 准备和请求构建，而具体的 AzureOpenAI 和 AsyncAzureOpenAI 类则负责认证和服务特定配置。

来源： src/openai/lib/azure.py52-88 src/openai/lib/azure.py89-359 src/openai/lib/azure.py360-634

认证配置

Azure OpenAI 支持三种互斥的认证方法，通过同步和异步客户端中的认证管道实现。

API 密钥身份验证

最简单的认证方法是使用 Azure OpenAI API 密钥

参数	环境变量	标题
api_key	AZURE_OPENAI_API_KEY	api-key

来源： src/openai/lib/azure.py188-189 src/openai/lib/azure.py325-327

Azure Active Directory 认证

对于企业场景，Azure AD 令牌提供集成认证

参数	环境变量	标题
azure_ad_token	AZURE_OPENAI_AD_TOKEN	Authorization: Bearer

来源： src/openai/lib/azure.py191-192 src/openai/lib/azure.py321-324

令牌提供程序认证

通过提供程序函数支持动态令牌刷新

• 同步： AzureADTokenProvider = Callable[[], str]
• 异步： AsyncAzureADTokenProvider = Callable[[], str | Awaitable[str]]

每次请求都会调用提供程序函数以获取新的令牌。

来源： src/openai/lib/azure.py33-34 src/openai/lib/azure.py299-312 src/openai/lib/azure.py573-588

端点配置

Azure OpenAI 端点遵循 Azure 特定的 URL 模式，与标准 OpenAI 端点不同。客户端支持两种主要的配置方法。

Azure 端点模式

推荐的配置使用 azure_endpoint，并带有可选的 azure_deployment

配置	结果基础 URL
仅 azure_endpoint	https://resource.azure.openai.com/openai/
azure_endpoint + azure_deployment	https://resource.azure.openai.com/openai/deployments/{deployment}/

来源： src/openai/lib/azure.py220-224 src/openai/lib/azure.py495-498

环境变量

可变	目的
AZURE_OPENAI_ENDPOINT	Azure 资源端点
OPENAI_API_VERSION	API 版本（必填）

来源： src/openai/lib/azure.py214-215 src/openai/lib/azure.py199-205

部署管理

Azure OpenAI 使用部署来管理模型实例。客户端根据端点类型自动处理部署路由。

部署端点处理

客户端自动为 _deployments_endpoints 中定义的特定端点添加部署前缀

来源： src/openai/lib/azure.py19-30 src/openai/lib/azure.py63-68

非部署端点

某些端点绕过部署路由，直接使用基础 Azure 端点

• /models - 模型列表
• /assistants - 助手管理
• /files - 文件操作

来源： src/openai/lib/azure.py76-86

实时配置

Azure OpenAI 的实时 API 需要专门的 WebSocket 配置，包括 Azure 特定的认证和 URL 模式。

WebSocket URL 构建

实时 WebSocket URL 遵循 Azure 特定的模式

基础配置	WebSocket URL 模式
azure_endpoint	wss://resource.azure.openai.com/openai/realtime
websocket_base_url	wss://custom-base/realtime

来源： src/openai/lib/azure.py334-357 src/openai/lib/azure.py610-633

实时认证

实时连接使用与 HTTP 请求相同的认证方法，并通过 WebSocket 握手传递头部信息。

来源： src/openai/lib/azure.py341-346 src/openai/lib/azure.py617-622

环境变量参考

Azure OpenAI 客户端支持通过环境变量进行自动配置

可变	必填	目的	默认
AZURE_OPENAI_API_KEY	*	API 认证密钥	无
AZURE_OPENAI_AD_TOKEN	*	Azure AD 认证令牌	无
AZURE_OPENAI_ENDPOINT	是	Azure 资源端点	无
OPENAI_API_VERSION	是	API 版本字符串	无
OPENAI_ORG_ID	否	组织 ID	无
OPENAI_PROJECT_ID	否	项目 ID	无

*需要一种认证方法

客户端会验证所需的配置是否存在，并对缺失的值抛出相应的错误。

来源： src/openai/lib/azure.py168-177 src/openai/lib/azure.py194-205 src/openai/lib/azure.py442-451