Tworzenie aplikacji przy użyciu modeli i biblioteki LangChain w usłudze Microsoft Foundry (wersja klasyczna)

LangChain to ekosystem deweloperów, który ułatwia tworzenie aplikacji rozumowania. Zawiera wiele komponentów, a większość z nich może być używana niezależnie, dzięki czemu można wybierać te, które są potrzebne.

Modele wdrożone w usłudze Microsoft Foundry z aplikacją LangChain można użyć na dwa sposoby:

W tym samouczku pokazano, jak używać pakietu langchain-azure-ai[v1] z LangChain przy użyciu Azure AI Model Inference API. Niektóre modele, takie jak OpenAI, Cohere lub Mistral, oferują własne interfejsy API i rozszerzenia LangChain. Te rozszerzenia mogą obejmować możliwości specyficzne dla modelu i są odpowiednie, jeśli trzeba ich używać. Zainstaluj rozszerzenie dla wybranego modelu, na przykład langchain-openai lub langchain-cohere.

Wymagania wstępne

Do uruchomienia tego samouczka potrzebne są następujące elementy:

• Konto Azure z aktywną subskrypcją. Jeśli go nie masz, utwórz konto free Azure, które obejmuje subskrypcję bezpłatnej wersji próbnej.

• Wymagana rola:

  • Właściciel lub współautor zasobu usługi Foundry lub centrum sztucznej inteligencji do wdrażania modeli

  • Użytkownik Foundry umożliwiający korzystanie z modelu w projekcie Foundry

    Ważna

    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.

  • Azure AI Developer aby używać modelu w projekcie opartym na centrum

• Wdrożenie modelu, które obsługuje API inferencji modelu. W tym artykule użyto Mistral-Large-3.

• Python 3.9 lub nowsza wersja zainstalowana, w tym narzędzie pip.

• Zainstalowano aplikację LangChain. Można go zainstalować za pomocą następującego polecenia:

  pip install langchain
  

• Zainstaluj integrację z usługą Foundry:

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

Konfigurowanie środowiska

Aby używać modułów LLM wdrożonych w portalu Microsoft Foundry, potrzebny jest punkt końcowy i poświadczenia, aby nawiązać z nim połączenie. Wykonaj następujące kroki, aby uzyskać potrzebne informacje z modelu, którego chcesz użyć:

1. Zaloguj się do Microsoft Foundry. Upewnij się, że przełącznik New Foundry jest włączony. Te kroki dotyczą rozwiązania Foundry (nowy).

   

2. Otwórz projekt, w którym wdrożono model, jeśli nie jest jeszcze otwarty.

3. Skopiuj adres URL punktu końcowego i klucz.

W tym scenariuszu ustaw adres URL punktu końcowego i klucz jako zmienne środowiskowe. (Jeśli skopiowany punkt końcowy zawiera dodatkowy tekst po /models, usuń go, aby adres URL zakończył się w /models sposób pokazany poniżej).

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

Utwórz klienta, aby nawiązać połączenie z modelem czatu AzureAIChatCompletionsModel przy użyciu klasy .

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 robi ten fragment kodu: Tworzy instancję klienta skonfigurowanego AzureAIChatCompletionsModel do łączenia się z wdrożonym modelem przy użyciu klucza API w celu uwierzytelnienia. Ten klient działa jako interfejs do API wnioskowania modelu.

Odwołania:

• LangChain Azure integracja sztucznej inteligencji
• Omówienie interfejsu API wnioskowania modelu

Jeśli punkt końcowy obsługuje Microsoft Entra ID, użyj następującego kodu, aby utworzyć klienta:

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

Jeśli planujesz używać wywołań asynchronicznych, użyj asynchronicznej wersji poświadczeń:

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

Jeśli punkt końcowy obsługuje pojedynczy model (na przykład wdrożenia bezserwerowego interfejsu API), nie uwzględnij parametru 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"],
)

Weryfikowanie konfiguracji

Przetestuj połączenie klienta przy użyciu prostego wywołania:

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

Co to robi: Wywołuje model z prostym monitem o zweryfikowanie uwierzytelniania i łączności. Oczekiwane dane wyjściowe: komunikat powitania z modelu (na przykład "Witaj! Jak mogę ci pomóc dzisiaj?").

Odwołania:

• Interfejs LangChain Runnable

Korzystanie z modeli uzupełniania czatu

