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) Azure AI Foundry

Dans ce tutoriel, vous utilisez le Kit de développement logiciel (SDK) Azure AI Foundry (et d’autres bibliothèques) pour créer, configurer et évaluer une application de conversation pour votre entreprise de vente au détail appelée Contoso Trek. Votre entreprise de vente au détail se spécialise dans l’équipement de camping extérieur et les vêtements. L’application de conversation doit répondre à des questions sur vos produits et services. Par exemple, l’application de conversation peut répondre à des questions comme « quelle tente est la plus étanche ? » ou « quel est le meilleur sac de couchage par temps froid ? ».

Il s’agit de la première partie d’un tutoriel qui en compte trois. Cette partie 1 vous permet d’écrire du code dans la deuxième partie et d’évaluer votre application de conversation dans la troisième partie. Dans cette partie, vous :

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

Si vous avez suivi d’autres tutoriels ou guides de démarrage rapide, vous avez peut-être déjà créé certaines des ressources nécessaires à ce tutoriel. Si tel est le cas, vous pouvez ignorer les étapes présentées ici.

Il s’agit de la première partie d’un tutoriel qui en compte trois.

Important

Les éléments marqués (préversion) dans cet article sont actuellement en préversion publique. Cette préversion est fournie sans contrat de niveau de service, nous la déconseillons dans des charges de travail de production. Certaines fonctionnalités peuvent être limitées ou non prises en charge. Pour plus d’informations, consultez Conditions d’Utilisation Supplémentaires relatives aux Évaluations Microsoft Azure.

Prérequis

• Compte Azure avec un abonnement actif. Si vous n’en avez pas un, créez un compte gratuitement.

Créer un projet

Pour créer un projet dans Azure AI Foundry, procédez comme suit :

1. Accédez à la page Accueil d’Azure AI Foundry.
2. Sélectionnez + Créer un projet.
3. Entrez un nom pour le projet. Conservez tous les autres paramètres par défaut.
4. Les projets sont créés dans des hubs. Si vous voyez Créer un nouveau hub, sélectionnez-le et spécifiez un nom. Sélectionnez ensuite Suivant. (Si vous ne voyez pas Créer un nouveau hub, ne vous inquiétez pas ; c'est parce qu'un nouveau hub est en cours de création pour vous.)
5. Sélectionnez Personnaliser pour spécifier les propriétés du hub.
6. Utilisez toutes les valeurs souhaitées, à l’exception de Region. Nous vous recommandons d'utiliser East US2 ou Suède centrale comme région pour cette série de didacticiels.
7. Cliquez sur Suivant.
8. Sélectionnez Créer un projet.

Déployer des modèles

Vous avez besoin de deux modèles pour créer une application de conversation basée sur la Génération augmentée de récupération (RAG) : un modèle de conversation Azure OpenAI (gpt-4o-mini) et un modèle d’incorporation Azure OpenAI (text-embedding-ada-002). Déployez ces modèles dans votre projet Azure AI Foundry en utilisant cet ensemble de d’étapes pour chaque modèle.

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

1. Dans le volet de navigation de 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.

   

3. Dans la page détails du modèle, sélectionnez Déployer.

   

4. Laissez par défaut le nom de déploiement . 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 Recherche Azure AI

L’objectif de cette application est de fonder les réponses du modèle sur vos données personnalisées. L’index de recherche est utilisé pour récupérer des documents pertinents en fonction de la question de l’utilisateur.

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

Remarque

La création d’un service Azure AI Search et des index de recherche ultérieurs entraîne des coûts associés. Vous pouvez voir des détails sur la tarification et les niveaux tarifaires du service Recherche Azure AI sur la page de création, afin de confirmer le coût avant de créer la ressource. Pour ce didacticiel, nous vous recommandons d’utiliser un niveau tarifaire Essentiel ou supérieur.

Si vous disposez déjà d’un service Recherche Azure AI, vous pouvez passer à la section suivante.

Sinon, vous pouvez créer un service Recherche Azure AI à l’aide du Portail Azure.

Conseil

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

1. Créez un service Recherche Azure AI sur le Portail Azure.
2. Sélectionnez les détails de votre groupe de ressources et de votre instance. Vous pouvez voir des détails sur la tarification et les niveaux tarifaires sur cette page.
3. Continuez avec l’Assistant et sélectionnez Vérifier + affecter pour créer la ressource.
4. Vérifiez les détails de votre service Recherche Azure AI, y compris le coût estimé.
5. Sélectionnez Créer pour créer le service Recherche Azure AI.

