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

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

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

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

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

• （预览版）不同提升的聚合。 在单个计分配置文件中，可以指定多个评分函数，然后设置 "functionAggregation": "product"。 对所有函数进行高度评分的文档处于优先顺序，同时取消在一个或多个字段中评分较弱的文档。

可以通过在 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 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 数据类型的详细信息，请参阅支持的数据类型。

新鲜度评分和距离评分是数量级评分的一种特殊情况，其中数量级是通过日期时间字段或地理字段自动计算的。

使用函数的规则

• 函数只能应用于被归为 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 网站）。

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

提升曲线的形状（常量、线性、对数、二次）会影响得分在整个范围内变化的剧烈程度。

使用新鲜度函数时，如果希望对最近的日期有更显著的提升效果，请选择二次插值。 二次函数放大了最近日期和较近位置的影响，并在范围的远端以较慢的速度逐渐减小。 相比之下，对数曲线在远端更急剧地移动。

下面是一个示例评分配置，展示了如何基于新鲜度来提升分值。

{
    "name": "docs-index",
    "fields": [
      { "name": "id", "type": "Edm.String", "key": true, "filterable": true },
      { "name": "title", "type": "Edm.String", "searchable": true },
      { "name": "content", "type": "Edm.String", "searchable": true },
      { "name": "lastUpdated", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true }
    ],
    "scoringProfiles": [
      {
        "name": "freshnessBoost",
        "text": {
          "weights": {
            "content": 1.0
          }
        },
        "functions": [
          {
            "type": "freshness",
            "fieldName": "lastUpdated",
            "boost": 2.0,
            "interpolation": "quadratic",
            "parameters": {
              "boostingDuration": "365D"
            }
          }
        ]
    }
  ]
}

• 该 freshness 函数计算从“现在”到 lastUpdated 的幅度。
• 当使用二次插值并设置正向加权时，最近日期的文档会获得更高的提升，而较旧的文档加权效果会迅速减弱。
• "boostingDuration": "365D" 定义了新鲜度评估的时间窗口，例如用于提升最近一年内的文档。
• "interpolation": "quadratic" 这意味着，对于离当前日期更近的文档来说，提升效应更强，而对于较旧的文档，效果会更迅速减弱。

在下一个示例中，线性内插为 30 天时段内的最新内容提供了稳定的首选项。 如果需要让该信号在与其他相关性因素的竞争中占优势，可以提高加权幅度。

{
  "name": "freshness30_linear",
  "functions": [
    {
      "type": "freshness",
      "fieldName": "lastUpdated",
      "boost": 3.0,
      "interpolation": "linear",
      "parameters": { "boostingDuration": "P30D" }
    }
  ]
}

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

以下示例演示具有两个计分概要文件的索引架构（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  
          }  
        }  
      ]  
    }  
  ]
}  

示例：函数聚合

在单个计分配置文件中，可以指定多个评分函数，然后设置 "functionAggregation": "product"。 对所有函数进行高度评分的文档处于优先顺序，同时取消在一个或多个字段中评分较弱的文档。

在此示例中，创建一个计分配置文件，其中包含两个提升函数，这些函数分别通过rating和baseRate进行提升，接着将functionAggregation设置为product。

### Create a new index
PUT {{url}}/indexes/hotels-scoring?api-version=2025-11-01-preview
Content-Type: application/json
api-key: {{key}}

