Compartilhar via

Início Rápido: Classificação semântica usando .NET ou Python

Neste início rápido, você aprenderá sobre as modificações de índice e consulta que invocam o classificador semântico.

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 o mínimo de esforço do desenvolvedor.

Observação

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

Pré-requisitos

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

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

  • Uma chave de API e um endpoint de serviço de pesquisa. Para obtê-los:

    1. Entre no portal do Azure e localize seu serviço de pesquisa.

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

    3. 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("semantic-config", new()
            {
                TitleField = new SemanticField("HotelName"),
                ContentFields =
                {
                    new SemanticField("Description"),
                },
                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 = "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>("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. Considerando a consulta "restaurante no site", o algoritmo de classificação BM25 retorna correspondências na ordem mostrada nesta captura de tela, em que a correspondência no "site" é considerada mais relevante porque é rara em todo o conjunto de dados:

Captura de tela mostrando correspondências classificadas por BM25.

Por outro lado, quando a classificação semântica é aplicada à mesma consulta ("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. É possível 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 do Azure, usando o link Todos os recursos ou Grupos de recursos no painel de navegação à esquerda.

Próxima etapa

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 demonstrações, experimente o seguinte tutorial:

Tutorial: Adicionar pesquisa a aplicativos Web