Développer des applications avec des modèles et LangChain dans Microsoft Foundry (classique)

LangChain est un écosystème de développeurs qui facilite la création d’applications de raisonnement. Il comprend plusieurs composants, et la plupart d’entre eux peuvent être utilisés indépendamment, de sorte que vous pouvez choisir et choisir les pièces dont vous avez besoin.

Vous pouvez utiliser des modèles déployés sur Microsoft Foundry avec LangChain de deux façons :

Ce tutoriel montre comment utiliser le package langchain-azure-ai[v1] avec LangChain à l’aide de l’API d’inférence de modèle IA Azure. Certains modèles, tels que OpenAI, Cohere ou Mistral, offrent leurs propres API et extensions LangChain. Ces extensions peuvent inclure des fonctionnalités spécifiques au modèle et conviennent si vous devez les utiliser. Installez l’extension pour le modèle de votre choix, tel que langchain-openai ou langchain-cohere.

Conditions préalables

Pour exécuter ce tutoriel, vous avez besoin des éléments suivants :

• Un compte Azure avec un abonnement actif. Si vous n'en avez pas, créez un compte Azure gratuit, qui inclut un abonnement d'essai gratuit.

• Rôle requis :
  • Propriétaire ou Contributeur sur la ressource Foundry ou AI Hub pour déployer des modèles
  • Azure AI User pour utiliser un modèle dans un projet Foundry
  • Développeur IA Azure pour utiliser le modèle dans un projet basé sur un hub

• Déploiement de modèle qui prend en charge l’API d’inférence de modèle. Cet article utilise Mistral-Large-3.

• Python 3.9 ou version ultérieure installée, y compris pip.

• LangChain installé. Vous pouvez l’installer à l’aide de la commande suivante :

  pip install langchain
  

• Installez l’intégration de Foundry :

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

Configurer l’environnement

Pour utiliser les LLMs déployés dans le portail Microsoft Foundry, vous avez besoin du point de terminaison et des informations d’identification pour vous y connecter. Procédez comme suit pour obtenir les informations dont vous avez besoin à partir du modèle que vous souhaitez utiliser :

1. Connectez-vous à Microsoft Foundry. Vérifiez que le commutateur New Foundry est activé. Ces étapes font référence à Foundry (nouveau).

   

2. Ouvrez le projet dans lequel le modèle est déployé, s’il n’est pas déjà ouvert.

3. Copiez l’URL du point de terminaison et la clé.

Dans ce scénario, définissez l’URL et la clé de point de terminaison en tant que variables d’environnement. (Si le point de terminaison que vous avez copié inclut du texte supplémentaire après /models, supprimez-le afin que l’URL se termine comme /models indiqué ci-dessous.)

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

Créez un client pour vous connecter au modèle de conversation à l’aide de la AzureAIChatCompletionsModel classe.

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

Ce que fait cet extrait de code : Instancie un AzureAIChatCompletionsModel client configuré pour se connecter à votre modèle déployé à l’aide d’une clé API pour l’authentification. Ce client agit comme une interface de l’API d’inférence de modèle.

Références:

• Intégration Azure AI de LangChain
• Vue d’ensemble de l’API d’inférence de modèle

Si votre point de terminaison prend en charge Microsoft Entra ID, utilisez le code suivant pour créer le client :

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

Si vous envisagez d’utiliser des appels asynchrones, utilisez la version asynchrone des informations d’identification :

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

Si votre point de terminaison sert un modèle unique (par exemple, les déploiements d’API serverless), n’incluez pas le model paramètre :

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

Vérifier votre configuration

Testez la connexion de votre client avec un appel simple :

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

Procédez comme suit : Appelle le modèle avec une invite simple pour vérifier l’authentification et la connectivité. Sortie attendue : message d’accueil du modèle (par exemple, « Hello ! » Comment puis-je vous aider aujourd’hui ?).

Références:

• Interface LangChain Runnable

Utiliser des modèles d’achèvement de conversation

Utilisez directement le modèle. ChatModels sont des instances de l’interface LangChain Runnable , qui fournit un moyen standard d’interagir avec eux. Pour appeler le modèle, transmettez une liste de messages à la invoke méthode.

from langchain_core.messages import HumanMessage, SystemMessage

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

model.invoke(messages)

Ce que fait cet extrait de code : Montre comment transmettre une liste d’objets HumanMessageSystemMessage à la méthode du invoke() modèle pour générer une réponse.

Références:

• LangChain Messages
• Interface LangChain Runnable

Composez les opérations en fonction des besoins en chaînes. Utilisez un modèle d’invite pour traduire des phrases :

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

Cette chaîne prend les entrées language et text. À présent, créez un analyseur de sortie :

from langchain_core.output_parsers import StrOutputParser

parser = StrOutputParser()

Ce que fait cet extrait de code : Crée un StrOutputParser élément qui convertit la sortie du modèle en format de chaîne, en supprimant toutes les métadonnées supplémentaires.

Références:

• Analyseurs de sortie LangChain

Combinez le modèle, le gabarit et l’analyseur de sortie à l’aide de l’opérateur de canal (|) :

chain = prompt_template | model | parser

Appelez la chaîne en fournissant language et text en utilisant la invoke méthode :

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

Chaîner plusieurs LLMs ensemble

Étant donné que les modèles dans Foundry exposent une API d’inférence de modèle commune, vous pouvez chaîner plusieurs opérations LLM et choisir le modèle le mieux adapté à chaque étape.

Dans l’exemple suivant, vous créez deux clients de modèle : un producteur et un vérificateur. Pour faire la distinction, utilisez un point de terminaison multimodèle, tel que l’API d’inférence de modèle et transmettez le model paramètre à un modèle volumineux pour la génération et un petit modèle pour la vérification. La production de contenu nécessite généralement un modèle plus volumineux, tandis que la vérification peut en utiliser une plus petite.

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

