Utiliser un index AI Search existant avec l'outil Azure AI Search

Utiliser un index Azure AI Search existant avec l'outil Azure AI Search de l’agent.

Remarque

Les index Azure AI Search doivent respecter les critères suivants :

• L'index doit contenir au moins un champ de texte consultable et récupérable (type Edm.String)
• L'index doit contenir au moins un champ vectoriel consultable (type Collection(Edm.Single))
• L'index doit utiliser un profil vectoriel ou une vectorisation intégrée

Rechercher dans les types

Index sans configuration sémantique

• Par défaut, l'outil Azure AI Search exécute une recherche hybride (mot-clé + vecteur) sur tous les champs de texte.
  

Index avec configuration sémantique

• Par défaut, l'outil Azure AI Search exécute une recherche hybride et sémantique sur tous les champs de texte.

Prise en charge de l’utilisation

Prise en charge d’Azure AI Foundry	Kit de développement logiciel (SDK) Python	Kit de développement logiciel (SDK) C#	Kit de développement logiciel (SDK) JavaScript	API REST	Configuration d’agent de base	Configuration d’agent standard
✔️	✔️	✔️	✔️	✔️	✔️	✔️

Configuration : créez un agent qui peut utiliser un index Azure AI Search existant

Prérequis : disposer d'un index Azure AI Search existant

Pour utiliser l'outil Azure AI Search, il faut disposer d'un index Azure AI Search existant. Si vous n'avez pas d'index existant, vous pouvez en créer un dans le Portail Microsoft Azure à l'aide de l'assistant d'importation et de vectorisation des données.

• Démarrage rapide : créer un index vectoriel avec l'assistant d'importation et de vectorisation des données dans le Portail Microsoft Azure

Créez une connexion de projet à la ressource Azure AI Search avec l'index que vous souhaitez utiliser

Une fois la configuration de l'agent terminée, vous devez créer une connexion de projet à la ressource Azure AI Search qui contient l'index que vous souhaitez utiliser.

Si vous avez déjà connecté à votre projet la ressource AI Search qui contient l'index que vous souhaitez utiliser, ignorez cette étape.

Obtenez votre clé de connexion à la ressource Azure AI Search et votre point de terminaison

1. Accédez à votre ressource Recherche Azure AI.

   • Dans le Portail Microsoft Azure, accédez à la ressource AI Search qui contient l’index à utiliser.

2. Copiez le point de terminaison de connexion.

   • Dans l'onglet Aperçu, copiez l'URL de votre ressource. L’URL doit être au format https://<your-resource-name>.search.windows.net/.

3. Vérifiez que le contrôle d'accès à l'API est défini sur Les deux et copiez l'une des clés sous Gérer les clés d'administration.

   • Dans la barre de navigation de gauche, descendez jusqu'à la section Paramètres et sélectionnez Clés.
   • Dans la section Contrôle d'accès à l'API, assurez-vous que l'option Les deux pour Contrôle d'accès basé sur la clé API et sur le rôle est sélectionnée.
   • Si vous souhaitez que la connexion utilise des clés API pour l'authentification, copiez l'une des clés sous Gérer les clés d’administration.

Créer une connexion de projet Recherche Azure AI

Si vous utilisez Microsoft Entra ID pour le type d'authentification de la connexion, vous devez attribuer manuellement à l'identité gérée par le projet les rôles Search Index Data Contributor et Search Service Contributor à la ressource Azure AI Search.

Azure CLI

Créez le fichier connections.yml suivant

Vous pouvez utiliser une clé API ou un fichier de configuration YAML sans informations d’identification. Remplacez les caractères de remplacement pour name, endpoint et api_key par les valeurs de votre ressource Azure AI Search. Pour plus d’informations sur le fichier de configuration YAML, consultez le Schéma YAML des connexions Azure AI Search.

• Exemple de clé API :

  name: my_project_acs_connection_keys
  type: azure_ai_search
  endpoint: https://contoso.search.windows.net/
  api_key: XXXXXXXXXXXXXXX
  

