Adicionar perfis de pontuação para aumentar as pontuações de pesquisa

Os perfis de pontuação permitem aumentar a classificação de documentos correspondentes com base em critérios específicos. Neste artigo, você vai aprender a especificar e atribuir um perfil de pontuação que aumenta a pontuação de busca com base nos parâmetros que você definir.

Você pode usar perfis de pontuação para busca por palavras-chave, busca em vetores e busca híbrida. É importante notar que os perfis de pontuação se aplicam apenas a campos não vetoriais. Portanto, seu índice só deve conter campos de texto ou numéricos que possam ser usados em um perfil de pontuação. O suporte a perfis de pontuação para busca em vetores e híbrida estará disponível nas APIs REST 2024-05-01-preview e 2024-07-01, além dos pacotes de SDK do Azure voltados para essas versões.

Principais pontos sobre perfis de pontuação

Os parâmetros de perfil de pontuação incluem:

• Campos ponderados, onde uma correspondência é encontrada em um campo de cadeia de caracteres específico. Por exemplo, talvez você queira que as correspondências encontradas em um campo "resumo" sejam mais relevantes do que a mesma correspondência encontrada no campo "conteúdo".

• Funções para dados numéricos, como datas, intervalos e coordenadas geográficas. Há também uma função Marcações que opera em um campo, fornecendo uma coleção arbitrária de cadeias de caracteres. Você pode optar por abordagem em vez de campos ponderados se quiser aumentar uma pontuação com base na presença de uma correspondência em um campo de marcações.

Você pode criar vários perfis e modificar a lógica de consulta para escolher qual deles será usado.

É possível ter até 100 perfis de pontuação em um índice (consulte Limites de serviço), mas você poderá especificar apenas um perfil no momento em qualquer consulta.

Definição do perfil de pontuação

Um perfil de pontuação é nomeado objeto definido em um esquema de índice. Um perfil de pontuação pode ser composto por campos ponderados, funções e parâmetros.

A definição a seguir mostra um perfil simples nomeado “geo”. Esse exemplo aumenta os itens que têm o termo de pesquisa no campo hotelName. Ele também usa a função distance para favorecer resultados que estão em um raio de dez quilômetros do local atual. Se alguém pesquisar o termo "pousada" e "pousada" fizer parte do nome do hotel, os documentos que incluírem hotéis com "pousada" em um raio de 10 KM da localização atual serão exibidos nas posições mais altas nos resultados da pesquisa.

"scoringProfiles": [
  {  
    "name":"geo",
    "text": {  
      "weights": {  
        "hotelName": 5
      }                              
    },
    "functions": [
      {  
        "type": "distance",
        "boost": 5,
        "fieldName": "location",
        "interpolation": "logarithmic",
        "distance": {
          "referencePointParameter": "currentLocation",
          "boostingDistance": 10
        }                        
      }                                      
    ]                     
  }            
]

Para usar esse perfil de pontuação, a consulta é formulada para especificar o parâmetro scoringProfile na solicitação. Se você estiver usando a API REST, as consultas serão especificadas por meio de solicitações GET e POST. No exemplo a seguir, “currentLocation” tem um delimitador de um único traço (-). Ele é seguido por coordenadas de longitude e latitude, em que longitude é um valor negativo.

GET /indexes/hotels/docs?search+inn&scoringProfile=geo&scoringParameter=currentLocation--122.123,44.77233&api-version=2024-07-01

Observe as diferenças de sintaxe ao usar POST. Em POST, "scoringParameters" é plural e é uma matriz.

POST /indexes/hotels/docs&api-version=2024-07-01
{
    "search": "inn",
    "scoringProfile": "geo",
    "scoringParameters": ["currentLocation--122.123,44.77233"]
}

Essa consulta pesquisa o termo “pousada” e passa o local atual. Observe que essa consulta inclui outros parâmetros, como scoringParameter. Os parâmetros de consulta, incluindo "scoringParameter", são descritos em Documentos de Pesquisa (API REST).

Confira o Exemplo estendido para busca em vetores e híbrida e o Exemplo estendido para busca por palavras-chave para mais cenários.

Como funciona a pontuação de busca na Pesquisa de IA do Azure

Os perfis de pontuação complementam o algoritmo de pontuação padrão, aumentando as pontuações das correspondências que atendem aos critérios do perfil. As funções de pontuação se aplicam à busca por palavras-chave, consultas vetoriais puras e consultas híbridas.

