Início Rápido: Classificação semântica

Neste início rápido, você usará a biblioteca de clientes Pesquisa de IA do Azure  para .NET para adicionar classificação semântica a um índice de pesquisa existente e consultar o índice.

A classificação semântica é uma funcionalidade do lado da consulta que utiliza a compreensão de leitura por máquina para reavaliar os resultados da pesquisa, promovendo as correspondências mais semanticamente relevantes ao topo da lista. Você pode adicionar uma configuração semântica a um índice existente sem nenhum requisito de recompilação. A classificação semântica é mais eficaz para texto informativo ou descritivo.

Dica

Quer começar imediatamente? Baixe o source code no GitHub.

Pré-requisitos

• Uma conta Azure com uma assinatura ativa. Criar uma conta gratuita.

• Um serviço de Busca de IA do Azure com o classificador semântico habilitado.

• Um índice com campos de texto descritivos atribuídos como e . Este início rápido pressupõe o índice de exemplo de hotéis.

• .NET 9 ou posterior.

• Visual Studio Code.

• Git para clonar o repositório de exemplo.

• O CLI do Azure para autenticação sem chave com Microsoft Entra ID.

Configurar acesso

Antes de começar, verifique se você tem permissões para acessar o conteúdo e as operações no Pesquisa de IA do Azure . Este início rápido usa Microsoft Entra ID para autenticação e acesso baseado em função para autorização. Você deve ser um Owner ou User Access Administrator para atribuir funções. Se as funções não forem viáveis, use a autenticação baseada em chave.

Para configurar o acesso recomendado baseado em papéis:

1. Habilitar acesso baseado em função para seu serviço de busca.

2. Atribua as seguintes funções à sua conta de usuário.

   • Colaborador do Search Service

   • Leitor de dados de índice de pesquisa

Observação

Ao contrário de outros tutoriais rápidos que criam e carregam um índice, este tutorial presume que um índice já existe e contém dados, então você não precisa da função de Colaborador de Dados do Índice de Pesquisa.

Obter o ponto de extremidade

Cada serviço de Pesquisa de IA do Azure tem um endpoint, que é uma URL exclusiva que identifica e fornece acesso de rede ao serviço. Em uma seção posterior, especifique esse ponto de extremidade para se conectar ao seu serviço de busca programaticamente.

Para acessar o endpoint:

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

2. No painel esquerdo, selecione Visão geral.

3. Anote o endpoint, que deve se parecer com https://my-service.search.windows.NET.

Começar com um índice

Este início rápido modifica um índice existente para incluir uma configuração semântica. Recomendamos o índice de exemplo de hotéis, que você pode criar em minutos usando um assistente de portal do Azure.

Para usar um índice diferente, substitua o nome do índice, os nomes de campo na configuração semântica e os nomes de campo em instruções de consulta em todo o código de exemplo. Seu índice deve conter campos de texto descritivos que são atribuídos como e .

Para examinar e consultar o índice de exemplo de hotéis antes da classificação semântica:

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

2. No painel esquerdo, selecione gerenciamento de pesquisaÍndices.

3. Selecione amostra de hotéis.

4. Selecione configurações semânticas para exibir as configurações existentes. Se você habilitou a classificação semântica durante o fluxo de criação do assistente, deve haver uma configuração padrão.

   

5. Selecione o Explorador de Pesquisa e, em seguida, selecione a Exibição JSON.

6. Cole o JSON a seguir no editor de consultas.

   {
     "search": "walking distance to live music",
     "select": "HotelId, HotelName, Description",
     "count": true
   }
   

7. Selecione Pesquisar para executar a consulta.

   A resposta deve ser semelhante ao exemplo a seguir. Essa é uma consulta de texto completo classificada por BM25, portanto, os resultados correspondem a termos de consulta individuais e variantes linguísticas, em vez do significado geral da consulta. Por exemplo, corresponde , e e correspondem independentemente, em vez de compor uma frase.

   "@odata.count": 30,
   "value": [
     {
       "@search.score": 5.004435,
       "HotelId": "2",
       "HotelName": "Old Century Hotel",
       "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
     },
     {
       "@search.score": 4.555706,
       "HotelId": "24",
       "HotelName": "Uptown Chic Hotel",
       "Description": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance."
     },
     {
       "@search.score": 3.5625167,
       "HotelId": "4",
       "HotelName": "Sublime Palace Hotel",
       "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
     },
     ... // Trimmed for brevity
   ]
   

   Dica

   Esta consulta mostra a aparência da resposta antes da classificação semântica ser aplicada. Depois de configurar uma configuração semântica, adicione e veja como a mesma consulta é classificada de forma diferente por classificação semântica.

Configurar o ambiente

1. Use o Git para clonar o repositório de exemplo.

   git clone https://github.com/Azure-Samples/azure-search-dotnet-samples
   

2. Navegue até a pasta de início rápido e abra-a no Visual Studio Code.

   cd azure-search-dotnet-samples/quickstart-semantic-ranking
   code .
   

3. Em , substitua o valor do espaço reservado pela URL obtida em Obter ponto de extremidade.

4. Repita a etapa anterior para .

5. Para autenticação sem chave com Microsoft Entra ID, entre em sua conta Azure. Se você tiver várias assinaturas, selecione a que contém o serviço de pesquisa de IA do Azure.

   az login
   

Executar o código

1. Execute o primeiro project para atualizar o índice com uma configuração semântica.

   dotnet run --project BuildIndex
   

2. Execute o segundo projeto para consultar o índice. Pressione Enter entre consultas para ver a progressão da consulta simples para a consulta semântica com legendas e respostas.

   dotnet run --project QueryIndex
   

Saída

O primeiro projeto atualiza o índice de amostra de hotéis com uma configuração semântica. A saída inclui a confirmação da configuração semântica.

Here's a list of all indexes on the search service. You should see hotels-sample:
hotels-sample

Added new semantic configuration 'semantic-config' to the index definition.
Index updated successfully.
Here is the revised index definition:
{
  "Name": "hotels-sample",
  ... // Trimmed for brevity
  "SemanticSearch": {
    "DefaultConfigurationName": "semantic-config",
    "Configurations": [
      {
        "Name": "hotels-sample-semantic-configuration",
        ... // Trimmed for brevity
      },
      {
        "Name": "semantic-config",
        "PrioritizedFields": {
          "TitleField": {
            "FieldName": "HotelName"
          },
          "ContentFields": [
            {
              "FieldName": "Description"
            }
          ],
          "KeywordsFields": [
            {
              "FieldName": "Tags"
            }
          ]
        },
        "RankingOrder": {}
      }
    ]
  }
}

O segundo projeto executa quatro consultas. O resultado inclui os resultados da pesquisa com pontuações de relevância, legendas e respostas.

Query 1: Simple query using the search string 'walking distance to live music'.
HotelId: 2
HotelName: Old Century Hotel
Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.
@search.score: 5.004435
----------------------------------------
HotelId: 24
HotelName: Uptown Chic Hotel
Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.
@search.score: 4.555706
----------------------------------------
... // Trimmed for brevity
Press Enter to continue to the next query...


Query 2: Semantic query (no captions, no answers) for 'walking distance to live music'.
HotelId: 24
HotelName: Uptown Chic Hotel
Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.
@search.score: 4.555706
@search.rerankerScore: 2.613231658935547
----------------------------------------
HotelId: 2
HotelName: Old Century Hotel
Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.
@search.score: 5.004435
@search.rerankerScore: 2.271434783935547
----------------------------------------
... // Trimmed for brevity
Press Enter to continue to the next query...


Query 3: Semantic query with captions.
Caption: Chic hotel near the city. High-rise hotel in downtown, within walking distance to<em> theaters, </em>art galleries, restaurants and shops. Visit<em> Seattle Art Museum </em>by day, and then head over to<em> Benaroya Hall </em>to catch the evening's concert performance.
HotelId: 24
HotelName: Uptown Chic Hotel
Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.
@search.score: 4.555706
@search.rerankerScore: 2.613231658935547
----------------------------------------
... // Trimmed for brevity
Press Enter to continue to the next query...


Query 4: Semantic query with a verbatim answer from the Description field for 'what's a good hotel for people who like to read'.
Extractive Answers:
  Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the<em> library </em>by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.
----------------------------------------
... // Trimmed for brevity

Entender o código

Observação

Os snippets de código nesta seção podem ter sido modificados para legibilidade. Para obter um exemplo de trabalho completo, consulte o código-fonte.

Agora que você executou o código, vamos dividir as etapas principais:

1. Configuração e autenticação
2. Atualizar o índice com uma configuração semântica
3. Consultar o índice

Configuração e autenticação

Ambos os projetos compartilham o mesmo padrão de configuração. Os arquivos definem o ponto de extremidade de pesquisa e são utilizados para autenticação sem chave.

var endpoint = new Uri("PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE");
var credential = new DefaultAzureCredential();
var indexClient = new SearchIndexClient(endpoint, credential);

Principais conclusões:

• DefaultAzureCredential fornece autenticação sem chave usando Microsoft Entra ID. Ele encadeia diversos tipos de credenciais, incluindo a credencial do CLI do Azure proveniente de az login.
• gerencia operações de nível de índice, como atualizar o esquema de índice.
• manipula operações de nível de documento, como consultar o índice.

Atualizar o índice com uma configuração semântica

O código a seguir adiciona uma configuração semântica ao índice existente. Essa operação não exclui nenhum documento de pesquisa e seu índice permanece operacional depois que a configuração é adicionada.

static void AddSemanticConfiguration(
    SearchIndex index,
    string semanticConfigName)
{
    if (index.SemanticSearch == null)
    {
        index.SemanticSearch = new SemanticSearch();
    }
    var configs = index.SemanticSearch.Configurations;
    if (!configs.Any(c => c.Name == semanticConfigName))
    {
        var prioritizedFields =
            new SemanticPrioritizedFields
        {
            TitleField = new SemanticField("HotelName"),
            ContentFields =
            {
                new SemanticField("Description")
            },
            KeywordsFields =
            {
                new SemanticField("Tags")
            }
        };

        configs.Add(
            new SemanticConfiguration(
                semanticConfigName,
                prioritizedFields
            )
        );
    }
    index.SemanticSearch.DefaultConfigurationName =
        semanticConfigName;
}

Principais conclusões:

• Uma configuração semântica especifica os campos usados para classificação semântica.
• Configurações semânticas podem ser adicionadas a índices existentes sem recompilação.
• define o campo que representa o título do documento.
• define os campos que contêm o conteúdo principal.
• define os campos que contêm palavras-chave ou marcas.

Consultar o índice

O QueryIndex project executa quatro consultas em sequência, progredindo de uma pesquisa de palavra-chave simples para classificação semântica com legendas e respostas.

Consulta simples

A primeira consulta é uma pesquisa de palavra-chave simples que não usa classificação semântica. Essa consulta serve como uma linha de base para comparar resultados com e sem reclassificado semântico.

await RunQuery(client, searchText, new SearchOptions
{
    Size = 5,
    QueryType = SearchQueryType.Simple,
    IncludeTotalCount = true,
    Select = { "HotelId", "HotelName", "Description" }
});

Principais conclusões:

• usa o algoritmo de classificação BM25 padrão.
• Os resultados são classificados apenas pela relevância da palavra-chave ().

Consulta semântica (sem legendas, sem respostas)

A próxima consulta adiciona classificação semântica sem legendas ou respostas. O código a seguir mostra o requisito mínimo para invocar a classificação semântica.

var semanticOptions = new SearchOptions
{
    Size = 5,
    QueryType = SearchQueryType.Semantic,
    SemanticSearch = new SemanticSearchOptions
    {
        SemanticConfigurationName = "semantic-config"
    },
    IncludeTotalCount = true,
    Select =
    {
        "HotelId", "HotelName", "Description"
    }
};
await RunQuery(client, searchText, semanticOptions);

Principais conclusões:

