점수 매기기 프로필을 추가하여 검색 점수 높이기

점수 매기기 프로필은 조건에 따라 일치하는 문서의 순위를 높이는 데 사용됩니다. 이 문서에서는 제공하는 매개 변수에 따라 검색 점수를 높이는 점수 매기기 프로필을 지정하고 할당하는 방법을 알아봅니다. 다음을 기반으로 점수 매기기 프로필을 만들 수 있습니다.

• 지정된 필드에서 찾은 일치 항목을 기반으로 향상이 이루어지는 가중 문자열 필드입니다. 예를 들어 "제목" 필드에 있는 일치 항목은 "설명" 필드에 있는 것과 동일한 일치 항목보다 관련성이 더 큰 것으로 간주됩니다.

• 날짜 및 지리적 좌표를 포함한 숫자 필드에 대한 함수입니다. 숫자 콘텐츠에 대한 함수는 거리 상승(지리적 좌표에 적용), 새로 고침(날짜/시간 필드에 적용), 범위 및 크기를 지원합니다.

• 문자열 컬렉션(태그)에 대한 함수입니다. 태그 함수는 컬렉션의 항목이 쿼리와 일치하는 경우 문서의 검색 점수를 높입니다.

Azure 포털에서 JSON 정의를 편집하거나, Create 또는 Update Index REST API 또는 Azure SDK의 동등한 인덱스 업데이트 API를 통해 프로그래밍 방식으로 점수 매기기 프로필을 인덱스에 추가할 수 있습니다. 인덱싱된 문서에 영향을 주지 않고 점수 매기기 프로필을 추가, 수정 또는 삭제할 수 있도록 인덱스 다시 작성 요구 사항이 없습니다.

Prerequisites

• 텍스트 또는 숫자(비벡터) 필드가 있는 검색 인덱스입니다.

점수 매기기 프로필 규칙

키워드 검색, 벡터 검색, 하이브리드 검색 및 의미 체계 재전송에서 점수 매기기 프로필을 사용할 수 있습니다. 그러나 점수 매기기 프로필은 비벡터 필드에만 적용되므로 인덱스에 증가하거나 가중치를 적용할 수 있는 텍스트 또는 숫자 필드가 있는지 확인합니다.

인덱스 하나에 최대 100개의 점수 매기기 프로필을 포함할 수는 있지만(서비스 한도 참조) 프로필은 지정된 쿼리에 한 번에 하나만 지정할 수 있습니다.

점수 매기기 프로필과 함께 의미 체계 순위 매기기를 사용하고 의미 체계 순위 후에 점수 매기기 프로필을 적용할 수 있습니다. 그렇지 않으면 여러 순위 또는 관련성 기능이 실행 중인 경우 의미 체계 순위가 마지막 단계입니다. 검색 채점의 작동 방식은 이에 대한 일러스트레이션을 제공합니다.

추가 규칙은 함수에 특별히 적용됩니다.

점수 매기기 프로필 정의

점수 매기기 프로필은 인덱스 스키마에 정의됩니다. 가중치 필드, 함수 및 매개 변수로 구성됩니다.

다음 정의는 "geo"라는 간단한 프로필을 보여 줍니다. 이 예제는 hotelName 필드에 검색 용어가 포함된 결과를 부스트합니다. 또한 distance 함수를 사용하여 현재 위치에서 10km 이내에 있는 결과의 점수를 높입니다. 누군가가 'inn'이라는 용어를 검색하고 '여관'이 호텔 이름의 일부인 경우 현재 위치의 반경 10km 내에 '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쿼리 매개 변수는 REST API(검색 문서)에 설명되어 있습니다.

더 많은 시나리오는 이 문서의 새로 고침 및 거리 및가중 텍스트 및 함수 에 대한 예제를 참조하세요.

검색 인덱스에 점수 매기기 프로필 추가

1. 인덱스 정의부터 시작합니다. 인덱스를 다시 작성하지 않고 기존 인덱스에서 점수 매기기 프로필을 추가하고 업데이트할 수 있습니다. 인덱스 만들기 또는 업데이트 요청을 사용하여 수정 내용을 게시합니다.

2. 이 문서에 제공된 템플릿에 붙여넣습니다.

3. 명명 규칙을 준수하는 이름을 지정합니다.

4. 점수 상승 조건을 지정합니다. 단일 프로필에 텍스트 가중 필드, 함수 또는 둘 다 포함될 수 있습니다.

