Démarrage rapide : Recherche générative (RAG) - Azure AI Search

Prérequis

Un compte Azure avec un abonnement actif. Créez un compte gratuitement.
Ressource Azure OpenAI.
- Choisissez une région qui prend en charge le modèle d’achèvement de conversation que vous souhaitez utiliser (gpt-4o, gpt-4o-mini ou un modèle équivalent).
- Déployez le modèle de complétion de conversation dans Azure AI Foundry ou utilisez une autre approche.
Ressource de recherche Azure AI.
- Nous vous recommandons d’utiliser le niveau De base ou supérieur.
- Activez le classement sémantique.
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 l’attribution de rôle Lecteur de données de l’index de recherche si l’exemple d’index des hôtels existe déjà. S’il n’existe pas, attribuez-vous les rôles Contributeur service Search et Contributeur de données d’index de recherche afin de pouvoir créer et interroger l’index.

Azure OpenAI reçoit la requête et les résultats de recherche de votre système local. Attribuez-vous le rôle Utilisateur OpenAI Cognitive Services sur Azure OpenAI.

Connectez-vous au portail Azure.
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. Dans Recherche Azure AI, sélectionnez ces rôles pour créer, charger et interroger un index de recherche, puis affectez-les à votre identité d’utilisateur Microsoft Entra ID :
  - Contributeur de données d’index de la Recherche
  - Contributeur du service de recherche
3. Dans Azure OpenAI, sélectionnez Contrôle d’accès (IAM) pour vous attribuer ce rôle sur Azure OpenAI :
  - Utilisateur OpenAI Cognitive Services

La prise en compte des autorisations peut prendre plusieurs minutes.

Création d'un index

Un index de recherche fournit des données ancrées dans le réel pour le modèle de conversation. 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.
Faites défiler l’index jusqu’à la fin, où vous pouvez trouver des espaces réservés pour les constructions qui peuvent être ajoutées à un index.
```
"analyzers": [],
"tokenizers": [],
"tokenFilters": [],
"charFilters": [],
"normalizers": [],
```

Sur une nouvelle ligne après les « normaliseurs », collez 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 : complimentary breakfast.

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. Nous avons utilisé une instruction sélectionner pour retourner uniquement les champs HotelName, Description et Tags.

{
"@odata.count": 18,
"@search.answers": [],
"value": [
   {
      "@search.score": 2.2896252,
      "@search.rerankerScore": 2.506816864013672,
      "@search.captions": [
      {
         "text": "Head Wind Resort. Suite. coffee in lobby\r\nfree wifi\r\nview. The best of old town hospitality combined with views of the river and cool breezes off the prairie. Our penthouse suites offer views for miles and the rooftop plaza is open to all guests from sunset to 10 p.m. Enjoy a **complimentary continental breakfast** in the lobby, and free Wi-Fi throughout the hotel..",
         "highlights": ""
      }
      ],
      "HotelName": "Head Wind Resort",
      "Description": "The best of old town hospitality combined with views of the river and cool breezes off the prairie. Our penthouse suites offer views for miles and the rooftop plaza is open to all guests from sunset to 10 p.m. Enjoy a complimentary continental breakfast in the lobby, and free Wi-Fi throughout the hotel.",
      "Tags": [
      "coffee in lobby",
      "free wifi",
      "view"
      ]
   },
   {
      "@search.score": 2.2158256,
      "@search.rerankerScore": 2.288334846496582,
      "@search.captions": [
      {
         "text": "Swan Bird Lake Inn. Budget. continental breakfast\r\nfree wifi\r\n24-hour front desk service. We serve a continental-style breakfast each morning, featuring a variety of food and drinks. Our locally made, oh-so-soft, caramel cinnamon rolls are a favorite with our guests. Other breakfast items include coffee, orange juice, milk, cereal, instant oatmeal, bagels, and muffins..",
         "highlights": ""
      }
      ],
      "HotelName": "Swan Bird Lake Inn",
      "Description": "We serve a continental-style breakfast each morning, featuring a variety of food and drinks. Our locally made, oh-so-soft, caramel cinnamon rolls are a favorite with our guests. Other breakfast items include coffee, orange juice, milk, cereal, instant oatmeal, bagels, and muffins.",
      "Tags": [
      "continental breakfast",
      "free wifi",
      "24-hour front desk service"
      ]
   },
   {
      "@search.score": 0.92481667,
      "@search.rerankerScore": 2.221315860748291,
      "@search.captions": [
      {
         "text": "White Mountain Lodge & Suites. Resort and Spa. continental breakfast\r\npool\r\nrestaurant. Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings..",
         "highlights": ""
      }
      ],
      "HotelName": "White Mountain Lodge & Suites",
      "Description": "Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings.",
      "Tags": [
      "continental breakfast",
      "pool",
      "restaurant"
      ]
   },
   . . .
]}

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/.

Créer un environnement virtuel

Dans cette étape, revenez à votre système local et Visual Studio Code. Nous vous recommandons de créer un environnement virtuel pour pouvoir installer les dépendances en isolation.

Dans Visual Studio Code, ouvrez le dossier contenant Quickstart-RAG.ipynb.
Appuyez sur Ctrl+Maj+P pour ouvrir la palette de commandes, recherchez « Python : Créer un environnement », puis sélectionnez Venv pour créer un environnement virtuel dans l’espace de travail actuel.
Sélectionnez Quickstart-RAG\requirements.txt pour les dépendances.

La création de l'environnement prend quelques minutes. Une fois l’environnement prêt, passez à l’étape suivante.

Vous utilisez Microsoft Entra ID et des attributions de rôle pour la connexion. Vérifiez que vous êtes connecté au même locataire et au même abonnement que Recherche Azure AI et Azure OpenAI. Vous pouvez utiliser Azure CLI sur la ligne de commande pour afficher les propriétés actuelles, modifier ses propriétés et vous connecter. Pour plus d’informations, consultez Se connecter sans clés.

Exécutez chacune des commandes suivantes en séquence.

az account show

az account set --subscription <PUT YOUR SUBSCRIPTION ID HERE>

az login --tenant <PUT YOUR TENANT ID HERE>

Vous devez maintenant être connecté à Azure depuis votre appareil local.

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.0b5 --quiet
! pip install azure-identity==1.16.1 --quiet
! pip install openai --quiet
! pip install aiohttp --quiet
! pip install ipykernel --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-4o"

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

Pour le cloud Azure Government, modifiez le point de terminaison d’API sur le fournisseur de jetons en "https://cognitiveservices.azure.us/.default".

