LlamaIndex Azure OpenAI LLM 集成指南:engine 部署映射、Entra ID 认证与 Responses API 实战
LlamaIndex Azure OpenAI LLM 集成指南:engine 部署映射、Entra ID 认证与 Responses API 实战
本文是 LlamaIndex 中 llama-index-llms-azure-openai 集成模块的完整技术指南。该模块位于 llama-index-integrations/llms/llama-index-llms-azure-openai,其 API 引用入口在 docs/api_reference/api_reference/llms/azure_openai.md,对外暴露 AsyncAzureOpenAI、AzureOpenAI、AzureOpenAIResponses、SyncAzureOpenAI 四个成员。读完本文,你将掌握:如何在 LlamaIndex 中通过 engine 参数对接 Azure OpenAI 模型部署、如何用 API Key 与 Microsoft Entra ID(原 Azure AD)两种方式完成认证、如何调用补全/对话/流式接口,以及如何使用基于 Responses API 的 AzureOpenAIResponses 类,并了解底层实现的关键细节。
模块全景:四个导出成员是什么
从 init.py 可以看到模块的导出清单:
from llama_index.llms.azure_openai.base import (
AzureOpenAI,
SyncAzureOpenAI,
AsyncAzureOpenAI,
)
from llama_index.llms.azure_openai.responses import AzureOpenAIResponses
__all__ = [
"AzureOpenAI",
"AzureOpenAIResponses",
"SyncAzureOpenAI",
"AsyncAzureOpenAI",
]
AzureOpenAI:核心 LLM 类,继承自llama_index.llms.openai.OpenAI(见 base.py)。它封装了 Azure 特有的部署路由、两类认证方式和 Chat Completions 接口。AzureOpenAIResponses:基于 OpenAI Responses API(/responses端点)的 Azure 变体,继承自llama_index.llms.openai.OpenAIResponses(见 responses.py)。SyncAzureOpenAI与AsyncAzureOpenAI:直接再导出 OpenAI SDK 中的 openai.AzureOpenAI 同步/异步客户端类型。它们不是独立的 LlamaIndex LLM 包装类,而是底层 HTTP 客户端,AzureOpenAI内部正是通过_get_client()/_get_aclient()来创建它们的。
从类型体系看,test_llms_azure_openai.py(tests/test_llms_azure_openai.py)通过 MRO 断言 BaseLLM 在 AzureOpenAI.__mro__ 中,确认它是一个标准 LlamaIndex LLM 实现,可与索引、查询引擎、Agent 等任意组件组合。
安装与前置条件
安装集成包:
pip install llama-index-llms-azure-openai
按 pyproject.toml 声明,该包的核心依赖为 llama-index-llms-openai>=0.7.0,<0.9、azure-identity>=1.15.0,<2、httpx 以及 llama-index-core>=0.14.3,<0.15。其中 azure-identity 用于 Entra ID 令牌获取,httpx 用于自定义 HTTP 客户端。
使用前需要在 Azure 门户完成以下准备工作:
- 在 Azure 中创建 OpenAI 资源,获得资源名称(resource name)。
- 在 Azure OpenAI Studio 中完成模型部署,记下部署名称(deployment name)——它对应代码里的
engine参数。 - 在 Azure 门户获取
api_base(形如https://YOUR_RESOURCE_NAME.openai.azure.com/)和api_key。
集成包内还提供了完整的环境变量设置与调用示例,见 README.md;更完整的图文步骤(含在 Azure 门户查找 API base / API key / 部署名称的流程)可参考 docs/examples/llm/azure_openai.ipynb。
engine 与 model:Azure 部署路由的核心概念
与普通 OpenAI 不同,Azure OpenAI 没有统一的模型端点,每个模型对应一个部署(deployment)。因此在 AzureOpenAI 中必须同时给出两个参数(base.py):
model:模型族名称,如gpt-35-turbo、gpt-4o,仅用于区分补全端点(completion)与对话端点(chat)。engine:必填项,对应你在 Azure 门户选择的部署名("model deployment name")。所有发给 Azure 的请求实际都路由到这个部署。
engine 的必填校验发生在构造函数中:if engine is None: raise ValueError("You must specify an engine parameter.")。同时模块提供了宽松的别名机制——resolve_from_aliases(见 utils.py)会按顺序从 engine、deployment_name、deployment_id、deployment、azure_deployment 中取第一个非空值:
engine = resolve_from_aliases(
engine, deployment_name, deployment_id, deployment, azure_deployment
)
这意味着如果你习惯用 deployment_name="my-gpt4" 或 azure_deployment="my-gpt4" 传入,效果与 engine="my-gpt4" 完全一致。
从源码结构看,engine 在请求链路中扮演了 model 的角色:_get_model_kwargs() 在父类基础上强制把 model 字段替换为 self.engine(base.py 与 responses.py 均有此逻辑):
def _get_model_kwargs(self, **kwargs):
model_kwargs = super()._get_model_kwargs(**kwargs)
model_kwargs["model"] = self.engine
return model_kwargs
配置方式一:构造函数直传参数
最简单且直观的方式是在构造 AzureOpenAI 时把全部信息作为参数传入(README.md):
from llama_index.llms.azure_openai import AzureOpenAI
llm = AzureOpenAI(
engine="my-custom-llm", # Azure 中的部署名
model="gpt-35-turbo-16k", # 模型族名称
temperature=0.0,
azure_endpoint="https://<your-resource-name>.openai.azure.com/",
api_key="<your-api-key>",
api_version="2023-07-01-preview",
)
AzureOpenAI 的构造函数签名(关键参数)如下:
| 参数 | 默认值 | 说明 |
|---|---|---|
model |
"gpt-35-turbo" |
模型族名称,决定走补全还是对话端点 |
engine |
None(必填) |
Azure 部署名,可被 deployment_name / deployment_id / deployment / azure_deployment 别名替代 |
temperature |
0.1 |
采样温度 |
max_tokens |
None |
生成最大 token 数 |
max_retries |
3 |
API 调用失败重试次数 |
timeout |
60.0 |
单次调用超时(秒) |
api_key |
None |
Azure OpenAI API Key |
api_version |
None |
如 2023-07-01-preview |
azure_endpoint |
None |
形如 https://YOUR_RESOURCE_NAME.openai.azure.com/ |
azure_deployment |
None |
部署名(可作为 engine 别名) |
azure_ad_token_provider |
None |
Entra ID 令牌回调函数 |
use_azure_ad |
False |
是否使用 Entra ID 令牌认证 |
additional_kwargs |
None |
附加到请求体的额外参数 |
http_client / async_http_client |
None |
自定义 httpx 客户端 |
callback_manager |
None |
LlamaIndex 回调管理器 |
配置方式二:环境变量
也可以不传任何参数,直接依赖环境变量。模块支持以下三个:
AZURE_OPENAI_ENDPOINT:形如https://YOUR_RESOURCE_NAME.openai.azure.com/AZURE_OPENAI_API_KEY:API KeyOPENAI_API_VERSION:API 版本,如2023-07-01-preview
import os
os.environ["OPENAI_API_KEY"] = "<your-api-key>"
os.environ["AZURE_OPENAI_ENDPOINT"] = "https://<your-resource-name>.openai.azure.com/"
os.environ["OPENAI_API_VERSION"] = "2023-07-01-preview"
from llama_index.llms.azure_openai import AzureOpenAI
llm = AzureOpenAI(engine="simon-llm", model="gpt-35-turbo-16k", temperature=0.0)
注意 engine 无论如何都无法通过环境变量省略,它必须显式给出。当 api_base 未传时,构造函数会调用 get_from_param_or_env 从参数或 AZURE_OPENAI_ENDPOINT 环境变量中解析 azure_endpoint。
认证方式一:API Key
默认(use_azure_ad=False)走 API Key 认证。在 _get_credential_kwargs() 中(base.py),若 api_key 为空则回退读取 AZURE_OPENAI_API_KEY 环境变量;两者都取不到时抛出 ValueError:
You must set an `api_key` parameter. Alternatively, you can set the AZURE_OPENAI_API_KEY env var OR set `use_azure_ad=True`.
认证方式二:Microsoft Entra ID(托管身份 / Token Provider)
生产环境中更推荐用托管身份(Managed Identity)配合 Entra ID 认证,避免在代码里硬编码密钥。设置 use_azure_ad=True 并传入 token provider 即可:
from llama_index.llms.azure_openai import AzureOpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
credential = DefaultAzureCredential()
token_provider = get_bearer_token_provider(
credential, "https://cognitiveservices.azure.com/.default"
)
llm = AzureOpenAI(
engine="llm_deployment",
model="YOUR_AZURE_OPENAI_COMPLETION_MODEL_NAME",
azure_ad_token_provider=token_provider,
use_azure_ad=True,
azure_endpoint="https://YOUR_RESOURCE_NAME.openai.azure.com/",
api_version="2023-07-01-preview",
)
两种 Entra ID 令牌获取路径:
- 显式 provider:传入
azure_ad_token_provider回调,每次取凭据时调用self.azure_ad_token_provider()得到令牌作为api_key。 - 隐式获取:不传 provider,仅设置
use_azure_ad=True,则调用refresh_openai_azuread_token(utils.py)——它会检查已有令牌是否在 60 秒内过期,过期则用azure.identity.DefaultAzureCredential拉取新令牌(按 azure-identity 约定的顺序尝试多种认证方式),失败则抛出包含错误详情的ValueError:
def refresh_openai_azuread_token(azure_ad_token=None):
if not azure_ad_token or azure_ad_token.expires_on < time.time() + 60:
try:
credential = DefaultAzureCredential()
azure_ad_token = credential.get_token(
"https://cognitiveservices.azure.com/.default"
)
except ClientAuthenticationError as err:
raise ValueError(...) from err
return azure_ad_token
测试 test_azure_openai.py 中 test_custom_azure_ad_token_provider 验证了:传入自定义 provider 后,complete() 调用期间 llm.api_key 会被动态设置为 provider 的返回值("mock_api_key"),证实令牌是"每次取用、动态刷新"的。
配置校验:validate_env
AzureOpenAI 还定义了一个 @model_validator(mode="before") 钩子 validate_env(base.py),在对象构造阶段做两件事:
- 若
api_base仍是默认的https://api.openai.com/v1且未提供azure_endpoint,报错提示必须把OPENAI_API_BASE指向形如https://YOUR_RESOURCE_NAME.openai.azure.com/的 Azure 端点; - 若
api_version为空,报错提示必须设置OPENAI_API_VERSION。
这从入口处避免了"拿着 OpenAI 的默认端点去调 Azure"这类典型配置错误。构造完成后,若 api_base 仍是 OpenAI 默认值或已指定 azure_endpoint,则把 api_base 重置为 None,确保最终请求走 azure_endpoint。
发起调用:补全、对话与流式输出
AzureOpenAI 完整继承了 OpenAI LLM 的调用接口(README.md):
文本补全(completion endpoint)
response = llm.complete("The sky is a beautiful blue and")
print(response)
流式补全
response = llm.stream_complete("The sky is a beautiful blue and")
for r in response:
print(r.delta, end="")
对话(chat endpoint)
from llama_index.core.llms import ChatMessage
messages = [
ChatMessage(role="system", content="You are a pirate with a colorful personality."),
ChatMessage(role="user", content="Hello"),
]
response = llm.chat(messages)
print(response)
流式对话
response = llm.stream_chat(messages)
for r in response:
print(r.delta, end="")
如果不想在每次调用里重复传公共参数,可以用 additional_kwargs 在实例级别统一设置,例如跟踪用户 ID:
llm = AzureOpenAI(
engine="simon-llm",
model="gpt-35-turbo-16k",
temperature=0.0,
additional_kwargs={"user": "your_user_id"},
)
由于继承了 OpenAI 的实现,同步方法 complete / chat / stream_complete / stream_chat 之外,同样可用的异步版本包括 acomplete / achat / astream_complete / astream_chat,并支持函数调用(tool calling)等 FunctionCallingLLM 能力(OpenAI 本身继承自 llama_index.core.llms.function_calling.FunctionCallingLLM)。
自定义 HTTP 客户端与连接复用
AzureOpenAI 支持传入自定义 httpx 客户端(适合代理、超时定制、TLS 配置等场景)。_get_client() / _get_aclient()(base.py)的逻辑是:若 reuse_client=True(默认),则缓存 _client / _aclient 复用;否则每次调用都新建客户端。构建 SDK 客户端时传入的凭据集合 _get_credential_kwargs() 包括:
{
"api_key": self.api_key,
"max_retries": self.max_retries,
"timeout": self.timeout,
"azure_endpoint": self.azure_endpoint,
"azure_deployment": self.azure_deployment,
"base_url": self.api_base, # 代理场景可用
"azure_ad_token_provider": self.azure_ad_token_provider,
"api_version": self.api_version,
"default_headers": self.default_headers,
"http_client": self._async_http_client if is_async else self._http_client,
}
api_base 字段官方定位是"Azure OpenAI 之上的代理"——如果你在 Azure 前面架了网关/代理,可以在这里指定其 Base URL。
测试 test_custom_http_client 验证了自定义 httpx.Client 会原样透传给 SDK 客户端构造。
AzureOpenAIResponses:基于 Responses API 的调用
AzureOpenAIResponses(responses.py)对接的是 Azure 上托管的 Responses API(OpenAI 新一代 /responses 端点),适用于 gpt-4o 等模型,api_version 需为 2025-03-01-preview 或更新版本。
from llama_index.llms.azure_openai import AzureOpenAIResponses
llm = AzureOpenAIResponses(
engine="AZURE_OPENAI_DEPLOYMENT_NAME",
model="YOUR_AZURE_OPENAI_MODEL_NAME",
api_key="YOUR_AZURE_OPENAI_API_KEY",
azure_endpoint="YOUR_AZURE_OPENAI_ENDPOINT",
api_version="2025-03-01-preview",
)
与 AzureOpenAI 的关键区别:
- 参数集面向 Responses API:
max_output_tokens(非max_tokens)、reasoning_options(配置 O1 类模型推理,如{"effort": "low", "summary": "concise"})、include(附加输出数据)、instructions、store、track_previous_responses、built_in_tools、truncation(默认"disabled")、previous_response_id、strict(结构化输出严格校验)等(参数语义继承自 llama-index-llms-openai 的 OpenAIResponses)。 - 客户端创建时机不同:为避开父类用 Azure 专属参数构造普通 OpenAI 客户端的冲突,
AzureOpenAIResponses在super().__init__()之前先构建SyncAzureOpenAI/AsyncAzureOpenAI客户端,再通过openai_client=/async_openai_client=注入父类。测试test_azure_openai_responses_constructor专门验证了这一行为:构造时 Azure 客户端各被调用一次,且azure_endpoint、api_key正确透传。 - 结构化输出路由:
structured_predict/astructured_predict会把model参数强制替换为self.engine(由_responses_model属性返回self.engine)。测试test_structured_predict_uses_engine_not_model断言responses.parse收到的model == "my-deployment",并注释了原因:父类默认传self.model(模型族名,如gpt-4o),Azure 按部署名路由,传模型族名会触发 404DeploymentNotFound。
流式响应中的内容过滤空块处理
Azure OpenAI 与 OpenAI 一个显著的差异是:流式响应中第一个 chunk 可能不含文本内容,只有 prompt_filter_results(内容安全过滤结果),其 choices 为空列表(详见微软内容过滤文档中对流式响应的说明)。若直接透传这类 chunk,会干扰流式解析。
模块对此做了专门处理。测试 test_azure_openai.py 中的 mock_chat_completion_stream_with_filter_results 构造了"先一个空 choices 的过滤块、再正常文本块"的模拟流,并分别在同步(test_chat_completion_with_filter_results)与异步(test_async_chat_completion_with_filter_results)两条链路上断言:stream_complete / stream_chat 与 astream_complete / astream_chat 都能正确跳过空块,最终输出拼接为 "Hello from\nAzure"。
这意味着:在 LlamaIndex 中使用 Azure OpenAI 做流式生成时,内容安全过滤导致的空块不会破坏输出,也不需要你在业务层额外过滤。
与 LlamaIndex 生态的集成用法
由于 AzureOpenAI 是标准的 BaseLLM 子类,它可以无缝替换任何 LlamaIndex 组件的默认 LLM,例如:
from llama_index.core import VectorStoreIndex, Settings
from llama_index.llms.azure_openai import AzureOpenAI
Settings.llm = AzureOpenAI(
engine="my-gpt4-deployment",
model="gpt-4o",
api_key="<your-api-key>",
azure_endpoint="https://<your-resource-name>.openai.azure.com/",
api_version="2025-03-01-preview",
)
# 之后的 index.as_query_engine().query(...) 等调用都会走 Azure OpenAI
index = VectorStoreIndex.from_documents(documents)
response = index.as_query_engine().query("你的问题")
常见错误与排查要点
| 报错信息 | 原因 | 解决办法 |
|---|---|---|
You must specify an engine parameter. |
未提供部署名 | 传入 engine(或其别名) |
You must set OPENAI_API_VERSION for Azure OpenAI. |
api_version 为空 |
设置 api_version 或 OPENAI_API_VERSION 环境变量(如 2023-07-01-preview) |
You must set OPENAI_API_BASE to your Azure endpoint... |
api_base 仍是 OpenAI 默认端点 |
改为 https://YOUR_RESOURCE_NAME.openai.azure.com/ |
You must set an api_key parameter... |
Key 与 Entra ID 均未配置 | 传 api_key、设置 AZURE_OPENAI_API_KEY,或 use_azure_ad=True |
404 DeploymentNotFound |
请求路由到了不存在的部署 | 确认 engine 与 Azure 门户中的部署名完全一致(Responses 场景尤为常见,见上文 structured_predict 说明) |
小结
llama-index-llms-azure-openai 通过 AzureOpenAI 与 AzureOpenAIResponses 两个 LLM 类,把 Azure OpenAI 的"部署即端点"模型接入 LlamaIndex 标准 LLM 体系,同时提供 API Key 与 Entra ID 两套认证、同步/异步/流式全接口、自定义 HTTP 客户端与内容过滤空块兼容等能力。关键实践要点可归纳为三条:部署名(engine)是唯一路由标识,必须显式配置;生产环境优先使用 Entra ID 托管身份认证;Responses API 场景选择 AzureOpenAIResponses 并匹配较新的 api_version。深入阅读源码可分别查看 base.py、responses.py 与 utils.py,运行验证可参考 tests/test_azure_openai.py 中的完整测试。