Partilhar 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 é uma funcionalidade do lado da consulta que usa a compreensão de leitura de máquina da Microsoft para repontuar os resultados da pesquisa, promovendo as correspondências semanticamente mais 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 você pelas modificações de índice e consulta que invocam o classificador semântico.

Nota

Para obter um exemplo de solução do Azure AI Search com interação ChatGPT, consulte esta demonstração ou este acelerador.

Pré-requisitos

  • Uma conta do Azure com uma subscrição ativa. Você pode criar uma conta gratuitamente.

  • Um recurso do Azure AI Search, na camada Básica ou superior, com o classificador semântico habilitado.

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

    Em Visão geral, copie o URL e salve-o para uma etapa posterior. Um ponto final de exemplo poderá ser parecido com https://mydemo.search.windows.net.

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

    Captura de ecrã a mostrar onde encontrar o ponto de extremidade HTTP e a chave de acesso do seu 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 seu conteúdo, pois 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 o 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 cliente Azure.Search.Documents para adicionar classificação semântica a um índice de pesquisa existente.

Como alternativa, você pode baixar o código-fonte para começar com um projeto concluído.

Configurar o 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 Solução....

  3. Selecione Procurar.

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

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

Criar um cliente de pesquisa

  1. Em Program.cs, aditar as seguintes using diretivas.

    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 os clientes precisam do ponto de extremidade do serviço e de uma chave de API de administrador 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 serviceName propriedade. 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);
     . . . 
 }

Criar um índice

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

// 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 no seu serviço de pesquisa:

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

SearchClient ingesterClient = adminClient.GetSearchClient(indexName);

Carregar documentos

O Azure AI Search pesquisa sobre o conteúdo armazenado no serviço. O código para carregar documentos é idêntico ao início rápido em C# para pesquisa de texto completo, por isso 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 partidas classificadas por BM25.

Em contraste, 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 melhor resultado é o hotel com o restaurante, que se alinha melhor às expectativas dos usuários.

Captura de ecrã a mostrar correspondências classificadas com base na classificação semântica.

Execute o programa

Pressione F5 para reconstruir o aplicativo e executar o programa em sua totalidade.

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

Clean up resources (Limpar recursos)

Ao trabalhar na sua própria subscrição, recomendamos que verifique, depois de concluir um projeto, se ainda vai precisar dos recursos que criou. Os recursos que deixar em execução podem custar dinheiro. Pode eliminar recursos individualmente ou eliminar o grupo de recursos para eliminar todo o conjunto de recursos.

Você pode localizar e gerenciar recursos no portal do Azure, usando o link Todos os recursos ou Grupos de recursos no painel de navegação esquerdo.

Próximos passos

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

Tutorial: Adicionar pesquisa a aplicações Web