• Sans information d’identification

  name: my_project_acs_connection_credentialless
  type: azure_ai_search
  endpoint: https://contoso.search.windows.net/
  

Exécutez ensuite la commande suivante :

Remplacez my_resource et my_project_name par votre groupe de ressources et votre nom de projet créés dans la configuration de l'agent.

az ml connection create --file {connection.yml} --resource-group {my_resource_group} --workspace-name {my_project_name}

Python

Remplacez les espaces réservés my_connection_name, my_endpoint et my_key (facultatif) par les détails de votre connexion Azure AI Search et exécutez le code suivant pour créer une connexion de projet à votre ressource Azure AI Search.

from azure.ai.ml.entities import AzureAISearchConnection

# create an Azure AI Search project connection
my_connection_name = "my-connection-name"
my_endpoint = "my-endpoint" # this could also be called target
my_api_keys = None # leave blank for Authentication type = AAD

my_connection = AzureAISearchConnection(name=my_connection_name,
                                    endpoint=my_endpoint, 
                                    api_key= my_api_keys)

# Create the connection
ml_client.connections.create_or_update(my_connection)

Azure AI Foundry

1. Dans Azure AI Foundry, accédez au projet que vous avez créé dans la configuration de l'agent. Cliquez sur Ouvrir dans le centre de gestion.

2. Cliquez sur l'onglet Connexions et sélectionnez Ajouter une connexion.

3. Sélectionnez Recherche Azure AI.

4. Fournissez les détails de connexion requis pour la ressource Azure AI Search que vous souhaitez utiliser. L'authentification par identité gérée et l'authentification par clé sont toutes deux prises en charge. Une fois tous les champs remplis, cliquez sur Ajouter une connexion.

5. Vérifiez que la connexion a été créée avec succès et qu'elle apparaît désormais dans l'onglet Connexions du projet.

Maintenant que vous avez créé une connexion de projet à votre ressource Azure AI Search, vous pouvez configurer et commencer à utiliser l'outil Azure AI Search avec le SDK. Voir l'onglet des exemples de code pour commencer.

Ajouter l’outil Recherche Azure AI à un agent

Vous pouvez ajouter l’outil Recherche Azure AI à un agent de façon programmatique à l’aide des exemples de code répertoriés en haut de cet article ou proposés dans le portail Azure AI Foundry. Si vous souhaitez utiliser le portail :

1. Dans l’écran Créer et déboguer de votre agent, faites défiler vers le bas le volet Configuration à droite jusqu’à connaissance. Sélectionnez ensuite Ajouter.

   

2. Sélectionnez Recherche Azure AI et suivez les invites pour ajouter l’outil.

   

Démarrage rapide : utiliser un index Azure AI Search existant avec l'outil Azure AI Search

Ce démarrage rapide montre comment utiliser un index Azure AI Search existant avec l'outil Azure AI Search.

Prérequis

Complétez la configuration de l'outil Azure AI Search.

Étape 1 : création d’un client Azure AI

Tout d'abord, créez un client Azure AI en utilisant la chaîne de connexion de votre projet.

Python

import os
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
from azure.ai.projects.models import AzureAISearchTool

# Create an Azure AI Client from a connection string, copied from your Azure AI Foundry project.
# At the moment, it should be in the format "<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<ProjectName>"
# HostName can be found by navigating to your discovery_url and removing the leading "https://" and trailing "/discovery" 
# To find your discovery_url, run the CLI command: az ml workspace show -n {project_name} --resource-group {resource_group_name} --query discovery_url
# Project Connection example: eastus.api.azureml.ms;my-subscription-id;my-resource-group;my-hub-name

connection_string = os.environ["PROJECT_CONNECTION_STRING"] 

project_client = AIProjectClient.from_connection_string(
    credential=DefaultAzureCredential(),
    conn_str=connection_string,
)

C#

using System;
using System.Threading.Tasks;
using Azure.Core;
using Azure.Core.TestFramework;
using NUnit.Framework;
using System.Collections.Generic;

