添加计分概要文件以提高搜索分数

计分概要文件用于根据条件来提升匹配文档的排名。 本文介绍如何指定和分配计分概要文件，以便根据提供的参数提升搜索分数。 可以根据以下内容创建计分概要文件：

• 加权字符串字段，其提升基于指定字段中找到的匹配项。 例如，在“主题”字段中找到的匹配项被认为比“说明”字段中找到的匹配项更相关。

• 数值字段的函数，包括日期和地理坐标。 数值内容函数支持提升距离（适用于地理坐标）、新鲜度（适用于日期时间字段）、范围和数量级。

• 字符串集合（标签）的函数。 如果集合中的任何项都与查询匹配，标记函数将提升文档的搜索分数。

可以通过在 Azure 门户中编辑其 JSON 定义或通过任何 Azure SDK 中的 创建或更新索引 REST 或等效索引更新 API 等 API 以编程方式将计分配置文件添加到索引。 没有索引重新生成要求，因此可以添加、修改或删除评分配置文件，而不会影响索引文档。

Prerequisites

• 包含文本或数字（非函数）字段的搜索索引。

计分概要文件的规则

可以在关键字搜索、向量搜索、混合搜索和语义重排中使用评分配置文件。 但是，计分配置文件仅适用于非函数字段，因此请确保索引具有可以提升或加权的文本或数值字段。

在一个索引中可以具有最多 100 个计分概要文件（请参阅服务限制），但在任何给定查询中，一次只能指定一个概要文件。

可以将 语义排名器 与评分配置文件一起使用，并在语义排名后应用该 评分配置文件。 否则，当多个排名或相关性功能发挥作用时，语义排名是最后一步。 搜索评分的工作原理提供了插图。

额外的规则 特别适用于函数。

计分概要文件定义

计分概要文件在索引架构中定义。 它由加权字段、函数和参数组成。

以下定义展示了一个名为“geo”的简单概要文件。 此示例用于提升在“hotelName”字段中具有搜索词的结果。 它还使用 distance 函数优先提升在当前位置 10 公里范围内的结果。 如果有人搜索“inn”一词，而“inn”恰好是酒店名称的一部分，包含当前位置 10 公里范围内带有“inn”的酒店的文档会在搜索结果中的较高位置出现。

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

若要使用此计分概要文件，查询要表述为指定请求中的 scoringProfile 参数。 如果使用 REST API，则通过 GET 和 POST 请求指定查询。 在以下示例中，“currentLocation”使用单破折号 (-) 作为分隔符。 它后跟经度和纬度坐标，其中经度为负值。

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

scoringParameters中介绍了查询参数（包括）。

有关更多方案，请参阅本文中 有关新鲜度、距离 和 加权文本和函数 的示例。

将计分概要文件添加到搜索索引

1. 从索引定义开始。 可以在现有索引中添加和更新计分概要文件，而无需重新生成它。 使用 创建或更新索引 请求发布修订。

2. 粘贴到本文中提供的模板中。

3. 提供符合命名约定的名称。

4. 指定提升条件。 单个配置文件可以包含文本加权字段和/或函数。

应以迭代方式使用数据集，该数据集将帮助你证明或否定给定概要文件的效力。

可以在 Azure 门户中定义计分配置文件，如以下屏幕截图所示，也可以通过 REST API 或 Azure SDK 以编程方式定义，例如 .NET 或 Python 客户端库中的 ScoringProfile 类。

Template

本部分演示计分概要文件的语法和模板。 有关属性的描述，请参阅 REST API 参考。

"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 or negative 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) "...", 

使用文本加权字段

当字段上下文很重要且查询包含 searchable 字符串字段时，使用文本加权字段。 例如，如果查询包含“airport”一词，则可能需要在 HotelName 字段中使用“airport”，而不是“描述”字段。

加权字段是由一个 searchable 字段和一个用作乘数的正数组成的名称-值对。 如果 HotelName 的原始字段分数为 3，则该字段的提升分数将变为 6，这将导致父文档本身的总分更高。

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

使用函数

当简单的相对权重不足或不适用时，请使用函数，例如距离和新鲜度的情况（即对数值数据的计算）。 可以为每个计分概要文件指定多个函数。 有关 Azure AI 搜索中使用的 EDM 数据类型的详细信息，请参阅支持的数据类型。

数量级是字段值（如日期或位置）与引用点（如“now”或目标位置）之间的计算距离。 它是评分函数的输入，并确定应用增益的程度。