# 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 chat model
 query="Can you recommend a few hotels with complimentary breakfast?"

 # Search results are created by the search client
 # Search results are composed of the top 5 results and the fields selected from the search index
 # Search results include the top 5 matches to your query
 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])

 # Send the search results and the query to the LLM to generate a response based on the prompt.
 response = openai_client.chat.completions.create(
     messages=[
         {
             "role": "user",
             "content": GROUNDED_PROMPT.format(query=query, sources=sources_formatted)
         }
     ],
     model=AZURE_DEPLOYMENT_MODEL
 )

 # Here is the response from the chat 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 :

Sure! Here are a few hotels that offer complimentary breakfast:

- **Head Wind Resort**
- Complimentary continental breakfast in the lobby
- Free Wi-Fi throughout the hotel

- **Double Sanctuary Resort**
- Continental breakfast included

- **White Mountain Lodge & Suites**
- Continental breakfast available

- **Swan Bird Lake Inn**
- Continental-style breakfast each morning with a variety of food and drinks 
 such as caramel cinnamon rolls, coffee, orange juice, milk, cereal, 
 instant oatmeal, bagels, and muffins

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 obtenez un message d’erreur Ressource introuvable, vérifiez les URI des ressources et si la version de l’API sur le modèle de conversation est valide.

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.

Envoyer une requête RAG complexe

Recherche Azure AI prend en charge les types complexes pour les structures JSON imbriquées. Dans l’hôtel-sample-index, Address est un exemple de type complexe, composé de Address.StreetAddress, Address.City, Address.StateProvince, Address.PostalCode et Address.Country. L’index a également une collection complexe de Rooms pour chaque hôtel.

Si votre index a des types complexes, votre requête peut fournir ces champs si vous convertissez d’abord les résultats de la recherche en JSON, puis que vous passez le JSON au modèle de conversation. L’exemple suivant ajoute des types complexes à la requête. Les instructions de mise en forme incluent une spécification JSON.

import json

# Query is the question being asked. It's sent to the search engine and the LLM.
query="Can you recommend a few hotels that offer complimentary breakfast? 
Tell me their description, address, tags, and the rate for one room that sleeps 4 people."

# Set up the search results and the chat thread.
# Retrieve the selected fields from the search index related to the question.
selected_fields = ["HotelName","Description","Address","Rooms","Tags"]
search_results = search_client.search(
    search_text=query,
    top=5,
    select=selected_fields,
    query_type="semantic"
)
sources_filtered = [{field: result[field] for field in selected_fields} for result in search_results]
sources_formatted = "\n".join([json.dumps(source) for source in sources_filtered])

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)

La sortie provient d’Azure OpenAI et ajoute du contenu à partir de types complexes.

Here are a few hotels that offer complimentary breakfast and have rooms that sleep 4 people:

1. **Head Wind Resort**
   - **Description:** The best of old town hospitality combined with views of the river and 
   cool breezes off the prairie. Enjoy a complimentary continental breakfast in the lobby, 
   and free Wi-Fi throughout the hotel.
   - **Address:** 7633 E 63rd Pl, Tulsa, OK 74133, USA
   - **Tags:** Coffee in lobby, free Wi-Fi, view
   - **Room for 4:** Suite, 2 Queen Beds (Amenities) - $254.99

2. **Double Sanctuary Resort**
   - **Description:** 5-star Luxury Hotel - Biggest Rooms in the city. #1 Hotel in the area 
   listed by Traveler magazine. Free WiFi, Flexible check in/out, Fitness Center & espresso 
   in room. Offers continental breakfast.
   - **Address:** 2211 Elliott Ave, Seattle, WA 98121, USA
   - **Tags:** View, pool, restaurant, bar, continental breakfast
   - **Room for 4:** Suite, 2 Queen Beds (Amenities) - $254.99

3. **Swan Bird Lake Inn**
   - **Description:** Continental-style breakfast featuring a variety of food and drinks. 
   Locally made caramel cinnamon rolls are a favorite.
   - **Address:** 1 Memorial Dr, Cambridge, MA 02142, USA
   - **Tags:** Continental breakfast, free Wi-Fi, 24-hour front desk service
   - **Room for 4:** Budget Room, 2 Queen Beds (City View) - $85.99

4. **Gastronomic Landscape Hotel**
   - **Description:** Known for its culinary excellence under the management of William Dough, 
   offers continental breakfast.
   - **Address:** 3393 Peachtree Rd, Atlanta, GA 30326, USA
   - **Tags:** Restaurant, bar, continental breakfast
   - **Room for 4:** Budget Room, 2 Queen Beds (Amenities) - $66.99
...
   - **Tags:** Pool, continental breakfast, free parking
   - **Room for 4:** Budget Room, 2 Queen Beds (Amenities) - $60.99

Enjoy your stay! Let me know if you need any more information.

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 individuellement, ou supprimer le groupe de ressources pour supprimer l’ensemble des ressources.

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

Prérequis

Un compte Azure avec un abonnement actif. Créez un compte gratuitement.
Ressource Azure OpenAI.
- Choisissez une région qui prend en charge le modèle d’achèvement de conversation que vous souhaitez utiliser (gpt-4o, gpt-4o-mini ou un modèle équivalent).
- Déployez le modèle de complétion de conversation dans Azure AI Foundry ou utilisez une autre approche.
Ressource de recherche Azure AI.
- Nous vous recommandons d’utiliser le niveau De base ou supérieur.
- Activez le classement sémantique.
Visual Studio Code.
Node.JS avec LTS.
TypeScript. Vous pouvez installer Globalement TypeScript à l’aide de npm :
```
npm install -g typescript
```

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 l’attribution de rôle Lecteur de données de l’index de recherche si l’exemple d’index des hôtels existe déjà. S’il n’existe pas, attribuez-vous les rôles Contributeur service Search et Contributeur de données d’index de recherche afin de pouvoir créer et interroger l’index.

Azure OpenAI reçoit la requête et les résultats de recherche de votre système local. Attribuez-vous le rôle Utilisateur OpenAI Cognitive Services sur Azure OpenAI.

Connectez-vous au portail Azure.
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. Dans Recherche Azure AI, sélectionnez ces rôles pour créer, charger et interroger un index de recherche, puis affectez-les à votre identité d’utilisateur Microsoft Entra ID :
  - Contributeur de données d’index de la Recherche
  - Contributeur du service de recherche
3. Dans Azure OpenAI, sélectionnez Contrôle d’accès (IAM) pour vous attribuer ce rôle sur Azure OpenAI :
  - Utilisateur OpenAI Cognitive Services

La prise en compte des autorisations peut prendre plusieurs minutes.

Création d'un index

