Użyj LangChain z modelami w Microsoft Foundry

Użyj langchain-azure-ai, aby utworzyć aplikacje LangChain, które wywołują modele wdrożone w Microsoft Foundry. Modele z interfejsami API zgodnymi z interfejsami OpenAI mogą być używane bezpośrednio. W tym artykule utworzysz klientów czatu i klientów do osadzania, uruchomisz ciągi monitów i połączysz generowanie z procesami weryfikacji.

Wymagania wstępne

  • Subskrypcja Azure. Utwórz je bezpłatnie.

  • Projekt Foundry.

  • Rola Użytkownika usługi Foundry w projekcie Foundry.

    Ważne

    Niedawno zmieniono nazwy ról RBAC w usłudze Foundry. Użytkownik Foundry, właściciel Foundry, właściciel konta Foundry i menedżer projektu Foundry były wcześniej nazywane odpowiednio użytkownikiem Azure AI, właścicielem Azure AI, właścicielem konta Azure AI i menedżerem projektu Azure AI. Poprzednie nazwy mogą być nadal widoczne w niektórych miejscach, podczas gdy zmiana nazwy jest wdrażana. Identyfikatory ról i uprawnienia podstawowe są niezmienione przez zmianę nazwy.

  • Wdrożony model czatu obsługujący interfejsy API zgodne z protokołem OpenAI, takie jak gpt-4.1 lub Mistral-Large-3.

  • Wdrożony model osadzania, taki jak text-embedding-3-large.

  • Python wersji 3.9 lub nowszej.

Zainstaluj wymagane pakiety:

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

Ważne

langchain-azure-ai używa nowego zestawu SDK Microsoft Foundry (wersja 2). Jeśli używasz klasycznej wersji Foundry, użyj langchain-azure-ai[v1], które korzysta z zestawu Azure AI Inference SDK (wycofanego z użycia). Dowiedz się więcej.

Konfigurowanie środowiska

Ustaw jeden z następujących wzorców połączeń:

  • Projekt punkt końcowy z użyciem Microsoft Entra ID (zalecane).
  • Bezpośredni punkt końcowy za pomocą klucza API.
import os

