Compartilhar via

Guia de Início Rápido: classificação semântica com .NET ou Python

  • Artigo

Na Pesquisa de IA do Azure, a classificação semântica é a funcionalidade do lado da consulta, que usa a compreensão de leitura de computador da Microsoft para pontuar os resultados da pesquisa, promovendo as correspondências mais semanticamente relevantes para o topo da lista. Dependendo do conteúdo e da consulta, a classificação semântica pode melhorar significativamente a relevância da pesquisa, com trabalho mínimo para o desenvolvedor.

Este guia de início rápido orienta sobre as modificações de índice e consulta que invocam o classificador semântico.

Observação

Para obter um exemplo de solução da Pesquisa de IA do Azure com interação com ChatGPT, consulte essa demonstração ou esse acelerador.

Pré-requisitos

  • Uma conta do Azure com uma assinatura ativa. Você pode criar uma conta gratuitamente.

  • Um recurso de Pesquisa de IA do Azure, na camada Básica ou superior, com classificador semântico habilitado.

  • Uma chave de API e um ponto de extremidade de serviço de pesquisa. Entre no portal do Azure e localize o serviço de pesquisa.

    Em Visão geral, copie a URL e salve-a para uma etapa posterior. Um ponto de extremidade de exemplo pode parecer com https://mydemo.search.windows.net.

    Em Chaves, copie e salve uma chave de administrador para obter direitos completos para criar e excluir objetos. Há duas chaves primárias e secundárias intercambiáveis. Escolha uma delas.

    Captura de tela mostrando onde encontrar o ponto de extremidade HTTP e a chave de acesso do serviço de pesquisa.

Adicionar classificação semântica

Para usar o classificador semântico, adicione uma configuração semântica a um índice de pesquisa e adicione parâmetros a uma consulta. Se você tiver um índice existente, poderá fazer essas alterações sem precisar reindexar o conteúdo porque não há impacto na estrutura do conteúdo pesquisável.

  • Uma configuração semântica define uma ordem de prioridade para campos que contribuem com um título, palavras-chave e conteúdo usados na reclassificação semântica. A priorização de campo permite um processamento mais rápido.

  • As consultas que invocam o classificador semântico incluem parâmetros para tipo de consulta e se as legendas e respostas são retornadas. Você pode adicionar esses parâmetros à lógica de consulta existente. Não há conflito com outros parâmetros.

Crie um aplicativo de console usando a biblioteca de clientes Azure.Search.Documentspara adicionar classificação semântica a um índice de pesquisa existente.

Como alternativa, é possível baixar o código-fonte para começar com um projeto concluído.

Configure seu ambiente

  1. Inicie o Visual Studio e crie um novo projeto para um aplicativo de console.

  2. Em Ferramentas>Gerenciador de Pacotes NuGet, selecione Gerenciar Pacotes NuGet para a Solução... .

  3. Selecione Procurar.

  4. Pesquise pelo pacote do Azure.Search.Documents e selecione a versão estável mais recente.

  5. Selecione Instalar para adicionar o assembly ao projeto e à solução.

Criar um cliente de pesquisa

  1. Em Program.cs, adicione as diretivas using a seguir.

    using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.Models;

  2. Crie dois clientes: SearchIndexClient cria o índice e SearchClient carrega e consulta um índice existente.

    Ambos as clientes precisam do ponto de extremidade de serviço e de uma chave de API de administração para autenticação com direitos de criação/exclusão. No entanto, o código cria o URI para você, portanto, especifique apenas o nome do serviço de pesquisa para a propriedade serviceName. Não inclua https:// ou .search.windows.net.

     static void Main(string[] args)
 {
     string serviceName = "<YOUR-SEARCH-SERVICE-NAME>";
     string apiKey = "<YOUR-SEARCH-ADMIN-API-KEY>";
     string indexName = "hotels-quickstart";


     // Create a SearchIndexClient to send create/delete index commands
     Uri serviceEndpoint = new Uri($"https://{serviceName}.search.windows.net/");
     AzureKeyCredential credential = new AzureKeyCredential(apiKey);
     SearchIndexClient adminClient = new SearchIndexClient(serviceEndpoint, credential);

     // Create a SearchClient to load and query documents
     SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, credential);
     . . . 
 }