• habilita a classificação semântica na consulta.
• especifica qual configuração semântica usar.
• indica relevância semântica (maior é melhor).
• Os resultados iniciais da consulta de termo são pontuados novamente usando modelos de classificação semântica. Para esse conjunto de dados e consulta, os efeitos da classificação semântica são mais pronunciados nos resultados de classificação inferior.

Consulta semântica com legendas

O código a seguir adiciona legendas para extrair as passagens mais relevantes de cada resultado, com realce de clique aplicado aos termos e frases importantes.

var captionsOptions = new SearchOptions
{
    Size = 5,
    QueryType = SearchQueryType.Semantic,
    SemanticSearch = new SemanticSearchOptions
    {
        SemanticConfigurationName = "semantic-config",
        QueryCaption =
            new QueryCaption(QueryCaptionType.Extractive)
        {
            HighlightEnabled = true
        }
    },
    IncludeTotalCount = true,
    Select =
    {
        "HotelId", "HotelName", "Description"
    }
};
captionsOptions.HighlightFields.Add("Description");
await RunQuery(
    client, searchText, captionsOptions, showCaptions: true
);

Principais conclusões:

• permite a extração de legendas dos campos de conteúdo.
• As legendas destacam as passagens mais relevantes e adicionam marcas <em> ao redor de termos importantes.

Consulta semântica com respostas

A consulta final adiciona respostas semânticas. Essa consulta usa uma cadeia de caracteres de pesquisa diferente () porque as respostas semânticas funcionam melhor quando a consulta é formulada como uma pergunta. A resposta é uma passagem verbatim extraída do índice, não uma resposta composta de um modelo de conclusão de chat.

A consulta e o conteúdo indexado devem ser alinhados de perto para que uma resposta seja retornada. Se nenhum candidato atingir o limite de confiança, a resposta não inclui uma resposta. Este exemplo usa uma pergunta que é conhecida por produzir um resultado para que você possa ver a sintaxe. Se as respostas não forem úteis para seu cenário, omita do código. Para respostas compostas, considere um padrão RAG ou recuperação agente.

var answersOptions = new SearchOptions
{
    Size = 5,
    QueryType = SearchQueryType.Semantic,
    SemanticSearch = new SemanticSearchOptions
    {
        SemanticConfigurationName = "semantic-config",
        QueryAnswer =
            new QueryAnswer(QueryAnswerType.Extractive)
    },
    IncludeTotalCount = true,
    Select =
    {
        "HotelId", "HotelName", "Description"
    }
};
await RunQuery(
    client, searchText2, answersOptions, showAnswers: true
);

Principais conclusões:

• permite respostas extrativas para consultas semelhantes a perguntas.
• As respostas são conteúdo verbatim extraído do índice, não do texto gerado.

Neste início rápido, você usará a biblioteca de clientes Pesquisa de IA do Azure  para Java para adicionar semantic ranking a um índice de pesquisa existente e consultar o índice.

A classificação semântica é uma funcionalidade do lado da consulta que utiliza a compreensão de leitura por máquina para reavaliar os resultados da pesquisa, promovendo as correspondências mais semanticamente relevantes ao topo da lista. Você pode adicionar uma configuração semântica a um índice existente sem nenhum requisito de recompilação. A classificação semântica é mais eficaz para texto informativo ou descritivo.

Dica

Quer começar imediatamente? Baixe o source code no GitHub.

Pré-requisitos

• Uma conta Azure com uma assinatura ativa. Criar uma conta gratuita.

• Um serviço de Busca de IA do Azure com o classificador semântico habilitado.

• Um índice com campos de texto descritivos atribuídos como e . Este início rápido pressupõe o índice de exemplo de hotéis.

• Java 21 (LTS) e Maven.

• Visual Studio Code.

• Git para clonar o repositório de exemplo.

• O CLI do Azure para autenticação sem chave com Microsoft Entra ID.

Configurar acesso

Antes de começar, verifique se você tem permissões para acessar o conteúdo e as operações no Pesquisa de IA do Azure . Este início rápido usa Microsoft Entra ID para autenticação e acesso baseado em função para autorização. Você deve ser um Owner ou User Access Administrator para atribuir funções. Se as funções não forem viáveis, use a autenticação baseada em chave.

Para configurar o acesso recomendado baseado em papéis:

1. Habilitar acesso baseado em função para seu serviço de busca.

2. Atribua as seguintes funções à sua conta de usuário.

   • Colaborador do Search Service

   • Leitor de dados de índice de pesquisa

Observação

Ao contrário de outros tutoriais rápidos que criam e carregam um índice, este tutorial presume que um índice já existe e contém dados, então você não precisa da função de Colaborador de Dados do Índice de Pesquisa.

Obter o ponto de extremidade

Cada serviço de Pesquisa de IA do Azure tem um endpoint, que é uma URL exclusiva que identifica e fornece acesso de rede ao serviço. Em uma seção posterior, especifique esse ponto de extremidade para se conectar ao seu serviço de busca programaticamente.

Para acessar o endpoint:

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

2. No painel esquerdo, selecione Visão geral.

3. Anote o endpoint, que deve se parecer com https://my-service.search.windows.NET.

Começar com um índice

Este início rápido modifica um índice existente para incluir uma configuração semântica. Recomendamos o índice de exemplo de hotéis, que você pode criar em minutos usando um assistente de portal do Azure.

Para usar um índice diferente, substitua o nome do índice, os nomes de campo na configuração semântica e os nomes de campo em instruções de consulta em todo o código de exemplo. Seu índice deve conter campos de texto descritivos que são atribuídos como e .

Para examinar e consultar o índice de exemplo de hotéis antes da classificação semântica:

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

2. No painel esquerdo, selecione gerenciamento de pesquisaÍndices.

3. Selecione amostra de hotéis.

4. Selecione configurações semânticas para exibir as configurações existentes. Se você habilitou a classificação semântica durante o fluxo de criação do assistente, deve haver uma configuração padrão.

   

5. Selecione o Explorador de Pesquisa e, em seguida, selecione a Exibição JSON.

6. Cole o JSON a seguir no editor de consultas.

   {
     "search": "walking distance to live music",
     "select": "HotelId, HotelName, Description",
     "count": true
   }
   

7. Selecione Pesquisar para executar a consulta.

   A resposta deve ser semelhante ao exemplo a seguir. Essa é uma consulta de texto completo classificada por BM25, portanto, os resultados correspondem a termos de consulta individuais e variantes linguísticas, em vez do significado geral da consulta. Por exemplo, corresponde , e e correspondem independentemente, em vez de compor uma frase.

   "@odata.count": 30,
   "value": [
     {
       "@search.score": 5.004435,
       "HotelId": "2",
       "HotelName": "Old Century Hotel",
       "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
     },
     {
       "@search.score": 4.555706,
       "HotelId": "24",
       "HotelName": "Uptown Chic Hotel",
       "Description": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance."
     },
     {
       "@search.score": 3.5625167,
       "HotelId": "4",
       "HotelName": "Sublime Palace Hotel",
       "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
     },
     ... // Trimmed for brevity
   ]
   

   Dica

   Esta consulta mostra a aparência da resposta antes da classificação semântica ser aplicada. Depois de configurar uma configuração semântica, adicione e veja como a mesma consulta é classificada de forma diferente por classificação semântica.

Configurar o ambiente

1. Use o Git para clonar o repositório de exemplo.

   git clone https://github.com/Azure-Samples/azure-search-java-samples
   

2. Navegue até a pasta de início rápido e abra-a no Visual Studio Code.

   cd azure-search-java-samples/quickstart-semantic-ranking
   code .
   

3. Em src/main/resources/application.properties, substitua o valor do espaço reservado de Azure.search.endpoint pela URL que você obteve em Get endpoint.

4. Compile o projeto para resolver dependências, incluindo Azure-search-documents.

   mvn compile
   

   Quando o build for concluído, verifique se não há erros na saída.

5. Para autenticação sem chave com Microsoft Entra ID, entre em sua conta Azure. Se você tiver várias assinaturas, selecione a que contém o serviço de pesquisa de IA do Azure.

   az login
   

Executar o código

1. Obtenha as configurações de índice existentes.

   mvn compile exec:java "-Dexec.mainClass=com.azure.search.quickstart.GetIndexSettings"
   

2. Atualize o índice com uma configuração semântica.

   mvn compile exec:java "-Dexec.mainClass=com.azure.search.quickstart.UpdateIndexSettings"
   

3. Execute uma consulta semântica.

   mvn compile exec:java "-Dexec.mainClass=com.azure.search.quickstart.SemanticQuery"
   

4. Execute uma consulta semântica com legendas.

   mvn compile exec:java "-Dexec.mainClass=com.azure.search.quickstart.SemanticQueryWithCaptions"
   

5. Execute uma consulta semântica com respostas.

   mvn compile exec:java "-Dexec.mainClass=com.azure.search.quickstart.SemanticAnswer"
   

Saída

A saída é o nome do índice, seus campos e suas configurações semânticas. Antes de adicionar uma nova configuração, o índice tem apenas a padrão.

Index name: hotels-sample
Number of fields: 23
Field: HotelId, Type: Edm.String, Searchable: true
Field: HotelName, Type: Edm.String, Searchable: true
Field: Description, Type: Edm.String, Searchable: true
// Trimmed for brevity
Semantic search configurations: 1
Configuration name: hotels-sample-semantic-configuration

A saída de lista todas as configurações semânticas no índice, incluindo a que o código adicionou, seguida por uma mensagem de êxito.

// Trimmed for brevity
Configuration name: semantic-config
Title field: HotelName
Keywords fields: Tags
Content fields: Description
----------------------------------------
Semantic configuration updated successfully.

A saída de [especificar termo] retorna todos os documentos correspondentes ordenados pela pontuação do reclassificador de classificação semântica.

Search result #1:
  Re-ranker Score: 2.61
  HotelId: 24
  HotelName: Uptown Chic Hotel
  Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.

Search result #2:
  Re-ranker Score: 2.27
  HotelId: 2
  HotelName: Old Century Hotel
  Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.

Search result #3:
  Re-ranker Score: 1.99
  HotelId: 4
  HotelName: Sublime Palace Hotel
  Description: Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience.
// Trimmed for brevity

A saída adiciona um elemento de legenda com realce de hits junto aos campos de pesquisa. Legendas são as passagens mais relevantes em um resultado. Se o índice incluir texto maior, as legendas ajudarão a extrair as frases mais interessantes.

Search result #1:
  Re-ranker Score: 2.61
  HotelName: Uptown Chic Hotel
  Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.

  Caption with highlights: Chic hotel near the city. High-rise hotel in downtown, within walking distance to<em> theaters, </em>art galleries, restaurants and shops. Visit<em> Seattle Art Museum </em>by day, and then head over to<em> Benaroya Hall </em>to catch the evening's concert performance.
------------------------------------------------------------
Search result #2:
  Re-ranker Score: 2.27
  HotelName: Old Century Hotel
  Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.

  Caption text: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live.
------------------------------------------------------------
// Trimmed for brevity

A saída inclui uma resposta semântica extraída de um dos resultados que melhor corresponde à pergunta, seguida pelos resultados da pesquisa com legendas.

Semantic answer result #1:
Semantic Answer: Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the<em> library </em>by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.
Semantic Answer Score: 0.98

Search Results:

Search result #1:
Re-ranker Score: 2.12
Hotel: Stay-Kay City Hotel
Description: This classic hotel is fully-refurbished and ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Times Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.
Caption: This classic hotel is<em> fully-refurbished </em>and ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Times Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.

Search result #2:
Re-ranker Score: 2.07
Hotel: Double Sanctuary Resort
Description: 5 star Luxury Hotel - Biggest Rooms in the city. #1 Hotel in the area listed by Traveler magazine. Free WiFi, Flexible check in/out, Fitness Center & espresso in room.
Caption: <em>5 star Luxury Hotel </em>-<em> Biggest </em>Rooms in the city. #1 Hotel in the area listed by Traveler magazine. Free WiFi, Flexible check in/out, Fitness Center & espresso in room.
// Trimmed for brevity