Connecter le service Recherche Azure AI à votre projet

Si vous disposez déjà d’une connexion Azure AI Search dans votre projet, vous pouvez ignorer l’installation Azure CLI et vous connecter.

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

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

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

3. Si vous disposez d’une connexion Azure AI Search, vous pouvez passer à la section suivante.

4. Sinon, sélectionnez Nouvelle connexion, puis Recherche Azure AI.

5. Recherchez votre service Recherche Azure AI 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. Pour sélectionner et utiliser l’option d’authentification Microsoft Entra ID recommandée, vous devez également configurer le contrôle d’accès pour le service Recherche Azure AI. Attribuez à votre compte d’utilisateur les rôles Contributeur aux données d’index de recherche et Contributeur au service de recherche. Pour plus d’informations, consultez Se connecter à Recherche Azure AI à l’aide de rôles et contrôle d’accès en fonction du rôle dans le portail Azure AI Foundry.

7. Sélectionnez Ajouter une connexion.

Installer Azure CLI et se connecter

Vous installez l'interface Azure CLI et vous vous connectez depuis votre environnement de développement local, afin de pouvoir utiliser vos informations d'identification pour appeler le service Azure OpenAI.

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

Windows

winget install -e --id Microsoft.AzureCLI

Linux

curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

macOS

brew update && brew install azure-cli

Vous pouvez suivre les instructions Comment installer l’interface de ligne de commande Azure si ces commandes ne fonctionnent pas pour votre système d’exploitation ou configuration particulier.

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

az login

Alternativement, vous pouvez vous connecter manuellement via le navigateur avec un code d'appareil.

az login --use-device-code

Créer un environnement Python

Tout d’abord, vous devez créer un environnement Python à utiliser pour installer le package dont vous avez besoin pour ce didacticiel. N’installez pas de packages dans votre installation globale de Python. Vous devez toujours utiliser 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

Nous vous recommandons d’utiliser Python 3.10 ou version ultérieure, mais l’utilisation d’au moins Python 3.8 est requise. Si vous n’avez pas installé une version appropriée de Python, vous pouvez suivre les instructions du didacticiel Python VS Code pour le moyen le plus simple d’installer Python sur votre système d’exploitation.

Créer un environnement virtuel

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

Windows

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

Linux

python3 -m venv .venv
source .venv/bin/activate

macOS

python3 -m venv .venv
source .venv/bin/activate

L'activation de l'environnement Python signifie que lorsque vous exécutez python ou pip depuis la ligne de commande, vous utilisez alors l'interpréteur Python contenu dans le dossier .venv de votre application.

Remarque

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

Installer des packages

Installez azure-ai-projects(préversion) et azure-ai-inference (préversion), ainsi que d’autres packages requis.

1. Tout d’abord, créez un fichier nommé requirements.txt dans votre dossier de projet. Ajoutez les packages suivants au fichier :

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

2. Installez les packages nécessaires :

   pip install -r requirements.txt
   

Créer un script d’assistance

Créez un dossier pour votre travail. Créez un fichier appelé config.py dans ce dossier. Ce script d’assistance est utilisé dans les deux parties suivantes de la série de tutoriels. 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)

Configuration des variables d’environnement

Votre chaîne de connexion de projet est requise pour appeler le service Azure OpenAI à 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 Azure AI Foundry que vous avez créé dans le guide de démarrage rapide sur le terrain de jeu Azure AI Foundry. Ouvrez le projet, puis recherchez la chaîne de connexion dans la page vue d’ensemble Vue d’ensemble. Copiez la chaîne de connexion et collez-la dans le fichier .env.

  

• 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

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.

Nettoyer les ressources

Pour éviter la facturation de coûts Azure inutiles, vous devez supprimer les ressources créées dans ce tutoriel si elles ne sont plus nécessaires. Pour gérer les ressources, vous pouvez utiliser le Portail Microsoft Azure.

Mais ne les supprimez pas encore si vous souhaitez créer une application de conversation dans la partie suivante 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 Kit de développement logiciel (SDK) Azure AI. Dans la partie suivante de cette série de tutoriels, vous générez l’application personnalisée.

Partie 2 : Créer une application de conversation personnalisée avec le Kit de développement logiciel (SDK) Azure AI