Un index de recherche fournit des données ancrées dans le réel pour le modèle de conversation. 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.
Faites défiler l’index jusqu’à la fin, où vous pouvez trouver des espaces réservés pour les constructions qui peuvent être ajoutées à un index.
```
"analyzers": [],
"tokenizers": [],
"tokenFilters": [],
"charFilters": [],
"normalizers": [],
```

Sur une nouvelle ligne après les « normaliseurs », collez 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 : complimentary breakfast.

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. Nous avons utilisé une instruction sélectionner pour retourner uniquement les champs HotelName, Description et Tags.

{
"@odata.count": 18,
"@search.answers": [],
"value": [
   {
      "@search.score": 2.2896252,
      "@search.rerankerScore": 2.506816864013672,
      "@search.captions": [
      {
         "text": "Head Wind Resort. Suite. coffee in lobby\r\nfree wifi\r\nview. The best of old town hospitality combined with views of the river and cool breezes off the prairie. Our penthouse suites offer views for miles and the rooftop plaza is open to all guests from sunset to 10 p.m. Enjoy a **complimentary continental breakfast** in the lobby, and free Wi-Fi throughout the hotel..",
         "highlights": ""
      }
      ],
      "HotelName": "Head Wind Resort",
      "Description": "The best of old town hospitality combined with views of the river and cool breezes off the prairie. Our penthouse suites offer views for miles and the rooftop plaza is open to all guests from sunset to 10 p.m. Enjoy a complimentary continental breakfast in the lobby, and free Wi-Fi throughout the hotel.",
      "Tags": [
      "coffee in lobby",
      "free wifi",
      "view"
      ]
   },
   {
      "@search.score": 2.2158256,
      "@search.rerankerScore": 2.288334846496582,
      "@search.captions": [
      {
         "text": "Swan Bird Lake Inn. Budget. continental breakfast\r\nfree wifi\r\n24-hour front desk service. We serve a continental-style breakfast each morning, featuring a variety of food and drinks. Our locally made, oh-so-soft, caramel cinnamon rolls are a favorite with our guests. Other breakfast items include coffee, orange juice, milk, cereal, instant oatmeal, bagels, and muffins..",
         "highlights": ""
      }
      ],
      "HotelName": "Swan Bird Lake Inn",
      "Description": "We serve a continental-style breakfast each morning, featuring a variety of food and drinks. Our locally made, oh-so-soft, caramel cinnamon rolls are a favorite with our guests. Other breakfast items include coffee, orange juice, milk, cereal, instant oatmeal, bagels, and muffins.",
      "Tags": [
      "continental breakfast",
      "free wifi",
      "24-hour front desk service"
      ]
   },
   {
      "@search.score": 0.92481667,
      "@search.rerankerScore": 2.221315860748291,
      "@search.captions": [
      {
         "text": "White Mountain Lodge & Suites. Resort and Spa. continental breakfast\r\npool\r\nrestaurant. Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings..",
         "highlights": ""
      }
      ],
      "HotelName": "White Mountain Lodge & Suites",
      "Description": "Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings.",
      "Tags": [
      "continental breakfast",
      "pool",
      "restaurant"
      ]
   },
   . . .
]}

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 des variables d’environnement pour le développement local

Créez un fichier .env .

Ajoutez les variables d’environnement suivantes au .env fichier, en remplaçant les valeurs par vos propres points de terminaison et clés de service.

AZURE_SEARCH_ENDPOINT=<YOUR AZURE AI SEARCH ENDPOINT>
AZURE_SEARCH_INDEX_NAME=hotels-sample-index

AZURE_OPENAI_ENDPOINT=<YOUR AZURE OPENAI ENDPOINT>
AZURE_OPENAI_VERSION=<YOUR AZURE OPENAI API VERSION>
AZURE_DEPLOYMENT_MODEL=<YOUR DEPLOYMENT NAME>

Configurer le projet Node.JS

Configurez le projet avec Visual Studio Code et TypeScript.

Démarrez Visual Studio Code dans un nouveau répertoire.
```
mkdir rag-quickstart && cd rag-quickstart
code .
```
Créez un package pour les modules ESM dans votre répertoire de projet.
```
npm init -y
npm pkg set type=module
```
Cela crée un package.json fichier avec des valeurs par défaut.

Installez les packages npm suivants.

npm install @azure/identity @azure/search-documents openai dotenv @types/node

Créez un src répertoire dans votre répertoire de projet.
```
mkdir src
```

Créez un tsconfig.json fichier dans le répertoire du projet pour ESM avec le contenu suivant.

{
  "compilerOptions": {
    "target": "esnext",
    "module": "NodeNext",
    "moduleResolution": "nodenext",
    "rootDir": "./src",
    "outDir": "./dist/",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true,
    "declaration": true,
    "sourceMap": true,
    "resolveJsonModule": true,
    "moduleDetection": "force", // Add this for ESM
    "allowSyntheticDefaultImports": true // Helpful for ESM interop
  },
  "include": [
    "src/**/*.ts"
  ]
}

Vous utilisez Microsoft Entra ID et des attributions de rôle pour la connexion. Vérifiez que vous êtes connecté au même locataire et au même abonnement que Recherche Azure AI et Azure OpenAI. Vous pouvez utiliser Azure CLI sur la ligne de commande pour afficher les propriétés actuelles, modifier ses propriétés et vous connecter. Pour plus d’informations, consultez Se connecter sans clés.

Exécutez chacune des commandes suivantes en séquence.

az account show

az account set --subscription <PUT YOUR SUBSCRIPTION ID HERE>

az login --tenant <PUT YOUR TENANT ID HERE>

Vous devez maintenant être connecté à Azure depuis votre appareil local.

Configurer le thread de requête et de conversation

Créez un script de requête qui utilise l’index Recherche Azure AI et le modèle de conversation pour générer des réponses basées sur des données de base. Les étapes suivantes vous guident tout au long de la configuration du script de requête.

Créez un query.ts fichier dans le src répertoire avec le code suivant.

// This is a RAG (Retrieval Augmented Generation) implementation that:
// 1. Takes a user query about hotels
// 2. Searches a hotel database using Azure AI Search
// 3. Formats the search results for the LLM
// 4. Sends the query and formatted results to Azure OpenAI
// 5. Returns a grounded response based only on the retrieved information

import { SearchClient, AzureKeyCredential, SearchDocumentsResult } from "@azure/search-documents";
import { AzureOpenAI } from "openai";
import { DefaultAzureCredential, getBearerTokenProvider } from "@azure/identity";

