Vývoj aplikací pomocí modelů a jazyka LangChain v Microsoft Foundry (classic)

Poznámka

Tento článek se týká portálu Microsoft Foundry (classic) Portal. Pokud používáte nový portál, použijte místo toho novou verzi tohoto článku.

LangChain je vývojářský ekosystém, který usnadňuje vytváření důvodových aplikací. Obsahuje více součástí a většina z nich se dá používat nezávisle, takže si můžete vybrat a zvolit potřebné součásti.

Modely nasazené do Microsoft Foundry s jazykem LangChain můžete použít dvěma způsoby:

V tomto kurzu se dozvíte, jak používat balíček langchain-azure-ai[v1] s jazykem LangChain pomocí rozhraní API pro odvozování modelů Azure AI. Některé modely, jako jsou OpenAI, Cohere nebo Mistral, nabízejí vlastní rozhraní API a rozšíření LangChain. Tato rozšíření můžou zahrnovat funkce specifické pro konkrétní model a jsou vhodné, pokud je potřebujete použít. Nainstalujte rozšíření pro zvolený model, například langchain-openai nebo langchain-cohere.

Pozor

Odvozování langchain-azure-ai[v1] modelu je zastaralé a bude vyřazeno 30. května 2026. Přepněte na obecně dostupné rozhraní API OpenAI/v1 se stabilní sadou OpenAI SDK zavedenou v langchain-azure-ai nebo langchain-openai. Další informace

Požadavky

Ke spuštění tohoto kurzu potřebujete:

  • Požadovaná role:

    • Vlastník nebo přispěvatel prostředku Foundry nebo AI Hub pro nasazení modelů

    • Uživatel Foundry pro použití modelu v projektu Foundry

      Important

      Nedávno byly přejmenovány role Foundry RBAC. Foundry User, Foundry Owner, Foundry Account Owner a Foundry Project Manager se dříve nazývaly Uživatel Azure AI, Vlastník Azure AI, Vlastník účtu Azure AI a Správce projektů Azure AI. Během zavádění přejmenování se stále můžou zobrazovat předchozí názvy na některých místech. ID rolí a základní oprávnění se při přejmenování nezmění.

    • Azure AI Developer použít model v projektu založeném na centru

  • Nasazení modelu, které podporuje rozhraní API pro odvozování modelů. Tento článek používá Mistral-Large-3.

  • Python 3.9 nebo novější nainstalovaný, včetně pip.

  • LangChain je nainstalován. Můžete ho nainstalovat pomocí následujícího příkazu:

    pip install langchain

  • Nainstalujte integraci Foundry:

    pip install -U langchain-azure-ai[v1]

Konfigurace prostředí

Pokud chcete používat LLM nasazené na portálu Microsoft Foundry, musíte k němu připojit koncový bod a přihlašovací údaje. Pokud chcete získat potřebné informace z modelu, který chcete použít, postupujte takto:

  1. Přihlaste se k Microsoft Foundry. Ujistěte se, že je zapnutý přepínač New Foundry . Tyto kroky odkazují na Foundry (nové).

  2. Otevřete projekt, ve kterém je model nasazený, pokud ještě není otevřený.

  3. Zkopírujte adresu URL koncového bodu a klíč.

V tomto scénáři nastavte adresu URL koncového bodu a klíč jako proměnné prostředí. (Pokud zkopírovaný koncový bod obsahuje další text za /models, odeberte ho, aby adresa URL skončila na /models, jak je znázorněno níže.)

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

Vytvořte klienta pro připojení k modelu chatu AzureAIChatCompletionsModel pomocí třídy.

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

Co tento fragment kódu dělá: Vytvoří instanci klienta, nakonfigurovaného pro připojení k nasazenému modelu pomocí klíče API ke ověření. Tento klient funguje jako rozhraní api pro odvozování modelů.

Odkazy:

Pokud váš koncový bod podporuje Microsoft Entra ID, vytvořte klienta pomocí následujícího kódu:

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

Poznámka

Při použití Microsoft Entra ID se ujistěte, že je koncový bod nasazený s danou metodou ověřování a že máte požadovaná oprávnění k jeho vyvolání.