// Create an Azure AI Client from a connection string, copied from your Azure AI Foundry project.
// At the moment, it should be in the format "<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<ProjectName>"
// Customer needs to login to Azure subscription via Azure CLI and set the environment variables
var connectionString = TestEnvironment.AzureAICONNECTIONSTRING;
var clientOptions = new AIProjectClientOptions();

// Adding the custom headers policy
clientOptions.AddPolicy(new CustomHeadersPolicy(), HttpPipelinePosition.PerCall);
var projectClient = new AIProjectClient(connectionString, new DefaultAzureCredential(), clientOptions);

JavaScript

const connectionString =
  process.env["AZURE_AI_PROJECTS_CONNECTION_STRING"] || "<project connection string>";

if (!connectionString) {
  throw new Error("AZURE_AI_PROJECTS_CONNECTION_STRING must be set in the environment variables");
}

const client = AIProjectsClient.fromConnectionString(
    connectionString || "",
    new DefaultAzureCredential(),
);

REST API

Suivez les instructions fournies dans Démarrage rapide de l’API REST pour définir les valeurs appropriées pour les variables d’environnement AZURE_AI_AGENTS_TOKEN et AZURE_AI_AGENTS_ENDPOINT.

Étape 2 : obtenir l'identifiant de connexion pour la ressource Azure AI Search

Obtenir l'identifiant de la connexion Azure AI Search dans le projet. Vous pouvez utiliser l'extrait de code pour imprimer l'ID de connexion de toutes les connexions Azure AI Search dans le projet.

Python

# AI Search resource connection ID
# This code looks for the AI Search Connection ID and saves it as variable conn_id

# If you have more than one AI search connection, try to establish the value in your .env file.
# Extract the connection list.
conn_list = project_client.connections._list_connections()["value"]
conn_id = ""

# Search in the metadata field of each connection in the list for the azure_ai_search type and get the id value to establish the variable
for conn in conn_list:
    metadata = conn["properties"].get("metadata", {})
    if metadata.get("type", "").upper() == "AZURE_AI_SEARCH":
        conn_id = conn["id"]
        break

C#

ListConnectionsResponse connections = await projectClient.GetConnectionsClient().GetConnectionsAsync(ConnectionType.AzureAISearch).ConfigureAwait(false);

        if (connections?.Value == null || connections.Value.Count == 0)
        {
            throw new InvalidOperationException("No connections found for the Azure AI Search.");
        }

JavaScript

const cognitiveServicesConnectionName = "<cognitiveServicesConnectionName>";
const cognitiveServicesConnection = await client.connections.getConnection(
  cognitiveServicesConnectionName,
);

REST API

Suivez les instructions fournies dans la section suivante pour obtenir l’ID de connexion à partir d’Azure AI Foundry.

La deuxième façon d'obtenir l'identifiant de connexion est de naviguer vers le projet dans Azure AI Foundry et de cliquer sur l'onglet Ressources connectées, puis de sélectionner votre ressource Azure AI Search. Dans l'URL, vous voyez le wsid=/subscription/your-subscription-id..., c'est l'identifiant de connexion que vous devez utiliser. Copiez tout ce qui vient après wsid=.

Étape 3 : configurer l’outil Recherche Azure AI

À l'aide de l'identifiant de connexion obtenu à l'étape précédente, vous pouvez maintenant configurer l'outil Azure AI Search pour qu'il utilise votre index Azure AI Search.

Python

# TO DO: replace this value with the connection ID of the search index
conn_id =  "/subscriptions/<your-subscription-id>/resourceGroups/<your-resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<your-project-name>/connections/<your-azure-ai-search-connection-name>"

# Initialize agent AI search tool and add the search index connection ID and index name
# TO DO: replace <your-index-name> with the name of the index you want to use
ai_search = AzureAISearchTool(index_connection_id=conn_id, index_name="<your-index-name>")

C#

// TO DO: replace this value with the connection ID of the search index
ConnectionResponse connection = connections.Value[0];

