從 Foundry 開始使用 LangChain 和 LangGraph

使用 langchain-azure-ai 套件作為建立具備 Microsoft Foundry 功能的 LangChain 與 LangGraph 應用程式的入口。 本文提供該套件的高階概覽，能讓您快速上手，接著再依各項功能深入查閱相應的詳細文件。

先決條件

• 一個 Azure 訂閱。 免費創建一個。

• Foundry 專案。

• Foundry 專案中的 Foundry 使用者角色 (最低權限角色

  Important

  Foundry RBAC 角色最近已重新命名。 Foundry 用戶、Foundry 擁有者、Foundry Account Owner 以及 Foundry Project Manager 先前分別被稱為 Azure AI 使用者、Azure AI 擁有者、Azure AI 帳戶擁有者及 Azure AI Project 管理者。 在更名期間，你可能還會在某些地方看到之前的名字。角色 ID 與核心權限不會因命名而改變。

  發展）。 如果你也建立或管理資源，請視需要使用貢獻者或擁有者。 詳情請參閱Microsoft Foundry的角色為基礎的存取控制。

• Python 3.10 或更新版本。

• Azure CLI已登入（az login），所以 DefaultAzureCredential 可以進行認證。

安裝套件

安裝基本套件：

pip install -U langchain-azure-ai azure-identity

根據你的情況安裝可選的額外功能：

pip install -U "langchain-azure-ai[tools]"
pip install -U "langchain-azure-ai[opentelemetry]"

• 如果你的應用程式使用命名空間[tools]的工具，例如文件智慧，請使用langchain_azure_ai.tools.*。
• 如果你想透過 OpenTelemetry 進行追蹤整合，可以使用 [opentelemetry] 。

選擇整合建構單元

請使用這張地圖為您的解決方案選擇合適的命名空間：

具體攻略請參考「 詳細學習每項能力 」章節。

連線至專案端點並使用對應的憑證

許多 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用於本地開發，或ManagedIdentityCredential用於 Azure 的生產工作負載。

其他類別也採用相同的專案-端點模式。

詳細學習每項能力

從這套文件中的這些指南開始：

• 使用 Foundry 模型與 LangChain 及 LangGraph 進行搭配
• 使用 Foundry Content Safety 中介軟體
• 搭配使用 Foundry Agent Service 和 LangGraph
• 使用 Foundry 工具箱搭配 LangChain
• 將 LangGraph 代理部署為 Foundry 託管代理
• 使用 Foundry 記憶體搭配 LangChain 和 LangGraph
• 使用 Foundry Observability 來追蹤應用程式

請使用這些套件資源以獲取模組層級的詳細資訊與更新：

• 套件概述與 README。
• 適用於langchain-azure-ai LangChain 的文件。

下一步