在 Microsoft Foundry（經典版）中開發模型與 LangChain 的應用程式

註

本文提及 Microsoft Foundry（經典）入口網站。如果你正在使用新的入口網站，請改用這篇文章的新版本。

LangChain 是一個開發者生態系統，讓建立推理應用變得更容易。它包含多個組件，且大多數可以獨立使用，因此你可以挑選所需的零件。

你可以用兩種方式使用部署到 Microsoft Foundry 的模型與 LangChain 搭配：

這個教學展示了如何利用 Azure AI 模型推論 API 搭配 LangChain 使用 langchain-azure-ai[v1] 套件。部分模型，如 OpenAI、Cohere 或 Mistral，提供自己的 API 與 LangChain 擴充功能。這些擴充可能包含特定模型的功能，適合需要它們時使用。安裝你選擇型號的擴充功能，例如 langchain-openai 或 langchain-cohere。

注意事項

模型 langchain-azure-ai[v1] 推論已被棄用，將於 2026 年 5 月 30 日除役。切換至正式發行的 OpenAI/v1 API，以及在 langchain-azure-ai 或 langchain-openai 中引進的穩定版 OpenAI SDK。了解更多。

先決條件

要執行這個教學，你需要：

一個有有效訂閱的 Azure 帳號。如果你還沒有，請建立一個free Azure帳號，其中包含免費試用訂閱。

必備角色：
- 在 Foundry 資源或 AI Hub 上作為模型部署的擁有者或貢獻者
- Foundry 使用者可在 Foundry 專案中使用該模型
  
  Important
  
  Foundry RBAC 角色最近已重新命名。 Foundry 用戶、Foundry 擁有者、Foundry Account Owner 以及 Foundry Project Manager 先前分別被稱為 Azure AI 使用者、Azure AI 擁有者、Azure AI 帳戶擁有者及 Azure AI Project 管理者。在更名期間，你可能還會在某些地方看到之前的名字。角色 ID 與核心權限不會因命名而改變。
- Azure AI Developer 用來在集線器基礎的專案中使用模型

支援模型推理 API 的模型部署。本文使用 Mistral-Large-3。
安裝了 Python 3.9 或更新版本，包含 pip。
LangChain 已安裝。你可以使用以下指令安裝：
```
pip install langchain
```
安裝 Foundry 整合套件：
```
pip install -U langchain-azure-ai[v1]
```

設定環境

若要使用部署於 Microsoft Foundry 入口網站的 LLM，您需要端點與認證才能加以連線。請依照以下步驟取得您想使用的模型所需的資訊：

登入 Microsoft Foundry。確定 新鑄造廠 的開關是開啟的。以下步驟適用於 Foundry（新）。
如果模型尚未開啟，請打開該模型部署的專案。
複製端點的網址和金鑰。

在此情境中，將端點的 URL 和鍵設為環境變數。 (如果您複製的端點包含在/models後的額外文字，請加以移除，這樣/models的 URL 結尾才能如以下所示。)

export AZURE_INFERENCE_ENDPOINT="https://<resource>.services.ai.azure.com/models"
export AZURE_INFERENCE_CREDENTIAL="<your-key-goes-here>"

建立一個客戶端，透過類別 AzureAIChatCompletionsModel 連接聊天模式。

import os
from langchain_azure_ai.chat_models import AzureAIChatCompletionsModel

model = AzureAIChatCompletionsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
    model="Mistral-Large-3",
)

此程式碼片段的功能：具現化 AzureAIChatCompletionsModel 用戶端，該用戶端已設定為使用 API 金鑰進行驗證，並連線至您部署的模型。此用戶端作為模型推論 API 的介面。

參考資料：

如果您的端點支援 Microsoft Entra ID，請使用以下程式碼建立用戶端：

import os
from azure.identity import DefaultAzureCredential
from langchain_azure_ai.chat_models.inference import AzureAIChatCompletionsModel

