LlamaIndex Azure OpenAI LLM 集成指南:engine 部署映射、Entra ID 认证与 Responses API 实战

原创2026-10-10 02:14:321,943 阅读
文章标签:人工智能大模型RAGAI AgentAgent 框架Agent 工作流Prompt 模板向量数据库Embedding

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 门户完成以下准备工作:

  1. 在 Azure 中创建 OpenAI 资源,获得资源名称(resource name)。
  2. 在 Azure OpenAI Studio 中完成模型部署,记下部署名称(deployment name)——它对应代码里的 engine 参数。
  3. 在 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 Key
  • OPENAI_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 令牌获取路径:

  1. 显式 provider:传入 azure_ad_token_provider 回调,每次取凭据时调用 self.azure_ad_token_provider() 得到令牌作为 api_key。
  2. 隐式获取:不传 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 按部署名路由,传模型族名会触发 404 DeploymentNotFound。

流式响应中的内容过滤空块处理

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 中的完整测试。

登录后查看全文
llama_index