Quando você usa perfis de pontuação ou qualquer outro recurso de aumento na Pesquisa de IA do Azure, o algoritmo RRF (função de classificação recíproca) atribui a pontuação, incluindo para consultas de texto e vetores independentes. Após a RRF, todos os ajustes de pontuação/aumento, classificação semântica e ponderação vetorial acontecem.

Adicionar um perfil de pontuação a um índice de pesquisa

1. Comece com uma definição de índice. Você pode adicionar e atualizar perfis de pontuação em um índice existente sem precisar recompilar ele. Use uma solicitação Criar ou Atualizar Índice para publicar a revisão.

2. Cole no modelo fornecido neste artigo.

3. Forneça um nome que siga as convenções de nomenclatura.

4. Especifique os critérios de aumento. Um único perfil pode conter campos ponderados de texto, funções ou ambos.

Você deve trabalhar iterativamente, usando um conjunto de dados que ajudará você a comprovar ou reprovar a eficácia de um determinado perfil.

Os perfis de pontuação podem ser definidos no portal do Azure, conforme mostrado na captura de tela a seguir, ou programaticamente por meio de APIs REST ou em SDKs do Azure, como a classe ScoringProfile no SDK do Azure para .NET.

Como usar campos ponderados de texto

Use campos ponderados de texto quando o contexto do campo for importante e as consultas incluírem campos de cadeia de caracteres searchable. Por exemplo, se uma consulta incluir o termo "aeroporto", você pode desejar que "aeroporto" no campo Descrição tenha mais peso do que no HotelName.

Os campos ponderados são pares nome-valor compostos por um campo searchable e um número positivo que é usado como multiplicador. Se a pontuação de campo original de HotelName for 3, a pontuação aumentada desse campo se tornará 6, contribuindo para uma pontuação geral mais alta para próprio documento pai.

"scoringProfiles": [  
    {  
      "name": "boostSearchTerms",  
      "text": {  
        "weights": {  
          "HotelName": 2,  
          "Description": 5 
        }  
      }  
    }
]

Usar funções

Use funções quando pesos relativos simples forem insuficientes ou não se aplicarem, como no caso da distância e da atualidade, que são cálculos sobre dados numéricos. Você pode especificar várias funções por perfil de pontuação. Para obter mais informações sobre os tipos de dados EDM usados na IA do Azure Search, consulte tipos de dados com suporte.

Regras para usar funções

• As funções só podem ser aplicadas a campos que são atribuídos como filterable.
• O tipo de função (“freshness”, “magnitude”, “distance”, “tag”) deve estar em minúsculas.
• As funções não podem incluir valores nulos ou vazios.
• As funções só podem ter um único campo por definição de função. Para usar a função "magnitude" duas vezes no mesmo perfil, forneça duas definições de magnitude, uma para cada campo.

Modelo

Esta seção mostra a sintaxe e o modelo para perfis de pontuação. Para uma descrição das propriedades, confira a Referência de API REST.