Entender o código

Observação

Os snippets de código nesta seção podem ter sido modificados para legibilidade. Para obter um exemplo de trabalho completo, consulte o código-fonte.

Agora que você executou o código, vamos dividir as etapas principais:

1. Configuração e autenticação
2. Atualizar o índice com uma configuração semântica
3. Consultar o índice

Configuração e autenticação

A classe carrega propriedades de uma fonte e cria um mecanismo de autenticação sem chave.

import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;

import java.io.IOException;
import java.io.InputStream;
import java.util.Properties;

public class SearchConfig {
    private static final Properties properties =
        new Properties();

    static {
        try (InputStream input = SearchConfig.class
            .getClassLoader()
            .getResourceAsStream(
                "application.properties")) {
            properties.load(input);
        } catch (IOException e) {
            throw new RuntimeException(
                "Failed to load application.properties",
                e);
        }
    }

    public static final String SEARCH_ENDPOINT =
        properties.getProperty(
            "azure.search.endpoint");
    public static final String INDEX_NAME =
        properties.getProperty(
            "azure.search.index.name");
    public static final String SEMANTIC_CONFIG_NAME =
        properties.getProperty(
            "semantic.configuration.name");

    public static final DefaultAzureCredential
        CREDENTIAL = new DefaultAzureCredentialBuilder()
            .build();
}

Principais conclusões:

• DefaultAzureCredential fornece autenticação sem chave usando Microsoft Entra ID. Ele encadeia diversos tipos de credenciais, incluindo a credencial do CLI do Azure proveniente de az login.
• As propriedades são carregadas do arquivo no classpath.
• Campos estáticos (SEARCH_ENDPOINT, INDEX_NAME, SEMANTIC_CONFIG_NAME, CREDENTIAL) são compartilhados em todas as classes no project.

Atualizar o índice com uma configuração semântica

A classe adiciona uma configuração semântica ao índice existente . Essa operação não exclui nenhum documento de pesquisa e seu índice permanece operacional depois que a configuração é adicionada.

import com.azure.search.documents.indexes
    .SearchIndexClientBuilder;
import com.azure.search.documents.indexes.models
    .SearchIndex;
import com.azure.search.documents.indexes.models
    .SemanticConfiguration;
import com.azure.search.documents.indexes.models
    .SemanticField;
import com.azure.search.documents.indexes.models
    .SemanticPrioritizedFields;
import com.azure.search.documents.indexes.models
    .SemanticSearch;

import java.util.ArrayList;
import java.util.List;

var indexClient = new SearchIndexClientBuilder()
    .endpoint(SearchConfig.SEARCH_ENDPOINT)
    .credential(SearchConfig.CREDENTIAL)
    .buildClient();

SearchIndex existingIndex =
    indexClient.getIndex(SearchConfig.INDEX_NAME);

var prioritizedFields =
    new SemanticPrioritizedFields()
        .setTitleField(
            new SemanticField("HotelName"))
        .setKeywordsFields(
            List.of(new SemanticField("Tags")))
        .setContentFields(
            List.of(
                new SemanticField("Description")));

var newSemanticConfiguration =
    new SemanticConfiguration(
        SearchConfig.SEMANTIC_CONFIG_NAME,
        prioritizedFields);

SemanticSearch semanticSearch =
    existingIndex.getSemanticSearch();
if (semanticSearch == null) {
    semanticSearch = new SemanticSearch();
    existingIndex.setSemanticSearch(semanticSearch);
}

List<SemanticConfiguration> configurations =
    semanticSearch.getConfigurations();
if (configurations == null) {
    configurations = new ArrayList<>();
    semanticSearch.setConfigurations(configurations);
}

configurations.add(newSemanticConfiguration);

indexClient.createOrUpdateIndex(existingIndex);

Principais conclusões:

• define quais campos o classificador semântico avalia. define o título do documento, define o conteúdo principal e define a palavra-chave ou os campos de marca.
• emparelha um nome com os campos priorizados, identificando qual configuração semântica usar no momento da consulta.
• createOrUpdateIndex envia o esquema atualizado para o search service sem recriar o índice ou excluir documentos.

Consultar o índice

As três classes a seguir consultam o índice em sequência, progredindo de uma pesquisa semântica básica para uma classificação semântica com legendas e respostas.

Consulta semântica (sem legendas, sem respostas)

A primeira consulta adiciona classificação semântica sem legendas ou respostas. A classe mostra o requisito mínimo para invocar a classificação semântica.

import com.azure.search.documents
    .SearchClientBuilder;
import com.azure.search.documents.SearchDocument;
import com.azure.search.documents.models.QueryType;
import com.azure.search.documents.models.SearchOptions;
import com.azure.search.documents.models.SearchResult;
import com.azure.search.documents.models
    .SemanticSearchOptions;
import com.azure.search.documents.util
    .SearchPagedIterable;

var searchClient = new SearchClientBuilder()
    .endpoint(SearchConfig.SEARCH_ENDPOINT)
    .indexName(SearchConfig.INDEX_NAME)
    .credential(SearchConfig.CREDENTIAL)
    .buildClient();

var searchOptions = new SearchOptions()
    .setQueryType(QueryType.SEMANTIC)
    .setSemanticSearchOptions(
        new SemanticSearchOptions()
            .setSemanticConfigurationName(
                SearchConfig.SEMANTIC_CONFIG_NAME))
    .setSelect("HotelId", "HotelName", "Description");

SearchPagedIterable results = searchClient.search(
    "walking distance to live music",
    searchOptions, null);

for (SearchResult result : results) {
    var document = result.getDocument(
        SearchDocument.class);
    double rerankerScore = result
        .getSemanticSearch().getRerankerScore();

    System.out.printf("Re-ranker Score: %.2f%n",
        rerankerScore);
    System.out.printf("HotelName: %s%n",
        document.get("HotelName"));
    System.out.printf("Description: %s%n%n",
        document.get("Description"));
}

Principais conclusões:

• habilita a classificação semântica na consulta.
• especifica qual configuração semântica usar.
• fornece uma iterável sobre os resultados reclassificados. Cada um contém um acessador para a pontuação do reclassificador.

Consulta semântica com legendas

A classe adiciona legendas para extrair as passagens mais relevantes de cada resultado, com destaque aplicado aos termos e frases importantes.

import com.azure.search.documents.models
    .QueryCaption;
import com.azure.search.documents.models
    .QueryCaptionResult;
import com.azure.search.documents.models
    .QueryCaptionType;

var searchOptions = new SearchOptions()
    .setQueryType(QueryType.SEMANTIC)
    .setSemanticSearchOptions(
        new SemanticSearchOptions()
            .setSemanticConfigurationName(
                SearchConfig.SEMANTIC_CONFIG_NAME)
            .setQueryCaption(
                new QueryCaption(
                    QueryCaptionType.EXTRACTIVE)
                    .setHighlightEnabled(true)))
    .setSelect(
        "HotelId", "HotelName", "Description");

SearchPagedIterable results = searchClient.search(
    "walking distance to live music",
    searchOptions, null);

for (SearchResult result : results) {
    List<QueryCaptionResult> captions =
        result.getSemanticSearch()
            .getQueryCaptions();
    if (captions != null && !captions.isEmpty()) {
        QueryCaptionResult caption = captions.get(0);
        if (caption.getHighlights() != null) {
            System.out.printf(
                "Caption: %s%n",
                caption.getHighlights());
        }
    }
}

Principais conclusões:

• permite a extração de legendas dos campos de conteúdo.
• adiciona tags em torno de termos importantes em legendas.
• Cada um fornece funcionalidade no mecanismo de busca semântica.

Consulta semântica com respostas

A classe adiciona respostas semânticas. Essa classe usa uma pergunta como o texto de pesquisa porque as respostas semânticas funcionam melhor quando a consulta é formulada como uma pergunta. A resposta é uma passagem verbatim extraída do índice, não uma resposta composta de um modelo de conclusão de chat.

A consulta e o conteúdo indexado devem ser alinhados de perto para que uma resposta seja retornada. Se nenhum candidato atingir o limite de confiança, a resposta não inclui uma resposta. Este exemplo usa uma pergunta que é conhecida por produzir um resultado para que você possa ver a sintaxe. Se as respostas não forem úteis para seu cenário, omita do código. Para respostas compostas, considere um padrão RAG ou recuperação agente.

import com.azure.search.documents.models
    .QueryAnswer;
import com.azure.search.documents.models
    .QueryAnswerResult;
import com.azure.search.documents.models
    .QueryAnswerType;

var searchOptions = new SearchOptions()
    .setQueryType(QueryType.SEMANTIC)
    .setSemanticSearchOptions(
        new SemanticSearchOptions()
            .setSemanticConfigurationName(
                SearchConfig.SEMANTIC_CONFIG_NAME)
            .setQueryCaption(
                new QueryCaption(
                    QueryCaptionType.EXTRACTIVE))
            .setQueryAnswer(
                new QueryAnswer(
                    QueryAnswerType.EXTRACTIVE)))
    .setSelect(
        "HotelName", "Description", "Category");

SearchPagedIterable results = searchClient.search(
    "What's a good hotel for people who like to read",
    searchOptions, null);

List<QueryAnswerResult> semanticAnswers =
    results.getSemanticResults().getQueryAnswers();

for (QueryAnswerResult answer :
    semanticAnswers != null ? semanticAnswers
        : List.<QueryAnswerResult>of()) {
    if (answer.getHighlights() != null) {
        System.out.printf(
            "Semantic Answer: %s%n",
            answer.getHighlights());
    } else {
        System.out.printf(
            "Semantic Answer: %s%n",
            answer.getText());
    }
    System.out.printf(
        "Semantic Answer Score: %.2f%n",
        answer.getScore());
}

Principais conclusões:

• permite respostas extrativas para consultas semelhantes a perguntas.
• As respostas são conteúdo verbatim extraído do índice, não do texto gerado.
• recupera os objetos de resposta separadamente dos resultados da pesquisa.

Neste início rápido, você usará a biblioteca de clientes Pesquisa de IA do Azure  para JavaScript para adicionar semantic ranking a um índice de pesquisa existente e consultar o índice.

A classificação semântica é uma funcionalidade do lado da consulta que utiliza a compreensão de leitura por máquina para reavaliar os resultados da pesquisa, promovendo as correspondências mais semanticamente relevantes ao topo da lista. Você pode adicionar uma configuração semântica a um índice existente sem nenhum requisito de recompilação. A classificação semântica é mais eficaz para texto informativo ou descritivo.

Dica

Quer começar imediatamente? Baixe o source code no GitHub.

Pré-requisitos

• Uma conta Azure com uma assinatura ativa. Criar uma conta gratuita.

• Um serviço de Busca de IA do Azure com o classificador semântico habilitado.

• Um índice com campos de texto descritivos atribuídos como e . Este início rápido pressupõe o índice de exemplo de hotéis.

• Node.js 20 LTS ou posterior.

• Visual Studio Code.

• Git para clonar o repositório de exemplo.

• O CLI do Azure para autenticação sem chave com Microsoft Entra ID.

Configurar acesso

Antes de começar, verifique se você tem permissões para acessar o conteúdo e as operações no Pesquisa de IA do Azure . Este início rápido usa Microsoft Entra ID para autenticação e acesso baseado em função para autorização. Você deve ser um Owner ou User Access Administrator para atribuir funções. Se as funções não forem viáveis, use a autenticação baseada em chave.

Para configurar o acesso recomendado baseado em papéis:

1. Habilitar acesso baseado em função para seu serviço de busca.

2. Atribua as seguintes funções à sua conta de usuário.

   • Colaborador do Serviço de Busca

   • Leitor de dados de índice de pesquisa

