Semantic reranker in Azure Cosmos DB

A semantic reranker uses an AI model to score and reorder candidate documents based on their relevance to a query or context. Retrieve candidates from Azure Cosmos DB by using vector search, full-text search, hybrid search, or another query. Then send those candidates to a separate inference endpoint by using the standalone Azure Data AI SDK.

Use the Azure Cosmos DB SDK for retrieval and the Azure Data AI InferenceClient for reranking. Reranking isn't a method on the Azure Cosmos DB container in these examples.

The semantic reranker service uses the Microsoft AI Semantic Ranker model, also used by Azure AI Search's Semantic Ranker.

Why use semantic reranker?

When you evaluate a search or retrieval system, consider:

  • Accuracy and recall: How closely the retrieved results match the ground truth.
  • Latency: The total time from submitting a query to receiving results.
  • Relevance: How well the retrieved documents match the user's intent.

A semantic reranker can move more relevant candidates closer to the top of your results, helping search applications, agents, and retrieval-augmented generation (RAG) workflows. It doesn't retrieve more documents from your container.

Reranking adds a network call and model inference time. Evaluate relevance before and after reranking to determine whether the improvement benefits your workload enough to justify the added latency.

Semantic reranker output

The response can include:

  • Document index: The zero-based position of a document in the submitted candidate list. Use this index to map a score back to the original document and its metadata.
  • Relevance score: A score from 0 to 1 that indicates how relevant the document is to the supplied context. Higher scores indicate higher relevance.
  • Original document: The submitted document, if you request documents in the response.
  • Sentence scores: Optional indices and relevance scores for up to the two highest-scoring sentences within each returned document, not scores for every sentence.
  • Inference latency: Timing information for the rerank request.
  • Token usage: Information about tokens consumed by the request.
  • Model identity: The model name and version reported by the service.

The examples request a subset of the candidates and don't request documents in the response. They use each returned index to preserve the original document's ID, title, and text. Don't assume the response contains every submitted candidate when you set a result limit.

Prerequisites and setup

Before you run the examples, prepare:

  • An existing Azure Cosmos DB account, database, and container with Movies data. Each item must have nonempty string fields named id, title, and text. The examples require unique candidate IDs.
  • Full-text search configured for the account and container, with a full-text policy and index on /text.
  • Permission to create an inference account in the existing resource group and assign its Azure roles, and to create Azure Cosmos DB data-plane role assignments. Ask an administrator to perform setup if you don't have these permissions.
  • A Microsoft Entra identity for local development. The steps in the following section grant this identity permission to query the source container and call the inference endpoint.
  • The .NET 8 SDK for C#, or Python 3.10 or later for Python.
  • The Azure CLI for local sign-in.
  • PowerShell 7.4 or later for the setup commands.

The following steps create or reuse a standalone inference account for your existing Azure Cosmos DB account. They don't recreate or modify your database, container, or data. For an end-to-end deployment that also loads MovieLens data and provides interactive Python and .NET apps, use the detailed semantic search samples.

Optional: Set up reranking in the Azure portal

For a quick interactive test, use the portal integration instead of creating the inference account manually:

  1. Open your existing Azure Cosmos DB account in the Azure portal and find Semantic Reranker in the resource menu.
  2. Turn on Semantic Reranker. The integration creates the companion inference account with the same name as your Azure Cosmos DB account. If the inference resource provider isn't registered, have an administrator register it, and then return to the portal.
  3. Review the identities listed under Reranker Permissions. Grant permissions is a bulk action for identities that currently have query permissions on the Azure Cosmos DB account. Use it only if all listed identities should have reranker access. To grant access to one user or managed identity instead, use the scoped runtime permission commands.
  4. Wait for the endpoint to become available and for role assignments to propagate.

The command-line procedure in the next section is useful for automation and explicit permission scope. If you already used the portal, you can still follow it to select your account and configure the examples: the endpoint lookup reuses the existing inference account instead of creating another one. Skip role assignments that you already have.

Select your existing account

Run the setup blocks in order in the same PowerShell session. Sign in by using the identity that performs setup:

az login

Replace the placeholders with your existing resource names. This procedure uses the same subscription, resource group, and account name for the inference account. The inference account name must start with a letter. This article uses uksouth; the available inference regions are eastus2, westus3, and uksouth.