# Option 1: Project endpoint (recommended)
os.environ["FOUNDRY_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>"

Co robi ten fragment kodu: Definiuje zmienne środowiskowe używane przez klasy modeli na potrzeby dostępu do punktów końcowych, zarówno projektowych, jak i bezpośrednich.

Korzystanie z modeli czatów

Można łatwo stworzyć wystąpienie modelu używając init_chat_model.

from langchain.chat_models import init_chat_model

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

Ważne

Korzystanie z init_chat_model wymaga langchain>=1.2.13. Jeśli nie możesz zaktualizować wersji, skonfiguruj klientów bezpośrednio.

Wszystkie modele foundry obsługujące interfejsy API zgodne z platformą OpenAI mogą być używane z klientem, ale najpierw należy wdrożyć je w zasobie usługi Foundry. Użycie project_endpoint (zmienna środowiskowa FOUNDRY_PROJECT_ENDPOINT) wymaga Microsoft Entra ID na potrzeby uwierzytelniania i roli Foundry User.

Co robi ten fragment kodu: Tworzy klienta modelu czatu przy użyciu wygodnej metody init_chat_model. Klient łączy się z określonym modelem za pośrednictwem punktu końcowego projektu Foundry lub bezpośredniego punktu końcowego skonfigurowanego w ekosystemie.

Odwołania:

Weryfikowanie konfiguracji

Uruchom proste wywołanie modelu:

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

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

Co robi ten fragment kodu: Wysyła podstawowy monit o zweryfikowanie punktu końcowego, uwierzytelniania i routingu modelu.

Odwołania:

Konfigurowalne modele

Można również utworzyć model konfigurowalny w czasie wykonywania, określając wartość configurable_fields. Gdy pominiemy parametr model, domyślnie staje się konfigurowalnym polem.

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?

Co robi ten fragment kodu: Tworzy konfigurowalne wystąpienie modelu, które umożliwia łatwe przełączanie modeli w czasie wywołania. Ponieważ brakuje parametru model w init_chat_model, jest to domyślnie pole konfigurowalne i może zostać przekazane za pomocą invoke(). Możesz dodać inne pola, które można konfigurować, konfigurując element configurable_fields.

Konfigurowanie klientów bezpośrednio

Możesz również utworzyć klienta modelu czatu przy użyciu AzureAIOpenAIApiChatModel klasy .

import os

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

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

Domyślnie AzureAIOpenAIApiChatModel używa interfejsu API odpowiedzi OpenAI. To zachowanie można zmienić, przekazując use_responses_api=False:

import os

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

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

Uruchamianie wywołań asynchronicznych

Użyj poświadczeń asynchronicznych, jeśli aplikacja wywołuje modele za pomocą polecenia ainvoke. W przypadku używania Microsoft Entra ID do uwierzytelniania użyj odpowiedniej implementacji asynchronicznej dla poświadczeń:

import os

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

model = AzureAIOpenAIApiChatModel(
	project_endpoint=os.environ["FOUNDRY_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())

Wskazówka

Jeśli uruchomisz ten kod w notesie Jupyter, możesz użyć await main() bezpośrednio zamiast asyncio.run(main()).

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

Co robi ten fragment kodu: Tworzy klienta asynchronicznego i uruchamia żądanie nieblokacyjne za pomocą polecenia ainvoke.

Odwołania:

Rozumowanie

Wiele modeli może wykonywać wieloetapowe rozumowanie, aby dojść do wniosku. Obejmuje to podzielenie złożonych problemów na mniejsze, bardziej zarządzane kroki.

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 ...

Odwołania:

Narzędzia po stronie serwera

Modele OpenAI wdrożone na platformie Foundry obsługują wywoływanie narzędzi po stronie serwera w pętli: modele mogą korzystać z wyszukiwarki internetowej, interpreterów kodu i innych narzędzi, a następnie analizować wyniki w jednym cyklu rozmowy. Jeśli model wywołuje po stronie serwera narzędzia, zawartość komunikatu odpowiedzi będzie zawierać zawartość reprezentującą wywołanie i wynik narzędzia.

Ważne

Narzędzia w przestrzeni nazw langchain_azure_ai.tools.builtin są obsługiwane tylko w modelach OpenAI.

Są to narzędzia udostępniane przez platformę OpenAI, które rozszerzają możliwości modelu. Aby wyświetlić pełną listę obsługiwanych narzędzi, zobacz wbudowane narzędzia.

W poniższym przykładzie pokazano, jak używać wyszukiwania w Internecie:

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))

Niektóre narzędzia mogą wymagać konfiguracji innych zasobów w projekcie. Użyj azure-ai-projects do skonfigurowania tych zasobów, a następnie odwołaj się do nich z LangChain/LangGraph.

W poniższym przykładzie pokazano, jak skonfigurować magazyn plików przed użyciem go w narzędziu:

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

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=os.environ["FOUNDRY_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,
    )

Co robi ten fragment kodu: Konfiguruje magazyn wektorów z plikiem w Microsoft Foundry, aby model mógł później przeszukiwać zawartość pliku (używaną z FileSearchTool w następnym bloku kodu).

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}]

Korzystanie z modeli Foundry w agentach

Użyj create_agent w połączeniu z modelami połączonymi z Foundry, aby utworzyć pętle agenta w stylu ReAct:

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.

Narzędzia po stronie serwera mogą być również używane, ale wymagają wywołania metody 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.", 
)

Wskazówka

Narzędzie generowania obrazów w narzędziu Foundry wymaga przekazania nazwy wdrożenia modelu dla generowania obrazu w ramach nagłówka x-ms-oai-image-generation-deployment. W przypadku korzystania z programu langchain-azure-aijest ona obsługiwana automatycznie. Jeśli jednak planujesz użyć tego narzędzia z langchain-openai, musisz podać nagłówek ręcznie.

Użyj modeli osadzania

Można łatwo stworzyć wystąpienie modelu używając init_embeddings.

from langchain.embeddings import init_embeddings
from azure.identity import DefaultAzureCredential

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

