Verwenden von LangChain mit Modellen in Microsoft Foundry

Verwenden Sie langchain-azure-ai, um LangChain-Apps zu erstellen, die Modelle aufrufen, die in Microsoft Foundry bereitgestellt werden. Modelle mit openAI-kompatiblen APIs können direkt verwendet werden. In diesem Artikel erstellen Sie Chat- und Einbettungsclients, führen Aufforderungsketten aus und kombinieren die Generierung mit Überprüfungsworkflows.

Voraussetzungen

• Ein Azure-Abonnement. Erstellen Sie eine kostenlos.
• Ein Foundry-Projekt.
• Die Rolle Azure AI User im Foundry-Projekt.
• Ein bereitgestelltes Chatmodell, das OpenAI-kompatible APIs unterstützt, wie zum Beispiel gpt-4.1 oder Mistral-Large-3.
• Ein bereitgestelltes Einbettungsmodell, wie text-embedding-3-large.
• Python 3.9 oder höher.

Installieren Sie die erforderlichen Pakete:

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

Konfigurieren der Umgebung

Legen Sie eines der folgenden Verbindungsmuster fest:

• Projektendpunkt mit Microsoft Entra ID (empfohlen).
• Direkter Endpunkt mit einem API-Schlüssel.

import os

# Option 1: Project endpoint (recommended)
os.environ["AZURE_AI_PROJECT_ENDPOINT"] = (
	"https://<resource>.services.ai.azure.com/api/projects/<project>"
)

# Option 2: Direct OpenAI-compatible endpoint + API key
os.environ["OPENAI_BASE_URL"] = (
	"https://<resource>.services.ai.azure.com/openai/v1"
)
os.environ["OPENAI_API_KEY"] = "<your-api-key>"

Funktionsweise dieses Codeausschnitts: Definiert Umgebungsvariablen, die von den langchain-azure-ai Modellklassen für den projektbasierten oder direkten Endpunktzugriff verwendet werden.

Verwenden von Chatmodellen

Sie können ein Modell ganz einfach instanziieren, indem Sie Folgendes verwenden init_chat_model:

from langchain.chat_models import init_chat_model

model = init_chat_model("azure_ai:gpt-4.1")

Alle Foundry-Modelle, die OpenAI-kompatible APIs unterstützen, können mit dem Client verwendet werden, müssen jedoch zuerst in Ihrer Foundry-Ressource bereitgestellt werden. Die Verwendung von project_endpoint (Umgebungsvariable AZURE_AI_PROJECT_ENDPOINT) erfordert Microsoft Entra ID für die Authentifizierung und die Rolle Azure AI User.

Funktionsweise dieses Codeausschnitts: Erstellt einen Chatmodellclient mithilfe der init_chat_model Komfortmethode. Der Client leitet über den im Foundry-Projekt konfigurierten Endpunkt oder über den direkten in der Umgebung konfigurierten Endpunkt zum angegebenen Modell weiter.

Verweise:

• AzureAIOpenAIApiChatModel

Überprüfen Des Setups

Führen Sie einen einfachen Modellaufruf aus:

response = model.invoke("Say hello")
response.pretty_print()

================================== Ai Message ==================================
Hello! 👋 How can I help you today?

Funktionsweise dieses Codeausschnitts: Sendet eine einfache Eingabeaufforderung, um endpunkt-, Authentifizierungs- und Modellrouting zu überprüfen.

Verweise:

• LangChain-Runnable-Schnittstelle

Konfigurierbare Modelle

Sie können auch ein laufzeitkonfigurierbares Modell erstellen, indem Sie angeben configurable_fields. Wenn Sie den model Parameter weglassen, wird er standardmäßig zu einem konfigurierbaren Feld.

from langchain.chat_models import init_chat_model
from azure.identity import DefaultAzureCredential

configurable_model = init_chat_model(
    model_provider="azure_ai", 
    temperature=0,
	credential=DefaultAzureCredential()
)


configurable_model.invoke(
    "what's your name",
    config={"configurable": {"model": "gpt-5-nano"}},  # Run with GPT-5-nano
).pretty_print()