Ce que fait cet extrait de code : Instancie deux clients distincts AzureAIChatCompletionsModel : une utilisation Mistral-Large-3 pour la génération de contenu et une autre Mistral-Small pour la vérification, ce qui montre comment choisir différents modèles pour différentes tâches.

Références:

• Intégration Azure AI de LangChain

L’exemple suivant génère un poème écrit par un poète urbain :

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

Ce que fait cet extrait de code : Crée un modèle d’invite et le chaîne avec le producer client de modèle pour générer du contenu créatif (un poème dans ce cas).

Chaînez les éléments :

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

Ce que fait cet extrait de code : Enchaîne le poème généré par le biais du verifier modèle pour examiner ou valider le contenu généré, illustrant un flux de travail producteur-vérificateur.

La chaîne précédente retourne uniquement la sortie de l’étape verifier . Pour accéder au résultat intermédiaire généré par le producer, utilisez un RunnablePassthrough pour générer cette étape intermédiaire.

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)

Appelez la chaîne à l’aide de la invoke méthode :

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

Ce que fait cet extrait de code : Appelle la chaîne complète producteur-vérificateur avec une entrée de sujet, qui retourne le contenu généré et le résultat de la vérification. Sortie attendue : objet JSON contenant poem et verification clés avec le poème généré et la réponse de vérification.

Références:

• Exécutables de LangChain

Utiliser des modèles d’incorporation

Créez un client d’incorporation de la même façon. Définissez les variables d’environnement pour qu’elle pointe vers un modèle d’incorporation :

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

Créez le client :

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

Ce que fait cet extrait de code : Instancie un client d'embeddings en utilisant AzureAIEmbeddingsModel pour convertir le texte en embeddings vectoriels, qui peuvent être utilisés pour la recherche sémantique et les comparaisons de similarités.

Références:

• Incorporations LangChain

Utilisez un stockage vectoriel en mémoire :

from langchain_core.vectorstores import InMemoryVectorStore

vector_store = InMemoryVectorStore(embed_model)

Ce que fait cet extrait de code : Crée un magasin de vecteurs en mémoire (InMemoryVectorStore) qui stocke les incorporations pour les opérations de recherche de similarité rapide.

Références:

• Magasins de vecteurs LangChain

Ajouter des documents :

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)

Ce que fait cet extrait de code : Convertit les documents en incorporations à l’aide du client d’incorporations et les ajoute au magasin de vecteurs pour une récupération ultérieure.

Références:

• Magasins de vecteurs LangChain

Recherchez par similarité :

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

Ce que fait cet extrait de code : Effectue une recherche sémantique sur le magasin vectoriel, retournant des documents les plus similaires à la requête en fonction de la similarité incorporée. Sortie attendue : liste des documents pertinents classés par score de similarité.

Utiliser Azure modèles OpenAI

Lorsque vous utilisez Azure modèles OpenAI avec le package langchain-azure-ai, utilisez le format de point de terminaison suivant :

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

Ce que fait cet extrait de code : il instancie un client configuré spécifiquement pour les modèles Azure OpenAI en utilisant le format de point de terminaison Azure OpenAI. Le paramètre endpoint pointe vers votre ressource OpenAI Azure, et le credential utilise la clé API stockée dans la variable d’environnement.

Références:

• intégration LangChain Azure IA

Débogage et résolution des problèmes

Si vous devez déboguer votre application et comprendre les demandes envoyées aux modèles dans Foundry, utilisez les fonctionnalités de débogage de l’intégration :

Tout d’abord, configurez la journalisation au niveau souhaité :

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)

Ce que fait cet extrait de code : Configure la journalisation Python au niveau du DÉBOGAGE pour capturer des informations détaillées sur les requêtes et réponses HTTP entre LangChain et l’API d’inférence de modèle.

Références:

• module de journalisation Python

Pour voir les charges utiles de la requête, passez logging_enable=True dans client_kwargs lors de l'instanciation du client :

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

Ce que fait cet extrait de code : Crée un client avec la journalisation activée pour capturer et afficher des charges utiles de requête/réponse détaillées, utiles pour le débogage des interactions d’API.

Utilisez le client comme d’habitude dans votre code.

Traçage

Utilisez le suivi dans Foundry en créant un traceur. Les journaux sont stockés dans Azure Application Insights et peuvent être consultés à tout moment à l’aide d’Azure Monitor ou du portail Foundry. Chaque hub IA a une instance Azure Application Insights associée.

Obtenez votre chaîne de connexion de l'instrumentation

Vous pouvez configurer votre application pour envoyer des données de télémétrie à Azure Application Insights à l’aide de l’une des méthodes suivantes :

1. Utilisez directement la chaîne de connexion pour Azure Application Insights :

   1. Accédez au portail Foundry et sélectionnez Suivi.

   2. Sélectionnez Gérer la source de données. Dans cet écran, vous pouvez voir l’instance associée au projet.

   3. Copiez la valeur sur la chaîne de connexion et définissez-la sur la variable suivante :

      import os
      
      application_insights_connection_string = "instrumentation...."
      

2. Utilisez le Kit de développement logiciel (SDK) Microsoft Foundry et le point de terminaison Project Foundry :

   1. Vérifiez que le package azure-ai-projects est installé dans votre environnement.

   2. Accédez au portail Foundry.

   3. Copiez l’URL du point de terminaison de votre projet Foundry et définissez-la dans le code suivant :

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

En savoir plus sur la visualisation et la gestion des traces.

Étapes suivantes

• Développer des applications avec LlamaIndex
• Visualiser et gérer les traces dans Foundry
• Utiliser des modèles Foundry
• Référence : API d’inférence de modèle