Pokud plánujete používat asynchronní volání, použijte asynchronní verzi přihlašovacích údajů:

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

Pokud váš koncový bod obsluhuje jeden model (například nasazení bezserverového rozhraní API), nezahrnujte parametr 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"],
)

Ověření nastavení

Otestujte připojení klienta pomocí jednoduchého vyvolání:

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

Co to dělá: Pomocí jednoduchého promptu zavolá model ke kontrole autentizace a připojení. Očekávaný výstup: Zpráva s pozdravem z modelu (například "Hello! Jak vám mohu dnes pomoct?").

Odkazy:

Použití modelů dokončování chatu

Použijte model přímo. ChatModels jsou instance rozhraní LangChain Runnable , které poskytuje standardní způsob interakce s nimi. Pokud chcete model volat, předejte metodě invoke seznam zpráv.

from langchain_core.messages import HumanMessage, SystemMessage

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

model.invoke(messages)

Co tento fragment kódu dělá: Ukazuje, jak předat seznam HumanMessage a SystemMessage objekty metodě modelu invoke() k vygenerování odpovědi.

Odkazy:

Sestavujte operace podle potřeby v propojeních. K překladu vět použijte výzvovou šablonu.

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

Tento řetězec přijímá vstupy language a text. Teď vytvořte výstupní analyzátor:

from langchain_core.output_parsers import StrOutputParser

parser = StrOutputParser()

Co tento fragment kódu dělá: Vytvoří StrOutputParser objekt, který převede výstup modelu na formát řetězce a odstraní všechna další metadata.

Odkazy:

Zkombinujte šablonu, model a výstupní analyzátor pomocí operátoru pipe (|):

chain = prompt_template | model | parser

Vyvolejte řetězec zadáním hodnot language a text pomocí metody invoke.

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

Zřetězte více LLM dohromady

Vzhledem k tomu, že modely v Foundry zpřístupňují společné rozhraní API pro odvozování modelů, můžete zřetězovat několik operací LLM a zvolit model, který je pro každý krok nejvhodnější.

V následujícím příkladu vytvoříte dva klienty modelu: jednoho producenta a jednoho ověřovatele. Pokud chcete jasně rozlišovat, použijte koncový bod s více modely, jako je Model Inference API, a předejte parametr model velkému modelu pro generování a malému modelu pro ověření. Vytváření obsahu obecně vyžaduje větší model, zatímco ověření může použít menší 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",
)

Co tento fragment kódu dělá: Vytvoří instanci dvou samostatných AzureAIChatCompletionsModel klientů: jednoho pro Mistral-Large-3 generování obsahu a další použití Mistral-Small k ověření, což demonstruje, jak zvolit různé modely pro různé úlohy.

Odkazy:

Tip

Projděte si kartu modelu pro každý model a seznamte se s nejlepšími případy použití.

Následující příklad generuje báseň napsanou městským básníkem:

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

Co tento úryvek dělá: Vytvoří šablonu výzvy a řetězí ji s klientem modelu producer za účelem generování kreativního obsahu (v tomto případě báseň).

Spojte části:

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

Co tento úryvek dělá: Zřetězí vygenerovanou báseň prostřednictvím verifier modelu k ověření či zhodnocení vygenerovaného obsahu a předvádí pracovní postup výrobce a ověřovatele.

Předchozí řetězec vrátí pouze výstup verifier kroku. Chcete-li získat přístup k přechodnému výsledku vygenerovanému producernástrojem , použijte RunnablePassthrough k výstupu tohoto přechodného kroku.

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)

Vyvolání řetězce pomocí invoke metody:

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

Co tento fragment kódu dělá: Volá úplný řetězec producent-ověřovatel se vstupem topiku, která vrací jak vygenerovaný obsah, tak i výsledek ověření. Očekávaný výstup: Objekt JSON obsahující poem a verification klíče s vygenerovanou básní a ověřovací odpovědí.

Odkazy:

Použití modelů vkládání

Vytvořte klienta vkládání podobným způsobem. Nastavte proměnné prostředí tak, aby odkazovaly na model vkládání:

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

Vytvořte klienta:

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