configurable_model.invoke(
    "what's your name",
    config={"configurable": {"model": "Mistral-Large-3"}}, # Run with Mistral Large
).pretty_print()

================================== Ai Message ==================================

Hi! I'm ChatGPT, an AI assistant built by OpenAI. You can call me ChatGPT or just Assistant. How can I help you today?
================================== Ai Message ==================================

I don't have a name, but you can call me **Assistant** or anything you like! 😊 What can I help you with today?

Funktionsweise dieses Codeausschnitts: Erstellt eine konfigurierbare Modellinstanz, mit der Sie Modelle problemlos zum Aufruf wechseln können. Da der model Parameter in init_chat_model fehlt, ist er standardmäßig ein konfigurierbares Feld und kann mit invoke() übergeben werden. Sie können andere Felder zur Konfiguration hinzufügen, indem Sie configurable_fields konfigurieren.

Konfigurieren von Clients direkt

Sie können auch einen Chatmodellclient mithilfe AzureAIOpenAIApiChatModel der Klasse erstellen.

import os

from azure.identity import DefaultAzureCredential
from langchain_azure_ai.chat_models import AzureAIOpenAIApiChatModel

model = AzureAIOpenAIApiChatModel(
	project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
	credential=DefaultAzureCredential(),
	model="Mistral-Large-3",
)

Standardmäßig verwendet AzureAIOpenAIApiChatModel die OpenAI-Antwort-API. Sie können dieses Verhalten ändern, indem Sie Folgendes übergeben use_responses_api=False:

import os

from azure.identity import DefaultAzureCredential
from langchain_azure_ai.chat_models import AzureAIOpenAIApiChatModel

model = AzureAIOpenAIApiChatModel(
    endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
    model="Mistral-Large-3",
    use_responses_api=False
)

Ausführen asynchroner Aufrufe

Verwenden Sie asynchrone Anmeldeinformationen, wenn Ihre App Modelle mit ainvoke aufruft. Wenn Sie Microsoft Entra ID für die Authentifizierung verwenden, verwenden Sie die entsprechende asynchrone Implementierung für Anmeldeinformationen:

import os

from azure.identity.aio import DefaultAzureCredential as DefaultAzureCredentialAsync
from langchain_azure_ai.chat_models import AzureAIOpenAIApiChatModel

model = AzureAIOpenAIApiChatModel(
	project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
	credential=DefaultAzureCredentialAsync(),
	model="gpt-4.1",
)


async def main():
	response = await model.ainvoke("Say hello asynchronously")
	response.pretty_print()


import asyncio
asyncio.run(main())

================================== Ai Message ==================================
Hello! 👋 How can I help you today?

Funktionsweise dieses Codeausschnitts: Erstellt einen asynchronen Client und führt eine nicht blockierende Anforderung mit ainvoke.

Verweise:

• Async-Anmeldeinformationen in Azure Identity
• LangChain-Runnable-Schnittstelle

Argumentation

Viele Modelle können eine mehrstufige Begründung durchführen, um zu einer Schlussfolgerung zu gelangen. Dies beinhaltet das Aufteilen komplexerEr Probleme in kleinere, verwaltbare Schritte.

from langchain.chat_models import init_chat_model

model = init_chat_model("azure_ai:DeepSeek-R1-0528")

for chunk in model.stream("Why do parrots have colorful feathers?"):
    reasoning_steps = [r for r in chunk.content_blocks if r["type"] == "reasoning"]
    print(reasoning_steps if reasoning_steps else chunk.text, end="")

print("\n")

Parrots have colorful feathers primarily due to a combination of evolutionary ...

Verweise:

• LangChain-Streaming

Serverseitige Tools

OpenAI-Modelle, die in Foundry bereitgestellt werden, unterstützen serverseitige Toolaufrufschleifen: Modelle können mit Web-Suche, Code-Interpretern und anderen Tools interagieren und dann die Ergebnisse in einer einzigen Konversationsrunde analysieren. Wenn ein Modell ein Tool serverseitig aufruft, enthält der Inhalt der Antwortnachricht Inhalte, die den Aufruf und das Ergebnis des Tools darstellen.

