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 você pelas modificações de índice e consulta que invocam a classificação semântica.

Observação

Procurando uma solução do Azure AI Search com interação chatGPT? Consulte esta demonstração ou este acelerador para obter detalhes.

Pré-requisitos

  • Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.

  • Azure AI Search, na camada Básica ou superior, com classificação semântica habilitada.

  • 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 no Bloco de Notas 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.

    Get an HTTP endpoint and access key

Adicionar classificação semântica

Para usar a classificação semântica, 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 a classificação semântica 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, você pode baixar o código-fonte para começar com um projeto concluído, ou seguir as etapas neste artigo para criar o seu.

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 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 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.

    Como o código cria o URI para você, especifique apenas o nome do serviço de pesquisa na propriedade "serviceName".

     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 a classificação semântica, 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:

Screenshot showing matches ranked by 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.

Screenshot showing matches ranked based on semantic ranking.

Executar o programa

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

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