Użyj modelu bezpośrednio. ChatModels to wystąpienia interfejsu LangChain Runnable , który zapewnia standardowy sposób interakcji z nimi. Aby wywołać model, przekaż listę komunikatów do metody invoke.

from langchain_core.messages import HumanMessage, SystemMessage

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

model.invoke(messages)

Co robi ten fragment kodu: Przedstawia sposób przekazywania listy HumanMessage obiektów i SystemMessage do metody modelu invoke() w celu wygenerowania odpowiedzi.

Odwołania:

• Wiadomości LangChain
• Interfejs LangChain Runnable

Redaguj operacje zgodnie z potrzebami w łańcuchach. Użyj szablonu monitu, aby przetłumaczyć zdania:

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

Ten łańcuch przyjmuje dane wejściowe language i text. Teraz utwórz analizator danych wyjściowych:

from langchain_core.output_parsers import StrOutputParser

parser = StrOutputParser()

Co robi ten fragment kodu: Tworzy obiekt StrOutputParser , który konwertuje dane wyjściowe modelu na format ciągu, rozbierając wszelkie dodatkowe metadane.

Odwołania:

• Analizatory danych wyjściowych langchain

Połącz szablon, model i parser danych wyjściowych używając operatora pipe (|):

chain = prompt_template | model | parser

Wywołaj łańcuch, podając wartości language i text przy użyciu metody invoke.

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

Łączenie wielu modułów LLM

Ponieważ modele w rozwiązaniu Foundry uwidacznia wspólny interfejs API wnioskowania modelu, można połączyć wiele operacji LLM i wybrać model najlepiej dopasowany do każdego kroku.

W poniższym przykładzie utworzysz dwóch klientów modelu: jednego producenta i jednego weryfikatora. Aby wyjaśnić różnicę, użyj wielomodelowego punktu końcowego, takiego jak interfejs API wnioskowania modelu, i przekaż model parametr do dużego modelu do generowania i małego modelu na potrzeby weryfikacji. Tworzenie zawartości zwykle wymaga większego modelu, podczas gdy weryfikacja może używać mniejszego modelu.

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 robi ten fragment kodu: Tworzy wystąpienie dwóch oddzielnych AzureAIChatCompletionsModel klientów: jeden używany do generowania zawartości za pomocą Mistral-Large-3, a drugi za pomocą Mistral-Small do weryfikacji, co demonstruje, jak wybierać różne modele dla różnych zadań.

Odwołania:

• LangChain Azure integracja sztucznej inteligencji

Poniższy przykład generuje wiersz napisany przez miejskiego poetę:

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 robi ten fragment kodu: Tworzy szablon polecenia i łączy go z klientem modelu producer, aby wygenerować kreatywną treść (w tym przypadku wiersz).

Połącz elementy:

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

Co robi ten fragment kodu? Łączy wygenerowany wiersz za pośrednictwem modelu verifier, aby zweryfikować lub przejrzeć wygenerowaną zawartość, demonstrując cykl pracy producenta i weryfikatora.

Poprzedni łańcuch zwraca tylko dane wyjściowe verifier kroku. Aby uzyskać dostęp do wyniku pośredniego wygenerowanego przez producer, użyj RunnablePassthrough, aby wyprowadzić ten krok pośredni.

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)

Wywołaj łańcuch przy użyciu invoke metody :

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

Co robi ten fragment kodu: Wywołuje kompletny łańcuch producent-weryfikator z danymi wejściowymi tematu, zwracając zarówno wygenerowaną zawartość, jak i wynik weryfikacji. Oczekiwany wynik: obiekt JSON zawierający klucze poem i verification z odpowiednio wygenerowanym wierszem oraz odpowiedzią weryfikacji.

Odwołania:

• Runnables LangChain

Użyj modeli osadzania

Utwórz klienta do obsługi osadzania w podobny sposób. Ustaw zmienne środowiskowe, aby wskazywały model osadzania:

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

Utwórz 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 robi ten fragment kodu: Tworzy wystąpienie klienta embeddings przy użyciu AzureAIEmbeddingsModel do konwertowania tekstu na wektory embeddings, które mogą służyć do wyszukiwania semantycznego i porównań podobieństw.

Odwołania:

• Osadzenia LangChain

Użyj magazynu wektorów w pamięci:

from langchain_core.vectorstores import InMemoryVectorStore

vector_store = InMemoryVectorStore(embed_model)

Co robi ten fragment kodu: Tworzy magazyn wektorów w pamięci (InMemoryVectorStore), który przechowuje osadzenia dla szybkiego wyszukiwania podobieństwa.

Odwołania:

• Magazyny wektorów LangChain

Dodaj 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 robi ten fragment kodu: Konwertuje dokumenty na osadzanie przy użyciu klienta osadzania i dodaje je do magazynu wektorów na potrzeby późniejszego pobierania.

Odwołania:

• Magazyny wektorów LangChain

Wyszukaj według podobieństwa:

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

Co robi ten fragment kodu: Wykonuje wyszukiwanie semantyczne względem magazynu wektorów, zwracając dokumenty najbardziej podobne do zapytania na podstawie podobieństwa osadzania. Oczekiwane dane wyjściowe: lista odpowiednich dokumentów sklasyfikowanych według wyniku podobieństwa.

Korzystanie z modeli Azure OpenAI

W przypadku używania modeli Azure OpenAI z pakietem langchain-azure-ai użyj następującego formatu punktu końcowego:

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 robi ten fragment: Tworzy instancję klienta skonfigurowanego specjalnie dla modeli Azure OpenAI przy użyciu formatu endpointu Azure OpenAI. Parametr endpoint wskazuje na zasób Azure OpenAI, a credential używa klucza interfejsu API przechowywanego w zmiennej środowiskowej.

Odwołania:

• LangChain Azure integracja sztucznej inteligencji

Debugowanie i rozwiązywanie problemów

Jeśli musisz debugować aplikację i zrozumieć żądania wysyłane do modeli w rozwiązaniu Foundry, skorzystaj z możliwości debugowania integracji:

Najpierw skonfiguruj rejestrowanie na żądanym poziomie:

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 robi ten fragment kodu: Konfiguruje rejestrowanie w Python na poziomie DEBUG, aby przechwycić szczegółowe informacje o żądaniach HTTP i odpowiedziach między LangChain a Model Inference API.

Odwołania:

• moduł logowania Python

Aby wyświetlić ładunki danych żądań, przekaż logging_enable=True w client_kwargs podczas tworzenia instancji 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 robi ten fragment kodu: Tworzy klienta z włączonym rejestrowaniem w celu przechwytywania i wyświetlania szczegółowych ładunków żądań/odpowiedzi, przydatnych do debugowania interakcji interfejsu API.

Korzystaj z klienta w kodzie tak jak zazwyczaj.

Śledzenie

Użyj śledzenia w narzędziu Foundry, tworząc traser. Dzienniki są przechowywane w usłudze aplikacja systemu Azure Insights i mogą być odpytywane w dowolnym momencie przy użyciu Azure Monitor lub portalu Usługi Foundry. Każde centrum sztucznej inteligencji ma skojarzone wystąpienie usługi aplikacja systemu Azure Insights.

Uzyskiwanie parametry połączenia instrumentacji

Aplikację można skonfigurować tak, aby wysyłała dane telemetryczne do usługi aplikacja systemu Azure Insights przy użyciu jednej z następujących metod:

1. Użyj ciągu połączenia, aby bezpośrednio połączyć się do aplikacja systemu Azure Insights.

   1. Przejdź do portalu Foundry i wybierz Śledzenie.

   2. Wybierz pozycję Zarządzaj źródłem danych. Na tym ekranie widać wystąpienie skojarzone z projektem.

   3. Skopiuj wartość w polu Parametry połączenia i ustaw ją na następującą zmienną:

      import os
      
      application_insights_connection_string = "instrumentation...."
      

2. Użyj zestawu SDK Microsoft Foundry i punktu końcowego Project Foundry:

   1. Upewnij się, że pakiet azure-ai-projects został zainstalowany w środowisku.

   2. Przejdź do portalu Foundry.

   3. Skopiuj adres URL punktu końcowego projektu Foundry i ustaw go w następującym kodzie:

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

Dowiedz się więcej na temat wizualizowania śladów i zarządzania nimi.

Następne kroki

• Tworzenie aplikacji za pomocą indeksu LlamaIndex
• Wizualizowanie śladów i zarządzanie nimi w narzędziu Foundry
• Używanie modeli Foundry
• Dokumentacja: interfejs API inferencji modelu