Usare un indice di Ricerca intelligenza artificiale esistente con lo strumento Ricerca intelligenza artificiale di Azure

Usare un indice di Ricerca intelligenza artificiale di Azure esistente con lo strumento ricerca di intelligenza artificiale di Azure dell'agente.

Nota

Gli indici di Ricerca intelligenza artificiale di Azure devono soddisfare i requisiti seguenti:

• L'indice deve contenere almeno un campo di testo ricercabile e recuperabile (tipo Edm.String)
• L'indice deve contenere almeno un campo vettore ricercabile (tipo Collection(Edm.Single))
• L'indice deve usare un profilo vettoriale o una vettorizzazione integrata

Tipi di ricerca

Indice senza configurazione semantica

• Per impostazione predefinita, lo strumento Ricerca intelligenza artificiale di Azure esegue una ricerca ibrida (parola chiave e vettore) in tutti i campi di testo.
  

Indice con configurazione semantica

• Per impostazione predefinita, lo strumento Ricerca intelligenza artificiale di Azure esegue la ricerca ibrida e semantica in tutti i campi di testo.

Installazione: creare un agente in grado di usare un indice di Ricerca intelligenza artificiale di Azure esistente

Prerequisito: avere un indice di Ricerca di intelligenza artificiale di Azure esistente

Un prerequisito per l'uso dello strumento Ricerca intelligenza artificiale di Azure consiste nell'avere un indice di Ricerca intelligenza artificiale di Azure esistente. Se non si dispone di un indice esistente, è possibile crearne uno nella portale di Azure usando l'importazione e la vettorializzazione guidata dei dati.

• Guida introduttiva: Creare un indice vettoriale con l'importazione e la vettorizzazione guidata dei dati nella portale di Azure

Creare una connessione di progetto alla risorsa di Ricerca intelligenza artificiale di Azure con l'indice da usare

Dopo aver completato l'installazione dell'agente, è necessario creare una connessione di progetto alla risorsa di Ricerca intelligenza artificiale di Azure contenente l'indice che si vuole usare.

Se è già stata connessa la risorsa di ricerca di intelligenza artificiale che contiene l'indice che si vuole usare per il progetto, ignorare questo passaggio.

Ottenere la chiave di connessione e l'endpoint della risorsa di Ricerca intelligenza artificiale di Azure

1. Accedere alla risorsa di Ricerca intelligenza artificiale di Azure.

   • Nella portale di Azure passare alla risorsa di ricerca di intelligenza artificiale che contiene l'indice che si vuole usare.

2. Copiare l'endpoint di connessione.

   • Nella scheda Panoramica copiare l'URL della risorsa. L'URL deve essere nel formato https://<your-resource-name>.search.windows.net/.

3. Verificare che il controllo di accesso all'API sia impostato su Entrambi e copiare una delle chiavi in Gestisci chiavi di amministrazione.

   • Dalla barra di spostamento a sinistra scorrere verso il basso fino alla sezione Impostazioni e selezionare Chiavi.
   • Nella sezione API Controllo di accesso verificare che sia selezionata l'opzione Chiave API e Controllo degli accessi in base al ruolo.
   • Se si vuole che la connessione usi le chiavi API per l'autenticazione, copiare una delle chiavi in Gestisci chiavi di amministrazione.

Creare una connessione al progetto di Ricerca intelligenza artificiale di Azure

Se si usa Microsoft Entra ID per il tipo di autenticazione della connessione, è necessario assegnare manualmente l'identità gestita dal progetto ai ruoli Collaboratore ai dati dell'indice di ricerca e Collaboratore al servizio di ricerca alla risorsa di Ricerca intelligenza artificiale di Azure.

Interfaccia della riga di comando di Azure

Creare il file di connections.yml seguente

È possibile usare una chiave API o un file di configurazione YAML senza credenziali. Sostituire i segnaposto per nameendpoint e api_key con i valori delle risorse di Ricerca intelligenza artificiale di Azure. Per altre informazioni sul file di configurazione YAML, vedere lo schema YAML della connessione di Ricerca di intelligenza artificiale di Azure.

• Esempio di chiave API:

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

• Senza credenziali

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

Eseguire quindi il comando seguente:

Sostituire my_resource e my_project_name con il gruppo di risorse e il nome del progetto creati nell'installazione dell'agente.

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

Python

Sostituire i segnaposto my_connection_name, my_endpointe my_key (facoltativo) con i dettagli della connessione di Ricerca intelligenza artificiale di Azure ed eseguire il codice seguente per creare una connessione di progetto alla risorsa di Ricerca di intelligenza artificiale di Azure.

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. In Azure AI Foundry passare al progetto creato nell'installazione dell'agente. Fare clic su Apri nel Centro gestione.

2. Fare clic sulla scheda Connessioni e selezionare Aggiungi connessione.

3. Selezionare Ricerca di intelligenza artificiale di Azure.

4. Specificare i dettagli di connessione necessari per la risorsa di Ricerca di intelligenza artificiale di Azure che si vuole usare. Sono supportate sia l'identità gestita che l'autenticazione basata su chiave. Dopo aver compilato tutti i campi, fare clic su Aggiungi connessione.

5. Verificare che la connessione sia stata creata correttamente e che sia ora visualizzata nella scheda Connessioni del progetto.

Dopo aver creato una connessione di progetto alla risorsa di Ricerca intelligenza artificiale di Azure, è possibile configurare e iniziare a usare lo strumento Ricerca intelligenza artificiale di Azure con l'SDK. Per iniziare, vedere la scheda degli esempi di codice.

Guida introduttiva: Usare un indice di Ricerca intelligenza artificiale di Azure esistente con lo strumento Ricerca intelligenza artificiale di Azure

Questa guida introduttiva illustra come usare un indice di Ricerca intelligenza artificiale di Azure esistente con lo strumento Ricerca intelligenza artificiale di Azure.

Prerequisiti

Completare la configurazione dello strumento Ricerca intelligenza artificiale di Azure.

Passaggio 1: Creare un client di intelligenza artificiale di Azure

Prima di tutto, creare un client di intelligenza artificiale di Azure usando il stringa di connessione del progetto.

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);

Passaggio 2: Ottenere l'ID connessione per la risorsa di Ricerca intelligenza artificiale di Azure

Ottenere l'ID connessione di Ricerca intelligenza artificiale di Azure nel progetto. È possibile usare il frammento di codice per stampare l'ID connessione di tutte le connessioni di Ricerca intelligenza artificiale di Azure nel progetto.

Python

# AI Search resource connection ID
# This code prints out the connection ID of all the Azure AI Search connections in the project
# If you have more than one AI search connection, make sure to select the correct one that contains the index you want to use.
conn_list = project_client.connections.list()
conn_id = ""
for conn in conn_list:
    if conn.connection_type == "AZURE_AI_SEARCH":
        print(f"Connection ID: {conn.id}")

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.");
        }

Il secondo modo per ottenere l'ID connessione consiste nel passare al progetto in Azure AI Foundry e fare clic sulla scheda Risorse connesse e quindi selezionare la risorsa di Ricerca di intelligenza artificiale di Azure. Nell'URL viene visualizzato wsid=/subscription/your-subscription-id..., questo è l'ID di connessione che è necessario usare. Copiare tutto ciò che viene dopo wsid=.

Passaggio 3: Configurare lo strumento Ricerca intelligenza artificiale di Azure

Usando l'ID connessione ottenuto nel passaggio precedente, è ora possibile configurare lo strumento Ricerca intelligenza artificiale di Azure per usare l'indice di Ricerca intelligenza artificiale di Azure.

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>") }
    }
};

Passaggio 4: Creare un agente con lo strumento Ricerca intelligenza artificiale di Azure abilitato

Modificare il modello in quello distribuito nel progetto. È possibile trovare il nome del modello in Azure AI Foundry nella scheda Modelli . È anche possibile modificare il nome e le istruzioni dell'agente in base alle proprie esigenze.

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;

Passaggio 5: Porre domande all'agente sui dati nell'indice

Dopo aver creato l'agente, porre domande sui dati nell'indice di Ricerca di intelligenza artificiale di Azure. L'esempio presuppone che l'indice di Ricerca intelligenza artificiale di Azure contenga informazioni sui piani di assistenza sanitaria.

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,
    "Hello, send an email with the datetime and weather information in New York?");
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();
    }
}