使用此 langchain-azure-ai 套件作為建置具備 Microsoft Foundry 功能的 LangChain 與 LangGraph 應用程式的入口。 本文提供套件的概覽，幫助你快速上手，然後進一步查閱每個功能的詳細文件。
先決條件
- 一個 Azure 訂閱。 免費創建一個。
- Foundry 專案。
- Foundry 專案中的 Azure AI 使用者角色（開發權限最低）。 如果你也建立或管理資源，請視需要使用貢獻者或擁有者。 詳情請參閱 Microsoft Foundry 的角色基礎存取控制。
- Python 3.10 或更新版本。
- Azure CLI已登入（
az login），所以DefaultAzureCredential可以進行認證。
小提示
本文提及支援使用版本 的 azure-ai-projects>=2.0。
如果你用的是 Foundry Classic，建議改用 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]"
- 如果你的應用程式使用命名空間
[tools]的工具，例如文件智慧，請使用langchain_azure_ai.tools.*。 - 如果你想透過 OpenTelemetry 進行追蹤整合，可以使用
[opentelemetry]。
選擇整合建構單元
請使用這張地圖為您的解決方案選擇合適的命名空間：
| 能力 | 命名空間 | 典型用途 |
|---|---|---|
| 鑄造代理服務 | langchain_azure_ai.agents |
建立受管理代理節點，為 LangGraph 和 LangChain 建立複雜的圖與流程。 詳見詳細範例。 |
| 鑄造廠內容安全 | langchain_azure_ai.agents.middleware |
使用 Foundry 內容安全與管理，確保你能部署具備適當防護措施的解決方案。 詳見詳細範例。 |
| 對話模型 | langchain_azure_ai.chat_models |
呼叫 Azure OpenAI 並建模目錄聊天模型。 詳見詳細範例。 |
| Embeddings | langchain_azure_ai.embeddings |
從目錄中呼叫嵌入模型，產生用於搜尋、檢索及排名工作流程的向量。 詳見詳細範例。 |
| 向量存放區 | langchain_azure_ai.vectorstores |
使用 Azure AI Search 和 Cosmos DB 向量整合。 |
| 尋回犬 | langchain_azure_ai.retrievers |
對 Azure 支援的索引和存放區執行檢索。 |
| 聊天記錄儲存庫 | langchain_azure_ai.chat_message_histories |
持續保存並重播跨會話的聊天歷史。 使用記憶體驅動的歷程紀錄來見所合併的傳遞聊天紀錄。 詳見詳細範例。 |
| 工具 | langchain_azure_ai.tools |
新增文件智慧、視覺、健康文本分析及邏輯應用程式等工具。 |
| 回調與追蹤 | langchain_azure_ai.callbacks |
擷取執行事件並傳送 OpenTelemetry 追蹤。 詳見詳細範例。 |
| 查詢建構子 | langchain_azure_ai.query_constructors |
建立後端專用的查詢過濾器以支援擷取情境。 |
具體攻略請參考「 詳細學習每項能力 」章節。
連結專案端點與憑證
許多 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 模型
一旦環境變數設定完成，你就可以透過以下方式使用模型：
import langchain.chat_models import init_chat_model
model = init_chat_model("azure_ai:gpt-5.2")
你也可以專門設定客戶端。 舉例來說，讓我們看看 AzureAIOpenAIApiChatModel 一個代表性的模式：
import os
from azure.identity import 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.
model_from_endpoint = AzureAIOpenAIApiChatModel(
endpoint=os.environ["OPENAI_BASE_URL"],
credential=DefaultAzureCredential(),
model="gpt-5.2",
)
# Option C: Use a different credential strategy.
model_with_cli_credential = AzureAIOpenAIApiChatModel(
endpoint=os.environ["OPENAI_BASE_URL"],
credential="super-secret",
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 Memory 與 LangChain 和 LangGraph 搭配使用
- 使用 Foundry Observability 來追蹤應用程式
請使用這些套件資源以獲取模組層級的詳細資訊與更新：
- 套件概述與 README。
-
適用於
langchain-azure-aiLangChain 的文件。