function getClients(): { openaiClient: AzureOpenAI, searchClient: SearchClient<{ HotelName: string; Description: string; Tags: string[] | string }>, modelName: string }  {

    const credential = new DefaultAzureCredential();

    // Search
    const azureSearchEndpoint = process.env.AZURE_SEARCH_ENDPOINT!;
    const azureSearchIndexName = process.env.AZURE_SEARCH_INDEX_NAME!;

    const searchClient = new SearchClient<{ HotelName: string; Description: string; Tags: string[] | string }>(
        azureSearchEndpoint,
        azureSearchIndexName,
        credential
    );


    // OpenAI
    const azureOpenAiEndpoint = process.env.AZURE_OPENAI_ENDPOINT!;
    const azureOpenAiApiVersion = process.env.AZURE_OPENAI_VERSION!;
    const azureOpenAiDeploymentName = process.env.AZURE_DEPLOYMENT_MODEL!;

    const scope = "https://cognitiveservices.azure.com/.default";
    const azureADTokenProvider = getBearerTokenProvider(credential, scope);
    const options = { azureADTokenProvider, deployment: azureOpenAiDeploymentName, apiVersion: azureOpenAiApiVersion, endpoint: azureOpenAiEndpoint }
    const openaiClient = new AzureOpenAI(options);

    return { openaiClient, searchClient, modelName: azureOpenAiDeploymentName };
}

async function queryAISearchForSources(searchClient: SearchClient<{ HotelName: string; Description: string; Tags: string[] | string }>, query: string): Promise<string> {
    console.log(`Searching for: "${query}"\n`);
    const searchResults: SearchDocumentsResult<{ HotelName: string; Description: string; Tags: string[] | string }> = await searchClient.search(query, {
        top: 5,
        select: ["Description", "HotelName", "Tags"]
    });

    const sources: string[] = [];
    for await (const result of searchResults.results) {
        const doc = result.document;
        sources.push(
            `Hotel: ${doc.HotelName}\n` +
            `Description: ${doc.Description}\n` +
            `Tags: ${Array.isArray(doc.Tags) ? doc.Tags.join(', ') : doc.Tags}\n`
        );
    }
    const sourcesFormatted = sources.join("\n---\n");
    return sourcesFormatted;
}
async function queryOpenAIForResponse(
    openaiClient: AzureOpenAI, 
    query: string, 
    sourcesFormatted: string, 
    modelName: string
): Promise<{ choices: { message: { content: string | null } }[] }> {

    const 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: {sources}
`;

    return openaiClient.chat.completions.create({
        model: modelName,
        messages: [
            {
                role: "user",
                content: GROUNDED_PROMPT.replace("{query}", query).replace("{sources}", sourcesFormatted),
            }
        ],
        temperature: 0.7,
        max_tokens: 800,
    });
}

async function main():Promise<void> {

    const { openaiClient, searchClient, modelName } = getClients();

    const query = "Can you recommend a few hotels with complimentary breakfast?";

    const sources = await queryAISearchForSources(searchClient, query);
    const response = await queryOpenAIForResponse(openaiClient, query, sources, modelName);

    // Print the response from the chat model
    const content = response.choices[0].message.content;
    if (content) {
        console.log(content);
    } else {
        console.log("No content available in the response.");
    }
}

main().catch((error) => {
    console.error("An error occurred:", error);
    process.exit(1);
});

Le code précédent effectue les opérations suivantes :

Importe les bibliothèques nécessaires pour Recherche Azure AI et Azure OpenAI.
Utilise des variables d’environnement pour configurer les clients Azure AI Search et Azure OpenAI.
Définit une fonction pour obtenir les clients pour Azure AI Search et Azure OpenAI, à l’aide de variables d’environnement pour la configuration.
Définit une fonction pour interroger Azure AI Search pour les sources en fonction de la requête utilisateur.
Définit une fonction pour interroger Azure OpenAI pour une réponse basée sur la requête utilisateur et les sources récupérées à partir d’Azure AI Search.
La main fonction orchestre le flux en appelant les fonctions de recherche et OpenAI, puis imprime la réponse.

Générez le code TypeScript en JavaScript.
```
tsc
```
Cette commande compile le code TypeScript dans le src répertoire et génère les fichiers JavaScript dans le dist répertoire.
Exécutez la commande suivante dans un terminal pour exécuter le script de requête :
```
node -r dotenv/config dist/query.js
```
Le .env est passé dans le runtime à l'aide du -r dotenv/config.

Le résultat consiste en des recommandations pour plusieurs hôtels. Voici un exemple de ce à quoi la sortie peut ressembler :

Sure! Here are a few hotels that offer complimentary breakfast:

- **Head Wind Resort**
- Complimentary continental breakfast in the lobby
- Free Wi-Fi throughout the hotel

- **Double Sanctuary Resort**
- Continental breakfast included

- **White Mountain Lodge & Suites**
- Continental breakfast available

- **Swan Bird Lake Inn**
- Continental-style breakfast each morning with a variety of food and drinks 
    such as caramel cinnamon rolls, coffee, orange juice, milk, cereal, 
    instant oatmeal, bagels, and muffins

Résolution des problèmes

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 obtenez un message d’erreur Ressource introuvable, vérifiez les URI des ressources et si la version de l’API sur le modèle de conversation est valide.

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.

Envoyer une requête RAG complexe

Recherche Azure AI prend en charge les types complexes pour les structures JSON imbriquées. Dans l’hôtel-sample-index, Address est un exemple de type complexe, composé de Address.StreetAddress, Address.City, Address.StateProvince, Address.PostalCode et Address.Country. L’index a également une collection complexe de Rooms pour chaque hôtel.

Si votre index a des types complexes, modifiez votre invite pour inclure des instructions de mise en forme :

Can you recommend a few hotels that offer complimentary breakfast? 
Tell me their description, address, tags, and the rate for one room that sleeps 4 people.

Créez un fichier queryComplex.ts dans le src répertoire.

Copiez le code suivant dans le fichier :

// This is a RAG (Retrieval Augmented Generation) implementation that:
// 1. Takes a user query about hotels
// 2. Searches a hotel database using Azure AI Search
// 3. Formats the search results for the LLM
// 4. Sends the query and formatted results to Azure OpenAI
// 5. Returns a grounded response based only on the retrieved information

import { SearchClient, SearchDocumentsResult } from "@azure/search-documents";
import { AzureOpenAI } from "openai";
import { DefaultAzureCredential, getBearerTokenProvider } from "@azure/identity";

function getClients(): { openaiClient: AzureOpenAI; searchClient: SearchClient<{ HotelName: string; Description: string; Tags: string[] | string; Address: string; Rooms: string }>; modelName: string }  {

    const credential = new DefaultAzureCredential();

    // Search
    const azureSearchEndpoint = process.env.AZURE_SEARCH_ENDPOINT!;
    const azureSearchIndexName = process.env.AZURE_SEARCH_INDEX_NAME!;
    const searchClient = new SearchClient<{ HotelName: string; Description: string; Tags: string[] | string; Address: string; Rooms: string }>(
        azureSearchEndpoint,
        azureSearchIndexName,
        credential
    );

    // OpenAI
    const azureOpenAiEndpoint = process.env.AZURE_OPENAI_ENDPOINT!;
    const azureOpenAiApiVersion = process.env.AZURE_OPENAI_VERSION!;
    const azureOpenAiDeploymentName = process.env.AZURE_DEPLOYMENT_MODEL!;

    const scope = "https://cognitiveservices.azure.com/.default";
    const azureADTokenProvider = getBearerTokenProvider(credential, scope);
    const options = { azureADTokenProvider, deployment: azureOpenAiDeploymentName, apiVersion: azureOpenAiApiVersion, endpoint: azureOpenAiEndpoint }
    const openaiClient = new AzureOpenAI(options);

    return { openaiClient, searchClient, modelName: azureOpenAiDeploymentName };
}


async function queryAISearchForSources(
    searchClient: SearchClient<{ HotelName: string; Description: string; Tags: string[] | string; Address: string; Rooms: string }>,
    query: string
): Promise<SearchDocumentsResult<{ HotelName: string; Description: string; Tags: string[] | string; Address: string; Rooms: string }>> {
    console.log(`Searching for: "${query}"\n`);

    const selectedFields: readonly ["HotelName", "Description", "Address", "Rooms", "Tags"] = ["HotelName", "Description", "Address", "Rooms", "Tags"];
    const searchResults = await searchClient.search(query, {
        top: 5,
        select: selectedFields,
        queryType: "semantic",
        semanticSearchOptions: {},
    });

    return searchResults;
}
async function queryOpenAIForResponse(
    openaiClient: AzureOpenAI, 
    query: string, 
    sourcesFormatted: string, 
    modelName: string
): Promise<{ choices: { message: { content: string | null } }[] }> {

    const 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: {sources}
`;

    return openaiClient.chat.completions.create({
        model: modelName,
        messages: [
            {
                role: "user",
                content: GROUNDED_PROMPT.replace("{query}", query).replace("{sources}", sourcesFormatted),
            }
        ],
        temperature: 0.7,
        max_tokens: 800,
    });
}

