Partage via

Tutoriel : Partie 1 - Configurer un environnement de développement et de projet pour créer une application de récupération des connaissances personnalisées (RAG) avec le Kit de développement logiciel (SDK) Microsoft Foundry (classique)

S'applique uniquement à :Portail Foundry (classique). Cet article n’est pas disponible pour le nouveau portail Foundry. En savoir plus sur le nouveau portail.

Note

Certains liens de cet article peuvent ouvrir du contenu dans la nouvelle documentation Microsoft Foundry au lieu de la documentation Foundry (classique) que vous affichez maintenant.

Dans ce tutoriel, vous allez configurer les ressources nécessaires pour créer une application de conversation de récupération des connaissances personnalisées (RAG) avec le Kit de développement logiciel (SDK) Microsoft Foundry. Il s’agit de la première partie d’une série de tutoriels en trois parties. Vous créez les ressources ici, générez l’application dans la deuxième partie et évaluez-la dans la troisième partie. Dans cette partie, vous :

  • Création d’un projet
  • Créer un index Azure AI Search
  • Installer le Azure CLI et se connecter
  • Installer Python et packages
  • Déployer des modèles dans votre projet
  • Configurer vos variables d’environnement

Si vous avez terminé d’autres didacticiels ou guides de démarrage rapide, vous avez peut-être déjà créé certaines des ressources nécessaires pour ce didacticiel. Si vous l’avez fait, n’hésitez pas à ignorer ces étapes.

Prerequisites

Important

Cet article fournit une prise en charge pour les versions antérieures des projets basés sur le hub. Elle ne fonctionnera pas pour les projets Foundry. Découvrez comment savoir quel type de projet j’ai ?

Remarque de compatibilité du Kit de développement logiciel (SDK) : les exemples de code nécessitent une version spécifique du Kit de développement logiciel (SDK) Microsoft Foundry. Si vous rencontrez des problèmes de compatibilité, envisagez de migrer d’un hub vers un projet Foundry.

  • Un compte Azure avec un abonnement actif et le rôle Owner ou Contributor assigné. Si vous n’en avez pas un, créez un compte gratuitement.
  • Microsoft Foundry : rôle Propriétaire ou Contributeur pour créer un projet.

Créer un projet hub

Pour créer un projet hub dans Microsoft Foundry, procédez comme suit :

  1. Connectez-vous à Microsoft Foundry. Assurez-vous que l'interrupteur New Foundry est désactivé. Ces étapes font référence à Foundry (classique).

  2. Ce que vous faites ensuite dépend de l’endroit où vous êtes :

    • Si vous n’êtes pas dans un projet ou si vous n’avez pas encore de projets : sélectionnez Créer dans la partie supérieure droite pour créer un projet Foundry

      Capture d’écran montrant comment créer un projet dans Foundry.

    • Si vous êtes dans un projet : sélectionnez la barre de navigation du projet, puis sélectionnez Créer une ressource.

      Capture d’écran montrant la création d’un projet à partir d’une barre de navigation.

  3. Sélectionnez la ressource du hub IA, puis sélectionnez Suivant.

  4. Entrez un nom pour le projet.

  5. Si vous avez un hub, vous verrez celui que vous avez utilisé le plus récemment.

    • Si vous avez accès à plusieurs hubs, vous pouvez sélectionner un autre hub dans la liste déroulante.

    • Si vous souhaitez en créer un, sélectionnez Créer un hub dans la liste déroulante.

      Capture d’écran de la page de détails du projet dans la boîte de dialogue Créer un projet.

  6. Si vous n’avez pas de hub, un hub par défaut est créé pour vous.

  7. Cliquez sur Créer.

Déployer des modèles

Vous avez besoin de deux modèles pour créer une application de conversation basée sur RAG : un modèle de conversation OpenAI Azure (gpt-4o-mini) et un modèle d’incorporation OpenAI Azure (text-embedding-ada-002). Déployez ces modèles dans votre projet Foundry à l’aide de cet ensemble d’étapes pour chaque modèle.

Ces étapes déploient un modèle sur un point de terminaison en temps réel à partir du catalogue de modèles du portail Foundry :

Conseil / Astuce