新鲜度评分和距离评分是数量级评分的一种特殊情况，其中数量级是通过日期时间字段或地理字段自动计算的。 为了直观地提升较新或更接近的值，请使用负提升值（参见示例以获取更多详细信息）。

使用函数的规则

• 函数只能应用于被归为 filterable 的字段。
• 函数类型（“freshness”、“magnitude”、“distance”、“tag”）必须是小写。
• 函数不能包含 null 值或空值。
• 每个函数定义只能有一个字段。 若要在同一概要文件中使用数量级两次，请提供两个数量级定义，每个定义对应一个字段。

设置内插

插值设定了用于提升新鲜度和距离的斜率形状。

当提升值为正值时，评分高到低，斜率始终下降。 在负面加权的情况下，斜率变陡（较新的文档被赋予更高的分数）。 内插值确定向上或向下斜率的曲线，以及响应日期或距离变化时提升分数的变化程度。 可以使用以下内插：

为 freshness 函数设置 boostingDuration

boostingDuration 是 freshness 函数的属性。 使用它设置一个有效期，超过这个有效期之后，针对特定文档的提升将停止。 例如，要在 10 天促销期内提升某个产品系列或品牌，应针对这些文档将 10 天期限指定为 "P10D"。

boostingDuration 必须设置为 XSD "dayTimeDuration" 值（ISO 8601 持续时间值的受限子集）的格式。 它的模式为：“P[nD][T[nH][nM][nS]]”。

下表提供几个示例。

有关更多示例，请参阅 XML 架构：数据类型（W3.org 网站）。

示例：通过新鲜度或距离提升

在 Azure AI 搜索中，新鲜度评分将日期和数值转换为一个表示文档日期与当前时间间隔的单一数值。 日期越大，数量级越大。 这会导致一种反直观的行为：最近的文档幅度较小，这意味着积极的加权因素倾向于支持较旧的文档，除非明确反转加权方向。

同样的逻辑适用于距离提升，其中更远的位置产生更大的数量级。

若要通过新鲜度或距离提升，请使用负提升值来确定较新的日期或更近的位置的优先级。 通过负助推因子反转提升方向，会惩罚数值较大的情况（如较旧的日期），从而有效地助推较新的日期。 例如，假设一个提升函数，如 b * (1 - x)（其中 x 是从 0 到 1 的规范化的幅度），该函数为较小的幅度（即较新的日期）提供更高的分数。

提升曲线的形状（常量、线性、对数、二次）会影响得分在整个范围内变化的剧烈程度。 当使用负因子时，曲线的行为会发生变化。例如，二次曲线在较旧日期时收敛得更慢，而对数曲线在远端变化更为急剧。

下面是一个示例计分配置文件，演示如何使用负提升解决反直观的新鲜度评分，并说明此上下文中数量级的工作原理。

"scoringProfiles": [
  {
    "name": "freshnessBoost",
    "text": {
      "weights": {
        "content": 1.0
      }
    },
    "functions": [
      {
        "type": "freshness",
        "fieldName": "lastUpdated",
        "boost": -2.0,
        "interpolation": "quadratic",
        "parameters": {
          "boostingDuration": "365D"
        }
      }
    ]
  }
]

• "fieldName": "lastUpdated" 是用于计算新鲜度的日期/时间字段。
• "boost": -2.0 是一个负提升因子，可反转默认行为。 由于较旧的日期有较大的数值，从而减少其重要性，并提升较新文档的重要性。
• "interpolation": "quadratic" 这意味着，对于离当前日期更近的文档来说，提升效应更强，而对于较旧的文档，效果会更迅速减弱。
• "boostingDuration": "365D" 定义评估新鲜度的时间范围。

示例：通过加权文本和函数进行提升操作

以下示例演示具有两个计分概要文件的索引架构（boostGenre、newAndHighlyRated）。 针对此索引的任何查询（包含任一概要文件作为查询参数）将使用此概要文件对结果集进行计分。

boostGenre 概要文件使用加权文本字段来提升 albumTitle、genre 和 artistName 字段中找到的匹配项。 这些字段各自提升 1.5、5 和 2。 为什么“genre”的提升比其他字段高得多？ 如果对有点同质的数据进行搜索（与 musicstoreindex 中的“流派”一样），则可能需要相对权重的较大方差。 例如，在 musicstoreindex 中，“rock”既作为流派显示，又显示在采用相同组句方式的流派说明中。 如果希望流派超过流派描述，流派字段需要更高的相对权重。

{  
  "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  
          }  
        }  
      ]  
    }  
  ]
}