async function main(): Promise<void> {

    const { openaiClient, searchClient, modelName } = getClients();

    const query = `
    Can you recommend a few hotels that offer complimentary breakfast? 
    Tell me their description, address, tags, and the rate for one room that sleeps 4 people.
    `;

    const sourcesResult = await queryAISearchForSources(searchClient, query);
    let sourcesFormatted = "";

    for await (const result of sourcesResult.results) {
        // Explicitly typing result to ensure compatibility
        sourcesFormatted += JSON.stringify(result.document) + "\n";
    }

    const response = await queryOpenAIForResponse(openaiClient, query, sourcesFormatted.trim(), modelName);

    // Print the response from the chat model
    const content = response.choices[0].message.content;
    if (content) {
        console.log(content);
    } else {
        console.log("No content available in the response.");
    }
}

main().catch((error) => {
    console.error("An error occurred:", error);
    process.exit(1);
});

Générez le code TypeScript en JavaScript.
```
tsc
```
Cette commande compile le code TypeScript dans le src répertoire et génère les fichiers JavaScript dans le dist répertoire.
Exécutez la commande suivante dans un terminal pour exécuter le script de requête :
```
node -r dotenv/config dist/queryComplex.js
```
Le .env est passé dans le runtime à l’aide du -r dotenv/config.
Affichez la sortie d'Azure OpenAI, qui ajoute du contenu de types complexes.

Here are a few hotels that offer complimentary breakfast and have rooms that sleep 4 people:

1. **Head Wind Resort**
   - **Description:** The best of old town hospitality combined with views of the river and 
   cool breezes off the prairie. Enjoy a complimentary continental breakfast in the lobby, 
   and free Wi-Fi throughout the hotel.
   - **Address:** 7633 E 63rd Pl, Tulsa, OK 74133, USA
   - **Tags:** Coffee in lobby, free Wi-Fi, view
   - **Room for 4:** Suite, 2 Queen Beds (Amenities) - $254.99

2. **Double Sanctuary Resort**
   - **Description:** 5-star Luxury Hotel - Biggest Rooms in the city. #1 Hotel in the area 
   listed by Traveler magazine. Free WiFi, Flexible check in/out, Fitness Center & espresso 
   in room. Offers continental breakfast.
   - **Address:** 2211 Elliott Ave, Seattle, WA 98121, USA
   - **Tags:** View, pool, restaurant, bar, continental breakfast
   - **Room for 4:** Suite, 2 Queen Beds (Amenities) - $254.99

3. **Swan Bird Lake Inn**
   - **Description:** Continental-style breakfast featuring a variety of food and drinks. 
   Locally made caramel cinnamon rolls are a favorite.
   - **Address:** 1 Memorial Dr, Cambridge, MA 02142, USA
   - **Tags:** Continental breakfast, free Wi-Fi, 24-hour front desk service
   - **Room for 4:** Budget Room, 2 Queen Beds (City View) - $85.99

4. **Gastronomic Landscape Hotel**
   - **Description:** Known for its culinary excellence under the management of William Dough, 
   offers continental breakfast.
   - **Address:** 3393 Peachtree Rd, Atlanta, GA 30326, USA
   - **Tags:** Restaurant, bar, continental breakfast
   - **Room for 4:** Budget Room, 2 Queen Beds (Amenities) - $66.99
...
   - **Tags:** Pool, continental breakfast, free parking
   - **Room for 4:** Budget Room, 2 Queen Beds (Amenities) - $60.99

Enjoy your stay! Let me know if you need any more information.

Résolution des erreurs

Pour déboguer les erreurs du Kit de développement logiciel (SDK) Azure, définissez la variable AZURE_LOG_LEVEL d’environnement sur l’une des valeurs suivantes : verbose, , info, warning, error. Cela permet la journalisation détaillée du Kit de développement logiciel (SDK) Azure, qui peut vous aider à identifier les problèmes liés à l’authentification, à la connectivité réseau ou à d’autres problèmes.

Réexécutez le script de requête. Vous devriez maintenant obtenir des déclarations informatives des SDK dans la sortie, fournissant plus de détails sur les problèmes.

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 individuellement, ou supprimer le groupe de ressources pour supprimer l’ensemble des ressources.

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

Prérequis