$ErrorActionPreference = "Stop"
$PSNativeCommandUseErrorActionPreference = $true
$subscriptionId = "<subscription-id>"
$resourceGroup = "<existing-resource-group>"
$accountName = "<existing-cosmos-db-account-name>"
$databaseName = "<existing-database-name>"
$containerName = "<existing-movies-container-name>"
$inferenceLocation = "uksouth"

az account set --subscription $subscriptionId
$cosmos = az cosmosdb show --name $accountName `
    --resource-group $resourceGroup --output json | ConvertFrom-Json
$principalId = az ad signed-in-user show --query id --output tsv

if ($accountName -cnotmatch '^[a-z][a-z0-9-]{2,43}$') {
    throw "The shared account name must start with a lowercase letter and contain 3-44 lowercase letters, digits, or hyphens."
}

If an administrator performs setup for you, replace $principalId with your Microsoft Entra user object ID, not the administrator's ID or an application client ID.

Register the inference resource provider

Check the resource provider registration for the selected subscription:

az provider show --namespace Microsoft.InferenceService --query registrationState --output tsv

If the result isn't Registered, an identity with subscription-level provider-registration permission needs to run the following command and wait for it to finish:

az provider register --namespace Microsoft.InferenceService --wait

Create or reuse the inference endpoint

The inference account is a separate Microsoft.InferenceService/inferenceAccounts resource. Its endpoint isn't the Azure Cosmos DB document endpoint.

The following block checks for the account first. It creates an account only when Azure Resource Manager returns HTTP 404. Authentication, authorization, and other errors stop setup instead of triggering creation. Don't issue another creation request for an account that already exists.

$inferenceId = "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.InferenceService/inferenceAccounts/$accountName"
$inferenceUri = "https://management.azure.com${inferenceId}?api-version=2026-10-15"
$armToken = az account get-access-token `
    --resource https://management.azure.com/ --query accessToken --output tsv |
    ConvertTo-SecureString -AsPlainText -Force

$inference = Invoke-RestMethod -Method Get -Uri $inferenceUri `
    -Authentication Bearer -Token $armToken `
    -SkipHttpErrorCheck -StatusCodeVariable status