Étant donné que vous pouvez personnaliser le volet gauche dans le portail Microsoft Foundry, vous pouvez voir différents éléments que ceux indiqués dans ces étapes. Si vous ne voyez pas ce que vous recherchez, sélectionnez ... Plus en bas du volet gauche.

  1. Dans le volet gauche, sélectionnez Catalogue de modèles.

  2. Sélectionnez le modèle gpt-4o-mini dans la liste des modèles. Vous pouvez utiliser la barre de recherche pour la trouver.

    Capture d’écran de la page de sélection du modèle.

  3. Dans la page détails du modèle, sélectionnez Utiliser ce modèle.

  4. Laissez le nom de déploiement par défaut, puis sélectionnez Déployer. Ou, si le modèle n'est pas disponible dans votre région, une autre région est sélectionnée pour vous et connectée à votre projet. Dans ce cas, sélectionnez Connecter et déployer.

Après avoir déployé le gpt-4o-mini, répétez les étapes pour déployer le modèle text-embedding-ada-002.

Créer un service Azure AI Search

L’objectif de cette application est de baser les réponses du modèle dans vos données personnalisées. L’index de recherche récupère les documents pertinents en fonction de la question de l’utilisateur.

Vous avez besoin d’un service Azure AI Search et d’une connexion pour créer un index de recherche.

Note

La création d’un service Azure AI Search et les index de recherche suivants entraînent des coûts. Pour confirmer les coûts avant de créer la ressource, vérifiez la tarification et les niveaux de tarification du service Azure AI Search sur la page de création de la ressource. Pour ce tutoriel, utilisez un niveau tarifaire de base ou supérieur.

Si vous disposez déjà d’un service Azure AI Search, accédez à la section next.

Sinon, créez un service Azure AI Search à l’aide du portail Azure.

Conseil / Astuce

Cette étape est la seule fois que vous utilisez le portail Azure dans cette série de tutoriels. Vous effectuez le reste de votre travail dans le portail Foundry ou dans votre environnement de développement local.

  1. Créer un service Azure AI Search dans le portail Azure.
  2. Sélectionnez les détails de votre groupe de ressources et de votre instance. Consultez les prix et les niveaux de tarification de cette page. Pour ce tutoriel, utilisez un niveau tarifaire de base ou supérieur.
  3. Continuez avec l'Assistant de configuration et sélectionnez Vérifier + affecter pour créer une ressource.
  4. Vérifiez les détails de votre service de Azure AI Search, y compris le coût estimé.
  5. Sélectionnez Create pour créer le service Azure AI Search.

Connecter le Azure AI Search à votre projet

Si votre projet dispose déjà d’une connexion Azure AI Search, accédez à Installez l’Azure CLI et connectez-vous.

Dans le portail Foundry, recherchez une ressource connectée Azure AI Search.

  1. Dans Foundry, accédez à votre projet et sélectionnez Centre de gestion dans le volet gauche.

  2. Dans la section Ressources connectées, recherchez si vous avez une connexion de type Azure AI Search.

  3. Si vous avez une connexion Azure AI Search, vous pouvez ignorer les étapes suivantes.

  4. Sinon, sélectionnez New connection puis Azure AI Search.

  5. Recherchez votre service Azure AI Search dans les options et sélectionnez Ajouter une connexion.

  6. Utilisez laclé API pour l’Authentification.

    Important

    L’option clé API n’est pas recommandée pour la production. L’approche recommandée est l’authentification Microsoft Entra ID, qui nécessite les rôles Search Index Data Contributor et Search Service Contributor (configurés dans les prérequis). Pour plus d’informations, consultez Connexion à Azure AI Search à l'aide des rôles. Pour ce didacticiel, la clé API est acceptable si vous souhaitez continuer rapidement. Basculez vers Entra ID avant de déployer en production.

  7. Sélectionnez Ajouter une connexion.

Créer un environnement Python

Dans l’IDE de votre choix, créez un dossier pour votre projet. Ouvrez une fenêtre de terminal dans ce dossier.

Tout d’abord, créez un environnement Python. N'installez pas de packages dans votre installation globale Python. Utilisez toujours un environnement virtuel ou conda lors de l’installation de packages Python. Sinon, vous pouvez interrompre votre installation globale de Python.

Si nécessaire, installez Python