지정된 프로필의 효능을 증명하거나 반증하는 데 도움이 되는 데이터 세트를 사용하여 반복적으로 작업해야 합니다.

채점 프로필은 다음 스크린샷과 같이 Azure Portal에서 정의하거나 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 또는 빈 값을 포함할 수 없습니다.
• 함수에는 함수 정의당 필드가 하나만 있을 수 있습니다. 같은 프로필에서 magnitude를 두 번 사용하려면 각 필드에 하나씩 두 개의 magnitude 정의를 제공합니다.

보간법 설정

보간법은 신선도와 거리를 증가시키기 위해 사용되는 기울기의 형태를 설정합니다.

상승 값이 양수이면 점수 매기기는 높음에서 낮음으로, 기울기는 항상 감소합니다. 음성 부스트를 사용하여 기울기가 증가합니다(최신 문서일수록 점수가 높아짐). 보간 값은 위쪽이나 아래쪽 기울기의 곡선을 결정하고 날짜나 거리 변경에 따라 부스트 점수가 얼마나 적극적으로 변경되는지를 결정합니다. 다음과 같은 보간을 사용할 수 있습니다.

freshness 함수에 대한 boostingDuration 설정

boostingDuration은 freshness 함수의 특성입니다. 이를 사용하여 특정 문서에 대한 상승이 중지되는 만료 기간을 설정합니다. 예를 들어 프로모션 기간 10일 동안 특정 제품 라인이나 브랜드를 상승시키려는 경우 해당 문서에 대해 10일의 기간을 "P10D"로 지정합니다.

boostingDuration 의 형식은 XSD "dayTimeDuration" 값(ISO 8601 기간 값의 제한된 하위 집합)으로 지정해야 합니다. 이 형식의 패턴은 "P[nD][T[nH][nM][nS]]"입니다.

다음 표에 여러 예제가 나와 있습니다.

더 많은 예제를 보려면 XML 스키마: Datatypes(W3.org 웹 사이트)를 참조하세요.

예: 최신 여부 또는 거리에 따른 부스팅

Azure AI Search에서 새로 고침 점수 매기기는 날짜와 값을 숫자 크기로 변환하며, 이는 문서의 날짜가 현재 시간에서 얼마나 멀리 떨어져 있는지를 나타내는 단일 숫자입니다. 날짜가 오래되면 크기가 더 큽니다. 이로 인해 직관적이지 않은 동작이 발생합니다. 최근 문서에는 크기가 작습니다. 즉, 승격 방향을 명시적으로 반전하지 않는 한 긍정적인 상승 요인이 이전 문서를 선호합니다.

이 동일한 논리는 멀리 떨어진 위치에서 더 큰 크기를 생성하는 거리 상승에 적용됩니다.

신선도나 거리 기준으로 우선 순위를 높이고자 한다면, 부정적인 가중치 값을 사용하여 최신 날짜나 가까운 위치를 우선적으로 선택합니다. 음성 부스팅 인자를 통해 부스트 방향을 반전시키면 더 큰 규모(오래된 날짜)에 페널티가 부과되며, 더 최신 문서를 효과적으로 부스팅합니다. 예를 들어, b * (1 - x)과 같은 증폭 함수(x는 0에서 1 사이로 정규화된 크기)를 사용하여 더 작은 크기(즉, 최신 날짜)에 더 높은 점수를 부여한다고 가정합니다.

상승 곡선의 모양(상수, 선형, 로그, 이차)은 범위 전체에서 점수가 얼마나 적극적으로 변하는지에 영향을 줍니다. 음수 인자가 있으면 곡선의 움직임이 대칭 이동됩니다. 예를 들어, 2차 곡선은 오래된 날짜일수록 더 느리게 감소하는 반면, 대수 곡선은 끝 부분으로 갈수록 더 급격하게 이동합니다.

다음은 음성 부스팅을 사용하여 직관적이지 않은 최신 여부 점수를 해결하는 방법을 보여 주고 컨텍스트에서 규모가 어떻게 작동하는지 설명하는 점수 매기기 프로필의 예입니다.

"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"는 신선도가 평가되는 시간 창을 정의합니다.

예: 가중 텍스트 및 함수로 증강

아래 예제에서는 2개의 점수 매기기 프로필 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  
          }  
        }  
      ]  
    }  
  ]
}