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

Use um índice de Pesquisa de IA do Azure existente com a ferramenta de Pesquisa de IA do Azure do agente.

Observação

Os índices de Pesquisa de IA do Azure devem atender aos seguintes requisitos:

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

Tipos de pesquisa

Indexar sem configuração semântica

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

Indexar com configuração semântica

• Por padrão, a ferramenta de Pesquisa de IA do Azure executa a pesquisa semântica e híbrida em todos os campos de texto.

Configuração: criar um agente que possa usar um índice existente da Pesquisa de IA do Azure

Pré-requisitos: ter um índice existente da Pesquisa de IA do Azure

Um pré-requisito de usar a ferramenta de Pesquisa de IA do Azure é ter um índice de Pesquisa de IA do Azure existente. Caso não tenha um índice existente, poderá criar um no portal do Azure usando o assistente de importação e vetorização de dados.

• 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 de Pesquisa de IA do Azure com o índice que você deseja usar

Após concluir a instalação do agente, crie uma conexão de projeto com o recurso de Pesquisa de IA do Azure que contém o índice que você deseja usar.

Caso já tenha conectado o recurso de Pesquisa de IA que contém o índice que deseja usar ao seu projeto, ignore esta etapa.

Obter a chave de conexão e o ponto de extremidade do recurso de Pesquisa de IA do Azure

1. Acesse o recurso de Pesquisa de IA do Azure.

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

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

   • No guia Visão geral, copie o URL do 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 Ambas 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 Chaves.
   • Na seção Controle de Acesso à API, verifique se a opção Ambas para Chave de API e Controle de acesso baseado em função está selecionada.
   • Caso queira que a conexão use chaves de API para autenticação, copie uma das chaves em Gerenciar chaves de administrador.

Criar uma conexão de projeto da Pesquisa de IA do Azure

Caso use o Microsoft Entra ID para o tipo de autenticação de conexão, será necessário atribuir manualmente a identidade gerenciada do projeto às funções de Colaborador de Dados de Índice de Pesquisa e Colaborador do Serviço de Pesquisa ao recurso de Pesquisa de IA do Azure.

CLI do Azure

Criar o arquivo de connections.yml a seguir

Você pode usar uma chave de API ou um arquivo de configuração YAML sem credencial. Substitua os espaços reservados para name, endpoint e api_key pelos valores de recurso do Pesquisa de IA do Azure. Para obter mais informações sobre o arquivo de configuração YAML, confira o esquema YAML de conexão da Pesquisa de IA do Azure.

• 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 credencial

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

Em seguida, execute o comando a seguir:

Substitua my_resource e my_project_name pelo seu grupo de recursos e o 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_endpoint e my_key (opcional) pelos detalhes da conexão da Pesquisa de IA do Azure e execute o código a seguir para criar uma conexão de projeto com o recurso de Pesquisa de IA do 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. Na Fábrica de IA do Azure, navegue até o projeto criado na configuração do agente. Selecione Abrir no centro de gerenciamento.

2. Selecione o guia Conexões e Adicionar Conexão.

3. Selecione Pesquisa de IA do Azure.

4. Forneça os detalhes de conexão necessários para o recurso da Pesquisa de IA do Azure que você deseja usar. Há suporte para identidade gerenciada e autenticação baseada em chave. Após preencher todos os campos, selecione Adicionar conexão.

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

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

Início Rápido – Usar um índice existente da Pesquisa de IA do Azure com a ferramenta de Pesquisa de IA do Azure

Este início rápido mostra como usar um índice existente da Pesquisa de IA do Azure com a ferramenta de Pesquisa de IA do Azure.

Pré-requisitos

Conclua a instalação da ferramenta de Pesquisa de IA do Azure.

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 de Pesquisa de IA do Azure

Obtenha a ID de conexão da Pesquisa de IA do Azure no projeto. Use o snippet de código para imprimir a ID de conexão de todas as conexões da Pesquisa de IA do Azure 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 na Fábrica de IA do Azure e selecionar o guia Recursos conectados e, em seguida, selecionar o recurso de Pesquisa de IA do Azure. No URL, você visualizará a wsid=/subscription/your-subscription-id..., essa é a ID de conexão que você precisa usar. Copie tudo o que vem depois de wsid=.

Etapa 3: configurar a ferramenta de Pesquisa de IA do Azure

Usando a ID de conexão que você obteve na etapa anterior, agora você pode configurar a ferramenta de Pesquisa de IA do Azure para usar o índice da Pesquisa de IA do 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>") }
    }
};

Etapa 4: criar um agente com a ferramenta de Pesquisa de IA do Azure habilitada

Altere o modelo para o implantado em seu projeto. É possível encontrar o nome do modelo na Fábrica de IA do Azure no guia Modelos. Também é possível 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: fazer perguntas ao agente sobre dados no índice

Agora que o agente foi criado, faça perguntas sobre os dados no índice de Pesquisa de IA do Azure. O exemplo pressupõe que o índice de Pesquisa de IA do Azure contém 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();
    }
}