Un compte Azure avec un abonnement actif. Créez un compte gratuitement.
Ressource Azure OpenAI.
- Choisissez une région qui prend en charge le modèle d’achèvement de conversation que vous souhaitez utiliser (gpt-4o, gpt-4o-mini ou un modèle équivalent).
- Déployez le modèle de complétion de conversation dans Azure AI Foundry ou utilisez une autre approche.
Ressource de recherche Azure AI.
- Nous vous recommandons d’utiliser le niveau De base ou supérieur.
- Activez le classement sémantique.
Visual Studio Code.
Node.JS avec LTS.

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 l’attribution de rôle Lecteur de données de l’index de recherche si l’exemple d’index des hôtels existe déjà. S’il n’existe pas, attribuez-vous les rôles Contributeur service Search et Contributeur de données d’index de recherche afin de pouvoir créer et interroger l’index.

Azure OpenAI reçoit la requête et les résultats de recherche de votre système local. Attribuez-vous le rôle Utilisateur OpenAI Cognitive Services sur Azure OpenAI.

Connectez-vous au portail Azure.
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. Dans Recherche Azure AI, sélectionnez ces rôles pour créer, charger et interroger un index de recherche, puis affectez-les à votre identité d’utilisateur Microsoft Entra ID :
  - Contributeur de données d’index de la Recherche
  - Contributeur du service de recherche
3. Dans Azure OpenAI, sélectionnez Contrôle d’accès (IAM) pour vous attribuer ce rôle sur Azure OpenAI :
  - Utilisateur OpenAI Cognitive Services

La prise en compte des autorisations peut prendre plusieurs minutes.

Création d'un index

Un index de recherche fournit des données ancrées dans le réel pour le modèle de conversation. 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.
Faites défiler l’index jusqu’à la fin, où vous pouvez trouver des espaces réservés pour les constructions qui peuvent être ajoutées à un index.
```
"analyzers": [],
"tokenizers": [],
"tokenFilters": [],
"charFilters": [],
"normalizers": [],
```

Sur une nouvelle ligne après les « normaliseurs », collez 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 : complimentary breakfast.

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. Nous avons utilisé une instruction sélectionner pour retourner uniquement les champs HotelName, Description et Tags.

{
"@odata.count": 18,
"@search.answers": [],
"value": [
   {
      "@search.score": 2.2896252,
      "@search.rerankerScore": 2.506816864013672,
      "@search.captions": [
      {
         "text": "Head Wind Resort. Suite. coffee in lobby\r\nfree wifi\r\nview. The best of old town hospitality combined with views of the river and cool breezes off the prairie. Our penthouse suites offer views for miles and the rooftop plaza is open to all guests from sunset to 10 p.m. Enjoy a **complimentary continental breakfast** in the lobby, and free Wi-Fi throughout the hotel..",
         "highlights": ""
      }
      ],
      "HotelName": "Head Wind Resort",
      "Description": "The best of old town hospitality combined with views of the river and cool breezes off the prairie. Our penthouse suites offer views for miles and the rooftop plaza is open to all guests from sunset to 10 p.m. Enjoy a complimentary continental breakfast in the lobby, and free Wi-Fi throughout the hotel.",
      "Tags": [
      "coffee in lobby",
      "free wifi",
      "view"
      ]
   },
   {
      "@search.score": 2.2158256,
      "@search.rerankerScore": 2.288334846496582,
      "@search.captions": [
      {
         "text": "Swan Bird Lake Inn. Budget. continental breakfast\r\nfree wifi\r\n24-hour front desk service. We serve a continental-style breakfast each morning, featuring a variety of food and drinks. Our locally made, oh-so-soft, caramel cinnamon rolls are a favorite with our guests. Other breakfast items include coffee, orange juice, milk, cereal, instant oatmeal, bagels, and muffins..",
         "highlights": ""
      }
      ],
      "HotelName": "Swan Bird Lake Inn",
      "Description": "We serve a continental-style breakfast each morning, featuring a variety of food and drinks. Our locally made, oh-so-soft, caramel cinnamon rolls are a favorite with our guests. Other breakfast items include coffee, orange juice, milk, cereal, instant oatmeal, bagels, and muffins.",
      "Tags": [
      "continental breakfast",
      "free wifi",
      "24-hour front desk service"
      ]
   },
   {
      "@search.score": 0.92481667,
      "@search.rerankerScore": 2.221315860748291,
      "@search.captions": [
      {
         "text": "White Mountain Lodge & Suites. Resort and Spa. continental breakfast\r\npool\r\nrestaurant. Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings..",
         "highlights": ""
      }
      ],
      "HotelName": "White Mountain Lodge & Suites",
      "Description": "Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings.",
      "Tags": [
      "continental breakfast",
      "pool",
      "restaurant"
      ]
   },
   . . .
]}

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 des variables d’environnement pour le développement local

Créez un fichier .env .

Ajoutez les variables d’environnement suivantes au .env fichier, en remplaçant les valeurs par vos propres points de terminaison et clés de service.

AZURE_SEARCH_ENDPOINT=<YOUR AZURE AI SEARCH ENDPOINT>
AZURE_SEARCH_INDEX_NAME=hotels-sample-index

AZURE_OPENAI_ENDPOINT=<YOUR AZURE OPENAI ENDPOINT>
AZURE_OPENAI_VERSION=<YOUR AZURE OPENAI API VERSION>
AZURE_DEPLOYMENT_MODEL=<YOUR DEPLOYMENT NAME>

Configurer le projet Node.JS

Configurez le projet avec Visual Studio Code et TypeScript.

Démarrez Visual Studio Code dans un nouveau répertoire.
```
mkdir rag-quickstart && cd rag-quickstart
code .
```
Créez un package pour les modules ESM dans votre répertoire de projet.
```
npm init -y
npm pkg set type=module
```
Cela crée un package.json fichier avec des valeurs par défaut.

Installez les packages npm suivants.

npm install @azure/identity @azure/search-documents openai dotenv

Créez un src répertoire dans votre répertoire de projet.
```
mkdir src
```

Vous utilisez Microsoft Entra ID et des attributions de rôle pour la connexion. Vérifiez que vous êtes connecté au même locataire et au même abonnement que Recherche Azure AI et Azure OpenAI. Vous pouvez utiliser Azure CLI sur la ligne de commande pour afficher les propriétés actuelles, modifier ses propriétés et vous connecter. Pour plus d’informations, consultez Se connecter sans clés.

Exécutez chacune des commandes suivantes en séquence.

az account show

az account set --subscription <PUT YOUR SUBSCRIPTION ID HERE>

az login --tenant <PUT YOUR TENANT ID HERE>

Vous devez maintenant être connecté à Azure depuis votre appareil local.

Configurer le thread de requête et de conversation

Créez un script de requête qui utilise l’index Recherche Azure AI et le modèle de conversation pour générer des réponses basées sur des données de base. Les étapes suivantes vous guident tout au long de la configuration du script de requête.