Utilisez Python 3.10 ou version ultérieure, mais au moins Python 3.9 est nécessaire. Si vous n'avez pas installé une version adaptée de Python, suivez les instructions du didacticiel Python de VS Code pour installer Python facilement sur votre système d'exploitation.

Créer un environnement virtuel

Si vous avez déjà installé Python 3.10 ou version ultérieure, créez un environnement virtuel à l’aide des commandes suivantes :

py -3 -m venv .venv
.venv\scripts\activate

Lorsque vous activez l’environnement Python, l’exécution de python ou pip à partir de la ligne de commande utilise l’interpréteur Python dans le dossier .venv de votre application.

Note

Utilisez la commande deactivate pour quitter l’environnement virtuel Python. Vous pouvez la réactiver ultérieurement si nécessaire.

Installer des packages

Installez les packages requis.

  1. Créez un fichier nommé requirements.txt dans votre dossier de projet. Ajoutez les packages suivants au fichier :

    azure-ai-projects==1.0.0b10
azure-ai-inference[prompts]
azure-identity
azure-search-documents
pandas
python-dotenv
opentelemetry-api

    Références : Azure bibliothèque cliente AI Projects, azure-ai-inference, python-dotenv.

  2. Installez les packages nécessaires :

    pip install -r requirements.txt

Configurer les variables d’environnement

La chaîne de connexion de votre projet est nécessaire pour appeler Azure OpenAI dans les modèles Microsoft Foundry à partir de votre code. Dans ce guide de démarrage rapide, vous enregistrez cette valeur dans un fichier .env, qui est un fichier qui contient des variables d’environnement que votre application peut lire.

Créez un fichier .env et collez le code suivant :

AIPROJECT_CONNECTION_STRING=<your-connection-string>
AISEARCH_INDEX_NAME="example-index"
EMBEDDINGS_MODEL="text-embedding-ada-002"
INTENT_MAPPING_MODEL="gpt-4o-mini"
CHAT_MODEL="gpt-4o-mini"
EVALUATION_MODEL="gpt-4o-mini"

  • Recherchez votre chaîne de connexion dans le projet Foundry que vous avez créé dans le guide de démarrage rapide du terrain de jeu Foundry. Ouvrez le projet, puis recherchez la connection string sur la page Overview. Copiez le connection string et collez-le dans le fichier .env.

    Screenshot affiche la page vue d’ensemble d’un projet et l’emplacement de connection string.

  • Si vous n’avez pas encore d’index de recherche, conservez la valeur « example-index » pour AISEARCH_INDEX_NAME. Dans la partie 2 de ce didacticiel, vous allez créer l’index à l’aide de ce nom. Si vous avez créé un index de recherche que vous souhaitez utiliser à la place, mettez à jour la valeur pour qu’elle corresponde au nom de cet index de recherche.

  • Si vous avez modifié les noms des modèles lorsque vous les avez déployés, mettez à jour les valeurs dans le fichier .env pour qu’ils correspondent aux noms que vous avez utilisés.

Conseil / Astuce

Si vous travaillez dans VS Code, fermez et rouvrez la fenêtre de terminal une fois que vous avez enregistré les modifications apportées au fichier .env.

Avertissement

Vérifiez que votre .env se trouve dans votre fichier .gitignore afin de ne pas l’archiver accidentellement dans votre dépôt Git.

Installer le Azure CLI et se connecter

Vous installez le Azure CLI et connectez-vous à partir de votre environnement de développement local afin de pouvoir utiliser vos informations d’identification utilisateur pour appeler Azure OpenAI dans Microsoft Foundry Models.

Dans la plupart des cas, vous pouvez installer Azure CLI à partir de votre terminal à l’aide de la commande suivante :

winget install -e --id Microsoft.AzureCLI

Vous pouvez suivre les instructions Comment installer l'Azure CLI si ces commandes ne fonctionnent pas pour votre système d'exploitation ou configuration particulière.

Après avoir installé le Azure CLI, connectez-vous à l’aide de la commande az login et connectez-vous à l’aide du navigateur :

az login

Vous pouvez également vous connecter manuellement via le navigateur avec un code d’appareil.

az login --use-device-code

Laissez cette fenêtre de terminal ouverte pour exécuter vos scripts Python à partir d’ici, maintenant que vous vous êtes connecté.

