Démarrage rapide : Recherche générative (RAG) avec des données de fondement à partir de Recherche Azure AI

Article
09/26/2024

Ce guide de démarrage rapide montre comment envoyer des requêtes à un modèle de langage volumineux (LLM) pour une expérience de recherche conversationnelle sur votre contenu indexé sur Recherche Azure AI. Vous utilisez le portail Azure pour configurer les ressources, puis exécutez du code Python pour appeler les API.

Prérequis

Un abonnement Azure. Créez-en un gratuitement.
Recherche Azure AI, niveau Essentiel ou supérieur pour pouvoir activer le classeur sémantique. La région doit être la même que celle utilisée pour Azure OpenAI.
Ressource Azure OpenAI avec un déploiement de gpt-35-turbo, gpt-4 ou modèle équivalent, dans la même région que Recherche Azure AI.
Visual Studio Code avec l’extension Python et le package Jupyter. Pour plus d’informations, consultez Python dans Visual Studio Code.

Télécharger un fichier

Téléchargez un notebook Jupyter à partir de GitHub pour envoyer les requêtes mentionnées dans ce guide de démarrage rapide. Si vous souhaitez obtenir plus d’informations, consultez Téléchargement de fichiers à partir de GitHub.

Vous pouvez également démarrer un nouveau fichier sur votre système local et créer des requêtes manuellement en tirant parti des instructions contenues dans cet article.

Configurer l’accès

Les demandes effectuées au point de terminaison de recherche doivent être authentifiées et autorisées. Vous pouvez utiliser des clés d’API ou des rôles pour cette tâche. Les clés sont plus faciles à utiliser, mais les rôles sont plus sécurisés. Ce guide de démarrage rapide part du principe que vous disposez de certains rôles.

Vous configurez deux clients. Vous avez donc besoin d’autorisations pour les deux ressources.

La Recherche Azure AI reçoit la demande de requête de votre système local. Attribuez-vous le rôle de Lecteur de données d’index de recherche pour cette tâche. Si vous créez et chargez également l’index d’échantillon d’hôtel, ajoutez également les rôles de Contributeur du service de recherche et Contributeur de données d’index de recherche.

Azure OpenAI reçoit la (requête) « Peux-tu recommander quelques hôtels » à partir de votre système local, ainsi que sa réception des résultats de recherche (source) du service de recherche. Attribuez-vous et au service de recherche le rôle d’Utilisateur OpenAI Cognitive Services.

Connectez-vous au portail Azure.
Configurez la Recherche Azure AI pour utiliser une identité managée affectée par le système afin de pouvoir lui attribuer des rôles :
1. Dans le portail Azure, recherchez votre service de recherche.
2. Dans le menu de gauche, sélectionnez Paramètres>Identité.
3. Sous l’onglet Attribuée par le système, définissez l’état sur Activé.
Configurez Recherche Azure AI pour l’accès en fonction du rôle :
1. Dans le portail Azure, recherchez votre service Recherche Azure AI.
2. Dans le menu de gauche, sélectionnez Paramètres>Clés, puis sélectionnez Contrôle d’accès en fonction du rôle ou Les deux.
Attribuer des rôles :
1. Dans le menu de gauche, sélectionnez Contrôle d’accès (IAM).
2. Pour Recherche Azure AI, vérifiez que vous disposez des autorisations nécessaires pour créer, charger et interroger un index de recherche :
  - Lecteur de données d’index de la Recherche
  - Contributeur de données d’index de la Recherche
  - Contributeur du service de recherche
3. Pour Azure OpenAI, sélectionnez Contrôle d’accès (IAM) pour vous affecter à vous-même et à l’identité de service de recherche les autorisations sur Azure OpenAI. Le code de ce démarrage rapide s’exécute localement. Les demandes adressées à Azure OpenAI proviennent de votre système. En outre, les résultats de recherche du moteur de recherche sont passés à Azure OpenAI. Pour ces raisons, vous et le service de recherche avez besoin d’autorisations sur Azure OpenAI.
  - Utilisateur OpenAI Cognitive Services

La prise en compte des autorisations peut prendre plusieurs minutes.

Création d'un index

Nous vous recommandons d’utiliser hotels-sample-index, qui peut être créé en quelques minutes et s’exécute sur n’importe quel niveau de service de recherche. Cet index est créé à l’aide d’exemples de données intégrés.

Dans le portail Azure, recherchez votre service de recherche.
Dans la page d’accueil Vue d’ensemble, sélectionnez Importer des données pour démarrer l’Assistant.
Dans la page Connexion à vos données, sélectionnez Exemples dans la liste déroulante.
Choisissez hotels-sample.
Sélectionnez Suivant dans les pages restantes, en acceptant les valeurs par défaut.
Une fois l’index créé, sélectionnez Gestion de la recherche> Index dans le menu de gauche pour ouvrir l’index.
Sélectionnez Modifier le fichier JSON.

