你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
使用 langchain-azure-ai 包作为构建具有 Microsoft Foundry 功能的 LangChain 和 LangGraph 应用程序的入口点。 本文为你提供软件包的高级流程图,帮助你快速入门,然后转到每个功能的合适详细文档。
先决条件
一个 Azure 订阅。 免费创建一个。
Foundry 项目的 Foundry 用户 角色(最低特权角色
Important
Foundry RBAC 角色最近已更名。 Foundry 用户、Foundry 所有者、Foundry 帐户所有者和 Foundry 项目经理之前的名称为“Azure AI 用户”、“Azure AI 所有者”、“Azure AI 帐户所有者”和“Azure AI 项目经理”。 在重命名推出时,你仍可能会在某些位置看到以前的名称。重命名后,角色 ID 和核心权限保持不变。
开发)。 如果还创建或管理资源,请根据需要使用 参与者 或 所有者 。 有关详细信息,请参阅Microsoft Foundry 的角色访问控制。
Python 3.11 或更高版本。
Azure CLI登录(
az login),以便DefaultAzureCredential进行身份验证。
提示
本文提到对 Microsoft Foundry (new)的支持,使用版本 azure-ai-projects>=2.0。
如果使用 Foundry 经典版,请改用 langchain-azure-ai[v1] 。
安装这个软件包
安装基本包:
pip install -U langchain-azure-ai azure-identity
根据方案安装可选附加项:
pip install -U "langchain-azure-ai[tools]"
pip install -U "langchain-azure-ai[opentelemetry]"
pip install -U "langchain-azure-ai[hosting]"
- 如果你的应用使用命名空间
[tools]中的工具,例如文档智能,请使用langchain_azure_ai.tools.*。 - 如果要通过 OpenTelemetry 跟踪集成,请使用
[opentelemetry]。 - 使用
[hosting]在 Foundry 代理服务上托管 LangGraph 代理。
选择集成模块
使用此地图为您的解决方案选择正确的命名空间:
| 能力 | 命名空间 | 典型使用 |
|---|---|---|
| Foundry 智能体服务 | langchain_azure_ai.agents |
生成托管代理节点,为 LangGraph 和 LangChain 生成复杂的图形和流。 请参阅详细示例。 |
| LangGraph 托管 | langchain_azure_ai.agents.hosting |
通过 Responses 或 Invocations 协议,在 Foundry Agent Service 上托管已编译的 LangGraph 代理。 请参阅详细示例。 |
| Foundry 内容安全 | langchain_azure_ai.agents.middleware |
使用 Foundry 内容安全和审查功能,以确保可以按照正确的指导原则部署解决方案。 请参阅详细示例。 |
| 聊天模型 | langchain_azure_ai.chat_models |
调用 Azure OpenAI 和模型目录中的聊天模型。 请参阅详细示例。 |
| 嵌入 | langchain_azure_ai.embeddings |
从目录中调用嵌入模型,并生成用于搜索、检索和排名工作流的矢量。 请参阅详细示例。 |
| 矢量存储 | langchain_azure_ai.vectorstores |
使用 Foundry IQ(Azure AI 搜索)和 Cosmos DB 矢量集成。 |
| 检索器 | langchain_azure_ai.retrievers |
对Azure支持的索引和存储运行检索。 |
| 聊天历史记录存储 | langchain_azure_ai.chat_history |
跨会话保留和重播聊天历史记录。 使用内存驱动历史记录检索合并的过往聊天历史。 请参阅详细示例。 |
| 工具 | langchain_azure_ai.tools |
添加文档智能、计算机视觉、健康文本分析和 Logic Apps 等工具;或整个项目工具箱。 请参阅详细示例 |
| 铸造工具箱 | langchain_azure_ai.tools |
通过单个 MCP 端点从 Foundry 工具箱加载托管工具和技能。 请参阅详细示例。 |
| 回调和跟踪 | langchain_azure_ai.callbacks |
捕获运行事件并发出 OpenTelemetry 跟踪。 请参阅详细示例。 |
| 查询构造函数 | langchain_azure_ai.query_constructors |
生成后端专用的查询筛选器,以用于数据检索的场景。 |
| 文档加载程序 | langchain_azure_ai.document_loaders |
使用 内容理解示例加载文档和媒体。 |
请参阅“详细了解每项功能”部分以获取特定演练。
使用项目终结点和凭据进行连接
许多 langchain-azure-ai 类支持通过 Foundry 项目终结点进行连接。 设置 AZURE_AI_PROJECT_ENDPOINT 一次,然后在受支持的类中重复使用它。
export AZURE_AI_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"
使用 project_endpoint 时,身份验证在项目中使用 Microsoft Entra ID 和 Azure RBAC。
API 密钥适用于直接服务终结点,例如 /openai/v1。
export OPENAI_BASE_URL="https://<resource>.services.ai.azure.com/openai/v1"
export OPENAI_API_KEY="<your-key>"
示例:使用 Foundry 模型
配置环境变量后,可以通过以下方法使用模型:
from langchain.chat_models import init_chat_model
model = init_chat_model("azure_ai:gpt-5.2")
还可以专门配置客户端。 例如,让我们看 AzureAIOpenAIApiChatModel 一下代表性模式:
import os
from azure.identity import AzureCliCredential, DefaultAzureCredential
from langchain_azure_ai.chat_models import AzureAIOpenAIApiChatModel
# Option A: Use a Foundry project endpoint (Microsoft Entra ID required).
model_from_project = AzureAIOpenAIApiChatModel(
project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
credential=DefaultAzureCredential(),
model="gpt-5.2",
)
# Option B: Use a service endpoint directly with an API key.
model_from_endpoint = AzureAIOpenAIApiChatModel(
endpoint=os.environ["OPENAI_BASE_URL"],
credential=os.environ["OPENAI_API_KEY"],
model="gpt-5.2",
)
# Option C: Use a different credential strategy.
model_with_cli_credential = AzureAIOpenAIApiChatModel(
endpoint=os.environ["OPENAI_BASE_URL"],
credential=AzureCliCredential(),
model="gpt-5.2",
)
此代码片段的作用: 显示从 Foundry 项目终结点或直接服务终结点初始化的同一模型,并演示如何交换凭据。
可以将相同的模式应用于工具。 例如,在设置AzureAIDocumentIntelligenceTool时,DefaultAzureCredential 可以使用项目终结点和 AZURE_AI_PROJECT_ENDPOINT 而无需额外配置。
from langchain_azure_ai.tools import AzureAIDocumentIntelligenceTool
document_tool = AzureAIDocumentIntelligenceTool()
工作原理DefaultAzureCredential
DefaultAzureCredential 按顺序尝试多个 Microsoft Entra ID 凭据源,并使用第一个有效源。 常见源是环境变量、托管标识、开发人员工具和Azure CLI。
将 DefaultAzureCredential 用作本地开发和已部署工作负荷的默认设置。 如果需要更严格的控制,请将其替换为特定凭据,例如用于仅限本地开发的AzureCliCredential或用于Azure中生产工作负载的ManagedIdentityCredential。
其他类也使用相同的项目终结点模式。
详细了解每个功能
请从这份文档集合中的以下指南开始:
- 将 Foundry 模型与 LangChain 和 LangGraph 配合使用
- 使用 Foundry 内容安全中间件
- 将 Foundry 代理服务与 LangGraph 配合使用
- 将 Foundry 工具箱与 LangChain 配合使用
- 将 LangGraph 代理作为 Foundry 托管代理进行托管
- 将 Foundry 内存与 LangChain 和 LangGraph 配合使用
- 使用 Foundry Observability 跟踪应用
使用这些包资源获取模块级详细信息和更新:
- 包概述 和 自述文件。
-
针对
langchain-azure-ai的 LangChain 文档
查找示例
使用这些存储库查找方案的示例:
- LangChain Azure SDK 示例用于 SDK 集成和托管。
- 用于模型、代理服务、内容安全和内容理解的 SDK 笔记本。
- 用于资源配置和托管代理部署的 Foundry LangGraph 示例。