Observação

Ao contrário de outros tutoriais rápidos que criam e carregam um índice, este tutorial presume que um índice já existe e contém dados, então você não precisa da função de Colaborador de Dados do Índice de Pesquisa.

Obter o ponto de extremidade

Cada serviço de Pesquisa de IA do Azure tem um endpoint, que é uma URL exclusiva que identifica e fornece acesso de rede para o serviço. Em uma seção posterior, especifique esse ponto de extremidade para se conectar ao seu serviço de busca programaticamente.

Para acessar o endpoint:

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

2. No painel esquerdo, selecione Visão geral.

3. Anote o endpoint, que deve se parecer com https://my-service.search.windows.NET.

Começar com um índice

Este início rápido modifica um índice existente para incluir uma configuração semântica. Recomendamos o índice de exemplo de hotéis, que você pode criar em minutos usando um assistente de portal do Azure.

Para usar um índice diferente, substitua o nome do índice, os nomes de campo na configuração semântica e os nomes de campo em instruções de consulta em todo o código de exemplo. Seu índice deve conter campos de texto descritivos que são atribuídos como e .

Para examinar e consultar o índice de exemplo de hotéis antes da classificação semântica:

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

2. No painel esquerdo, selecione gerenciamento de pesquisaÍndices.

3. Selecione amostra de hotéis.

4. Selecione configurações semânticas para exibir as configurações existentes. Se você habilitou a classificação semântica durante o fluxo de criação do assistente, deve haver uma configuração padrão.

   

5. Selecione o Explorador de Pesquisa e, em seguida, selecione a Exibição JSON.

6. Cole o JSON a seguir no editor de consultas.

   {
     "search": "walking distance to live music",
     "select": "HotelId, HotelName, Description",
     "count": true
   }
   

7. Selecione Pesquisar para executar a consulta.

   A resposta deve ser semelhante ao exemplo a seguir. Essa é uma consulta de texto completo classificada por BM25, portanto, os resultados correspondem a termos de consulta individuais e variantes linguísticas, em vez do significado geral da consulta. Por exemplo, corresponde , e e correspondem independentemente, em vez de compor uma frase.

   "@odata.count": 30,
   "value": [
     {
       "@search.score": 5.004435,
       "HotelId": "2",
       "HotelName": "Old Century Hotel",
       "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
     },
     {
       "@search.score": 4.555706,
       "HotelId": "24",
       "HotelName": "Uptown Chic Hotel",
       "Description": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance."
     },
     {
       "@search.score": 3.5625167,
       "HotelId": "4",
       "HotelName": "Sublime Palace Hotel",
       "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
     },
     ... // Trimmed for brevity
   ]
   

   Dica

   Esta consulta mostra a aparência da resposta antes da classificação semântica ser aplicada. Depois de configurar uma configuração semântica, adicione e veja como a mesma consulta é classificada de forma diferente por classificação semântica.

Configurar o ambiente

1. Use o Git para clonar o repositório de exemplo.

   git clone https://github.com/Azure-Samples/azure-search-javascript-samples
   

2. Navegue até a pasta de início rápido e abra-a no Visual Studio Code.

   cd azure-search-javascript-samples/quickstart-semantic-ranking-js
   code .
   

3. Em , substitua o valor do espaço reservado pela URL obtida em Obter ponto de extremidade.

4. Renomeie para .

   mv sample.env .env
   

5. Instale as dependências.

   npm install
   

   Quando a instalação for concluída, você deverá ver uma pasta node_modules no diretório project.

6. Para autenticação sem chave com Microsoft Entra ID, entre em sua conta Azure. Se você tiver várias assinaturas, selecione a que contém o serviço de pesquisa de IA do Azure.

   az login
   

Executar o código

1. Obtenha as configurações de índice existentes.

   node -r dotenv/config src/getIndexSettings.js
   

2. Atualize o índice com uma configuração semântica.

   node -r dotenv/config src/updateIndexSettings.js
   

3. Execute uma consulta semântica.

   node -r dotenv/config src/semanticQuery.js
   

4. Execute uma consulta semântica com legendas.

   node -r dotenv/config src/semanticQueryReturnCaptions.js
   

5. Execute uma consulta semântica com respostas.

   node -r dotenv/config src/semanticAnswer.js
   

Saída

O script retorna o nome do índice, seus campos e quaisquer configurações semânticas existentes.

Getting semantic ranking index settings...
Index name: hotels-sample
Number of fields: 23
Field: HotelId, Type: Edm.String, Searchable: true
Field: HotelName, Type: Edm.String, Searchable: true
Field: Description, Type: Edm.String, Searchable: true
Field: Description_fr, Type: Edm.String, Searchable: true
Field: Category, Type: Edm.String, Searchable: true
Field: Tags, Type: Collection(Edm.String), Searchable: true
// Trimmed for brevity
Semantic ranking configurations: 1
Configuration name: hotels-sample-semantic-configuration
Title field: undefined

O script retorna todas as configurações semânticas no índice, incluindo a que o código adicionou, seguida por uma mensagem de sucesso.

Semantic configurations:
----------------------------------------
Configuration name: hotels-sample-semantic-configuration
Title field: undefined
Keywords fields:
Content fields: AzureSearch_DocumentKey
----------------------------------------
Configuration name: semantic-config
Title field: HotelName
Keywords fields: Tags
Content fields: Description
----------------------------------------
Semantic configuration updated successfully.

O script retorna todos os documentos correspondentes ordenados pela pontuação de classificação semântica do re-ranker.

Search result #1:
  Re-ranker Score: 2.613231658935547
  HotelId: 24
  HotelName: Uptown Chic Hotel
  Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.

Search result #2:
  Re-ranker Score: 2.271434783935547
  HotelId: 2
  HotelName: Old Century Hotel
  Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.

Search result #3:
  Re-ranker Score: 1.9861756563186646
  HotelId: 4
  HotelName: Sublime Palace Hotel
  Description: Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience.
// Trimmed for brevity

O script retorna um elemento de legenda com realce de clique ao lado de campos de pesquisa. Legendas são as passagens mais relevantes em um resultado. Se o índice incluir texto maior, as legendas ajudarão a extrair as frases mais interessantes.

Search result #1:
  Re-ranker Score: 2.613231658935547
  HotelName: Uptown Chic Hotel
  Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.

  Caption with highlights: Chic hotel near the city. High-rise hotel in downtown, within walking distance to<em> theaters, </em>art galleries, restaurants and shops. Visit<em> Seattle Art Museum </em>by day, and then head over to<em> Benaroya Hall </em>to catch the evening's concert performance.
------------------------------------------------------------
Search result #2:
  Re-ranker Score: 2.271434783935547
  HotelName: Old Century Hotel
  Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.

  Caption text: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live.
------------------------------------------------------------
// Trimmed for brevity

O script retorna uma resposta semântica extraída de um dos resultados que melhor corresponde à pergunta, seguido pelos resultados da pesquisa com legendas.

Answers:

Semantic answer result #1:
Semantic Answer: Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the<em> library </em>by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.
Semantic Answer Score: 0.9829999804496765

Search Results:

Search result #1:
2.124817371368408
Stay-Kay City Hotel
This classic hotel is fully-refurbished and ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Times Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.
Caption: This classic hotel is<em> fully-refurbished </em>and ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Times Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.
// Trimmed for brevity

Entender o código

Observação

Os snippets de código nesta seção podem ter sido modificados para legibilidade. Para obter um exemplo de trabalho completo, consulte o código-fonte.

Agora que você executou o código, vamos dividir as etapas principais:

1. Configuração e autenticação
2. Atualizar o índice com uma configuração semântica
3. Consultar o índice

Configuração e autenticação

O arquivo carrega variáveis de ambiente e cria um para autenticação.

import { DefaultAzureCredential }
    from "@azure/identity";

export const searchEndpoint =
    process.env.AZURE_SEARCH_ENDPOINT
    || "PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE";
export const indexName =
    process.env.AZURE_SEARCH_INDEX_NAME
    || "hotels-sample";
export const semanticConfigurationName =
    process.env.SEMANTIC_CONFIGURATION_NAME
    || "semantic-config";

export const credential = new DefaultAzureCredential();

Principais conclusões:

• DefaultAzureCredential fornece autenticação sem chave usando Microsoft Entra ID. Ele encadeia diversos tipos de credenciais, incluindo a credencial do CLI do Azure proveniente de az login.
• As variáveis de ambiente são carregadas do arquivo usando .

Atualizar o índice com uma configuração semântica

O arquivo adiciona uma configuração semântica ao índice existente . Essa operação não exclui nenhum documento de pesquisa e seu índice permanece operacional depois que a configuração é adicionada.

import { SearchIndexClient }
    from "@azure/search-documents";
import {
    searchEndpoint, indexName,
    credential, semanticConfigurationName
} from "./config.js";

const indexClient = new SearchIndexClient(
    searchEndpoint, credential
);
const existingIndex =
    await indexClient.getIndex(indexName);

const fields = {
    titleField: { name: "HotelName" },
    keywordsFields: [{ name: "Tags" }],
    contentFields: [{ name: "Description" }]
};

const newSemanticConfiguration = {
    name: semanticConfigurationName,
    prioritizedFields: fields
};

if (existingIndex.semanticSearch
    && existingIndex.semanticSearch.configurations) {
    existingIndex.semanticSearch.configurations
        .push(newSemanticConfiguration);
} else {
    existingIndex.semanticSearch = {
        configurations: [newSemanticConfiguration]
    };
}

await indexClient.createOrUpdateIndex(existingIndex);

Principais conclusões:

• Uma configuração semântica especifica os campos usados para classificação semântica. define o título do documento, define o conteúdo principal e define a palavra-chave ou os campos de marca.
• Você cria um objeto de configuração e o envia por push para a matriz do índice existente.
• createOrUpdateIndex envia o esquema atualizado para o search service sem recriar o índice ou excluir documentos.

Consultar o índice

Os scripts de consulta executam três consultas em sequência, progredindo de uma pesquisa semântica básica para uma classificação semântica com legendas e respostas.

Consulta semântica (sem legendas, sem respostas)

O código a seguir mostra o requisito mínimo para invocar a classificação semântica.

import { SearchClient }
    from "@azure/search-documents";
import {
    credential, searchEndpoint,
    indexName, semanticConfigurationName
} from "./config.js";

const searchClient = new SearchClient(
    searchEndpoint, indexName, credential
);

const results = await searchClient.search(
    "walking distance to live music",
    {
        queryType: "semantic",
        semanticSearchOptions: {
            configurationName:
                semanticConfigurationName
        },
        select: [
            "HotelId", "HotelName", "Description"
        ]
    }
);

Principais conclusões:

• habilita a classificação semântica na consulta.
• especifica qual configuração semântica usar.
• Os resultados indicam relevância semântica (quanto maior, melhor).

Consulta semântica com legendas

O código a seguir adiciona legendas para extrair as passagens mais relevantes de cada resultado, com realce de clique aplicado aos termos e frases importantes.

const results = await searchClient.search(
    "walking distance to live music",
    {
        queryType: "semantic",
        semanticSearchOptions: {
            configurationName:
                semanticConfigurationName,
            captions: {
                captionType: "extractive",
                highlight: true
            }
        },
        select: [
            "HotelId", "HotelName", "Description"
        ]
    }
);

for await (const result of results.results) {
    const captions = result.captions;
    if (captions && captions.length > 0) {
        const caption = captions[0];
        if (caption.highlights) {
            console.log(
                `Caption: ${caption.highlights}`
            );
        }
    }
}

Principais conclusões:

• permite a extração de legendas dos campos de conteúdo.
• As legendas destacam as passagens mais relevantes e adicionam marcas <em> em volta de termos importantes.

Consulta semântica com respostas