Recherchez « semantic » pour accéder à la section dans l’index pour une configuration sémantique. Remplacez la ligne "semantic": {} vide par la configuration sémantique suivante. Cet exemple spécifie un "defaultConfiguration", qui est important pour l’exécution de ce guide de démarrage rapide.

"semantic":{
   "defaultConfiguration":"semantic-config",
   "configurations":[
      {
         "name":"semantic-config",
         "prioritizedFields":{
            "titleField":{
               "fieldName":"HotelName"
            },
            "prioritizedContentFields":[
               {
                  "fieldName":"Description"
               }
            ],
            "prioritizedKeywordsFields":[
               {
                  "fieldName":"Category"
               },
               {
                  "fieldName":"Tags"
               }
            ]
         }
      }
   ]
},

Enregistrez les changements apportés.

Exécutez la requête suivante dans l’Explorateur de recherche pour tester votre index : hotels near the ocean with beach access and good views.

Vous devez obtenir un résultat semblable à l’exemple qui suit. Les résultats retournés directement à partir du moteur de recherche se composent de champs et de leurs valeurs détaillées, ainsi que des métadonnées telles qu’un score de recherche et une note de classement sémantique et une légende si vous utilisez le classeur sémantique.

   "@search.score": 5.600783,
   "@search.rerankerScore": 2.4191176891326904,
   "@search.captions": [
     {
       "text": "Contoso Ocean Motel. Budget. pool\r\nair conditioning\r\nbar. Oceanfront hotel overlooking the beach features rooms with a private balcony and 2 indoor and outdoor pools. Various shops and art entertainment are on the boardwalk, just steps away..",
       "highlights": "Contoso Ocean Motel. Budget.<em> pool\r\nair conditioning\r\nbar. O</em>ceanfront hotel overlooking the beach features rooms with a private balcony and 2 indoor and outdoor pools. Various shops and art entertainment are on the boardwalk, just steps away."
     }
   ],
   "HotelId": "41",
   "HotelName": "Contoso Ocean Motel",
   "Description": "Oceanfront hotel overlooking the beach features rooms with a private balcony and 2 indoor and outdoor pools. Various shops and art entertainment are on the boardwalk, just steps away.",
   "Category": "Budget",
   "Tags": [
     "pool",
     "air conditioning",
     "bar"
   ],

Obtenir des points de terminaison de service

Dans les sections restantes, vous configurez des appels d’API vers Azure OpenAI et Recherche Azure AI. Obtenez les points de terminaison de service pour pouvoir les fournir en tant que variables dans votre code.

Connectez-vous au portail Azure.
Rechercher votre service de recherche.
Dans la page d’accueil Vue d’ensemble, copiez l’URL. Voici un exemple de point de terminaison : https://example.search.windows.net.
Recherchez votre service Azure OpenAI.
Dans la page d’accueil Vue d’ensemble, sélectionnez le lien pour afficher les points de terminaison. Copiez l’URL. Voici un exemple de point de terminaison : https://example.openai.azure.com/.

Configurer la requête et le thread de conversation

Cette section utilise Visual Studio Code et Python pour appeler les API de conversation complètes sur Azure OpenAI.

Démarrez Visual Studio Code et ouvrez le fichier .ipynb ou créez un fichier Python.

Installez les packages Python suivants.

! pip install azure-search-documents==11.6.0b4 --quiet
! pip install azure-identity==1.16.0 --quiet
! pip install openai --quiet
! pip intall aiohttp --quiet

Définissez les variables suivantes, en remplaçant les espaces réservés par les points de terminaison que vous avez collectés à l’étape précédente.

 AZURE_SEARCH_SERVICE: str = "PUT YOUR SEARCH SERVICE ENDPOINT HERE"
 AZURE_OPENAI_ACCOUNT: str = "PUT YOUR AZURE OPENAI ENDPOINT HERE"
 AZURE_DEPLOYMENT_MODEL: str = "gpt-35-turbo"

Exécutez le code suivant pour définir les paramètres de la requête. La requête est une recherche par mot clé utilisant le classement sémantique. Lors d’une recherche par mot clé, le moteur de recherche renvoie jusqu’à 50 correspondances, mais seules les 5 premières sont fournies au modèle. Si vous ne pouvez pas [activer le classeur sémantique semantic-how-to-enable-disable.md) sur votre service de recherche, définissez la valeur sur false.
```
# Set query parameters for grounding the conversation on your search index
 search_type="text"
 use_semantic_reranker=True
 sources_to_include=5
```

Configurez les clients, l’invite, la requête et la réponse.