Co tento fragment kódu dělá: Vytvoří instanci klienta vkládání pomocí AzureAIEmbeddingsModel převodu textu na vektorové vkládání, které lze použít pro sémantické vyhledávání a porovnávání podobností.

Odkazy:

Použití úložiště vektorů v paměti:

from langchain_core.vectorstores import InMemoryVectorStore

vector_store = InMemoryVectorStore(embed_model)

Co tento fragment kódu dělá: Vytvoří úložiště vektorů v paměti (InMemoryVectorStore), které ukládá vkládání pro rychlé operace vyhledávání podobnosti.

Odkazy:

Přidat dokumenty:

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)

Co tento fragment kódu dělá: Převede dokumenty na vkládání pomocí klienta pro vkládání a přidá je do úložiště vektorů pro pozdější načtení.

Odkazy:

Hledání podle podobnosti:

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

Co tento fragment kódu dělá: Provede sémantické vyhledávání v úložišti vektorů a vrací dokumenty, které se nejvíce podobají dotazu na základě podobnosti vkládání. Očekávaný výstup: Seznam relevantních dokumentů seřazených podle skóre podobnosti

Použití modelů OpenAI Azure

Při použití Azure modelů OpenAI s balíčkem langchain-azure-ai použijte následující formát koncového bodu:

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

Co tento fragment kódu dělá: Instancuje klienta nakonfigurovaného speciálně pro Azure OpenAI modely pomocí formátu koncového bodu Azure OpenAI. Parametr endpoint odkazuje na váš prostředek Azure OpenAI a credential používá klíč rozhraní API uložený v proměnné prostředí.

Odkazy:

Ladění a řešení potíží

Pokud potřebujete ladit aplikaci a porozumět požadavkům odesílaných do modelů v Foundry, použijte možnosti ladění integrace:

Nejprve nakonfigurujte protokolování na požadovanou úroveň:

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)

Co tento fragment kódu dělá: Nastaví protokolování Python na úrovni DEBUG, aby zachytil podrobné informace o požadavcích HTTP a odpovědích mezi LangChainem a rozhraním API pro odvozování modelů.

Odkazy:

  • modul protokolování Python

Pokud chcete zobrazit datové části požadavku, předejte logging_enable=True v client_kwargs při vytváření instance klienta.

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

Co tento fragment kódu dělá: Vytvoří klienta s povoleným protokolováním pro zaznamenání a zobrazení podrobných datových částí požadavků a odpovědí, které jsou užitečné pro ladění interakcí s rozhraním API.

V kódu používejte klienta jako obvykle.

Trasování

Použití trasování v Foundry vytvořením traceru. Protokoly se ukládají v Aplikace Azure Insights a dají se kdykoli dotazovat pomocí Azure Monitor nebo portálu Foundry. Každé centrum AI má přidruženou instanci Aplikace Azure Insights.

Získejte připojovací řetězec instrumentace

Tip

Vzhledem k tomu, že na portálu Microsoft Foundry můžete usouložit levé podokno, může se zobrazit jiné položky, než je znázorněno v tomto postupu. Pokud nevidíte, co hledáte, vyberte ... Další v dolní části levého podokna.

Aplikaci můžete nakonfigurovat tak, aby odesílala telemetrická data do služby Aplikace Azure Insights pomocí některé z následujících metod:

  1. Použijte připojovací řetězec pro přímý přístup k Aplikace Azure Insights.

    1. Přejděte na portál Foundry a vyberte Trasování.

    2. Vyberte Spravovat zdroj dat. Na této obrazovce uvidíte instanci přidruženou k projektu.

    3. Zkopírujte hodnotu v připojovacím řetězci a nastavte ji na následující proměnnou:

      import os

application_insights_connection_string = "instrumentation...."

  2. Použijte sadu Microsoft Foundry SDK a koncový bod Project Foundry:

    1. Ujistěte se, že máte ve svém prostředí nainstalovaný balíček azure-ai-projects .

    2. Přejděte na portál Foundry.

    3. Zkopírujte adresu URL koncového bodu projektu Foundry a nastavte ji v následujícím kódu:

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

Přečtěte si další informace o tom, jak vizualizovat a spravovat trasování.

Další kroky

  • Last updated on