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

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 :

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.

Conditions préalables

• Un compte Azure avec un abonnement actif et un rôle Propriétaire ou Contributeur attribué. Si vous n’en avez pas, 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 basé sur le 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’avez pas de projets existants : suivez les étapes du Démarrage rapide : Prise en main de Microsoft Foundry pour créer votre premier projet.

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

     

   • Si vous n’êtes pas dans un projet : sélectionnez Créer dans le haut à droite pour créer un projet Foundry

     

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.

     

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 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 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 :

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.

   

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 Recherche Azure AI

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.

Si vous disposez déjà d’un service Recherche d’IA Azure, accédez à la section suivante.

Sinon, créez un service Recherche d’IA Azure à l’aide du portail Azure.

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. 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 Recherche d’IA Azure, 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 votre projet dispose déjà d’une connexion Azure AI Search, accédez à Installer 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 Recherche Azure AI.

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

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. L’approche recommandée est l’authentification d’ID Microsoft Entra , qui nécessite les rôles Contributeur aux données d’index de recherche et Contributeur de service de recherche (configurés dans les conditions préalables). Pour plus d’informations, consultez Se connecter à la Recherche Azure AI à 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 de 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 requis. Si vous n’avez pas installé une version appropriée de Python, suivez 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 version ultérieure est déjà installé, créez un environnement virtuel à l’aide des commandes suivantes :

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

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

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

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

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 : bibliothèque cliente Azure AI Projects, azure-ai-inference, python-dotenv.

2. Installez les packages nécessaires :

   pip install -r requirements.txt
   

Configurer les variables d’environnement

Votre chaîne de connexion de projet est requise pour appeler Azure OpenAI dans Microsoft Foundry Models à 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 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.

Installer Azure CLI et se connecter

Vous installez l’interface 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 Modèles Microsoft Foundry.

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

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

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

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és.

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.

Nettoyer les ressources

Pour éviter d’entraîner des coûts 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 Microsoft 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 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.