A consulta final adiciona respostas semânticas. Essa consulta usa uma pergunta como o texto de pesquisa porque as respostas semânticas funcionam melhor quando a consulta é formulada como uma pergunta. A resposta é uma passagem verbatim extraída do índice, não uma resposta composta de um modelo de conclusão de chat.

A consulta e o conteúdo indexado devem ser alinhados de perto para que uma resposta seja retornada. Se nenhum candidato atingir o limite de confiança, a resposta não inclui uma resposta. Este exemplo usa uma pergunta que é conhecida por produzir um resultado para que você possa ver a sintaxe. Se as respostas não forem úteis para seu cenário, omita do código. Para respostas compostas, considere um padrão RAG ou recuperação agente.

const results = await searchClient.search(
    "What's a good hotel for people who "
    + "like to read",
    {
        queryType: "semantic",
        semanticSearchOptions: {
            configurationName:
                semanticConfigurationName,
            captions: {
                captionType: "extractive"
            },
            answers: {
                answerType: "extractive"
            }
        },
        select: [
            "HotelName", "Description", "Category"
        ]
    }
);

const semanticAnswers = results.answers;
for (const answer of semanticAnswers || []) {
    if (answer.highlights) {
        console.log(
            `Semantic Answer: ${answer.highlights}`
        );
    } else {
        console.log(
            `Semantic Answer: ${answer.text}`
        );
    }
    console.log(
        `Semantic Answer Score: ${answer.score}`
    );
}

Principais conclusões:

• permite respostas extrativas para consultas semelhantes a perguntas.
• As respostas são conteúdo verbatim extraído do índice, não do texto gerado.
• recupera os objetos de resposta separadamente dos resultados da pesquisa.

Neste início rápido, você usará a biblioteca de clientes Pesquisa de IA do Azure  para Python para adicionar semantic ranking a um índice de pesquisa existente e consultar o índice.

A classificação semântica é uma funcionalidade do lado da consulta que utiliza a compreensão de leitura por máquina para reavaliar os resultados da pesquisa, promovendo as correspondências mais semanticamente relevantes ao topo da lista. Você pode adicionar uma configuração semântica a um índice existente sem nenhum requisito de recompilação. A classificação semântica é mais eficaz para texto informativo ou descritivo.

Dica

Quer começar imediatamente? Baixe o source code no GitHub.

Pré-requisitos

• Uma conta Azure com uma assinatura ativa. Criar uma conta gratuita.

• Um serviço de Busca de IA do Azure com o classificador semântico habilitado.

• Um índice com campos de texto descritivos atribuídos como e . Este início rápido pressupõe o índice de exemplo de hotéis.

• Python 3.10 ou posterior.

• Visual Studio Code com a extensão Python.

• Git para clonar o repositório de exemplo.

• O CLI do Azure para autenticação sem chave com Microsoft Entra ID.

Configurar acesso

Antes de começar, verifique se você tem permissões para acessar o conteúdo e as operações no Pesquisa de IA do Azure . Este início rápido usa Microsoft Entra ID para autenticação e acesso baseado em função para autorização. Você deve ser um Owner ou User Access Administrator para atribuir funções. Se as funções não forem viáveis, use a autenticação baseada em chave.

Para configurar o acesso recomendado baseado em papéis:

1. Habilitar acesso baseado em função para seu serviço de busca.

2. Atribua as seguintes funções à sua conta de usuário.

   • Colaborador do Search Service

   • Leitor de dados de índice de pesquisa

Observação

Ao contrário de outros tutoriais rápidos que criam e carregam um índice, este tutorial presume que um índice já existe e contém dados, então você não precisa da função de Colaborador de Dados do Índice de Pesquisa.

Obter o ponto de extremidade

Cada serviço de Pesquisa de IA do Azure tem um endpoint, que é uma URL exclusiva que identifica e fornece acesso de rede ao serviço. Em uma seção posterior, especifique esse ponto de extremidade para se conectar ao seu serviço de busca programaticamente.

Para acessar o endpoint:

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

2. No painel esquerdo, selecione Visão geral.

3. Anote o endpoint, que deve se parecer com https://my-service.search.windows.NET.

Começar com um índice

Este início rápido modifica um índice existente para incluir uma configuração semântica. Recomendamos o índice de exemplo de hotéis, que você pode criar em minutos usando um assistente de portal do Azure.

Para usar um índice diferente, substitua o nome do índice, os nomes de campo na configuração semântica e os nomes de campo em instruções de consulta em todo o código de exemplo. Seu índice deve conter campos de texto descritivos que são atribuídos como e .

Para examinar e consultar o índice de exemplo de hotéis antes da classificação semântica:

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

2. No painel esquerdo, selecione gerenciamento de pesquisaÍndices.

3. Selecione amostra de hotéis.

4. Selecione configurações semânticas para exibir as configurações existentes. Se você habilitou a classificação semântica durante o fluxo de criação do assistente, deve haver uma configuração padrão.

   

5. Selecione o Explorador de Pesquisa e, em seguida, selecione a Exibição JSON.

6. Cole o JSON a seguir no editor de consultas.

   {
     "search": "walking distance to live music",
     "select": "HotelId, HotelName, Description",
     "count": true
   }
   

7. Selecione Pesquisar para executar a consulta.

   A resposta deve ser semelhante ao exemplo a seguir. Essa é uma consulta de texto completo classificada por BM25, portanto, os resultados correspondem a termos de consulta individuais e variantes linguísticas, em vez do significado geral da consulta. Por exemplo, corresponde , e e correspondem independentemente, em vez de compor uma frase.

   "@odata.count": 30,
   "value": [
     {
       "@search.score": 5.004435,
       "HotelId": "2",
       "HotelName": "Old Century Hotel",
       "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
     },
     {
       "@search.score": 4.555706,
       "HotelId": "24",
       "HotelName": "Uptown Chic Hotel",
       "Description": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance."
     },
     {
       "@search.score": 3.5625167,
       "HotelId": "4",
       "HotelName": "Sublime Palace Hotel",
       "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
     },
     ... // Trimmed for brevity
   ]
   

   Dica

   Esta consulta mostra a aparência da resposta antes da classificação semântica ser aplicada. Depois de configurar uma configuração semântica, adicione e veja como a mesma consulta é classificada de forma diferente por classificação semântica.

Configurar o ambiente

1. Use o Git para clonar o repositório de exemplo.

   git clone https://github.com/Azure-Samples/azure-search-python-samples
   

2. Navegue até a pasta de início rápido e abra-a no Visual Studio Code.

   cd azure-search-python-samples/Quickstart-Semantic-Ranking
   code .
   

3. Em , substitua o valor do espaço reservado pela URL obtida em Obter ponto de extremidade.

4. Renomeie para .

   mv sample.env .env
   

5. Abra .

6. Pressione Ctrl+Shift+P, selecione Bloco de Anotações: Selecione Kernel do Bloco de Anotações e siga os prompts para criar um ambiente virtual. Selecione requirements.txt para as dependências.

   Quando concluir, você deverá ver uma pasta .venv no diretório project.

7. Para autenticação sem chave com Microsoft Entra ID, entre em sua conta Azure. Se você tiver várias assinaturas, selecione a que contém o serviço de pesquisa de IA do Azure.

   az login
   

Executar o código

1. Execute as células para instalar os pacotes necessários e carregar variáveis de ambiente.

2. Execute as células restantes sequencialmente para adicionar uma configuração semântica e consultar o índice.

Saída

A saída da célula é o nome do índice, seus campos e quaisquer configurações semânticas existentes.

Index name: hotels-sample
Number of fields: 23
Field: HotelId, Type: Edm.String, Searchable: True
Field: HotelName, Type: Edm.String, Searchable: True
Field: Description, Type: Edm.String, Searchable: True
Field: Description_fr, Type: Edm.String, Searchable: True
Field: Category, Type: Edm.String, Searchable: True
Field: Tags, Type: Collection(Edm.String), Searchable: True
// Trimmed for brevity
Semantic config: hotels-sample-semantic-configuration
Title field: HotelName

A saída da célula lista todas as configurações semânticas no índice, incluindo a que o código adicionou, seguida por uma mensagem de êxito.

Semantic configurations:
----------------------------------------
  Configuration: hotels-sample-semantic-configuration
    Title field: HotelName
    Keywords fields: Category
    Content fields: Description

  Configuration: semantic-config
    Title field: HotelName
    Keywords fields: Tags
    Content fields: Description

✅ Semantic configuration successfully added!

A saída da célula retorna todos os documentos correspondentes ordenados pela pontuação BM25. Essa consulta de linha de base não usa classificação semântica.

5.360838
4
Sublime Palace Hotel
Description: Sublime Cliff Hotel is located in the heart of the
historic center of Sublime in an extremely vibrant and lively area
within short walking distance to the sites and landmarks of the city
and is surrounded by the extraordinary beauty of churches, buildings,
shops and monuments. Sublime Cliff is part of a lovingly restored
19th century resort, updated for every modern convenience.
4.691083
2
Old Century Hotel
Description: The hotel is situated in a nineteenth century plaza,
which has been expanded and renovated to the highest architectural
standards to create a modern, functional and first-class hotel in
which art and unique historical elements coexist with the most
modern comforts. The hotel also regularly hosts events like wine
tastings, beer dinners, and live music.
// Trimmed for brevity

A saída da célula retorna todos os documentos correspondentes, ordenados pela pontuação do reclassificador semântico.

2.613231658935547
24
Uptown Chic Hotel
Description: Chic hotel near the city. High-rise hotel in downtown,
within walking distance to theaters, art galleries, restaurants and
shops. Visit Seattle Art Museum by day, and then head over to
Benaroya Hall to catch the evening's concert performance.
2.271434783935547
2
Old Century Hotel
Description: The hotel is situated in a nineteenth century plaza,
which has been expanded and renovated to the highest architectural
standards to create a modern, functional and first-class hotel in
which art and unique historical elements coexist with the most
modern comforts. The hotel also regularly hosts events like wine
tastings, beer dinners, and live music.
// Trimmed for brevity

A saída da célula adiciona um elemento de legenda com realce de clique ao lado de campos de pesquisa. Legendas são as passagens mais relevantes em um resultado. Se o índice incluir texto maior, as legendas ajudarão a extrair as frases mais interessantes.

2.613231658935547
24
Uptown Chic Hotel
Description: Chic hotel near the city. High-rise hotel in downtown,
within walking distance to theaters, art galleries, restaurants and
shops. Visit Seattle Art Museum by day, and then head over to
Benaroya Hall to catch the evening's concert performance.
Caption: Chic hotel near the city. High-rise hotel in downtown,
within walking distance to<em> theaters, </em>art galleries,
restaurants and shops. Visit<em> Seattle Art Museum </em>by day, and
then head over to<em> Benaroya Hall </em>to catch the evening's
concert performance.
// Trimmed for brevity

A saída da célula inclui uma resposta semântica extraída de um dos resultados que melhor corresponde à pergunta, seguida pelos resultados da pesquisa com legendas.

Semantic Answer: Nature is Home on the beach. Explore the shore by
day, and then come home to our shared living space to relax around a
stone fireplace, sip something warm, and explore the<em> library
</em>by night. Save up to 30 percent. Valid Now through the end of
the year. Restrictions and blackouts may apply.
Semantic Answer Score: 0.9829999804496765

Entender o código

Observação

Os snippets de código nesta seção podem ter sido modificados para legibilidade. Para obter um exemplo de trabalho completo, consulte o código-fonte.

Agora que você executou o código, vamos dividir as etapas principais:

1. Configuração e autenticação
2. Atualizar o índice com uma configuração semântica
3. Consultar o índice

Configuração e autenticação

A célula carrega variáveis de ambiente e cria um sistema para autenticação.

from dotenv import load_dotenv
from azure.identity import DefaultAzureCredential
from azure.identity import get_bearer_token_provider
import os

load_dotenv(override=True)