Vérifier votre configuration

Vérifiez que votre environnement est configuré correctement en exécutant un test rapide :

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

# Check the SDK version
print(f"Azure AI Projects SDK version: {azure.ai.projects.__version__}")

# Test that you can connect to your project
project = AIProjectClient.from_connection_string(
    conn_str=os.environ["AIPROJECT_CONNECTION_STRING"], credential=DefaultAzureCredential()
)
print("✓ Setup verified! Ready to build your RAG app.")

Si vous voyez "Setup successful!", vos informations d’identification et sdk Azure sont correctement configurées.

Conseil / Astuce

Ce tutoriel nécessite le SDK Azure AI Projects version 1.0.0b10. La version du Kit de développement logiciel (SDK) affichée ci-dessus vous permet de vérifier la compatibilité. Si vous disposez d’une autre version, la from_connection_string() méthode n’est peut-être pas disponible. Pour installer la version requise, exécutez pip install azure-ai-projects==1.0.0b10.

Références : bibliothèque cliente Azure AI Projects, DefaultAzureCredential.

Créer un script d’assistance

Créez un dossier pour votre travail. Créez un fichier nommé config.py dans ce dossier. Vous allez utiliser ce script d’assistance dans les deux prochaines parties de la série de tutoriels. Le script charge vos variables d’environnement et initialise le client Azure AI Projects. Ajoutez le code suivant :

# ruff: noqa: ANN201, ANN001

import os
import sys
import pathlib
import logging
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.inference.tracing import AIInferenceInstrumentor

# load environment variables from the .env file
from dotenv import load_dotenv

load_dotenv()

# Set "./assets" as the path where assets are stored, resolving the absolute path:
ASSET_PATH = pathlib.Path(__file__).parent.resolve() / "assets"

# Configure an root app logger that prints info level logs to stdout
logger = logging.getLogger("app")
logger.setLevel(logging.INFO)
logger.addHandler(logging.StreamHandler(stream=sys.stdout))


# Returns a module-specific logger, inheriting from the root app logger
def get_logger(module_name):
    return logging.getLogger(f"app.{module_name}")


# Enable instrumentation and logging of telemetry to the project
def enable_telemetry(log_to_project: bool = False):
    AIInferenceInstrumentor().instrument()

    # enable logging message contents
    os.environ["AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED"] = "true"

    if log_to_project:
        from azure.monitor.opentelemetry import configure_azure_monitor

        project = AIProjectClient.from_connection_string(
            conn_str=os.environ["AIPROJECT_CONNECTION_STRING"], credential=DefaultAzureCredential()
        )
        tracing_link = f"https://ai.azure.com/tracing?wsid=/subscriptions/{project.scope['subscription_id']}/resourceGroups/{project.scope['resource_group_name']}/providers/Microsoft.MachineLearningServices/workspaces/{project.scope['project_name']}"
        application_insights_connection_string = project.telemetry.get_connection_string()
        if not application_insights_connection_string:
            logger.warning(
                "No application insights configured, telemetry will not be logged to project. Add application insights at:"
            )
            logger.warning(tracing_link)

            return

        configure_azure_monitor(connection_string=application_insights_connection_string)
        logger.info("Enabled telemetry logging to project, view traces at:")
        logger.info(tracing_link)

Références : AIProjectClient, DefaultAzureCredential, load_dotenv.

Note

Ce script utilise également un package que vous n’avez pas encore installé, azure.monitor.opentelemetry. Vous installerez ce package dans la prochaine partie de la série de tutoriels.

Nettoyer les ressources

Pour éviter d'entraîner des coûts de Azure inutiles, supprimez les ressources que vous avez créées dans ce didacticiel si elles ne sont plus nécessaires. Pour gérer les ressources, vous pouvez utiliser le portail Azure.

Mais ne les supprimez pas encore si vous souhaitez créer une application de conversation dans la prochaine partie de cette série de tutoriels.

Étape suivante

Dans ce tutoriel, vous allez configurer tout ce dont vous avez besoin pour créer une application de conversation personnalisée avec le sdk Azure AI. Dans la partie suivante de cette série de tutoriels, vous générez l’application personnalisée.

Part 2 : Créer une application de conversation personnalisée avec le SDK d’ia Azure

  • Last updated on