Co robi ten fragment kodu: Tworzy klienta modelu osadzania przy użyciu metody ułatwienia init_embeddings. W przeciwieństwie do init_chat_model, init_embeddings nie używa automatycznie DefaultAzureCredential jako rozwiązania zapasowego, więc należy jawnie przekazać poświadczenie.

Wszystkie modele foundry obsługujące interfejsy API zgodne z platformą OpenAI mogą być używane z klientem, ale najpierw należy wdrożyć je w zasobie usługi Foundry. Użycie project_endpoint (zmienna środowiskowa FOUNDRY_PROJECT_ENDPOINT) wymaga Microsoft Entra ID na potrzeby uwierzytelniania i roli Foundry User.

Możesz też utworzyć klienta osadzania za pomocą polecenia AzureAIOpenAIApiEmbeddingsModel.

import os

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

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

Uwierzytelnianie za pomocą bezpośredniego dostępu do punktu końcowego i klucza API:

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",
)

Co robi ten fragment kodu: Konfiguruje generowanie osadzeń dla przepływów pracy wyszukiwania wektorowego, znajdowania i klasyfikowania.

Odwołania:

Przykład: uruchamianie wyszukiwania podobieństwa za pomocą magazynu wektorów

Użyj magazynu wektorów w pamięci na potrzeby eksperymentowania lokalnego.

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'}]

Co robi ten fragment kodu: Dodaje przykładowe dokumenty do magazynu wektorów i zwraca najbardziej podobny dokument dla zapytania.

Odwołania:

Debugowanie żądań przy użyciu rejestrowania

Włącz langchain_azure_ai rejestrowanie debugowania, aby sprawdzić przepływ żądań.

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)

Co robi ten fragment kodu: Konfiguruje rejestrowanie w Pythonie w celu emitowania szczegółowych dzienników SDK, które ułatwiają rozwiązywanie problemów z punktem końcowym lub ładunkiem.

Odwołania:

Odwołanie do zmiennych środowiskowych

Można skonfigurować następujące zmienne środowiskowe. Te wartości można również skonfigurować podczas konstruowania obiektów:

Zmienna Roli Przykład Parametr w konstruktorze
FOUNDRY_PROJECT_ENDPOINT Punkt końcowy projektu FoundryLab. Użycie punktu końcowego projektu wymaga uwierzytelniania Microsoft Entra ID (zalecane). https://contoso.services.ai.azure.com/api/projects/my-project project_endpoint
AZURE_OPENAI_ENDPOINT Root dla zasobów OpenAI. https://contoso.openai.azure.com Brak.
OPENAI_BASE_URL Bezpośredni punkt końcowy zgodny z protokołem OpenAI używany na potrzeby wywołań modelu. https://contoso.services.ai.azure.com/openai/v1 endpoint
OPENAI_API_KEY Lub AZURE_OPENAI_API_KEY Klucz interfejsu API używany z OPENAI_BASE_URL lub AZURE_OPENAI_ENDPOINT do uwierzytelniania opartego na kluczach. <your-api-key> credential
AZURE_OPENAI_DEPLOYMENT_NAME Nazwa wdrożenia modelu w zasobie Foundry lub OpenAI. Sprawdź nazwę w portalu Foundry, ponieważ nazwy wdrożeń mogą różnić się od używanego modelu bazowego. Można użyć dowolnego modelu obsługującego interfejsy API zgodne z protokołem OpenAI, jednak nie wszystkie parametry mogą być obsługiwane. Mistral-Large-3 model
AZURE_OPENAI_API_VERSION Wersja interfejsu API do użycia. Gdy element api_version jest dostępny, skonstruujemy klientów OpenAI i wprowadzamy api-version parametr zapytania za pomocą polecenia default_query. v1 Lub preview api_version

Ważne

Zmienne środowiskowe AZURE_AI_INFERENCE_ENDPOINT i AZURE_AI_CREDENTIALS używane dla AzureAIChatCompletionsModel lub AzureAIEmbeddingsModel (starsza wersja) nie są już używane.

Następny krok

Użycie funkcji Foundry Content Safety z LangGraph

Powiązana zawartość

  • Last updated on