// Initialize agent Azure AI search tool and add the search index connection ID and index name
// TO DO: replace <your-index-name> with the name of the index you want to use
ToolResources searchResource = new ToolResources
{
    AzureAISearch = new AzureAISearchResource
    {
        IndexList = { new IndexResource(connection.Id, "<your-index-name>") }
    }
};

JavaScript

const azureAISearchTool = ToolUtility.createAzureAISearchTool(
  cognitiveServicesConnection.id,
  cognitiveServicesConnection.name,
);

// Create agent with the Azure AI search tool
const agent = await client.agents.createAgent("gpt-4o-mini", {
  name: "my-agent",
  instructions: "You are a helpful agent",
  tools: [azureAISearchTool.definition],
  toolResources: azureAISearchTool.resources,
});
console.log(`Created agent, agent ID : ${agent.id}`);

REST API

Non applicable

Étape 4 : créer un agent avec l'outil Azure AI Search activé

Changez le modèle pour celui déployé dans votre projet. Vous trouverez le nom du modèle dans Azure AI Foundry sous l'onglet Modèles. Vous pouvez également modifier le nom et les instructions de l'agent en fonction de vos besoins.

Python

agent = project_client.agents.create_agent(
    model="gpt-4o-mini",
    name="my-assistant",
    instructions="You are a helpful assistant",
    tools=ai_search.definitions,
    tool_resources = ai_search.resources,
)
print(f"Created agent, ID: {agent.id}")

C#

AgentsClient agentClient = projectClient.GetAgentsClient();

Response<Agent> agentResponse = await agentClient.CreateAgentAsync(
    model: "gpt-4o-mini",
    name: "my-assistant",
    instructions: "You are a helpful assistant.",
    tools: new List<ToolDefinition> { new AzureAISearchToolDefinition() },
    toolResources: searchResource);
Agent agent = agentResponse.Value;

JavaScript

const agent = await client.agents.createAgent("gpt-4o-mini", {
  name: "my-agent",
  instructions: "You are a helpful agent",
  tools: [azureAISearchTool.definition],
  toolResources: azureAISearchTool.resources,
});
console.log(`Created agent, agent ID : ${agent.id}`);

REST API

curl $AZURE_AI_AGENTS_ENDPOINT/assistants?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "instructions": "You are a helpful agent.",
        "name": "my-agent",
        "tools": [
          {"type": "azure_ai_search"}
        ],
        "model": "gpt-4o-mini",
        "tool_resources": {
            "azure_ai_search": {
              "indexes": [
                  {
                      "index_connection_id": "/subscriptions/<your-subscription-id>/resourceGroups/<your-resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<your-project-name>/connections/<your-azure-ai-search-connection-name>",
                      "index_name": "<your-index-name>",
                      "query_type": "semantic"
                  }
              ]
            }
        }
      }'

Étape 5 : poser à l'agent des questions sur les données contenues dans l'index

Maintenant que l'agent est créé, posez-lui des questions sur les données de votre index Azure AI Search. L'exemple suppose que votre index Azure AI Search contient des informations sur les régimes de soins de santé.

Python

# Create a thread
thread = project_client.agents.create_thread()
print(f"Created thread, thread ID: {thread.id}")
 
# Create a message
message = project_client.agents.create_message(
    thread_id=thread.id,
    role="user",
    content="what are my health insurance plan coverage types?",
)
print(f"Created message, message ID: {message.id}")
    
# Run the agent
run = project_client.agents.create_and_process_run(thread_id=thread.id, assistant_id=agent.id)
print(f"Run finished with status: {run.status}")
 
if run.status == "failed":
    # Check if you got "Rate limit is exceeded.", then you want to get more quota
    print(f"Run failed: {run.last_error}")

# Get messages from the thread 
messages = project_client.agents.list_messages(thread_id=thread.id)
print(f"Messages: {messages}")
    
assistant_message = ""
for message in messages.data:
    if message["role"] == "assistant":
        assistant_message = message["content"][0]["text"]["value"]

# Get the last message from the sender
print(f"Assistant response: {assistant_message}")

C#