"scoringProfiles": [  
  {   
    "name": "name of scoring profile",   
    "text": (optional, only applies to searchable fields) {   
      "weights": {   
        "searchable_field_name": relative_weight_value (positive #'s),   
        ...   
      }   
    },   
    "functions": (optional) [  
      {   
        "type": "magnitude | freshness | distance | tag",   
        "boost": # (positive number used as multiplier for raw score != 1),   
        "fieldName": "(...)",   
        "interpolation": "constant | linear (default) | quadratic | logarithmic",   

        "magnitude": {
          "boostingRangeStart": #,   
          "boostingRangeEnd": #,   
          "constantBoostBeyondRange": true | false (default)
        }  

        // ( - or -)  

        "freshness": {
          "boostingDuration": "..." (value representing timespan over which boosting occurs)   
        }  

        // ( - or -)  

        "distance": {
          "referencePointParameter": "...", (parameter to be passed in queries to use as reference location)   
          "boostingDistance": # (the distance in kilometers from the reference location where the boosting range ends)   
        }   

        // ( - or -)  

        "tag": {
          "tagsParameter":  "..."(parameter to be passed in queries to specify a list of tags to compare against target field)   
        }
      }
    ],   
    "functionAggregation": (optional, applies only when functions are specified) "sum (default) | average | minimum | maximum | firstMatching"   
  }   
],   
"defaultScoringProfile": (optional) "...", 

Set interpolations

As interpolações definem a forma da inclinação usada para pontuação. Como a pontuação é decrescente, a inclinação está sempre diminuindo, mas é a interpolação que determina a curva da inclinação descendente. As seguintes interpolações podem ser usadas:

Definir o atributo boostingDuration para função "freshness"

boostingDuration é um atributo da função freshness. Você pode usá-lo para definir um período de expiração após o qual o aumento será interrompido para um documento específico. Por exemplo, para aumentar uma linha de produtos ou marca por um período promocional de 10 dias, você especificaria o período de 10 dias como "P10D" para esses documentos.

boostingDuration deve ser formatado como um valor XSD de "dayTimeDuration" (um subconjunto restrito de um valor de duração ISO 8601). O padrão para isso é: "P[nD][T[nH][nM][nS]]".

A tabela a seguir fornece vários exemplos.

Para obter mais exemplos, consulte Esquema XML: tipos de dados (site W3.org).

Exemplo estendido para busca em vetores e híbrida

Confira essa postagem no blog e esse notebook para uma demonstração de uso dos perfis de pontuação e aumento de pontuação de documentos em cenários de IA generativa e vetorial.

Exemplo estendido para busca por palavra-chave

O exemplo a seguir mostra o esquema de um índice com dois perfis de pontuação (boostGenre, newAndHighlyRated). Qualquer consulta em relação a esse índice que inclua um dos perfis como um parâmetro de consulta usará o perfil para pontuar o conjunto de resultados.

O perfil boostGenre usa campos de texto ponderados, aumentando as correspondências encontradas nos campos albumTitle, genre e artistName. Os campos são aumentados 1,5, 5 e 2, respectivamente. Por que o campo gênero aumentou muito mais do que os outros? Se a pesquisa for conduzida sobre dados relativamente homogêneos (como é o caso de 'genre' em musicstoreindex), uma variação maior nos pesos relativos poderá ser necessária. Por exemplo, em musicstoreindex, 'rock' é exibido como um gênero e em descrições de gênero redigidas de forma idêntica. Se você quiser que gênero tenha um peso maior do que a descrição do gênero, o campo gênero precisará ter um peso relativo muito mais alto.

{  
  "name": "musicstoreindex",  
  "fields": [  
    { "name": "key", "type": "Edm.String", "key": true },  
    { "name": "albumTitle", "type": "Edm.String" },  
    { "name": "albumUrl", "type": "Edm.String", "filterable": false },  
    { "name": "genre", "type": "Edm.String" },  
    { "name": "genreDescription", "type": "Edm.String", "filterable": false },  
    { "name": "artistName", "type": "Edm.String" },  
    { "name": "orderableOnline", "type": "Edm.Boolean" },  
    { "name": "rating", "type": "Edm.Int32" },  
    { "name": "tags", "type": "Collection(Edm.String)" },  
    { "name": "price", "type": "Edm.Double", "filterable": false },  
    { "name": "margin", "type": "Edm.Int32", "retrievable": false },  
    { "name": "inventory", "type": "Edm.Int32" },  
    { "name": "lastUpdated", "type": "Edm.DateTimeOffset" }  
  ],  
  "scoringProfiles": [  
    {  
      "name": "boostGenre",  
      "text": {  
        "weights": {  
          "albumTitle": 1.5,  
          "genre": 5,  
          "artistName": 2  
        }  
      }  
    },  
    {  
      "name": "newAndHighlyRated",  
      "functions": [  
        {  
          "type": "freshness",  
          "fieldName": "lastUpdated",  
          "boost": 10,  
          "interpolation": "quadratic",  
          "freshness": {  
            "boostingDuration": "P365D"  
          }  
        },  
        {
          "type": "magnitude",  
          "fieldName": "rating",  
          "boost": 10,  
          "interpolation": "linear",  
          "magnitude": {  
            "boostingRangeStart": 1,  
            "boostingRangeEnd": 5,  
            "constantBoostBeyondRange": false  
          }  
        }  
      ]  
    }  
  ],  
  "suggesters": [  
    {  
      "name": "sg",  
      "searchMode": "analyzingInfixMatching",  
      "sourceFields": [ "albumTitle", "artistName" ]  
    }  
  ]   
}  

Confira também

• Relevância e pontuação na IA do Azure Search
• referência da API REST (a página pode estar em inglês)
• Criar API do índice
• SDK do .NET da IA do Azure Search
• O que são perfis de pontuação?