{
    "name": "hotels-scoring",  
    "fields": [
        {"name": "HotelId", "type": "Edm.String", "key": true, "filterable": true, "facetable": true},
        {"name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": true},
        {"name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": true, "analyzer": "en.lucene"},
        {"name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
        {"name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true},
        {"name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "sortable": true, "facetable": true},
        {"name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true, "facetable": true},
        {"name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true},
        {"name": "BaseRate", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true },
        {"name": "Address", "type": "Edm.ComplexType", 
            "fields": [
            {"name": "StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": true, "searchable": true},
            {"name": "City", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
            {"name": "StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
            {"name": "PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true}
            ]
        }
    ],
    "scoringProfiles": [
        {
            "name": "productAggregationProfile",
            "functions": [
                {
                    "type": "magnitude",
                    "fieldName": "Rating",
                    "boost": 2.0,
                    "interpolation": "linear",
                    "magnitude": {
                        "boostingRangeStart": 1.0,
                        "boostingRangeEnd": 5.0,
                        "constantBoostBeyondRange": false
                    }
                },
                {
                    "type": "magnitude",
                    "fieldName": "BaseRate",
                    "boost": 1.5,
                    "interpolation": "linear",
                    "magnitude": {
                        "boostingRangeStart": 50.0,
                        "boostingRangeEnd": 400.0,
                        "constantBoostBeyondRange": false
                    }
                }
            ],
            "functionAggregation": "product"
        }
    ],
    "defaultScoringProfile": "productAggregationProfile"
}

下一个请求将使用可搜索的内容加载索引，这些内容用于测试概况。

### Upload documents to the index
POST {{url}}/indexes/hotels-scoring/docs/index?api-version=2025-11-01-preview
Content-Type: application/json
api-key: {{key}}

  {
        "value": [
        {
        "@search.action": "upload",
        "HotelId": "1",
        "HotelName": "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.",
        "Category": "Boutique",
        "Tags": [ "view", "air conditioning", "concierge" ],
        "ParkingIncluded": false,
        "LastRenovationDate": "2022-01-18T00:00:00Z",
        "Rating": 3.60,
        "BaseRate": 200.0,
        "Address": 
            {
            "StreetAddress": "677 5th Ave",
            "City": "New York",
            "StateProvince": "NY",
            "PostalCode": "10022"
            } 
        },
        {
        "@search.action": "upload",
        "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.",
         "Category": "Boutique",
        "Tags": [ "pool", "free wifi", "concierge" ],
        "ParkingIncluded": false,
        "LastRenovationDate": "2019-02-18T00:00:00Z",
        "Rating": 3.60,
        "BaseRate": 150.0,
        "Address": 
            {
            "StreetAddress": "140 University Town Center Dr",
            "City": "Sarasota",
            "StateProvince": "FL",
            "PostalCode": "34243"
            } 
        },
        {
        "@search.action": "upload",
        "HotelId": "3",
        "HotelName": "Gastronomic Landscape Hotel",
        "Description": "The Gastronomic Landscape Hotel stands out for its culinary excellence under the management of William Dough, who advises on and oversees all of the Hotel’s restaurant services.",
        "Category": "Suite",
        "Tags": [ "restaurant", "bar", "continental breakfast" ],
        "ParkingIncluded": true,
        "LastRenovationDate": "2015-09-20T00:00:00Z",
        "Rating": 4.80,
        "BaseRate": 350.0,
        "Address": 
            {
            "StreetAddress": "3393 Peachtree Rd",
            "City": "Atlanta",
            "StateProvince": "GA",
            "PostalCode": "30326"
            } 
        },
        {
        "@search.action": "upload",
        "HotelId": "4",
        "HotelName": "Sublime Palace Hotel",
        "Description": "Sublime Palace 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.",
        "Tags": [ "concierge", "view", "air conditioning" ],
        "ParkingIncluded": true,
        "LastRenovationDate": "2020-02-06T00:00:00Z",
        "Rating": 4.60,
        "BaseRate": 275.0,
        "Address": 
            {
            "StreetAddress": "7400 San Pedro Ave",
            "City": "San Antonio",
            "StateProvince": "TX",
            "PostalCode": "78216"
            }
        }
    ]
}

运行查询，使用计分概要文件中的条件根据高评分和高基础速率提升结果。 聚合提升分数，以进一步增强在这两个功能中均获得高分的结果。

### Search with boost
POST {{url}}/indexes/hotels-scoring/docs/search?api-version=2025-11-01-preview
Content-Type: application/json
api-key: {{key}}

{
    "search": "expensive and good hotels",
    "count": true,
    "select": "HotelId, HotelName, Description, Rating, BaseRate",
    "scoringProfile": "productAggregationProfile"
}

此查询的最高响应是“文体景观酒店”，搜索分数几乎是下一个最接近的匹配项的两倍。 这家特别的酒店具有最高的评级和最高的基价，因此两个函数的复合将推动该匹配位居榜首。

{
  "@odata.count": 4,
  "value": [
    {
      "@search.score": 1.0541908,
      "HotelId": "3",
      "HotelName": "Gastronomic Landscape Hotel",
      "Description": "The Gastronomic Hotel stands out for its culinary excellence under the management of William Dough, who advises on and oversees all of the Hotel\u2019s restaurant services.",
      "Rating": 4.8,
      "BaseRate": 350.0
    },
    {
      "@search.score": 0.53451097,
      "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.",
      "Rating": 3.6,
      "BaseRate": 150.0
    },
    {
      "@search.score": 0.53185254,
      "HotelId": "1",
      "HotelName": "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.",
      "Rating": 3.6,
      "BaseRate": 200.0
    },
    {
      "@search.score": 0.44853577,
      "HotelId": "4",
      "HotelName": "Sublime Palace Hotel",
      "Description": "Sublime Palace 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.",
      "Rating": 4.6,
      "BaseRate": 275.0
    }
  ]
}

调优建议

• 开始保守：将范围提高到 1.25–2.0；只有当最新性真正具有决定性时才增加。

• 窗口大小建议：P30D 适用于热点内容；P90D 或 P180D 适用于中等时效性内容；P365D 适用于长尾内容。

• 内插选项：

  • 使用二次插值时，能对最近内容给予更强的加权。
  • 如果需要稳定渐变，则为线性。
  • 使用对数插值时，偏好较为温和。

• 聚合：如果合并多个函数，则求和最简单;当希望单个信号主宰时切换到最大值