Créez un query.js fichier dans le src répertoire avec le code suivant.

// This is a RAG (Retrieval Augmented Generation) implementation that:
// 1. Takes a user query about hotels
// 2. Searches a hotel database using Azure AI Search
// 3. Formats the search results for the LLM
// 4. Sends the query and formatted results to Azure OpenAI
// 5. Returns a grounded response based only on the retrieved information

import { SearchClient } from "@azure/search-documents";
import { AzureOpenAI } from "openai";
import { DefaultAzureCredential, getBearerTokenProvider } from "@azure/identity";

function getClients() {

    const credential = new DefaultAzureCredential();

    // Search
    const azureSearchEndpoint = process.env.AZURE_SEARCH_ENDPOINT;
    const azureSearchIndexName = process.env.AZURE_SEARCH_INDEX_NAME;

    const searchClient = new SearchClient(
        azureSearchEndpoint,
        azureSearchIndexName,
        credential
    );


    // OpenAI
    const azureOpenAiEndpoint = process.env.AZURE_OPENAI_ENDPOINT;
    const azureOpenAiApiVersion = process.env.AZURE_OPENAI_VERSION;
    const azureOpenAiDeploymentName = process.env.AZURE_DEPLOYMENT_MODEL;

    const scope = "https://cognitiveservices.azure.com/.default";
    const azureADTokenProvider = getBearerTokenProvider(credential, scope);
    const options = { azureADTokenProvider, deployment: azureOpenAiDeploymentName, apiVersion: azureOpenAiApiVersion, endpoint: azureOpenAiEndpoint }
    const openaiClient = new AzureOpenAI(options);

    return { openaiClient, searchClient, modelName: azureOpenAiDeploymentName };
}

async function queryAISearchForSources(searchClient, query) {
    console.log(`Searching for: "${query}"\n`);
    const searchResults = await searchClient.search(query, {
        top: 5,
        select: ["Description", "HotelName", "Tags"]
    });

    const sources = [];
    for await (const result of searchResults.results) {
        const doc = result.document;
        sources.push(
            `Hotel: ${doc.HotelName}\n` +
            `Description: ${doc.Description}\n` +
            `Tags: ${Array.isArray(doc.Tags) ? doc.Tags.join(', ') : doc.Tags}\n`
        );
    }
    const sourcesFormatted = sources.join("\n---\n");
    return sourcesFormatted;
}
async function queryOpenAIForResponse(openaiClient, query, sourcesFormatted, modelName) {

    const 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: {sources}
`;

    return openaiClient.chat.completions.create({
        model: modelName,
        messages: [
            {
                role: "user",
                content: GROUNDED_PROMPT.replace("{query}", query).replace("{sources}", sourcesFormatted),
            }
        ],
        temperature: 0.7,
        max_tokens: 800,
    });
}

async function main() {

    const { openaiClient, searchClient, modelName } = getClients();

    const query = "Can you recommend a few hotels with complimentary breakfast?";

    const sources = await queryAISearchForSources(searchClient, query);
    const response = await queryOpenAIForResponse(openaiClient, query, sources, modelName);

    // Print the response from the chat model
    const content = response.choices[0].message.content;
    if (content) {
        console.log(content);
    } else {
        console.log("No content available in the response.");
    }
}

main().catch((error) => {
    console.error("An error occurred:", error);
    process.exit(1);
});

Le code précédent effectue les opérations suivantes :

Importe les bibliothèques nécessaires pour Recherche Azure AI et Azure OpenAI.
Utilise des variables d’environnement pour configurer les clients Azure AI Search et Azure OpenAI.
Définit une fonction pour obtenir les clients pour Azure AI Search et Azure OpenAI, à l’aide de variables d’environnement pour la configuration.
Définit une fonction pour interroger Azure AI Search pour les sources en fonction de la requête utilisateur.
Définit une fonction pour interroger Azure OpenAI pour une réponse basée sur la requête utilisateur et les sources récupérées à partir d’Azure AI Search.
La main fonction orchestre le flux en appelant les fonctions de recherche et OpenAI, puis imprime la réponse.

Exécutez la commande suivante dans un terminal pour exécuter le script de requête :
```
node -r dotenv/config query.js
```
Le .env est passé dans le runtime à l’aide du -r dotenv/config.

Affichez le résultat, qui se compose de recommandations pour divers hôtels. Voici un exemple de ce à quoi la sortie peut ressembler :

Sure! Here are a few hotels that offer complimentary breakfast:

- **Head Wind Resort**
- Complimentary continental breakfast in the lobby
- Free Wi-Fi throughout the hotel

- **Double Sanctuary Resort**
- Continental breakfast included

- **White Mountain Lodge & Suites**
- Continental breakfast available

- **Swan Bird Lake Inn**
- Continental-style breakfast each morning with a variety of food and drinks 
    such as caramel cinnamon rolls, coffee, orange juice, milk, cereal, 
    instant oatmeal, bagels, and muffins

Résolution des problèmes

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 obtenez un message d’erreur Ressource introuvable, vérifiez les URI des ressources et si la version de l’API sur le modèle de conversation est valide.

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.

Envoyer une requête RAG complexe

Recherche Azure AI prend en charge les types complexes pour les structures JSON imbriquées. Dans l’hôtel-sample-index, Address est un exemple de type complexe, composé de Address.StreetAddress, Address.City, Address.StateProvince, Address.PostalCode et Address.Country. L’index a également une collection complexe de Rooms pour chaque hôtel.

Si votre index a des types complexes, modifiez votre invite pour inclure des instructions de mise en forme :

Can you recommend a few hotels that offer complimentary breakfast? 
Tell me their description, address, tags, and the rate for one room that sleeps 4 people.

Créez un fichier queryComplex.js.

Copiez le code suivant dans le fichier :

// This is a RAG (Retrieval Augmented Generation) implementation that:
// 1. Takes a user query about hotels
// 2. Searches a hotel database using Azure AI Search
// 3. Formats the search results for the LLM
// 4. Sends the query and formatted results to Azure OpenAI
// 5. Returns a grounded response based only on the retrieved information

import { SearchClient } from "@azure/search-documents";
import { AzureOpenAI } from "openai";
import { DefaultAzureCredential, getBearerTokenProvider } from "@azure/identity";

function getClients() {

    const credential = new DefaultAzureCredential();

    // Search
    const azureSearchEndpoint = process.env.AZURE_SEARCH_ENDPOINT;
    const azureSearchIndexName = process.env.AZURE_SEARCH_INDEX_NAME;

    const searchClient = new SearchClient(
        azureSearchEndpoint,
        azureSearchIndexName,
        credential
    );


    // OpenAI
    const azureOpenAiEndpoint = process.env.AZURE_OPENAI_ENDPOINT;
    const azureOpenAiApiVersion = process.env.AZURE_OPENAI_VERSION;
    const azureOpenAiDeploymentName = process.env.AZURE_DEPLOYMENT_MODEL;

    const scope = "https://cognitiveservices.azure.com/.default";
    const azureADTokenProvider = getBearerTokenProvider(credential, scope);
    const options = { azureADTokenProvider, deployment: azureOpenAiDeploymentName, apiVersion: azureOpenAiApiVersion, endpoint: azureOpenAiEndpoint }
    const openaiClient = new AzureOpenAI(options);

    return { openaiClient, searchClient, modelName: azureOpenAiDeploymentName };
}

async function queryAISearchForSources(
    searchClient,
    query
) {
    console.log(`Searching for: "${query}"\n`);

    const selectedFields = ["HotelName", "Description", "Address", "Rooms", "Tags"];
    const searchResults = await searchClient.search(query, {
        top: 5,
        select: selectedFields,
        queryType: "semantic",
        semanticSearchOptions: {},
    });

    return searchResults;
}
async function queryOpenAIForResponse(
    openaiClient, 
    query, 
    sourcesFormatted, 
    modelName
){

    const 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: {sources}
`;

    return openaiClient.chat.completions.create({
        model: modelName,
        messages: [
            {
                role: "user",
                content: GROUNDED_PROMPT.replace("{query}", query).replace("{sources}", sourcesFormatted),
            }
        ],
        temperature: 0.7,
        max_tokens: 800,
    });
}