Crie um índice

Crie ou atualize um esquema de índice para incluir um SemanticConfiguration. Se você estiver atualizando um índice existente, essa modificação não exigirá uma reindexação porque a estrutura de seus documentos não será alterada.

// Create hotels-quickstart index
private static void CreateIndex(string indexName, SearchIndexClient adminClient)
{

    FieldBuilder fieldBuilder = new FieldBuilder();
    var searchFields = fieldBuilder.Build(typeof(Hotel));

    var definition = new SearchIndex(indexName, searchFields);
    var suggester = new SearchSuggester("sg", new[] { "HotelName", "Category", "Address/City", "Address/StateProvince" });
    definition.Suggesters.Add(suggester);
    definition.SemanticSearch = new SemanticSearch
    {
        Configurations =
        {
            new SemanticConfiguration("my-semantic-config", new()
            {
                TitleField = new SemanticField("HotelName"),
                ContentFields =
                {
                    new SemanticField("Description"),
                    new SemanticField("Description_fr")
                },
                KeywordsFields =
                {
                    new SemanticField("Tags"),
                    new SemanticField("Category")
                }
            })
        }
    };

    adminClient.CreateOrUpdateIndex(definition);
}

O código a seguir cria o índice em seu serviço de pesquisa:

// Create index
Console.WriteLine("{0}", "Creating index...\n");
CreateIndex(indexName, adminClient);

SearchClient ingesterClient = adminClient.GetSearchClient(indexName);

Carregue os documentos

O Azure AI Search pesquisa o conteúdo armazenado no serviço. O código para carregar documentos é idêntico ao início rápido do C# para pesquisa de texto completo, portanto, não precisamos duplicá-lo aqui. Você deve ter quatro hotéis com nomes, endereços e descrições. Sua solução deve ter tipos para hotéis e endereços.

Pesquisar um índice

Aqui está uma consulta que invoca o classificador semântico, com opções de pesquisa para especificar parâmetros:

Console.WriteLine("Example of a semantic query.");

options = new SearchOptions()
{
    QueryType = Azure.Search.Documents.Models.SearchQueryType.Semantic,
    SemanticSearch = new()
    {
        SemanticConfigurationName = "my-semantic-config",
        QueryCaption = new(QueryCaptionType.Extractive)
    }
};
options.Select.Add("HotelName");
options.Select.Add("Category");
options.Select.Add("Description");

// response = srchclient.Search<Hotel>("*", options);
response = srchclient.Search<Hotel>("what hotel has a good restaurant on site", options);
WriteDocuments(response);

Para comparação, aqui estão os resultados de uma consulta que usa a classificação BM25 padrão, com base na frequência e proximidade do termo. Dada a consulta "qual hotel tem um bom restaurante no local", o algoritmo de classificação BM25 retorna correspondências na ordem mostrada nesta captura de tela:

Captura de tela mostrando correspondências classificadas por BM25.

Por outro lado, quando a classificação semântica é aplicada à mesma consulta ("qual hotel tem um bom restaurante no local"), os resultados são reclassificados com base na relevância semântica para a consulta. Desta vez, o principal resultado é o hotel com o restaurante, que se alinha melhor às expectativas do usuário.

Captura de tela mostrando correspondências classificadas com base em classificação semântica.

Executar o programa

Pressione F5 para reconstruir o aplicativo e executar o programa por completo.

A saída inclui mensagens de Console.WriteLine, com a adição de resultados e informações de consulta.

Limpar os recursos

Quando você está trabalhando em sua própria assinatura, é uma boa ideia identificar, no final de um projeto, se você ainda precisa dos recursos criados. Recursos deixados em execução podem custar dinheiro. Você pode excluir os recursos individualmente ou excluir o grupo de recursos para excluir todo o conjunto de recursos.

Você pode localizar e gerenciar recursos no portal usando o link Todos os recursos ou Grupos de recursos no painel de navegação à esquerda.

Próximas etapas

Neste início rápido, você aprendeu a invocar a classificação semântica em um índice existente. Recomendamos tentar a classificação semântica em seus próprios índices como uma próxima etapa. No entanto, se você quiser continuar com as demonstrações, visite o link a seguir.

Tutorial: Adicionar pesquisa a aplicativos Web