# Set up the query for generating responses
 from azure.identity import DefaultAzureCredential
 from azure.identity import get_bearer_token_provider
 from azure.search.documents import SearchClient
 from openai import AzureOpenAI

 credential = DefaultAzureCredential()
 token_provider = get_bearer_token_provider(credential, "https://cognitiveservices.azure.com/.default")
 openai_client = AzureOpenAI(
     api_version="2024-06-01",
     azure_endpoint=AZURE_OPENAI_ACCOUNT,
     azure_ad_token_provider=token_provider
 )

 search_client = SearchClient(
     endpoint=AZURE_SEARCH_SERVICE,
     index_name="hotels-sample-index",
     credential=credential
 )

 # This prompt provides instructions to the model
 GROUNDED_PROMPT="""
 You are a friendly assistant that recommends hotels based on activities and amenities.
 Answer the query using only the sources provided below in a friendly and concise bulleted manner.
 Answer ONLY with the facts listed in the list of sources below.
 If there isn't enough information below, say you don't know.
 Do not generate answers that don't use the sources below.
 Query: {query}
 Sources:\n{sources}
 """

 # Query is the question being asked. It's sent to the search engine and the LLM.
 query="Can you recommend a few hotels near the ocean with beach access and good views"

 # Set up the search results and the chat thread.
 # Retrieve the selected fields from the search index related to the question.
 search_results = search_client.search(
     search_text=query,
     top=5,
     select="Description,HotelName,Tags"
 )
 sources_formatted = "\n".join([f'{document["HotelName"]}:{document["Description"]}:{document["Tags"]}' for document in search_results])

 response = openai_client.chat.completions.create(
     messages=[
         {
             "role": "user",
             "content": GROUNDED_PROMPT.format(query=query, sources=sources_formatted)
         }
     ],
     model=AZURE_DEPLOYMENT_MODEL
 )

 print(response.choices[0].message.content)

Le résultat provient d’Azure OpenAI et se compose de recommandations pour plusieurs hôtels. Voici un exemple de ce à quoi la sortie peut ressembler :

Based on your criteria, we recommend the following hotels:

- Contoso Ocean Motel: located right on the beach and has private balconies with ocean views. They also have indoor and outdoor pools. It's located on the boardwalk near shops and art entertainment.
- Northwind Plaza & Suites: offers ocean views, free Wi-Fi, full kitchen, and a free breakfast buffet. Although not directly on the beach, this hotel has great views and is near the aquarium. They also have a pool.

Several other hotels have views and water features, but do not offer beach access or views of the ocean.

Si vous recevez un message d’erreur Interdit, vérifiez la configuration de Recherche Azure AI pour vous assurer que l’accès en fonction du rôle est activé.

Si vous recevez un message d’erreur Autorisation échouée, patientez quelques minutes, puis réessayez. Plusieurs minutes peuvent être nécessaires avant que les attributions de rôles soient opérationnelles.

Si vous souhaitez expérimenter davantage, modifiez la requête et exécutez à nouveau la dernière étape afin de mieux comprendre comment le modèle fonctionne avec les données de base.

Vous pouvez également modifier l’invite pour modifier le ton ou la structure du résultat.

Vous pouvez également essayer la requête sans classement sémantique en définissant use_semantic_reranker=False à l’étape des paramètres de requête. Le classement sémantique ne peut pas améliorer de manière significative la pertinence des résultats de requête et la capacité du LLM à retourner des informations utiles. L’expérimentation peut vous aider évaluer son utilité pour votre contenu.

Résolution des erreurs

Pour déboguer les erreurs d’authentification, insérez le code suivant avant l’étape qui appelle le moteur de recherche et le LLM.

import sys
import logging # Set the logging level for all azure-storage-* libraries
logger = logging.getLogger('azure.identity') 
logger.setLevel(logging.DEBUG)

handler = logging.StreamHandler(stream=sys.stdout)
formatter = logging.Formatter('[%(levelname)s %(name)s] %(message)s')
handler.setFormatter(formatter)
logger.addHandler(handler)

Réexécutez le script de requête. Vous devez maintenant obtenir des instructions INFO et DEBUG dans la sortie, qui fournissent plus de détails sur le problème.

Si vous voyez des messages de sortie liés à ManagedIdentityCredential et des échecs d’acquisition de jetons, vous avez peut-être plusieurs locataires et votre connexion Azure utilise un locataire qui ne dispose pas de votre service de recherche. Pour obtenir votre ID de locataire, recherchez « Propriétés du locataire » sur le Portail Azure ou exécutez az login tenant list.

Une fois que vous avez votre ID de locataire, exécutez az login --tenant <YOUR-TENANT-ID> dans une invite de commande, puis réexécutez le script.

Nettoyer

Lorsque vous travaillez dans votre propre abonnement, il est recommandé, à la fin de chaque projet, de déterminer si vous avez toujours besoin des ressources que vous avez créées. Les ressources laissées en cours d’exécution peuvent vous coûter de l’argent. Vous pouvez supprimer les ressources une par une ou supprimer le groupe de ressources.

Vous pouvez rechercher et gérer des ressources dans le portail en tirant parti des liens Toutes les ressources ou Groupes de ressources situés dans le volet le plus à gauche.

Voir aussi

Tutoriel : Comment créer une solution RAG dans Recherche Azure AI

Partager via