async function main() {

    const { openaiClient, searchClient, modelName } = getClients();

    const query = `
    Can you recommend a few hotels that offer complimentary breakfast? 
    Tell me their description, address, tags, and the rate for one room that sleeps 4 people.
    `;

    const sourcesResult = await queryAISearchForSources(searchClient, query);
    let sourcesFormatted = "";

    for await (const result of sourcesResult.results) {
        // Explicitly typing result to ensure compatibility
        sourcesFormatted += JSON.stringify(result.document) + "\n";
    }

    const response = await queryOpenAIForResponse(openaiClient, query, sourcesFormatted.trim(), modelName);

    // Print the response from the chat model
    const content = response.choices[0].message.content;
    if (content) {
        console.log(content);
    } else {
        console.log("No content available in the response.");
    }
}

main().catch((error) => {
    console.error("An error occurred:", error);
    process.exit(1);
});

Exécutez la commande suivante dans un terminal pour exécuter le script de requête :
```
node -r dotenv/config queryComplex.js
```
Le .env est passé dans le runtime à l’aide du -r dotenv/config.

Affichez la sortie d'Azure OpenAI, qui ajoute du contenu de types complexes.

Here are a few hotels that offer complimentary breakfast and have rooms that sleep 4 people:

1. **Head Wind Resort**
   - **Description:** The best of old town hospitality combined with views of the river and 
   cool breezes off the prairie. Enjoy a complimentary continental breakfast in the lobby, 
   and free Wi-Fi throughout the hotel.
   - **Address:** 7633 E 63rd Pl, Tulsa, OK 74133, USA
   - **Tags:** Coffee in lobby, free Wi-Fi, view
   - **Room for 4:** Suite, 2 Queen Beds (Amenities) - $254.99

2. **Double Sanctuary Resort**
   - **Description:** 5-star Luxury Hotel - Biggest Rooms in the city. #1 Hotel in the area 
   listed by Traveler magazine. Free WiFi, Flexible check in/out, Fitness Center & espresso 
   in room. Offers continental breakfast.
   - **Address:** 2211 Elliott Ave, Seattle, WA 98121, USA
   - **Tags:** View, pool, restaurant, bar, continental breakfast
   - **Room for 4:** Suite, 2 Queen Beds (Amenities) - $254.99

3. **Swan Bird Lake Inn**
   - **Description:** Continental-style breakfast featuring a variety of food and drinks. 
   Locally made caramel cinnamon rolls are a favorite.
   - **Address:** 1 Memorial Dr, Cambridge, MA 02142, USA
   - **Tags:** Continental breakfast, free Wi-Fi, 24-hour front desk service
   - **Room for 4:** Budget Room, 2 Queen Beds (City View) - $85.99

4. **Gastronomic Landscape Hotel**
   - **Description:** Known for its culinary excellence under the management of William Dough, 
   offers continental breakfast.
   - **Address:** 3393 Peachtree Rd, Atlanta, GA 30326, USA
   - **Tags:** Restaurant, bar, continental breakfast
   - **Room for 4:** Budget Room, 2 Queen Beds (Amenities) - $66.99
...
   - **Tags:** Pool, continental breakfast, free parking
   - **Room for 4:** Budget Room, 2 Queen Beds (Amenities) - $60.99

Enjoy your stay! Let me know if you need any more information.

Résolution des erreurs

Pour déboguer les erreurs du Kit de développement logiciel (SDK) Azure, définissez la variable AZURE_LOG_LEVEL d’environnement sur l’une des valeurs suivantes : verbose, , info, warning, error. Cela permet la journalisation détaillée du Kit de développement logiciel (SDK) Azure, qui peut vous aider à identifier les problèmes liés à l’authentification, à la connectivité réseau ou à d’autres problèmes.

Réexécutez le script de requête. Vous devriez maintenant obtenir des déclarations informatives des SDK dans la sortie, fournissant plus de détails sur les problèmes.

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 individuellement, ou supprimer le groupe de ressources pour supprimer l’ensemble des ressources.

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

Partager via

Démarrage rapide : Recherche générative (RAG) à l’aide de données de base à partir d’Azure AI Search

Prérequis

Télécharger un fichier

Configurer l’accès

Création d'un index

Obtenir des points de terminaison de service

Créer un environnement virtuel

Connexion à Azure

Configurer la requête et le thread de conversation

Envoyer une requête RAG complexe

Résolution des erreurs

Nettoyer

Prérequis

Configurer l’accès

Création d'un index

Obtenir des points de terminaison de service

Configurer des variables d’environnement pour le développement local

Configurer le projet Node.JS

Connexion à Azure

Configurer le thread de requête et de conversation

Résolution des problèmes

Envoyer une requête RAG complexe

Résolution des erreurs

Nettoyer

Prérequis

Configurer l’accès

Création d'un index

Obtenir des points de terminaison de service

Configurer des variables d’environnement pour le développement local

Configurer le projet Node.JS

Connexion à Azure

Configurer le thread de requête et de conversation

Résolution des problèmes

Envoyer une requête RAG complexe

Résolution des erreurs

Nettoyer

Contenu connexe

Commentaires

Ressources supplémentaires