search_endpoint = os.environ["AZURE_SEARCH_ENDPOINT"]
credential = DefaultAzureCredential()
index_name = os.getenv(
    "AZURE_SEARCH_INDEX", "hotels-sample"
)

Principais conclusões:

• DefaultAzureCredential fornece autenticação sem chave usando Microsoft Entra ID. Ele encadeia diversos tipos de credenciais, incluindo a credencial do CLI do Azure proveniente de az login.
• As variáveis de ambiente são carregadas do arquivo usando .

Atualizar o índice com uma configuração semântica

A célula adiciona uma configuração semântica ao índice existente . Essa operação não exclui nenhum documento de pesquisa e seu índice permanece operacional depois que a configuração é adicionada.

from azure.search.documents.indexes.models import (
    SemanticConfiguration,
    SemanticField,
    SemanticPrioritizedFields,
    SemanticSearch
)

new_semantic_config = SemanticConfiguration(
    name="semantic-config",
    prioritized_fields=SemanticPrioritizedFields(
        title_field=SemanticField(field_name="HotelName"),
        keywords_fields=[
            SemanticField(field_name="Tags")
        ],
        content_fields=[
            SemanticField(field_name="Description")
        ]
    )
)

if existing_index.semantic_search is None:
    existing_index.semantic_search = SemanticSearch(
        configurations=[new_semantic_config]
    )
else:
    existing_index.semantic_search.configurations.append(
        new_semantic_config
    )

result = index_client.create_or_update_index(existing_index)

Principais conclusões:

• Uma configuração semântica especifica os campos usados para classificação semântica. define o título do documento, define o conteúdo principal e define a palavra-chave ou os campos de marca.
• Crie a configuração com o modelo associado e, em seguida, acrescente-a ao índice existente.
• create_or_update_index envia o esquema atualizado para o search service sem recriar o índice ou excluir documentos.

Consultar o índice

As células de consulta executam quatro consultas em sequência: uma pesquisa de palavra-chave de linha de base seguida por três variações de classificação semântica com funcionalidade crescente.

Consulta por termo (linha de base)

A célula executa uma busca por palavra-chave usando o algoritmo de pontuação BM25. Essa consulta de linha de base não usa classificação semântica e serve como um ponto de comparação.

from azure.search.documents import SearchClient

search_client = SearchClient(
    endpoint=search_endpoint,
    index_name=index_name,
    credential=credential
)

results = search_client.search(
    query_type='simple',
    search_text="walking distance to live music",
    select='HotelId,HotelName,Description',
    include_total_count=True
)

Principais conclusões:

• especifica uma pesquisa de palavra-chave usando a pontuação BM25.
• Os resultados indicam a pontuação de relevância BM25.

Consulta semântica (sem legendas, sem respostas)

A célula mostra o requisito mínimo para invocar a classificação semântica.

from azure.search.documents import SearchClient

search_client = SearchClient(
    endpoint=search_endpoint,
    index_name=index_name,
    credential=credential
)

results = search_client.search(
    query_type='semantic',
    semantic_configuration_name='semantic-config',
    search_text="walking distance to live music",
    select='HotelId,HotelName,Description',
    query_caption='extractive'
)

Principais conclusões:

• habilita a classificação semântica na consulta.
• especifica qual configuração semântica usar.
• Os resultados indicam relevância semântica (quanto maior, melhor).

Consulta semântica com legendas

A célula adiciona legendas para extrair as passagens mais relevantes de cada resultado, com realce de clique aplicado aos termos e frases importantes.

results = search_client.search(
    query_type='semantic',
    semantic_configuration_name='semantic-config',
    search_text="walking distance to live music",
    select='HotelName,HotelId,Description',
    query_caption='extractive'
)

for result in results:
    captions = result["@search.captions"]
    if captions:
        caption = captions[0]
        if caption.highlights:
            print(f"Caption: {caption.highlights}\n")

Principais conclusões:

• permite a extração de legendas dos campos de conteúdo.
• As legendas destacam as passagens mais relevantes e adicionam marcas <em> ao redor de termos importantes.

Consulta semântica com respostas

A célula adiciona respostas semânticas. Essa consulta usa uma pergunta como o texto de pesquisa porque as respostas semânticas funcionam melhor quando a consulta é formulada como uma pergunta. A resposta é uma passagem verbatim extraída do índice, não uma resposta composta de um modelo de conclusão de chat.

A consulta e o conteúdo indexado devem ser alinhados de perto para que uma resposta seja retornada. Se nenhum candidato atingir o limite de confiança, a resposta não inclui uma resposta. Este exemplo usa uma pergunta que é conhecida por produzir um resultado para que você possa ver a sintaxe. Se as respostas não forem úteis para seu cenário, omita do código. Para respostas compostas, considere um padrão RAG ou recuperação agente.

results = search_client.search(
    query_type='semantic',
    semantic_configuration_name='semantic-config',
    search_text="what's a good hotel for people who "
                "like to read",
    select='HotelName,Description,Category',
    query_caption='extractive',
    query_answer="extractive",
)

semantic_answers = results.get_answers()
for answer in semantic_answers:
    if answer.highlights:
        print(f"Semantic Answer: {answer.highlights}")
    else:
        print(f"Semantic Answer: {answer.text}")
    print(f"Semantic Answer Score: {answer.score}\n")

Principais conclusões:

• permite respostas extrativas para consultas semelhantes a perguntas.
• As respostas são conteúdo verbatim extraído do índice, não do texto gerado.
• recupera os objetos de resposta separadamente dos resultados da pesquisa.

Neste início rápido, você usará a biblioteca de clientes Pesquisa de IA do Azure  para JavaScript (compatível com TypeScript) para adicionar semantic ranking a um índice de pesquisa existente e consultar o índice.

A classificação semântica é uma funcionalidade do lado da consulta que utiliza a compreensão de leitura por máquina para reavaliar os resultados da pesquisa, promovendo as correspondências mais semanticamente relevantes ao topo da lista. Você pode adicionar uma configuração semântica a um índice existente sem nenhum requisito de recompilação. A classificação semântica é mais eficaz para texto informativo ou descritivo.

Dica

Quer começar imediatamente? Baixe o source code no GitHub.

Pré-requisitos

• Uma conta Azure com uma assinatura ativa. Criar uma conta gratuita.

• Um serviço de Busca de IA do Azure com o classificador semântico habilitado.

• Um índice com campos de texto descritivos atribuídos como e . Este início rápido pressupõe o índice de exemplo de hotéis.

• Node.js 20 LTS ou posterior para executar o código compilado.

• TypeScript para compilar TypeScript para JavaScript.

• Visual Studio Code.

• Git para clonar o repositório de exemplo.

• O CLI do Azure para autenticação sem chave com Microsoft Entra ID.

Configurar acesso

Antes de começar, verifique se você tem permissões para acessar o conteúdo e as operações no Pesquisa de IA do Azure . Este início rápido usa Microsoft Entra ID para autenticação e acesso baseado em função para autorização. Você deve ser um Owner ou User Access Administrator para atribuir funções. Se as funções não forem viáveis, use a autenticação baseada em chave.

Para configurar o acesso recomendado baseado em papéis:

1. Habilitar acesso baseado em função para seu serviço de busca.

2. Atribua as seguintes funções à sua conta de usuário.

   • Colaborador do Search Service

   • Leitor de dados de índice de pesquisa

Observação

Ao contrário de outros tutoriais rápidos que criam e carregam um índice, este tutorial presume que um índice já existe e contém dados, então você não precisa da função de Colaborador de Dados do Índice de Pesquisa.

Obter o ponto de extremidade

Cada serviço de Pesquisa de IA do Azure tem um endpoint, que é uma URL exclusiva que identifica e fornece acesso de rede ao serviço. Em uma seção posterior, especifique esse ponto de extremidade para se conectar ao seu serviço de busca programaticamente.

Para acessar o endpoint:

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

2. No painel esquerdo, selecione Visão geral.

3. Anote o endpoint, que deve se parecer com https://my-service.search.windows.NET.

Começar com um índice

Este início rápido modifica um índice existente para incluir uma configuração semântica. Recomendamos o índice de exemplo de hotéis, que você pode criar em minutos usando um assistente de portal do Azure.

Para usar um índice diferente, substitua o nome do índice, os nomes de campo na configuração semântica e os nomes de campo em instruções de consulta em todo o código de exemplo. Seu índice deve conter campos de texto descritivos que são atribuídos como e .

Para examinar e consultar o índice de exemplo de hotéis antes da classificação semântica:

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

2. No painel esquerdo, selecione gerenciamento de pesquisaÍndices.

3. Selecione amostra de hotéis.

4. Selecione configurações semânticas para exibir as configurações existentes. Se você habilitou a classificação semântica durante o fluxo de criação do assistente, deve haver uma configuração padrão.

   

5. Selecione o Explorador de Pesquisa e, em seguida, selecione a Exibição JSON.

6. Cole o JSON a seguir no editor de consultas.

   {
     "search": "walking distance to live music",
     "select": "HotelId, HotelName, Description",
     "count": true
   }
   

7. Selecione Pesquisar para executar a consulta.

   A resposta deve ser semelhante ao exemplo a seguir. Essa é uma consulta de texto completo classificada por BM25, portanto, os resultados correspondem a termos de consulta individuais e variantes linguísticas, em vez do significado geral da consulta. Por exemplo, corresponde , e e correspondem independentemente, em vez de compor uma frase.

   "@odata.count": 30,
   "value": [
     {
       "@search.score": 5.004435,
       "HotelId": "2",
       "HotelName": "Old Century Hotel",
       "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
     },
     {
       "@search.score": 4.555706,
       "HotelId": "24",
       "HotelName": "Uptown Chic Hotel",
       "Description": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance."
     },
     {
       "@search.score": 3.5625167,
       "HotelId": "4",
       "HotelName": "Sublime Palace Hotel",
       "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
     },
     ... // Trimmed for brevity
   ]
   

   Dica

   Esta consulta mostra a aparência da resposta antes da classificação semântica ser aplicada. Depois de configurar uma configuração semântica, adicione e veja como a mesma consulta é classificada de forma diferente por classificação semântica.

Configurar o ambiente

1. Use o Git para clonar o repositório de exemplo.

   git clone https://github.com/Azure-Samples/azure-search-javascript-samples
   

2. Navegue até a pasta de início rápido e abra-a no Visual Studio Code.

   cd azure-search-javascript-samples/quickstart-semantic-ranking-ts
   code .
   

3. Em , substitua o valor do espaço reservado pela URL obtida em Obter ponto de extremidade.

4. Renomeie para .

   mv sample.env .env
   

5. Instale as dependências.

   npm install
   

   Quando a instalação for concluída, você deverá ver uma pasta node_modules no diretório project.

6. Compile os arquivos TypeScript.

   npm run build
   

7. Para autenticação sem chave com Microsoft Entra ID, entre em sua conta Azure. Se você tiver várias assinaturas, selecione a que contém o serviço de pesquisa de IA do Azure.

   az login
   

Executar o código

1. Obtenha as configurações de índice existentes.

   node -r dotenv/config dist/getIndexSettings.js
   

2. Atualize o índice com uma configuração semântica.

   node -r dotenv/config dist/updateIndexSettings.js
   

3. Execute uma consulta semântica.

   node -r dotenv/config dist/semanticQuery.js
   

4. Execute uma consulta semântica com legendas.

   node -r dotenv/config dist/semanticQueryReturnCaptions.js
   

5. Execute uma consulta semântica com respostas.

   node -r dotenv/config dist/semanticAnswer.js
   

   Observação

   Esses comandos executam arquivos da pasta porque você transpilou anteriormente de TypeScript para JavaScript com .

Saída

O script retorna o nome do índice, a contagem de campos, os detalhes do campo com o tipo e o status pesquisável e as configurações semânticas existentes.