if ($status -eq 404) {
    $body = @{ location = $inferenceLocation } | ConvertTo-Json
    $inference = Invoke-RestMethod -Method Put -Uri $inferenceUri `
        -Authentication Bearer -Token $armToken `
        -ContentType "application/json" -Body $body `
        -SkipHttpErrorCheck -StatusCodeVariable status
    if ($status -notin 200, 201, 202) {
        throw "Inference creation failed (HTTP $status): $($inference | ConvertTo-Json -Depth 10)"
    }
} elseif ($status -ne 200) {
    throw "Inference lookup failed (HTTP $status): $($inference | ConvertTo-Json -Depth 10)"
}

$deadline = (Get-Date).AddMinutes(10)
do {
    $inference = Invoke-RestMethod -Method Get -Uri $inferenceUri `
        -Authentication Bearer -Token $armToken `
        -SkipHttpErrorCheck -StatusCodeVariable status
    if ($status -notin 200, 404) {
        throw "Inference status lookup failed (HTTP $status): $($inference | ConvertTo-Json -Depth 10)"
    }
    if ($status -eq 200) {
        $state = $inference.properties.provisioningState
        if ($state -in "Failed", "Canceled") {
            throw "Inference provisioning ended in state '$state'. Inspect the resource's Azure activity log."
        }
        if ($state -eq "Succeeded" -and $inference.properties.endpoint) {
            break
        }
    }
    if ((Get-Date) -ge $deadline) {
        throw "Timed out waiting for the inference endpoint. Inspect the existing resource before retrying; don't send another creation request."
    }
    Start-Sleep -Seconds 10
} while ($true)

$env:INFERENCE_ENDPOINT = $inference.properties.endpoint
Write-Host "Inference endpoint: $env:INFERENCE_ENDPOINT"

For a reused account, setup retains its existing location. The REST API version and SDK package version identifiers in this article are the versions used to validate these examples.

Grant runtime permissions

The local development identity needs two independent permissions. If it doesn't already have equivalent access, run these commands or have an administrator run them with your user object ID:

az cosmosdb sql role assignment create --account-name $accountName --resource-group $resourceGroup --principal-id $principalId --role-definition-id "00000000-0000-0000-0000-000000000001" --scope "/dbs/$databaseName/colls/$containerName"
az role assignment create --assignee-object-id $principalId --assignee-principal-type User --role "Semantic Reranker User" --scope $inferenceId

The first command assigns Cosmos DB Built-in Data Reader only for the source container. The second assigns Semantic Reranker User only for the inference account. Neither command grants resource-group-wide runtime access.

Access to the inference account doesn't grant permission to query Azure Cosmos DB, and Azure Cosmos DB read access doesn't grant inference access. Role assignments can take a few minutes to propagate. For a deployed application, grant the corresponding permissions to its managed identity instead of your user.

Configure your environment

Continue in the same shell. The preceding setup block already populates INFERENCE_ENDPOINT from the provisioned resource, so you don't need to construct or guess its URL.

$env:COSMOS_DB_ENDPOINT = $cosmos.documentEndpoint
$env:COSMOS_DB_DATABASE = $databaseName
$env:COSMOS_DB_CONTAINER = $containerName
$env:RERANKER_MODEL = "aisearch-reranker"

These variables apply to the current shell and its child processes. If you open a new shell, repeat the account selection, endpoint lookup, and environment configuration. Don't put credentials or account-specific endpoints in source code. If an administrator performed setup, sign in with your own identity before running the examples.

Variable Purpose
COSMOS_DB_ENDPOINT Azure Cosmos DB endpoint used to retrieve candidates.
COSMOS_DB_DATABASE Existing database that contains the Movies container.
COSMOS_DB_CONTAINER Existing container with the Movies data and full-text configuration.
INFERENCE_ENDPOINT Standalone inference endpoint used for reranking.
RERANKER_MODEL Reranker model identifier configured for the inference service.

Both clients use DefaultAzureCredential with Microsoft Entra ID authentication. The examples don't use account keys. The Python and C# programs only query existing items and call inference. They don't create resources, load data, or generate embeddings.

API parameters

In Python, pass a request dictionary to InferenceClient.semantic_rerank. In C#, construct SemanticRerankingOptions with the query and document strings, then pass it to InferenceClient.SemanticRerankAsync.

The query describes the user's intent. The documents are candidate strings to score. These examples serialize only each candidate's title and text as JSON and keep its ID locally.

The following options are set explicitly in the examples:

Python request field C# request property Purpose
model Model Selects the configured reranker model.
documentType DocumentType Sets the document format to JSON.
targetPaths TargetPaths Selects up to 100 JSON field paths to score. Python request dictionaries use a comma-separated string; typed Python models and C# use a list of paths.
returnDocuments ReturnDocuments Set to false because the application retains the original candidates.
topK TopK Limits the returned results to three, or fewer if fewer candidates were retrieved.
sort Sort Set to true to return results ordered by reranking score.
returnSentenceScore ReturnSentenceScore Set to true to request optional sentence-level scores for returned documents.

JSON target paths

Set documentType to json when the candidate strings contain JSON, and supply target paths. Target paths are required for JSON documents. In Python request dictionaries, use a comma-separated string such as "targetPaths": "title,text"; for a typed model, use target_paths=["title", "text"]. In C#, populate the TargetPaths list with separate entries, such as TargetPaths = { "title", "text" } in an object initializer. Use dot notation within a path to select nested fields, such as meta.content.

Specify no more than 100 target paths per request. This limit counts the selected field paths, not the number of candidate documents or the depth of nested properties. For example, title and meta.content count as two paths.

For example, the following document can be scored with "targetPaths": "title,meta.content" in a Python request dictionary, target_paths=["title", "meta.content"] in a Python typed model, or TargetPaths = { "title", "meta.content" } in a C# object initializer:

{
  "title": "Space adventure",
  "meta": {
    "content": "A crew learns to work together on a journey through space."
  }
}

The paths refer to the JSON strings sent to inference, not directly to your Azure Cosmos DB items. Serialize the intended fields into those strings first. Selecting reranker fields doesn't change the retrieval query. For plain-text candidates, use documentType="text" and omit target paths.

Batch size and result limits

The optional batchSize request field (BatchSize in C#) controls the number of documents processed in each batch. It differs from:

  • The retrieval candidate limit, which controls how many items the Azure Cosmos DB query retrieves.
  • topK (TopK in C#), which limits how many ranked results the reranker returns.

A smaller topK value doesn't reduce the number of documents submitted for scoring. Don't use batchSize to bypass service request limits. The examples leave it unset; this article doesn't prescribe a service default, supported range, or performance benefit for changing it. Validate a batch size with your deployed service before tuning it.

Python dictionaries and typed models

Python accepts either a request dictionary or a SemanticRerankingInferenceContent model. Dictionaries use the JSON field names. Typed-model keyword arguments and attributes use snake_case. Don't mix these naming conventions.

Dictionary field Python model attribute C# property
returnDocuments return_documents ReturnDocuments
topK top_k TopK
batchSize batch_size BatchSize
documentType document_type DocumentType
targetPaths target_paths TargetPaths
returnSentenceScore return_sentence_score ReturnSentenceScore

The query, documents, model, and sort names are the same in Python dictionaries and models. In the Python example, you can replace the request dictionary with this equivalent model, using the same variables. Keep the retry and diagnostic arguments on the semantic_rerank call unchanged:

from azure.data.ai.models import SemanticRerankingInferenceContent

request = SemanticRerankingInferenceContent(
    query=context,
    documents=documents,
    model=model,
    document_type="json",
    target_paths=["title", "text"],
    return_documents=False,
    top_k=top_k,
    sort=True,
    return_sentence_score=True,
)

Read optional diagnostics

Each result's document index maps to the submitted candidate list. When requested and available, sentence scores cover up to the two highest-scoring sentences in each returned document, not every sentence. A sentence index identifies a sentence within that document. Don't interpret it as a character offset or infer which JSON field it belongs to. The API reference doesn't define sentence segmentation or JSON-field alignment.

The examples request sentence scores and print them separately from document scores. They also read the optional response metadata:

In C#, SemanticRerankAsync returns Azure.Response<SemanticRerankingResult>. Its Value.Metadata property provides optional SemanticRerankingMetadata. The JSON response field and Python attribute remain meta.

| JSON response field | Python model attribute | C# property | | --- | --- | --- | | scores[].sentenceScores | scores[].sentence_scores | Scores[].SentenceScores | | meta.modelName | meta.model_name | Metadata.ModelName`` | | meta.modelVersion|meta.model_version|Metadata.ModelVersion | | `meta.tokenUsage.totalTokens` | `meta.token_usage.total_tokens` | `Metadata.TokenUsage.TotalTokens | | meta.latency.dataPreprocessTime | meta.latency.data_preprocess_duration | Metadata.Latency.DataPreprocessDuration`` | | meta.latency.inferenceTime|meta.latency.inference_duration|Metadata.Latency.InferenceDuration | | `meta.latency.postProcessTime` | `meta.latency.post_process_duration` | `Metadata.Latency.PostProcessDuration |

Python duration attributes are datetime.timedelta values; convert them to milliseconds with total_seconds() * 1000. C# duration properties are nullable TimeSpan values; use TotalMilliseconds when present. Service phase timings aren't client end-to-end elapsed time. Reranker token usage isn't an Azure Cosmos DB request-unit charge or an embedding-token count.

Diagnostics can be absent. The examples preserve missing metadata as JSON null and use null for missing or empty sentence-score lists, rather than fabricating zero measurements. An absent diagnostic doesn't mean the rerank failed.

Handle retries and collect a support reference

The inference client has its own retry policy, separate from the Azure Cosmos DB client used for retrieval. The examples configure two retries after the initial attempt for eligible failures, including HTTP 429 responses. In Python, the per-call retry_on_methods=["POST"] option also enables status-based retries for the rerank POST when the response doesn't include Retry-After.

Let the SDK apply the server's retry delay instead of adding another retry loop. Retry-After can contain a delay in seconds or an HTTP date. The SDKs also recognize retry-after-ms and x-ms-retry-after-ms, which contain milliseconds. The service delay can exceed the SDK's fallback backoff cap, so a retry-count limit isn't an end-to-end time limit.

With the package versions used here, C# prefers the millisecond headers before Retry-After, while Python prefers Retry-After before the millisecond headers. A selected zero delay or past date doesn't disable SDK backoff. Don't assume the clients calculate identical waits.

For authorization failures, check the endpoint, identity, and role assignments instead of adding application-level retries. The tested Python retry policy can retry a 403 response that includes Retry-After, within the configured limits; the C# policy doesn't retry 403.

For support, capture the service correlation ID from the X-Correlation-ID response header when present. This is different from the outgoing x-ms-client-request-id and from an Azure Cosmos DB query's activity ID.

Response header Diagnostic use
X-Correlation-ID Service-generated reference to include with the UTC request time and HTTP status when requesting support.
Retry-After Server retry delay in seconds or as an HTTP date.
retry-after-ms, x-ms-retry-after-ms Server retry delay in milliseconds, when supplied.

The examples print HTTP status and these selected headers to stderr, separately from the result JSON on stdout. Missing headers remain null. C# reads the raw response from the result or RequestFailedException. Python uses a response hook for success and the final HttpResponseError for failure. Because the Python hook runs on each attempt, it doesn't report intermediate failures as final results.

After the SDK finishes any eligible retries, the examples rethrow the original exception. They don't return retrieval results as a successful rerank. Keep diagnostic logs private and review them before sharing; don't send credentials, authorization headers, or candidate text with a support reference.

Query and rerank existing Movies data

The examples retrieve up to ten movies by using full-text search for space or adventure. They then rerank those candidates against the context Space adventures about friendship and teamwork.

The query uses a small page-size hint to demonstrate consuming all pages. The ten-candidate cap belongs to this example, not the service limit. The output includes the original candidates, the requested result limit, the reranked results, optional sentence scores, and service metadata. Results, scores, and available diagnostics depend on your data and service response.

Create a console project:

dotnet new console --name SemanticRerankerSample --framework net8.0 --no-restore
Set-Location SemanticRerankerSample

Replace SemanticRerankerSample.csproj with the following content to configure the project and its supporting dependencies:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
  </PropertyGroup>
  <ItemGroup>
    <!-- This Azure.Core version supplies the Azure.Identity credential types. -->
    <PackageReference Include="Azure.Core" Version="1.64.0" />
    <PackageReference Include="Microsoft.Azure.Cosmos" Version="3.63.2" />
    <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
  </ItemGroup>
</Project>

This version of Azure.Core supplies the Azure.Identity credential types. Don't add a separate Azure.Identity package to this project.

Add the latest compatible stable Azure Data AI package. The command records the resolved version in the project file:

dotnet add package Azure.Data.AI

Replace Program.cs with the following code:

using Azure;
using Azure.Data.AI;
using Azure.Identity;
using Microsoft.Azure.Cosmos;
using System.Text.Json;

string cosmosEndpoint = Required("COSMOS_DB_ENDPOINT");
string databaseName = Required("COSMOS_DB_DATABASE");
string containerName = Required("COSMOS_DB_CONTAINER");
string inferenceEndpoint = Required("INFERENCE_ENDPOINT");
string model = Required("RERANKER_MODEL");

// Query existing Movies data. This program never creates or changes items.
const string sql = """
    SELECT TOP 10 c.id, c.title, c.text
    FROM c
    WHERE FullTextContainsAny(c.text, "space", "adventure")
    ORDER BY RANK FullTextScore(c.text, "space", "adventure")
    """;
const string context = "Space adventures about friendship and teamwork.";

var credential = new DefaultAzureCredential();
var jsonOptions = new JsonSerializerOptions(JsonSerializerDefaults.Web);
using var cosmos = new CosmosClient(cosmosEndpoint, credential, new CosmosClientOptions
{
    ConnectionMode = ConnectionMode.Direct,
    UseSystemTextJsonSerializerWithOptions = jsonOptions
});
Container container = cosmos.GetContainer(databaseName, containerName);
using FeedIterator<Movie> iterator = container.GetItemQueryIterator<Movie>(
    new QueryDefinition(sql),
    requestOptions: new QueryRequestOptions { MaxItemCount = 2 });
var candidates = new List<Movie>();
int pageCount = 0;
// A page can be empty. Consume the iterator, not just its first page.
while (iterator.HasMoreResults)
{
    var page = await iterator.ReadNextAsync();
    pageCount++;
    candidates.AddRange(page);
}

if (candidates.Count is < 1 or > 10)
    throw new InvalidOperationException("Expected between 1 and 10 existing movie candidates.");
if (candidates.Any(movie => string.IsNullOrWhiteSpace(movie.Id)
    || string.IsNullOrWhiteSpace(movie.Title) || string.IsNullOrWhiteSpace(movie.Text)))
    throw new InvalidOperationException("Each candidate must have nonempty id, title, and text.");
if (candidates.Select(movie => movie.Id).Distinct(StringComparer.Ordinal).Count() != candidates.Count)
    throw new InvalidOperationException("This sample requires unique candidate IDs.");

int topK = Math.Min(3, candidates.Count);
// Send only the fields to score. Keep IDs locally for index-based mapping.
var documents = candidates.Select(movie =>
    JsonSerializer.Serialize(new { title = movie.Title, text = movie.Text }));
var inferenceOptions = new InferenceClientOptions();
inferenceOptions.Retry.MaxRetries = 2;
var inference = new InferenceClient(new Uri(inferenceEndpoint), credential, inferenceOptions);
var request = new SemanticRerankingOptions(context, documents)
{
    Model = model,
    DocumentType = SemanticRerankingDocumentType.Json,
    TargetPaths = { "title", "text" },
    ReturnDocuments = false,
    TopK = topK,
    Sort = true,
    ReturnSentenceScore = true
};
Azure.Response<SemanticRerankingResult> response;
try
{
    response = await inference.SemanticRerankAsync(request);
    Report(response.GetRawResponse(), response.GetRawResponse().Status);
}
catch (RequestFailedException error)
{
    Report(error.GetRawResponse(), error.Status);
    throw;
}
var scores = response.Value.Scores;
if (scores.Count != topK)
    throw new InvalidOperationException("Unexpected reranker result count.");

var seen = new HashSet<int>();
var results = new List<RankedMovie>();
foreach (var entry in scores)
{
    if (entry.Index is not int index)
        throw new InvalidOperationException("Reranker returned a missing index.");
    if (entry.Score is not float score)
        throw new InvalidOperationException("Reranker returned a missing score.");
    if (index < 0 || index >= candidates.Count || !seen.Add(index))
        throw new InvalidOperationException("Reranker returned an invalid or duplicate index.");
    if (!float.IsFinite(score))
        throw new InvalidOperationException("Reranker returned a nonfinite score.");
    Movie source = candidates[index];
    results.Add(new(index, source.Id, source.Title, source.Text, score));
}

var sentenceScores = scores.Select(entry => new
{
    retrievalIndex = entry.Index,
    scores = entry.SentenceScores is { Count: > 0 } sentences
        ? sentences.Select(sentence => new { index = sentence.Index, score = sentence.Score }).ToArray()
        : null
}).ToArray();
SemanticRerankingMetadata? meta = response.Value.Metadata;
var metadata = new
{
    modelName = meta?.ModelName,
    modelVersion = meta?.ModelVersion,
    totalTokens = meta?.TokenUsage?.TotalTokens,
    dataPreprocessMilliseconds = meta?.Latency?.DataPreprocessDuration?.TotalMilliseconds,
    inferenceMilliseconds = meta?.Latency?.InferenceDuration?.TotalMilliseconds,
    postProcessMilliseconds = meta?.Latency?.PostProcessDuration?.TotalMilliseconds
};

Console.WriteLine(JsonSerializer.Serialize(new
{
    query = context, candidateCount = candidates.Count,
    queryPages = pageCount, requestedTopK = topK,
    candidates, results, sentenceScores, metadata
}, new JsonSerializerOptions(JsonSerializerDefaults.Web) { WriteIndented = true }));

static string Required(string name) =>
    Environment.GetEnvironmentVariable(name) is { } value && !string.IsNullOrWhiteSpace(value)
        ? value.Trim() : throw new InvalidOperationException($"Set {name}.");

static void Report(Response? response, int status) =>
    Console.Error.WriteLine(JsonSerializer.Serialize(new
    {
        status,
        serviceCorrelationId = Header(response, "X-Correlation-ID"),
        retryAfter = Header(response, "Retry-After"),
        retryAfterMs = Header(response, "retry-after-ms"),
        xMsRetryAfterMs = Header(response, "x-ms-retry-after-ms")
    }));

static string? Header(Response? response, string name) =>
    response is not null && response.Headers.TryGetValue(name, out string? value)
        ? value : null;

internal sealed record Movie(string Id, string Title, string Text);
internal sealed record RankedMovie(int RetrievalIndex, string Id, string Title, string Text, double Score);

Restore the packages, build, and run the example:

dotnet restore
dotnet build --no-restore
dotnet run --no-build --no-restore

Limitations

  • Semantic reranker supports up to 50 documents per rerank call.
  • A single context-document pair supports up to 2,048 tokens.

Pricing

Semantic reranker pricing is $1 USD for 1,000 rerank calls. Regional and cloud pricing might vary. For full details, see the Azure Cosmos DB pricing page.