Edit

Share via

Use scoring profiles with semantic ranker in Azure AI Search

Note

This feature is currently in public preview. This preview is provided without a service-level agreement and isn't recommended for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see Supplemental Terms of Use for Microsoft Azure Previews.

Using a scoring profile with semantic ranker is supported in newer Azure AI Search preview REST API versions and Azure SDK preview packages. With this feature, the scoring profile is processed last. Without this feature, semantic ranking is processed last.

To ensure the scoring profile provides the determining score, the semantic ranker adds a new response field, @search.rerankerBoostedScore, that applies scoring profile logic on semantically ranked results. In search results that include @search.score from level 1 ranking, @search.rerankerScore from semantic ranker, and @search.reRankerBoostedScore, results are sorted by @search.reRankerBoostedScore.

Note

If you're using a stable API version or an earlier preview, scoring profiles are only used upstream, before the semantic ranking step. For a diagram of the scoring workflow, see Relevance in Azure AI Search.

Prerequisites

Tip

For all preview features, we recommend reviewing the Azure SDK change logs to check for feature availability: Python SDK change log, .NET SDK change log, Java SDK change log, JavaScript SDK change log.

Limitations

Boosting of semantically ranked results applies to scoring profile functions only. There's no boosting if the scoring profile consists only of weighted text fields.

How does semantic configuration with scoring profiles work?

When you execute a semantic query associated with a scoring profile, a third search score, @search.rerankerBoostedScore value, is generated for every document in your search results. This boosted score, calculated by applying the scoring profile to the existing reranker score, doesn't have a guaranteed range (0–4) like a normal reranker score, and scores can be significantly higher than 4.

Starting in API version 2025-05-01-preview, semantic results are sorted by @search.rerankerBoostedScore by default if a scoring profile exists. If the rankingOrder property isn't specified, then BoostedReRankerScore is the default value in the semantic configuration.

In this scenario, a scoring profile is used twice.

  1. First, the scoring profile defined in your index is used during the initial L1 ranking phase, boosting results from:

    • Text-based queries (BM25 or RRF)
    • The text portion of vector queries
    • Hybrid queries that combine both types

  2. Next, the semantic ranker rescores the top 50 results, promoting more semantically relevant matches to the top. This step can erase the benefit of the scoring profile. For example, if you boosted based on freshness, then semantic reordering replaces that boost with its own logic of what is most relevant.

  3. Finally, the scoring profile is applied again, after reranking, restoring the boosts influence over the final order of results. If you boost by freshness, the semantically ranked results are rescored based on freshness.

Enable scoring profiles in semantic configuration

To enable scoring profiles with semantic ranking, use preview API version 2025-05-01-preview to update an index by setting the rankingOrder property of its semantic configuration. Use the PUT method to update the index with your revisions. No index rebuild is required.

PUT https://{service-name}.search.windows.com/indexes/{index-name}?api-version=2025-05-01-Preview
{
  "semantic": {
    "configurations": [
      {
        "name": "mySemanticConfig",
        "rankingOrder": "boostedReRankerScore"
      }
    ]
  }
}

Disable scoring profiles in semantic configuration

To opt out of sorting by semantic reranker boosted score, set the rankingOrder field to reRankerScore value in the semantic configuration.

PUT https://{service-name}.search.windows.com/indexes/{index-name}?api-version=2025-05-01-Preview
{
  "semantic": {
    "configurations": [
      {
        "name": "mySemanticConfig",
        "rankingOrder": "reRankerScore"
      }
    ]
  }
}

Even if you opt out of sorting by @search.rerankerBoostedScore, the boostedReRankerScore field is still produced in the response, but it's no longer used to sort results.

Example query and response

Start with a semantic query that specifies a scoring profile. The query uses the new preview REST API, and it targets a search index that has rankingOrder set to boostedReRankerScore.

POST https://{service-name}.search.windows.com/indexes/{index-name}/docs/search?api-version=2025-05-01-Preview
{
  "search": "my query to be boosted",
  "scoringProfile": "myScoringProfile",
  "queryType": "semantic"
}

The response includes the new rerankerBoostedScore, alongside the L1 @search.score and the L2 @search.rerankerScore. Results are ordered by @search.rerankerBoostedScore.

{
  "value": [
    {
      "@search.score": 0.63,
      "@search.rerankerScore": 2.98,
      "@search.rerankerBoostedScore": 7.68,
      "content": "boosted content 2"
    },
    {
      "@search.score": 1.12,
      "@search.rerankerScore": 3.12,
      "@search.rerankerBoostedScore": 5.61,
      "content": "boosted content 1"
    }
  ]
}