Bien démarrer avec LangChain et LangGraph avec Foundry

Utilisez le package langchain-azure-ai comme point d’entrée pour la création d’applications LangChain et LangGraph avec Microsoft fonctionnalités Foundry. Cet article vous donne une carte de haut niveau du package afin de pouvoir commencer rapidement, puis passer à la documentation approfondie appropriée pour chaque fonctionnalité.

Conditions préalables

  • Un abonnement Azure. Créez-en un gratuitement.
  • Un projet Foundry.
  • Rôle Utilisateur Azure AI sur le projet Foundry (rôle avec le moins de privilèges pour le développement). Si vous créez ou gérez également des ressources, utilisez Contributeur ou Propriétaire en fonction des besoins. Pour plus d’informations, consultez Contrôle d’accès basé sur des rôles pour Microsoft Foundry.
  • Python 3.10 ou version ultérieure.
  • Azure CLI connecté (az login) afin que DefaultAzureCredential puisse s’authentifier.

Conseil

Cet article mentionne la prise en charge de Microsoft Foundry (nouveau), qui utilise la version azure-ai-projects>=2.0. Si vous utilisez Foundry classic, utilisez langchain-azure-ai[v1] à la place.

Installer le package

Installez le package de base :

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

Installez des extras facultatifs en fonction de votre scénario :

pip install -U "langchain-azure-ai[tools]"
pip install -U "langchain-azure-ai[opentelemetry]"
  • Utilisez [tools] si votre application utilise des outils à partir de l’espace de noms langchain_azure_ai.tools.*, comme Document Intelligence.
  • Utilisez [opentelemetry] si vous souhaitez suivre l’intégration via OpenTelemetry.

Identifier les éléments de base de l'intégration

Utilisez cette carte pour choisir l’espace de noms approprié pour votre solution :

Capacité Espace de noms Utilisation classique
Service de l'agent Foundry langchain_azure_ai.agents Créez des nœuds d’agent managé pour générer des graphiques et des flux complexes pour LangGraph et LangChain. Consultez des exemples détaillés.
Sécurité du contenu de fonderie langchain_azure_ai.agents.middleware Utilisez La sécurité et la modération du contenu Foundry pour vous assurer que vous pouvez déployer la solution avec les garde-fous appropriés. Consultez des exemples détaillés.
Modèles de conversation langchain_azure_ai.chat_models Appelez les modèles de conversation d’Azure OpenAI et du catalogue de modèles. Consultez des exemples détaillés.
Incorporations langchain_azure_ai.embeddings Appelez des modèles incorporés à partir du catalogue et générez des vecteurs pour les workflows de recherche, de récupération et de classement. Consultez des exemples détaillés.
Bases de données de vecteurs langchain_azure_ai.vectorstores Utilisez les intégrations vectorielles avec Recherche Azure AI et Cosmos DB.
Retrievers langchain_azure_ai.retrievers Exécutez la récupération de données sur des index et des magasins hébergés par Azure.
Stockage de l'historique des conversations langchain_azure_ai.chat_message_histories Conserver et relire l’historique des conversations entre les sessions. Utilisez des historiques optimisés en mémoire pour récupérer l’historique de conversation de passe consolidé. Consultez des exemples détaillés.
Outils langchain_azure_ai.tools Ajoutez des outils tels que Document Intelligence, Vision, analyse de texte de santé et Logic Apps.
Fonctions de rappel et traçage langchain_azure_ai.callbacks Capturez les événements d’exécution et émettez des traces OpenTelemetry. Consultez des exemples détaillés.
Constructeurs de requête langchain_azure_ai.query_constructors Créez des filtres de requête spécifiques au serveur principal pour les scénarios de récupération.

Consultez la section Découvrir chaque fonctionnalité en détail pour obtenir des procédures pas à pas spécifiques.

Connecter aux interfaces de projet et aux identifiants.

De nombreuses langchain-azure-ai classes prennent en charge la connexion via un point de terminaison de projet Foundry. Définissez-le AZURE_AI_PROJECT_ENDPOINT une fois, puis réutilisez-le dans les classes prises en charge.

export AZURE_AI_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"

Lorsque vous utilisez project_endpoint, l’authentification utilise Microsoft Entra ID et Azure RBAC sur le projet.

Les clés API sont destinées aux points de terminaison de service directs, tels que /openai/v1.

export OPENAI_BASE_URL="https://<resource>.services.ai.azure.com/openai/v1"
export OPENAI_API_KEY="<your-key>"

Exemple : Utiliser des modèles de Foundry

Une fois les variables d’environnement configurées, vous pouvez utiliser un modèle en procédant comme suit :

import langchain.chat_models import init_chat_model

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

Vous pouvez également configurer des clients spécifiquement. Par exemple, voyons AzureAIOpenAIApiChatModel comme un modèle représentatif :

import os

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

# Option A: Use a Foundry project endpoint (Microsoft Entra ID required).
model_from_project = AzureAIOpenAIApiChatModel(
  project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
  credential=DefaultAzureCredential(),
  model="gpt-5.2",
)

# Option B: Use a service endpoint directly.
model_from_endpoint = AzureAIOpenAIApiChatModel(
  endpoint=os.environ["OPENAI_BASE_URL"],
  credential=DefaultAzureCredential(),
  model="gpt-5.2",
)

# Option C: Use a different credential strategy.
model_with_cli_credential = AzureAIOpenAIApiChatModel(
  endpoint=os.environ["OPENAI_BASE_URL"],
  credential="super-secret",
  model="gpt-5.2",
)

Ce que fait cet extrait de code : Affiche le même modèle initialisé à partir d’un point de terminaison de projet Foundry ou d’un point de terminaison de service direct et montre comment échanger des informations d’identification.

Vous pouvez appliquer le même modèle aux outils. Par exemple, lorsque AZURE_AI_PROJECT_ENDPOINT est défini, vous pouvez utiliser le point de terminaison du projet AzureAIDocumentIntelligenceTool et DefaultAzureCredential sans configuration supplémentaire.

from langchain_azure_ai.tools import AzureAIDocumentIntelligenceTool

document_tool = AzureAIDocumentIntelligenceTool()

Comment DefaultAzureCredential fonctionne

DefaultAzureCredential tente plusieurs sources d'informations d'identification Microsoft Entra ID dans l'ordre et utilise la première qui fonctionne. Les sources courantes sont des variables d’environnement, une identité managée, des outils de développement et des Azure CLI.

Utilisez DefaultAzureCredential comme valeur par défaut pour le développement local et les charges de travail déployées. Si vous avez besoin d’un contrôle plus strict, remplacez-le par des informations d’identification spécifiques telles que AzureCliCredential pour le développement local uniquement ou ManagedIdentityCredential pour les charges de travail de production dans Azure.

Le même modèle de point de terminaison de projet est également utilisé par d’autres classes.

Découvrir chaque fonctionnalité en détail

Commencez par les guides suivants dans cet ensemble de documentation :

Utilisez ces ressources de package pour obtenir des détails et des mises à jour au niveau du module :

Étape suivante

Utiliser des modèles Foundry avec LangChain

  • Last updated on