評分設定檔可用來根據使用者定義的準則提升或抑制符合文件的排名。 在本文中,了解如何指定及指派評分設定檔,以根據您提供的參數來提升搜尋分數。 您可以根據下列項目建立評分設定檔:
加權字串欄位,其中增效 (boosting) 是以指定欄位中找到的相符項目為基礎。 例如,在 [主旨] 欄位中找到的相符專案會被視為比在 [描述] 欄位中找到的相同相符專案更相關。
數值欄位的函數,包括日期和地理座標。 數值內容的函式支援距離增效 (適用於地理座標)、新鮮度 (適用於日期時間欄位)、範圍和範圍。
字串集合的函式(標籤)。 如果集合中的任何專案與查詢相符,標籤函式會提升檔的搜尋分數。
(預覽) 相異加速器的彙總。 在單一評分設定檔中,你可以指定多個評分函數,然後設定
"functionAggregation": "product"。 所有功能得分高的文件會被優先處理,而在一個或多個領域得分較弱的文件則會被排除。
您可以在 Azure 入口網站中編輯其 JSON 定義,或透過任何 Azure SDK 中的 建立或更新索引 REST 或對等索引更新 API 等 API,以程式設計方式將評分配置檔新增至索引。 沒有索引重建需求,因此您可以新增、修改或刪除評分配置檔,而不會影響已編製索引的檔。
Prerequisites
- 具有文字或數值(非函式)欄位的搜尋索引。
評分設定檔的規則
您可以在關鍵字搜尋、向量搜尋、混合搜尋以及語意重新排名中使用評分設定檔。 不過,評分配置檔僅適用於非函式欄位,因此請確定您的索引具有可提升或加權的文字或數值欄位。
在一個索引中最多可有 100 個評分設定檔(參見 服務限制),但每次查詢只能指定一個設定檔。
您可以將語意排名與評分設定檔搭配使用,並在進行語意排名後套用評分設定檔。 否則,當多個排名或相關性功能被使用時,語意排序是最後一個步驟。 搜尋評分的運作 方式說明了操作順序。
額外的規則 特別套用至函式。
Note
不熟悉相關性概念嗎? 請造訪 Azure AI 搜尋服務中的相關性和評分 (英文),以取得背景資訊。 您也可以在 YouTube 上觀看這段影片 (英文),以取得 BM25 排名結果的評分設定檔。
評分設定檔定義
評分設定檔是在索引結構描述中所定義。 它包含加權欄位、函式和參數。
下列定義顯示名為 "geo" 的簡單設定檔。 此範例會提升 hotelName 欄位中有搜尋字詞的結果。 也會使用 distance 函式,優先列出與目前位置相距 10 公里以內的結果。 如果有人搜尋「inn」一詞,而「inn」恰好是旅館名稱的一部分,包含「inn」的旅館且位於當前位置10公里半徑內的文件會在搜尋結果中排名更高。
"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 的查詢參數在搜尋檔案 (REST API)中有所描述。
如需更多案例,請參閱本文中 新鮮度和距離 和 加權文字和函 式的範例。
將評分設定檔新增至搜尋索引
從索引定義開始。 您可以在現有的索引上新增和更新評分設定檔,而不需要重建。 使用 Get Index 拉取現有索引,並使用 Create 或 Update 索引 請求來發布修訂。
在本文提供的範本中貼上。
提供遵守命名慣例的名稱。
您應該反覆運作,使用資料集協助您證明或反駁給定設定檔的效力。
評分配置檔可以在 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」而不是 Description 欄位。
加權欄位是由 searchable 欄位與做為乘數的正數組成的名稱/值對。 如果 HotelName 的原始欄位分數為 3,該欄位的提升分數會變成 6,因而讓父文件本身的整體分數提高。
"scoringProfiles": [
{
"name": "boostSearchTerms",
"text": {
"weights": {
"HotelName": 2,
"Description": 5
}
}
}
]
使用函式
當簡單相對權數不足或不適用時,請使用函式,如同距離和時效性的情況,需對數值資料進行計算。 您可以為每個評分設定檔指定多個函式。 如需 Azure AI 搜尋服務中所用 EDM 資料類型的詳細資訊,請參閱支援的資料類型。
| Function | Description | 使用案例 |
|---|---|---|
| distance | 依鄰近性或地理位置提升。 此函數僅適用於 Edm.GeographyPoint 欄位。 |
用於「尋找我附近」案例。 |
| freshness | 依日期時間欄位 (Edm.DateTimeOffset) 中的值提升。
設定 boostingDuration 以指定值,代表發生提升的時間範圍。 |
當你想推廣最近(較新的)日期時使用。 您也可以提升像行事曆事件這類未來日期的項目,讓越接近現在的事件比日期較遠的事件權重更高。 範圍的一端固定為目前時間。 |
| magnitude | 大小是文件值(如日期或地點)與參考點(如「現在」或目標地點)之間的計算距離。 它是計分功能的輸入,決定加壓的幅度。 根據數值欄位的值範圍改變排名。 此值必須是整數或浮點數。 就 1 到 4 的星級評等而言,這會是 1。 就超過 50% 的利潤而言,這會是 50。 此函數僅適用於 Edm.Double 和 Edm.Int 欄位。 使用 magnitude 函式時,若您想要反轉模式 (例如將價格低的項目提升為高於價格高的項目),可將高至低的範圍反轉。 假設價格範圍為 $100 美元到 $1 美元,您會將 boostingRangeStart 設定為 100,並將 boostingRangeEnd 設定為 1,以在較低的價格項目提升。 |
請在您要依獲利率、評等、點選連結計數、下載次數、最高價格、最低價格或下載計數來提升時使用。 當兩個項目相關時,會先顯示具有較高評等的專案。 |
| 加標籤 | 依搜尋文件和查詢字串共通的標記提升。 標籤會在 tagsParameter 中提供。 此函式只能與 Edm.String 和 Collection(Edm.String) 類型的搜尋欄位搭配使用。 |
請在您有標籤欄位時使用。 如果清單中的指定標記本身是逗號分隔清單,您可以對欄位使用文字正規化程式,在查詢時移除逗號 (將逗號字元對應至空格)。 此方法會將清單「扁平化」,讓所有字詞都是單一且長串的逗號分隔字詞。 |
新鮮度和距離評分是基於量級的評分特例,其中量級是自動根據日期時間或地理欄位計算。
使用函數的規則
- 函式只能套用至屬性為
filterable的欄位。 - 函式類型 ("freshness"、"magnitude"、"distance"、"tag") 必須是小寫。
- 函式不可包含 null 或空值。
- 函式的每個函式定義只能有一個欄位。 若要在同一個設定檔中使用範圍兩次,請提供兩個定義範圍,每個欄位各一個。
設定內插補點
插補設定斜率的形狀,用於提升新鮮度和距離。 由於評分是從高到低,斜率總是下降,但插值可決定下降曲線的形狀,以及當文件日期變舊時提升分數變化速度有多快。
| Interpolation | Description |
|---|---|
linear |
對於在最大和最小範圍內的項目,會在已持續遞減的量中套用提升。 建議在需要逐漸降低相關性時使用。 線性是評分設定檔的預設插補。 |
constant |
對於在開始和結束範圍內的項目,會對排名結果套用常數提升。 當您想要一般懲罰,無論年齡為何時,請使用此選項。 |
quadratic |
二次插值在初期下降得較緩慢,接近範圍末端時下降速度加快,下降幅度明顯增加。 當您希望大幅提高最新文件的權重,並明顯降低較舊文件的權重時,可使用此內插法。 標籤評分函式中不允許此插補選項。 |
logarithmic |
對數起初以較高的速度減少,而在接近結束範圍時,它會以更小的間隔減少。 當您強烈偏好最新內容時,建議使用這個方法,但隨著文件逐漸過時,敏感性會降低。 標籤評分函式中不允許此插補選項。 |
設定 boostingDuration for freshness 函式
boostingDuration 是 freshness 函式的屬性。 您可以使用它來設定有效期限,之後特定檔案的提升效果將停止。 例如,若要在為期 10 天的促銷期間提升某個產品系列或品牌,您可以為這些文件指定 10 天的期間 "P10D"。
boostingDuration 必須格式化為 XSD "dayTimeDuration" 值 (ISO 8601 持續時間值的限定子集)。 其模式為:"P[nD][T[nH][nM][nS]]"。
下表提供數個範例。
| Duration | boostingDuration |
|---|---|
| 1 天 | "P1D" |
| 2 天又 12 個小時 | "P2DT12H" |
| 15 分鐘 | "PT15M" |
| 30 天 5 小時 10 分鐘又 6.334 秒 | "P30DT5H10M6.334S" |
| 1 年 | “365D” |
如需更多範例,請參閱 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 和 musicName 欄位中找到的相符項目。 欄位分別提升了 1.5、5 和 2。 為何內容類型提升的程度遠比其他多? 如果搜尋是針對有點同質的數據進行(就音樂商店索引中的「類型」而言),您可能需要較大的相對權數變異數。 例如,在 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
}
}
]
}
]
}
範例:函數聚合
Note
此功能目前處於預覽階段,透過 2025-11-01-preview REST API 及提供此功能的 Azure SDK 預覽套件提供。
在單一評分設定檔中,你可以指定多個評分函數,然後設定 "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"
}
此查詢的最高回應是「Gastronomic Landscape Hotel」,其搜尋分數幾乎是下一個接近匹配的兩倍。 這家飯店同時擁有最高評價和最高基本房價,因此兩者的結合使這家飯店在排名中居於首位。
{
"@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 用於長尾內容。
插值選擇:
- 當您希望強力推動近期文件,可以使用二次曲線。
- 當您需要穩定的梯度時,可以使用線性曲線。
- 當您需要溫和的偏重時,可以使用對數曲線。
聚合:若結合多個函數,求和最為簡單;當你想讓單一訊號主導時,切換到最大值