Index name: hotels-sample
Number of fields: 23
Field: HotelId, Type: Edm.String, Searchable: true
Field: HotelName, Type: Edm.String, Searchable: true
Field: Description, Type: Edm.String, Searchable: true
// Trimmed for brevity
Semantic ranking configurations: 1
Configuration name: hotels-sample-semantic-configuration
Title field: undefined

O script retorna todas as configurações semânticas, incluindo a que você adicionou.

Semantic configurations:
----------------------------------------
Configuration name: hotels-sample-semantic-configuration
Title field: undefined
Keywords fields:
Content fields: AzureSearch_DocumentKey
----------------------------------------
Configuration name: semantic-config
Title field: HotelName
Keywords fields: Tags
Content fields: Description
----------------------------------------
Semantic configuration updated successfully.

O script retorna resultados ordenados pela pontuação do reclassificador.

Search result #1:
  Re-ranker Score: 2.613231658935547
  HotelId: 24
  HotelName: Uptown Chic Hotel
  Description: Chic hotel near the city. High-rise hotel in downtown,
  within walking distance to theaters, art galleries, restaurants and
  shops. Visit Seattle Art Museum by day, and then head over to
  Benaroya Hall to catch the evening's concert performance.

Search result #2:
  Re-ranker Score: 2.271434783935547
  HotelId: 2
  HotelName: Old Century Hotel
  Description: The hotel is situated in a nineteenth century plaza...
  // Trimmed for brevity

O script retorna legendas extrativas com realce de clique. Legendas são as passagens mais relevantes em um resultado.

Search result #1:
  Re-ranker Score: 2.613231658935547
  HotelName: Uptown Chic Hotel
  Description: Chic hotel near the city. High-rise hotel in downtown,
  within walking distance to theaters, art galleries, restaurants and
  shops. Visit Seattle Art Museum by day, and then head over to
  Benaroya Hall to catch the evening's concert performance.

  Caption with highlights: Chic hotel near the city. High-rise hotel
  in downtown, within walking distance to<em> theaters, </em>art
  galleries, restaurants and shops. Visit<em> Seattle Art Museum
  </em>by day, and then head over to<em> Benaroya Hall </em>to catch
  the evening's concert performance.
------------------------------------------------------------
Search result #2:
  Re-ranker Score: 2.271434783935547
  HotelName: Old Century Hotel
  // Trimmed for brevity

O script retorna uma resposta semântica (conteúdo verbatim) extraída do resultado que melhor corresponde à pergunta.

Semantic answer result #1:
Semantic Answer: Nature is Home on the beach. Explore the shore by
day, and then come home to our shared living space to relax around
a stone fireplace, sip something warm, and explore the<em> library
</em>by night. Save up to 30 percent. Valid Now through the end of
the year. Restrictions and blackouts may apply.
Semantic Answer Score: 0.9829999804496765

Search Results:

Search result #1:
2.124817371368408
Stay-Kay City Hotel
This classic hotel is fully-refurbished and ideally located on the
main commercial artery of the city in the heart of New York...
Caption: This classic hotel is<em> fully-refurbished </em>and
ideally located on the main commercial artery of the city...
// Trimmed for brevity

Entender o código

Observação

Os snippets de código nesta seção podem ter sido modificados para legibilidade. Para obter um exemplo de trabalho completo, consulte o código-fonte.

Agora que você executou o código, vamos dividir as etapas principais:

1. Configuração e autenticação
2. Atualizar o índice com uma configuração semântica
3. Consultar o índice

Configuração e autenticação

O arquivo carrega variáveis de ambiente, cria uma para autenticação e define uma interface para segurança de tipo.

import { DefaultAzureCredential }
    from "@azure/identity";

export const searchEndpoint =
    process.env.AZURE_SEARCH_ENDPOINT
    || "PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE";
export const indexName =
    process.env.AZURE_SEARCH_INDEX_NAME
    || "hotels-sample";
export const semanticConfigurationName =
    process.env.SEMANTIC_CONFIGURATION_NAME
    || "semantic-config";

export const credential = new DefaultAzureCredential();

export interface HotelDocument {
    HotelId: string;
    HotelName: string;
    Description: string;
    Category: string;
    Tags: string[];
}

Principais conclusões:

• DefaultAzureCredential fornece autenticação sem chave usando Microsoft Entra ID. Ele encadeia diversos tipos de credenciais, incluindo a credencial do CLI do Azure proveniente de az login.
• A interface HotelDocument fornece verificação de tipos em tempo de compilação para resultados de pesquisa, garantindo o acesso seguro de tipo para campos de documento.
• As variáveis de ambiente são carregadas do arquivo usando .

Atualizar o índice com uma configuração semântica

O arquivo adiciona uma configuração semântica ao índice existente . Essa operação não exclui nenhum documento de pesquisa e seu índice permanece operacional depois que a configuração é adicionada. As anotações de tipo TypeScript garantem que a configuração corresponda ao esquema esperado.

import {
    SearchIndexClient,
    SemanticConfiguration,
    SemanticPrioritizedFields,
    SemanticField
} from "@azure/search-documents";
import {
    searchEndpoint, indexName,
    credential, semanticConfigurationName
} from "./config.js";

const indexClient = new SearchIndexClient(
    searchEndpoint, credential
);
const existingIndex =
    await indexClient.getIndex(indexName);

const fields: SemanticPrioritizedFields = {
    titleField: { name: "HotelName" },
    keywordsFields: [
        { name: "Tags" }
    ] as SemanticField[],
    contentFields: [
        { name: "Description" }
    ] as SemanticField[]
};

const newSemanticConfiguration:
    SemanticConfiguration = {
    name: semanticConfigurationName,
    prioritizedFields: fields
};

if (existingIndex.semanticSearch
    && existingIndex.semanticSearch.configurations) {
    existingIndex.semanticSearch.configurations
        .push(newSemanticConfiguration);
} else {
    existingIndex.semanticSearch = {
        configurations: [newSemanticConfiguration]
    };
}

await indexClient.createOrUpdateIndex(existingIndex);

Principais conclusões:

• Tipos TypeScript, como , e fornecem validação em tempo de compilação para a estrutura de configuração.
• define o título do documento, define o conteúdo principal e define a palavra-chave ou os campos de marca.
• createOrUpdateIndex envia o esquema atualizado para o search service sem recriar o índice ou excluir documentos.

Consultar o índice

Os scripts de consulta executam três consultas em sequência, progredindo de uma pesquisa semântica básica para uma classificação semântica com legendas e respostas.

Consulta semântica (sem legendas, sem respostas)

O script mostra o requisito mínimo para invocar a classificação semântica com resultados de tipo seguro.

import { SearchClient }
    from "@azure/search-documents";
import {
    HotelDocument, credential,
    searchEndpoint, indexName,
    semanticConfigurationName
} from "./config.js";

const searchClient =
    new SearchClient<HotelDocument>(
        searchEndpoint, indexName, credential
    );

const results = await searchClient.search(
    "walking distance to live music",
    {
        queryType: "semantic",
        semanticSearchOptions: {
            configurationName:
                semanticConfigurationName
        },
        select: [
            "HotelId", "HotelName", "Description"
        ]
    }
);

Principais conclusões:

• SearchClient<HotelDocument> fornece acesso seguro por tipo aos campos do documento em resultados, com preenchimento automático dos nomes dos campos em select e result.document.
• habilita a classificação semântica na consulta.
• especifica qual configuração semântica usar.

Consulta semântica com legendas

O script adiciona rótulos para que sejam extraídas as passagens mais relevantes de cada resultado, com realce dos termos e frases importantes.

const results = await searchClient.search(
    "walking distance to live music",
    {
        queryType: "semantic",
        semanticSearchOptions: {
            configurationName:
                semanticConfigurationName,
            captions: {
                captionType: "extractive",
                highlight: true
            }
        },
        select: [
            "HotelId", "HotelName", "Description"
        ]
    }
);

for await (const result of results.results) {
    const captions = result.captions;
    if (captions && captions.length > 0) {
        const caption = captions[0];
        if (caption.highlights) {
            console.log(
                `Caption: ${caption.highlights}`
            );
        }
    }
}

Principais conclusões:

• permite a extração de legendas dos campos de conteúdo.
• As legendas destacam as passagens mais relevantes e adicionam marcas <em> ao redor de termos importantes.

Consulta semântica com respostas

O script adiciona respostas semânticas. Ele usa uma pergunta como o texto de pesquisa porque as respostas semânticas funcionam melhor quando a consulta é formulada como uma pergunta. A resposta é uma passagem verbatim extraída do índice, não uma resposta composta de um modelo de conclusão de chat.

A consulta e o conteúdo indexado devem ser alinhados de perto para que uma resposta seja retornada. Se nenhum candidato atingir o limite de confiança, a resposta não inclui uma resposta. Este exemplo usa uma pergunta que é conhecida por produzir um resultado para que você possa ver a sintaxe. Se as respostas não forem úteis para seu cenário, omita do código. Para respostas compostas, considere um padrão RAG ou recuperação agente.

const results = await searchClient.search(
    "What's a good hotel for people who "
    + "like to read",
    {
        queryType: "semantic",
        semanticSearchOptions: {
            configurationName:
                semanticConfigurationName,
            captions: {
                captionType: "extractive"
            },
            answers: {
                answerType: "extractive"
            }
        },
        select: [
            "HotelName", "Description", "Category"
        ]
    }
);

const semanticAnswers = results.answers;
for (const answer of semanticAnswers || []) {
    if (answer.highlights) {
        console.log(
            `Semantic Answer: ${answer.highlights}`
        );
    } else {
        console.log(
            `Semantic Answer: ${answer.text}`
        );
    }
    console.log(
        `Semantic Answer Score: ${answer.score}`
    );
}

Principais conclusões:

• permite respostas extrativas para consultas semelhantes a perguntas.
• As respostas são conteúdo verbatim extraído do índice, não do texto gerado.
• recupera os objetos de resposta separadamente dos resultados da pesquisa.

Neste início rápido, você usará as APIs REST Pesquisa de IA do Azure  para adicionar semantic ranking a um índice de pesquisa existente e consultar o índice.

A classificação semântica é uma funcionalidade do lado da consulta que utiliza a compreensão de leitura por máquina para reavaliar os resultados da pesquisa, promovendo as correspondências mais semanticamente relevantes ao topo da lista. Você pode adicionar uma configuração semântica a um índice existente sem nenhum requisito de recompilação. A classificação semântica é mais eficaz para texto informativo ou descritivo.

Dica

Quer começar imediatamente? Baixe o source code no GitHub.

Pré-requisitos

• Uma conta Azure com uma assinatura ativa. Criar uma conta gratuita.

• Um serviço de Busca de IA do Azure com o classificador semântico habilitado.

• Um índice com campos de texto descritivos atribuídos como e . Este início rápido pressupõe o índice de exemplo de hotéis.

• Visual Studio Code com a extensão do cliente REST.

• Git para clonar o repositório de exemplo.

• O CLI do Azure para autenticação sem chave com Microsoft Entra ID.

Configurar acesso

Antes de começar, verifique se você tem permissões para acessar o conteúdo e as operações no Pesquisa de IA do Azure . Este início rápido usa Microsoft Entra ID para autenticação e acesso baseado em função para autorização. Você deve ser um Owner ou User Access Administrator para atribuir funções. Se as funções não forem viáveis, use a autenticação baseada em chave.

Para configurar o acesso recomendado baseado em papéis:

1. Habilitar acesso baseado em função para seu serviço de busca.

2. Atribua as seguintes funções à sua conta de usuário.

   • Colaborador do Search Service

   • Leitor de dados de índice de pesquisa

Observação

Ao contrário de outros tutoriais rápidos que criam e carregam um índice, este tutorial presume que um índice já existe e contém dados, então você não precisa da função de Colaborador de Dados do Índice de Pesquisa.

Obter o ponto de extremidade