Diese Tools werden von OpenAI bereitgestellt, die die Funktionen des Modells erweitern. Die vollständige Liste der unterstützten Tools finden Sie unter integrierten Tools.

Das folgende Beispiel zeigt die Verwendung der Websuche:

from langchain.chat_models import init_chat_model
from langchain_azure_ai.tools.builtin import WebSearchTool
from azure.identity import DefaultAzureCredential

model = init_chat_model("azure_ai:gpt-4.1", credential=DefaultAzureCredential())
model_with_web_search = model.bind_tools([WebSearchTool()])

result = model_with_web_search.invoke("What is the current price of gold? Give me the answer in one sentence.")
result.content[-1]["text"]

As of today, March 24, 2026, the spot price of gold is approximately $4,397.80 per ounce. ([tradingeconomics.com](https://tradingeconomics.com/commodity/gold))

Einige Tools erfordern möglicherweise die Konfiguration anderer Ressourcen in Ihrem Projekt. Verwenden Sie azure-ai-projects, um diese Ressourcen zu konfigurieren und sie dann in LangChain/LangGraph zu referenzieren.

Das folgende Beispiel zeigt, wie Sie einen Dateispeicher konfigurieren, bevor Sie ihn in einem Tool verwenden:

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

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Create vector store and upload file
vector_store = openai.vector_stores.create(name="ProductInfoStore")
vector_store_id = vector_store.id

with open("product_info.md", "rb") as file_handle:
    vector_store_file = openai.vector_stores.files.upload_and_poll(
        vector_store_id=vector_store.id,
        file=file_handle,
    )

Was dieses Snippet macht: Es richtet einen Vektorspeicher mit einer Datei in Microsoft Foundry ein, sodass ein Modell später den Inhalt dieser Datei durchsuchen kann (wird mit dem FileSearchTool im nächsten Codeblock verwendet).

from langchain_azure_ai.tools.builtin import FileSearchTool

model_with_tools = model.bind_tools([FileSearchTool(vector_store_ids=[vector_store.id])])

results = model_with_tools.invoke("Tell me about Contoso products")
print("Answer:", results.content[-1]["text"])
print("Annotations:", results.content[-1]["annotations"])

Answer: Contoso offers the following products:

1. **The widget**
   - Description: A high-quality widget that is perfect for all your widget needs.
   - Price: $19.99

2. **The gadget**
   - Description: An advanced gadget that offers exceptional performance and reliability.
   - Price: $49.99

These products are part of Contoso's main offerings as detailed in their product information documentation.
Annotations: [{'file_id': 'assistant-MvU5SEqUcUBumoLUV5BXxn', 'filename': 'product_info.md', 'type': 'file_citation', 'file_index': 395}]

Verwende Foundry-Modelle in Agents

Verwenden Sie create_agent mit Modellen, die mit Foundry verbunden sind, um ReAct-Stil-Agentschleifen zu erstellen.

from langchain.agents import create_agent

agent = create_agent(
    model="azure_ai:gpt-5.2", 
    system_prompt="You're an informational agent. Answer questions cheerfully.", 
)

response = agent.invoke({"messages": "what's your name?"})
response["messages"][-1].pretty_print()

================================== Ai Message ==================================

I’m ChatGPT, your AI assistant.

Serverseitige Tools können auch verwendet werden, erfordern jedoch einen Aufruf bind_tools.

from langchain.chat_models import init_chat_model
from langchain.agents import create_agent
from langchain_azure_ai.tools.builtin import ImageGenerationTool

model = init_chat_model("azure_ai:gpt-5.2")
tools = [ImageGenerationTool(model="gpt-image-1.5", size="1024x1024")]
model_with_tools = model.bind_tools(tools)

agent = create_agent(
    model=model_with_tools,
    tools=tools,
    system_prompt="You're an informational agent. Answer questions with graphics.", 
)

Verwenden von Einbettungsmodellen

Sie können ein Modell ganz einfach instanziieren, indem Sie Folgendes verwenden init_embeddings:

from langchain.embeddings import init_embeddings

embed_model = init_embeddings("azure_ai:text-embedding-3-small")

Funktionsweise dieses Codeausschnitts: Erstellt einen Einbettungsmodellclient mithilfe der init_embeddings Komfortmethode.

Alle Foundry-Modelle, die OpenAI-kompatible APIs unterstützen, können mit dem Client verwendet werden, müssen jedoch zuerst in Ihrer Foundry-Ressource bereitgestellt werden. Die Verwendung von project_endpoint (Umgebungsvariable AZURE_AI_PROJECT_ENDPOINT) erfordert Microsoft Entra ID für die Authentifizierung und die Rolle Azure AI User.

Oder erstellen Sie den Einbettungsclient mit AzureAIOpenAIApiEmbeddingsModel.

import os

from azure.identity import DefaultAzureCredential
from langchain_azure_ai.embeddings import AzureAIOpenAIApiEmbeddingsModel

embed_model = AzureAIOpenAIApiEmbeddingsModel(
	project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
	credential=DefaultAzureCredential(),
	model="text-embedding-3-large",
)

Für die direkte Endpunkt- und API-Schlüsselauthentifizierung:

import os

from langchain_azure_ai.embeddings import AzureAIOpenAIApiEmbeddingsModel

embed_model = AzureAIOpenAIApiEmbeddingsModel(
	endpoint=os.environ["OPENAI_BASE_URL"],
	credential=os.environ["OPENAI_API_KEY"],
	model="text-embedding-3-large",
)

Funktionsweise dieses Codeausschnitts: Konfiguriert die Generierung von Einbettungen für Vektorsuch-, Abruf- und Bewertungsworkflows.

Verweise:

• AzureAIOpenAIApiEmbeddingsModel

Beispiel: Ausführen der Ähnlichkeitssuche mit einem Vektorspeicher

Verwenden Sie einen speicherinternen Vektorspeicher für lokale Experimente.

from langchain_core.documents import Document
from langchain_core.vectorstores import InMemoryVectorStore

vector_store = InMemoryVectorStore(embed_model)

documents = [
	Document(id="1", page_content="foo", metadata={"baz": "bar"}),
	Document(id="2", page_content="thud", metadata={"bar": "baz"}),
]

vector_store.add_documents(documents=documents)

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

* thud [{'bar': 'baz'}]

Funktionsweise dieses Codeausschnitts: Fügt Beispieldokumente zu einem Vektorspeicher hinzu und gibt das ähnlichste Dokument für eine Abfrage zurück.

Verweise:

• LangChain-Vektorspeicher

Fehlerbehebung von Anfragen mit Protokollierung

Aktivieren Sie langchain_azure_ai die Debugprotokollierung, um den Anforderungsfluss zu prüfen.

import logging
import sys

logger = logging.getLogger("langchain_azure_ai")
logger.setLevel(logging.DEBUG)

handler = logging.StreamHandler(stream=sys.stdout)
formatter = logging.Formatter(
	"%(asctime)s:%(levelname)s:%(name)s:%(message)s"
)
handler.setFormatter(formatter)
logger.addHandler(handler)

Was dieser Codeausschnitt macht: Konfiguriert das Python-Logging, um detaillierte SDK-Protokolle auszugeben, die helfen, Probleme mit Endpunkten oder Nutzlasten zu beheben.

Verweise:

• Python Protokollierung

Referenz zu Umgebungsvariablen

Sie können die folgenden Umgebungsvariablen konfigurieren. Diese Werte können auch beim Erstellen der Objekte konfiguriert werden:

Nächster Schritt

Verwandte Inhalte

• Übersicht über Gießereimodelle
• übersicht über Microsoft Foundry SDK
• Verwenden von LangChain mit Arbeitsspeicher in Foundry
• Verwendung von LangChain mit dem Foundry Agent Service