// Create thread for communication
Response<AgentThread> threadResponse = await agentClient.CreateThreadAsync();
AgentThread thread = threadResponse.Value;

// Create message to thread
Response<ThreadMessage> messageResponse = await agentClient.CreateMessageAsync(
    thread.Id,
    MessageRole.User,
    "what are my health insurance plan coverage types?");
ThreadMessage message = messageResponse.Value;

// Run the agent
Response<ThreadRun> runResponse = await agentClient.CreateRunAsync(thread, agent);

do
{
    await Task.Delay(TimeSpan.FromMilliseconds(500));
    runResponse = await agentClient.GetRunAsync(thread.Id, runResponse.Value.Id);
}
while (runResponse.Value.Status == RunStatus.Queued
    || runResponse.Value.Status == RunStatus.InProgress);

Response<PageableList<ThreadMessage>> afterRunMessagesResponse
    = await agentClient.GetMessagesAsync(thread.Id);
IReadOnlyList<ThreadMessage> messages = afterRunMessagesResponse.Value.Data;

// Note: messages iterate from newest to oldest, with the messages[0] being the most recent
foreach (ThreadMessage threadMessage in messages)
{
    Console.Write($"{threadMessage.CreatedAt:yyyy-MM-dd HH:mm:ss} - {threadMessage.Role,10}: ");
    foreach (MessageContent contentItem in threadMessage.ContentItems)
    {
        if (contentItem is MessageTextContent textItem)
        {
            Console.Write(textItem.Text);
        }
        else if (contentItem is MessageImageFileContent imageFileItem)
        {
            Console.Write($"<image from ID: {imageFileItem.FileId}");
        }
        Console.WriteLine();
    }
}

JavaScript

  // create a thread
  const thread = await client.agents.createThread();

  // add a message to thread
  await client.agents.createMessage(
    thread.id, {
    role: "user",
    content: "what are my health insurance plan coverage types?",
  });

  // Intermission is now correlated with thread
  // Intermission messages will retrieve the message just added

  // create a run
  const streamEventMessages = await client.agents.createRun(thread.id, agent.id).stream();

  for await (const eventMessage of streamEventMessages) {
    switch (eventMessage.event) {
      case RunStreamEvent.ThreadRunCreated:
        break;
      case MessageStreamEvent.ThreadMessageDelta:
        {
          const messageDelta = eventMessage.data;
          messageDelta.delta.content.forEach((contentPart) => {
            if (contentPart.type === "text") {
              const textContent = contentPart;
              const textValue = textContent.text?.value || "No text";
            }
          });
        }
        break;

      case RunStreamEvent.ThreadRunCompleted:
        break;
      case ErrorEvent.Error:
        console.log(`An error occurred. Data ${eventMessage.data}`);
        break;
      case DoneEvent.Done:
        break;
    }
  }

  // Print the messages from the agent
  const messages = await client.agents.listMessages(thread.id);

  // Messages iterate from oldest to newest
  // messages[0] is the most recent
  for (let i = messages.data.length - 1; i >= 0; i--) {
    const m = messages.data[i];
    if (isOutputOfType<MessageTextContentOutput>(m.content[0], "text")) {
      const textContent = m.content[0];
      console.log(`${textContent.text.value}`);
      console.log(`---------------------------------`);
    }
  }

REST API

Créer un thread

curl $AZURE_AI_AGENTS_ENDPOINT/threads?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  -d ''

Ajouter une question utilisateur au thread

curl $AZURE_AI_AGENTS_ENDPOINT/threads/thread_abc123/messages?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "role": "user",
      "content": "what are my health insurance plan coverage types?"
    }'

Exécuter le thread

curl $AZURE_AI_AGENTS_ENDPOINT/threads/thread_abc123/runs?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "asst_abc123",
  }'

Récupérer l’état de l’exécution

curl $AZURE_AI_AGENTS_ENDPOINT/threads/thread_abc123/runs/run_abc123?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN"

Récupérer la réponse de l’agent

curl $AZURE_AI_AGENTS_ENDPOINT/threads/thread_abc123/messages?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN"