Usar um índice de Pesquisa de IA existente com a ferramenta Azure AI Search

Use um índice existente do Azure AI Search com a ferramenta Azure AI Search do agente.

Nota

Os índices do Azure AI Search devem atender aos seguintes requisitos:

• O índice deve conter pelo menos um campo de texto pesquisável & recuperável (digite Edm.String)
• O índice deve conter pelo menos um campo vetorial pesquisável (tipo Collection(Edm.Single))
• O índice deve usar um perfil vetorial/vetorização integrada

Tipos de pesquisa

Índice sem configuração semântica

• Por padrão, a ferramenta Azure AI Search executa uma pesquisa híbrida (palavra-chave + vetor) em todos os campos de texto.
  

Índice com configuração semântica

• Por padrão, a ferramenta Azure AI Search executa a pesquisa híbrida + semântica em todos os campos de texto.

Configuração: crie um agente que possa usar um índice existente do Azure AI Search

Pré-requisito: Ter um índice existente do Azure AI Search

Um pré-requisito para usar a ferramenta Azure AI Search é ter um índice existente do Azure AI Search. Se você não tiver um índice existente, poderá criar um no portal do Azure usando o assistente de importação e vetorização de dados.

• Guia de início rápido: criar um índice de vetor com o assistente de importação e vetorização de dados no portal do Azure

Criar uma conexão de projeto com o recurso Azure AI Search com o índice que você deseja usar

Depois de concluir a configuração do agente, você deve criar uma conexão de projeto com o recurso Azure AI Search que contém o índice que você deseja usar.

Se você já conectou o recurso AI Search que contém o índice que deseja usar ao seu projeto, ignore esta etapa.

Obter sua chave de conexão de recurso do Azure AI Search e ponto de extremidade

1. Acesse seu recurso Azure AI Search.

   • No portal do Azure, navegue até o recurso AI Search que contém o índice que você deseja usar.

2. Copie o ponto de extremidade de conexão.

   • Na guia Visão geral, copie a URL do seu recurso. O URL deve estar no formato https://<your-resource-name>.search.windows.net/.

3. Verifique se o controle de acesso à API está definido como Ambos e copie uma das chaves em Gerenciar chaves de administrador.

   • Na barra de navegação à esquerda, role para baixo até a seção Configurações e selecione Teclas.
   • Na seção Controle de acesso à API, verifique se a opção Chave de API e Controle de acesso baseado em função está selecionada.
   • Se você quiser que a conexão use chaves de API para autenticação, copie uma das chaves em Gerenciar chaves de administração.

Criar uma conexão de projeto do Azure AI Search

Se você usar a ID do Microsoft Entra para o tipo de autenticação de conexão, precisará atribuir manualmente a identidade gerenciada do projeto às funções Colaborador de Dados de Índice de Pesquisa e Colaborador do Serviço de Pesquisa ao recurso Azure AI Search.

CLI do Azure

Crie o seguinte arquivo connections.yml

Você pode usar uma chave de API ou um arquivo de configuração YAML sem credenciais. Substitua os espaços reservados para nameo , endpoint e api_key pelos seus valores de recurso do Azure AI Search. Para obter mais informações sobre o arquivo de configuração YAML, consulte o esquema YAML de conexão do Azure AI Search.

• Exemplo de chave de API:

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

• Sem credenciais

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

Em seguida, execute o seguinte comando:

Substitua my_resource e my_project_name pelo grupo de recursos e nome do projeto criados na configuração do agente.

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

Python

Substitua os espaços reservados my_connection_name, my_endpointe my_key (opcional) pelos detalhes de conexão do Azure AI Search e execute o código a seguir para criar uma conexão de projeto com seu recurso 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. No Azure AI Foundry, navegue até o projeto criado na configuração do agente. Clique em Abrir no centro de gerenciamento.

2. Clique na guia Conexões e selecione Adicionar conexão.

3. Selecione Azure AI Search.

4. Forneça os detalhes de conexão necessários para o recurso Azure AI Search que você deseja usar. Há suporte para Identidade Gerenciada e autenticação baseada em chave. Depois que todos os campos estiverem preenchidos, clique em Adicionar conexão.

5. Verifique se a conexão foi criada com êxito e agora aparece na guia Conexões do projeto.

Agora que você criou uma conexão de projeto com seu recurso Azure AI Search, você pode configurar e começar a usar a ferramenta Azure AI Search com o SDK. Consulte a guia de exemplos de código para começar.

Guia de início rápido – Usar um índice existente do Azure AI Search com a ferramenta Azure AI Search

Este guia de início rápido mostra como usar um índice existente do Azure AI Search com a ferramenta Azure AI Search.

Pré-requisitos

Conclua a configuração da ferramenta Azure AI Search.

Etapa 1: Criar um cliente de IA do Azure

Primeiro, crie um Cliente de IA do Azure usando a cadeia de conexão do seu projeto.

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

Etapa 2: Obter a ID de conexão para o recurso Azure AI Search

Obtenha a ID de conexão da conexão do Azure AI Search no projeto. Você pode usar o trecho de código para imprimir a ID de conexão de todas as conexões do Azure AI Search no projeto.

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

A segunda maneira de obter a ID de conexão é navegar até o projeto no Azure AI Foundry e clicar na guia Recursos conectados e, em seguida, selecionar seu recurso Azure AI Search. No URL, você vê o wsid=/subscription/your-subscription-id..., este é o ID de conexão que você precisa usar. Copie tudo o que vem depois de wsid=.

Etapa 3: Configurar a ferramenta Azure AI Search

Usando a ID de conexão obtida na etapa anterior, agora você pode configurar a ferramenta Azure AI Search para usar seu índice 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>") }
    }
};

Etapa 4: Criar um agente com a ferramenta Azure AI Search habilitada

Altere o modelo para o implantado em seu projeto. Você pode encontrar o nome do modelo no Azure AI Foundry na guia Modelos . Você também pode alterar o nome e as instruções do agente para atender às suas necessidades.

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;

Etapa 5: Faça perguntas ao agente sobre os dados no índice

Agora que o agente foi criado, faça perguntas sobre os dados em seu índice do Azure AI Search. O exemplo pressupõe que seu índice do Azure AI Search contenha informações sobre planos de saúde.

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