Cada serviço de Pesquisa de IA do Azure tem um endpoint, que é uma URL exclusiva que identifica e fornece acesso de rede ao serviço. Em uma seção posterior, especifique esse ponto de extremidade para se conectar ao seu serviço de busca programaticamente.

Para acessar o endpoint:

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

2. No painel esquerdo, selecione Visão geral.

3. Anote o endpoint, que deve se parecer com https://my-service.search.windows.NET.

Começar com um índice

Este início rápido modifica um índice existente para incluir uma configuração semântica. Recomendamos o índice de exemplo de hotéis, que você pode criar em minutos usando um assistente de portal do Azure.

Para usar um índice diferente, substitua o nome do índice, os nomes de campo na configuração semântica e os nomes de campo em instruções de consulta em todo o código de exemplo. Seu índice deve conter campos de texto descritivos que são atribuídos como e .

Para examinar e consultar o índice de exemplo de hotéis antes da classificação semântica:

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

2. No painel esquerdo, selecione gerenciamento de pesquisaÍndices.

3. Selecione amostra de hotéis.

4. Selecione configurações semânticas para exibir as configurações existentes. Se você habilitou a classificação semântica durante o fluxo de criação do assistente, deve haver uma configuração padrão.

   

5. Selecione o Explorador de Pesquisa e, em seguida, selecione a Exibição JSON.

6. Cole o JSON a seguir no editor de consultas.

   {
     "search": "walking distance to live music",
     "select": "HotelId, HotelName, Description",
     "count": true
   }
   

7. Selecione Pesquisar para executar a consulta.

   A resposta deve ser semelhante ao exemplo a seguir. Essa é uma consulta de texto completo classificada por BM25, portanto, os resultados correspondem a termos de consulta individuais e variantes linguísticas, em vez do significado geral da consulta. Por exemplo, corresponde , e e correspondem independentemente, em vez de compor uma frase.

   "@odata.count": 30,
   "value": [
     {
       "@search.score": 5.004435,
       "HotelId": "2",
       "HotelName": "Old Century Hotel",
       "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
     },
     {
       "@search.score": 4.555706,
       "HotelId": "24",
       "HotelName": "Uptown Chic Hotel",
       "Description": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance."
     },
     {
       "@search.score": 3.5625167,
       "HotelId": "4",
       "HotelName": "Sublime Palace Hotel",
       "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
     },
     ... // Trimmed for brevity
   ]
   

   Dica

   Esta consulta mostra a aparência da resposta antes da classificação semântica ser aplicada. Depois de configurar uma configuração semântica, adicione e veja como a mesma consulta é classificada de forma diferente por classificação semântica.

Configurar o ambiente

1. Use o Git para clonar o repositório de exemplo.

   git clone https://github.com/Azure-Samples/azure-search-rest-samples
   

2. Navegue até a pasta de início rápido e abra-a no Visual Studio Code.

   cd azure-search-rest-samples/Quickstart-semantic-ranking
   code .
   

3. Em , substitua o valor do espaço reservado pela URL obtida em Obter ponto de extremidade.

4. Repita a etapa anterior para .

5. Para autenticação sem chave com Microsoft Entra ID, entre em sua conta Azure. Se você tiver várias assinaturas, selecione a que contém o serviço de pesquisa de IA do Azure.

   az login
   

6. Para autenticação sem chave com o Microsoft Entra ID, gere um token de acesso.

   az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv
   

7. Em ambos os arquivos, substitua o valor do espaço reservado pelo token da etapa anterior.

Executar o código

1. Abra .

2. Selecione Enviar Solicitação na primeira solicitação GET para verificar sua conexão.

   Uma resposta deve aparecer em um painel adjacente. Se você tiver índices existentes, eles serão listados pelo nome. Se o código HTTP estiver , você estará pronto para continuar.

3. Envie a solicitação para adicionar uma configuração semântica ao índice.

   Se você receber um erro, o esquema de índice será diferente do exemplo. Envie a solicitação , copie o JSON de resposta, adicione a seção do código-fonte ao JSON e substitua o corpo da solicitação PUT pelo esquema mesclado.

4. Alterne e envie as solicitações sequencialmente: uma consulta simples para comparação de linha de base e, em seguida, consultas semânticas com classificação, legendas e respostas.

Saída

A solicitação retorna resultados classificados pela relevância BM25, que é indicada pelo campo.

{
  "@odata.count": 30,
  "value": [
    {
      "@search.score": 5.004435,
      "HotelId": "2",
      "HotelName": "Old Century Hotel",
      "Description": "The hotel is situated in a nineteenth century plaza..."
    },
    // Trimmed for brevity
  ]
}

A solicitação adiciona . Observe que a ordem muda em relação à consulta simples.

{
  "@odata.count": 30,
  "@search.answers": [],
  "value": [
    {
      "@search.score": 4.555706,
      "@search.rerankerScore": 2.613231658935547,
      "HotelId": "24",
      "HotelName": "Uptown Chic Hotel",
      "Description": "Chic hotel near the city. High-rise hotel in downtown..."
    },
    // Trimmed for brevity
  ]
}

A solicitação adiciona texto extraído e destaques.

{
  "value": [
    {
      "@search.score": 4.555706,
      "@search.rerankerScore": 2.613231658935547,
      "@search.captions": [
        {
          "text": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops...",
          "highlights": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to<em> theaters, </em>art galleries, restaurants and shops..."
        }
      ],
      "HotelId": "24",
      "HotelName": "Uptown Chic Hotel"
    },
    // Trimmed for brevity
  ]
}

A solicitação retorna uma resposta extrativa quando a consulta é formulada como uma pergunta.

{
  "@odata.count": 46,
  "@search.answers": [
    {
      "key": "38",
      "text": "Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the library by night...",
      "highlights": "Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the<em> library </em>by night...",
      "score": 0.9829999804496765
    }
  ],
  "value": [
    {
      "@search.score": 2.060124,
      "@search.rerankerScore": 2.124817371368408,
      "@search.captions": [
        {
          "text": "This classic hotel is fully-refurbished and ideally located on the main commercial artery of the city...",
          "highlights": "This classic hotel is<em> fully-refurbished </em>and ideally located on the main commercial artery of the city..."
        }
      ],
      "HotelId": "1",
      "HotelName": "Stay-Kay City Hotel"
    },
    // Trimmed for brevity
  ]
}

Entender o código

Observação

Os snippets de código nesta seção podem ter sido modificados para legibilidade. Para obter um exemplo de trabalho completo, consulte o código-fonte.

Agora que você executou o código, vamos dividir as etapas principais:

1. Configuração e autenticação
2. Atualizar o índice com uma configuração semântica
3. Consultar o índice

Configuração e autenticação

Ambos os arquivos definem variáveis na parte superior para reutilização em todas as solicitações.

@searchUrl = PUT-YOUR-SEARCH-SERVICE-URL-HERE
@personalAccessToken = PUT-YOUR-PERSONAL-ACCESS-TOKEN-HERE
@api-version = 2025-09-01

Principais conclusões:

• @searchUrl é o ponto de extremidade do serviço de pesquisa.
• @personalAccessToken é um token Microsoft Entra ID obtido do CLI do Azure. Isso substitui as chaves de API pela autenticação sem chave.
• é incluído em cada cabeçalho de solicitação para autenticação.

Atualizar o índice com uma configuração semântica

A solicitação em envia o esquema de índice completo junto com uma nova seção. A API REST requer o esquema completo para qualquer operação de atualização, portanto, você não pode enviar apenas a configuração semântica.

A principal adição é a seção.

"semantic": {
    "configurations": [
        {
            "name": "semantic-config",
            "rankingOrder":
                "BoostedRerankerScore",
            "prioritizedFields": {
                "titleField": {
                    "fieldName": "HotelName"
                },
                "prioritizedContentFields": [
                    {
                        "fieldName": "Description"
                    }
                ],
                "prioritizedKeywordsFields": [
                    {
                        "fieldName": "Tags"
                    }
                ]
            }
        }
    ]
}

Principais conclusões:

• identifica qual campo contém o título do documento para avaliação semântica.
• identifica os campos de conteúdo principais. O classificador semântico os avalia primeiro ao pontuar relevância.
• identifica campos de palavras-chave ou tags para contexto adicional.
• combina a pontuação BM25 com a pontuação de reclassificador semântico.
• A API REST requer o esquema completo para operações PUT. Somente a seção é nova; todos os outros campos não são alterados.

Consultar o índice

As solicitações em andamento variam de uma simples pesquisa por palavra-chave até a classificação semântica com legendas e respostas. Todas as consultas são solicitações POST para Documents - Search Post (API REST).

Consulta simples

A solicitação é uma pesquisa de palavra-chave simples que não usa classificação semântica. Ele serve como uma linha de base para comparar resultados com e sem reranqueamento semântico.

{
    "search":
        "walking distance to live music",
    "select":
        "HotelId, HotelName, Description",
    "count": true,
    "queryType": "simple"
}

Principais conclusões:

• usa o algoritmo de classificação BM25 padrão.
• Os resultados são classificados apenas pela relevância da palavra-chave ().

Consulta semântica (sem legendas, sem respostas)

A solicitação adiciona classificação semântica. O JSON a seguir mostra o requisito mínimo para invocar a classificação semântica.

{
    "search":
        "walking distance to live music",
    "select":
        "HotelId, HotelName, Description",
    "count": true,
    "queryType": "semantic",
    "semanticConfiguration": "semantic-config"
}

Principais conclusões:

• habilita a classificação semântica na consulta.
• especifica qual configuração semântica usar.

Consulta semântica com legendas

A solicitação adiciona legendas para extrair as passagens mais relevantes de cada resultado, com realce dos termos e frases importantes.

{
    "search":
        "walking distance to live music",
    "select":
        "HotelId, HotelName, Description",
    "count": true,
    "queryType": "semantic",
    "semanticConfiguration": "semantic-config",
    "captions": "extractive|highlight-true"
}

Principais conclusões:

• permite legendas extrativas com etiquetas em torno de termos importantes.
• As legendas aparecem na matriz para cada resultado.

Consulta semântica com respostas

A solicitação adiciona respostas semânticas. Ele usa uma pergunta como o texto de pesquisa porque as respostas semânticas funcionam melhor quando a consulta é formulada como uma pergunta. A resposta é uma passagem verbatim extraída do índice, não uma resposta composta de um modelo de conclusão de chat.

A consulta e o conteúdo indexado devem ser alinhados de perto para que uma resposta seja retornada. Se nenhum candidato atingir o limite de confiança, a resposta não inclui uma resposta. Este exemplo usa uma pergunta que é conhecida por produzir um resultado para que você possa ver a sintaxe. Se as respostas não forem úteis para seu cenário, omita o parâmetro de sua solicitação. Para respostas compostas, considere um padrão RAG ou recuperação agente.

{
    "search":
        "what's a good hotel for people who like to read",
    "select":
        "HotelId, HotelName, Description",
    "count": true,
    "queryType": "semantic",
    "semanticConfiguration": "semantic-config",
    "captions": "extractive|highlight-true",
    "answers": "extractive"
}

Principais conclusões:

• permite respostas extrativas para consultas semelhantes a perguntas.
• As respostas aparecem na matriz de nível superior, separadas dos resultados individuais.
• As respostas são conteúdo verbatim extraído do índice, não do texto gerado.

Limpar os recursos

Quando você trabalha em sua própria assinatura, é uma boa ideia concluir um projeto removendo os recursos que você não precisa mais. Recursos que ficam em execução podem custar dinheiro.

No portal do Azure, selecione Todos recursos ou grupos Resource no painel esquerdo para localizar e gerenciar recursos. Você pode excluir recursos individualmente ou excluir o grupo de recursos para remover todos os recursos de uma só vez.

Conteúdo relacionado

• Classificação semântica em Pesquisa de IA do Azure 
• Configurar o classificador semântico
• Adicionar reescrita de consulta ao classificador semântico
• Usar perfis de pontuação com classificador semântico