model = AzureAIChatCompletionsModel(
    endpoint=os.environ["AZURE_AI_INFERENCE_ENDPOINT"],
    credential=DefaultAzureCredential(),
    model="Mistral-Large-3",
)

註

使用 Microsoft Entra ID 時，請確保端點已部署該認證方法，且你擁有呼叫該方法所需的權限。

如果你打算使用非同步通話，請使用非同步版本的憑證：

from azure.identity.aio import (
    DefaultAzureCredential as DefaultAzureCredentialAsync,
)
from langchain_azure_ai.chat_models.inference import AzureAIChatCompletionsModel

model = AzureAIChatCompletionsModel(
    endpoint=os.environ["AZURE_AI_INFERENCE_ENDPOINT"],
    credential=DefaultAzureCredentialAsync(),
    model="Mistral-Large-3",
)

如果你的端點服務單一模型（例如無伺服器 API 部署），就不要包含 model 以下參數：

import os
from langchain_azure_ai.chat_models.inference import AzureAIChatCompletionsModel

model = AzureAIChatCompletionsModel(
    endpoint=os.environ["AZURE_AI_INFERENCE_ENDPOINT"],
    credential=os.environ["AZURE_AI_CREDENTIAL"],
)

確認你的設定

用簡單的召喚來測試你的客戶連結：

response = model.invoke("Say hello")
print(response.content)

這樣做的功能： 用簡單的提示呼叫模型以驗證認證與連線。預期輸出：模型的問候訊息（例如：「你好！今天有什麼我可以幫忙的？」）。

參考資料：

LangChain 可執行介面

使用對話補全模型

直接使用模型。 ChatModels 是 LangChain Runnable 介面的實例，提供與它們互動的標準方式。要呼叫模型，將訊息清單傳給 invoke 方法。

from langchain_core.messages import HumanMessage, SystemMessage

messages = [
    SystemMessage(content="Translate the following from English into Italian"),
    HumanMessage(content="hi!"),
]

model.invoke(messages)

這段內容：示範如何將與 HumanMessage 物件的清單SystemMessage傳遞給模型的方法invoke()以產生回應。

參考資料：

根據需求將運算串接成鏈。使用提示詞範本翻譯句子：

from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import ChatPromptTemplate

system_template = "Translate the following into {language}:"
prompt_template = ChatPromptTemplate.from_messages(
    [("system", system_template), ("user", "{text}")]
)

這條鏈會接收 language 和 text 輸入。接著，建立一個輸出解析器：

from langchain_core.output_parsers import StrOutputParser

parser = StrOutputParser()

這段程式碼的功能：建立一個StrOutputParser，將模型的輸出轉換為字串格式，並去除多餘的元數據。

參考資料：

LangChain 輸出解析器

使用管線（|）運算子結合範本、模型與輸出解析器：

chain = prompt_template | model | parser

請使用 language 方法提供text 和 invoke 值，並由此召喚鏈條：

chain.invoke({"language": "italian", "text": "hi"})

將多個 LLM 鏈結在一起

因為 Foundry 中的模型會公開通用模型推斷 API，您可以鏈結多個 LLM 作業並選擇最適合每個步驟的模型。

在以下範例中，你建立兩個模型客戶端：一個生產者與一個驗證者。為了區分清楚，使用多模型端點（如 Model Inference API ），並將參數傳給 model 大型模型產生，小型模型進行驗證。內容製作通常需要較大的模型，而驗證則可以使用較小的模型。

from langchain_azure_ai.chat_models import AzureAIChatCompletionsModel

producer = AzureAIChatCompletionsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
    model="Mistral-Large-3",
)

verifier = AzureAIChatCompletionsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
    model="mistral-small",
)

這段內容 ：實例化兩個獨立 AzureAIChatCompletionsModel 客戶端：一個 Mistral-Large-3 用於內容生成，另一個 Mistral-Small 用於驗證，示範如何為不同任務選擇不同模型。

參考資料：

LangChain Azure AI 整合

提示

檢視每個模型的模型卡，了解最佳使用情境。

以下範例生成了一首由都市詩人所寫的詩：

from langchain_core.prompts import PromptTemplate

producer_template = PromptTemplate(
    template="You are an urban poet, your job is to come up \
             verses based on a given topic.\n\
             Here is the topic you have been asked to generate a verse on:\n\
             {topic}",
    input_variables=["topic"],
)

verifier_template = PromptTemplate(
    template="You are a verifier of poems, you are tasked\
              to inspect the verses of poem. If they consist of violence and abusive language\
              report it. Your response should be only one word either True or False.\n \
              Here is the lyrics submitted to you:\n\
              {input}",
    input_variables=["input"],
)

此程式碼片段的作用：建立一個提示範本，並將其與producer模型用戶端結合，以產生有創意的內容 (此案例中為一首詩)。

串聯元件：

chain = producer_template | producer | parser | verifier_template | verifier | parser

這段內容 ：將生成的詩歌串接於 verifier 模型中，以驗證或審查生成內容，展現製作者與驗證者的工作流程。

前一個鏈只回傳該 verifier 步的輸出。要存取由 producer所產生的中間結果，使用 a RunnablePassthrough 來輸出該中間步驟。

from langchain_core.runnables import RunnablePassthrough, RunnableParallel

generate_poem = producer_template | producer | parser
verify_poem = verifier_template | verifier | parser

chain = generate_poem | RunnableParallel(poem=RunnablePassthrough(), verification=RunnablePassthrough() | verify_poem)

呼叫鏈時，請使用 invoke 以下方法：

chain.invoke({"topic": "living in a foreign country"})

這段程式碼的功能：呼叫完整的生產者-驗證者鏈，並提供主題輸入，回傳生成的內容和驗證結果。預期輸出：包含 poem 和 verification 的 JSON 物件，包含產生的詩歌與驗證回應鍵。

參考資料：

LangChain 可執行裝置

使用嵌入模型

用類似方式建立一個嵌入客戶端。將環境變數設定為指向嵌入模型：

export AZURE_INFERENCE_ENDPOINT="<your-model-endpoint-goes-here>"
export AZURE_INFERENCE_CREDENTIAL="<your-key-goes-here>"

建立客戶端：

import os
from langchain_azure_ai.embeddings import AzureAIEmbeddingsModel

embed_model = AzureAIEmbeddingsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
    model="text-embedding-3-large",
)

這段內容 ：實例化一個嵌入客戶端，將 AzureAIEmbeddingsModel 文字轉換為向量嵌入，可用於語意搜尋與相似度比較。

參考資料：

LangChain 嵌入

使用記憶體中向量儲存庫：

from langchain_core.vectorstores import InMemoryVectorStore

vector_store = InMemoryVectorStore(embed_model)

此程式碼片段的功能：建立記憶體內向量儲存區 (InMemoryVectorStore)，用於儲存嵌入以進行快速相似性搜尋作業。

參考資料：

LangChain 向量儲存庫

新增文件：

from langchain_core.documents import Document

document_1 = Document(id="1", page_content="foo", metadata={"baz": "bar"})
document_2 = Document(id="2", page_content="thud", metadata={"bar": "baz"})

documents = [document_1, document_2]
vector_store.add_documents(documents=documents)

這段片段的功能： 使用嵌入用戶端將文件轉換成嵌入，並將它們添加到向量存儲庫中，方便日後檢索。

參考資料：

LangChain 向量儲存庫

依相似性搜尋：

results = vector_store.similarity_search(query="thud", k=1)
for doc in results:
    print(f"* {doc.page_content} [{doc.metadata}]")

這段內容 ：對向量儲存執行語意搜尋，根據嵌入相似度返回與查詢最相似的文件。預期輸出：依相似度分數排序的相關文件列表。

使用 Azure OpenAI 模型

當你使用Azure OpenAI 模型搭配 langchain-azure-ai 套件時，請使用以下端點格式：

import os
from langchain_azure_ai.chat_models.inference import AzureAIChatCompletionsModel

llm = AzureAIChatCompletionsModel(
    endpoint="https://<resource>.openai.azure.com/openai/v1",
    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
    model="gpt-4o"
)

此片段的功能： 實例化一個專為Azure OpenAI模型配置的客戶端，採用Azure OpenAI端點格式。 endpoint 參數指向你Azure OpenAI 資源，而 credential 則使用環境變數中儲存的 API 金鑰。

參考資料：

LangChain Azure AI 整合

除錯與故障排除

如果你需要除錯應用程式並理解 Foundry 中送給模型的請求，請使用整合的除錯功能：

首先，將記錄設定到所需的等級：

import sys
import logging

# Acquire the logger for this client library. Use 'azure' to affect both
# 'azure.core` and `azure.ai.inference' libraries.
logger = logging.getLogger("azure")

# Set the desired logging level. logging.INFO or logging.DEBUG are good options.
logger.setLevel(logging.DEBUG)

# Direct logging output to stdout:
handler = logging.StreamHandler(stream=sys.stdout)
# Or direct logging output to a file:
# handler = logging.FileHandler(filename="sample.log")
logger.addHandler(handler)

# Optional: change the default logging format. Here we add a timestamp.
formatter = logging.Formatter("%(asctime)s:%(levelname)s:%(name)s:%(message)s")
handler.setFormatter(formatter)

此摘要的功能： 在 DEBUG 層級建立Python日誌，以擷取 LangChain 與 Model Inference API 之間 HTTP 請求與回應的詳細資訊。

參考資料：

Python 日誌模組

要查看請求有效載荷，請在實例化客戶端時傳遞 logging_enable=True 給 client_kwargs ：

import os
from langchain_azure_ai.chat_models import AzureAIChatCompletionsModel

model = AzureAIChatCompletionsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
    model="Mistral-Large-3",
    client_kwargs={"logging_enable": True},
)

這段程式碼片段的功能：建立一個啟用日誌的客戶端，以便捕捉並顯示詳細的請求與回應內容，這對於除錯 API 互動非常有用。

在程式碼裡照常使用客戶端。

追蹤

使用追蹤功能，請在 Foundry 中建立追蹤器。日誌儲存在 Azure 應用程式 Insights，並可隨時使用 Azure 監視器或 Foundry 入口網站查詢。每個 AI 中樞都有對應的 Azure 應用程式 Insights 實例。

取得你的儀表連接字串

提示

因為你可以在 Microsoft Foundry 入口網站中自訂左側窗格，所以你可能會看到與這些步驟中顯示的不同物品。如果你找不到你想要的，選擇 ⋯⋯更多選項 在左側窗格底部。

您可以透過以下任一方法設定您的應用程式將遙測資料傳送至 Azure 應用程式 Insights：

使用連接字串直接連至 Azure 應用程式 Insights：
1. 前往 Foundry 入口網站，選擇「追蹤」。
2. 選擇 管理資料來源。在這個畫面中，你可以看到與該專案相關的實例。
3. 複製 Connection 字串 的值，並設為以下變數：
```
import os

application_insights_connection_string = "instrumentation...."
```

使用 Microsoft Foundry SDK 與 Foundry Project 端點：

確保你已將套件 azure-ai-projects 安裝在你的環境中。
前往 Foundry 門戶。

複製你的 Foundry 專案端點網址，並用以下程式碼設定：

from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential

project_client = AIProjectClient(
    credential=DefaultAzureCredential(),
    endpoint="<your-foundry-project-endpoint-url>",
)

application_insights_connection_string = project_client.telemetry.get_application_insights_connection_string()

了解更多如何視覺化和管理痕跡的方法。

下一步

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-05-26

在 Microsoft Foundry（經典版）中開發模型與 LangChain 的應用程式

先決條件

設定環境

確認你的設定

使用對話補全模型

將多個 LLM 鏈結在一起

使用嵌入模型

使用 Azure OpenAI 模型

除錯與故障排除

追蹤

取得你的儀表連接字串

下一步

意見反應

其他資源