Configure semantic ranker and return captions in search results

Semantic ranking iterates over an initial result set, applying an L2 ranking methodology that promotes the most semantically relevant results to the top of the stack. You can also get semantic captions, with highlights over the most relevant terms and phrases, and semantic answers.

This article explains how to configure a search index for semantic reranking.

Note

If you have existing code that calls preview or previous API versions, see Migrate semantic ranking code for help with modifying your code.

Prerequisites

Azure AI Search in any region that provides semantic ranking.
An existing search index with rich text content. Semantic ranking applies to strings (nonvector) fields and works best on content that is informational or descriptive.
Permission to create and use objects on Azure AI Search. We recommend role-based access, but you can use API keys if a role assignment isn't feasible. For more information, see Connect to a search service.
The 2026-05-01-preview version of the Search Service REST APIs.

Choose a client

You can specify a semantic configuration on new or existing indexes, using any of the following tools and software development kits (SDKs) to add a semantic configuration:

Azure portal, using the index designer to add a semantic configuration.
Visual Studio Code with the REST client and a Create or Update Index (REST) API.
Azure SDK for .NET
Azure SDK for Python
Azure SDK for Java
Azure SDK for JavaScript

Add a semantic configuration

Some workloads create a semantic configuration automatically. If you're using agentic retrieval and a knowledge source that indexes content on Azure AI Search, your generated index already has a semantic configuration that works for your content.

For other workloads, you can set up a semantic configuration yourself. A semantic configuration is a section in your index that establishes the field inputs used for semantic ranking. You can add or update a semantic configuration at any time, no rebuild necessary. If you create multiple configurations, you can specify a default. At query time, specify a semantic configuration on a query request, or leave it blank to use the default.

You can create up to 100 semantic configurations in a single index.

When semantic configuration is optional

Important

These features and functionality are part of the 2026-05-01-preview REST API. The 2026-05-01-preview is licensed to you as part of your Azure subscription and is subject to the terms applicable to "Previews" in the Microsoft Product Terms, the Microsoft Products and Services Data Protection Addendum ("DPA"), and the Supplemental Terms of Use for Microsoft Azure Previews.

The 2026-05-01-preview supports connections to other Microsoft services and third-party services. Use of these services is subject to their respective terms and might result in data processing or storage outside of the Azure compliance boundary, as well as data flowing into the Azure compliance boundary.

It's your responsibility to manage whether your data will flow outside of your organization's compliance and geographic boundaries and any related implications, and that appropriate permissions, boundaries, and approvals are provisioned.

You're responsible for carefully reviewing and testing applications you build in the context of your specific use cases and making all appropriate decisions and customizations. This includes implementing your own responsible AI mitigations, such as metaprompts, content filters, or other safety systems, and ensuring your applications meet appropriate quality, reliability, security, and trustworthiness standards. For more information, see the Azure AI Search Transparency Note.

In the 2026-05-01-preview API, supported agentic retrieval flows can use Azure AI Search ranking behavior without requiring an explicit semantic configuration on the underlying index. This preview behavior helps teams start with knowledge base retrieval without blocking on semantic configuration authoring.

This change doesn't remove classic semantic ranking configuration. Continue to define a semantic configuration for classic semantic search queries, older API versions, and workloads that need explicit control over title, content, and keyword fields.

For search index knowledge sources, semanticConfigurationName remains a supported property. Set it when you want the knowledge source to use a specific semantic configuration. In supported 2026-05-01-preview agentic retrieval flows, you can omit it when you want the service to use the preview behavior that doesn't require an explicit semantic configuration on the underlying index.

Semantic configuration is optional only for supported agentic retrieval knowledge base retrieve flows that use the 2026-05-01-preview API. Classic semantic search queries and older API versions still require a semantic configuration when you use semantic ranking. If you create an index without a semantic configuration for the preview flow, don't assume that the same index can be used unchanged with GA or older preview semantic ranking APIs.

A semantic configuration has a name and the following properties:

Property	Characteristics
Title field	A short string, ideally under 25 words. This field could be the title of a document, name of a product, or a unique identifier. If you don't have suitable field, leave it blank.
Content fields	Longer chunks of text in natural language form, subject to maximum token input limits on the machine learning models. Common examples include the body of a document, description of a product, or other free-form text.
Keyword fields	A list of keywords, such as the tags on a document, or a descriptive term, such as the category of an item.

You can only specify one title field, but you can have as many content and keyword fields as you like. For content and keyword fields, list the fields in priority order because lower priority fields might get truncated.

Across all semantic configuration properties, the fields you assign must be:

Attributed as searchable and retrievable
Strings of type Edm.String, Collection(Edm.String), string subfields of Edm.ComplexType

Go to your search service in the Azure portal.
From Indexes on the left-navigation pane, select an index.
Select Semantic configurations and then select Add semantic configuration.
On the New semantic configuration page, enter a semantic configuration name and select the fields to use in the semantic configuration. Only searchable and retrievable string fields are eligible. Make sure to list content fields and keyword fields in priority order.
Select Save to save the configuration settings.
Select Save again on the index page to save the semantic configuration in the index.

Formulate a Create or Update Index request.

Add a semantic configuration to the index definition, perhaps after scoringProfiles or suggesters. Specifying a default is optional but useful if you have more than one configuration.

"semantic": {
    "defaultConfiguration": "my-semantic-config-default",
    "configurations": [
        {
            "name": "my-semantic-config-default",
            "prioritizedFields": {
                "titleField": {
                    "fieldName": "HotelName"
                },
                "prioritizedContentFields": [
                    {
                        "fieldName": "Description"
                    }
                ],
                "prioritizedKeywordsFields": [
                    {
                        "fieldName": "Tags"
                    }
                ]
            }
        },
                    {
            "name": "my-semantic-config-desc-only",
            "prioritizedFields": {
                "prioritizedContentFields": [
                    {
                        "fieldName": "Description"
                    }
                ]
            }
        }
    ]
}

Use the SemanticConfiguration class in the Azure SDK for .NET.

The following example is from the semantic ranking sample authored by the Azure SDK team.

string indexName = "hotel";
SearchIndex searchIndex = new(indexName)
{
    Fields =
    {
        new SimpleField("HotelId", SearchFieldDataType.String) { IsKey = true, IsFilterable = true, IsSortable = true, IsFacetable = true },
        new SearchableField("HotelName") { IsFilterable = true, IsSortable = true },
        new SearchableField("Description") { IsFilterable = true },
        new SearchableField("Category") { IsFilterable = true, IsSortable = true, IsFacetable = true },
    },
    SemanticSearch = new()
    {
        Configurations =
        {
            new SemanticConfiguration("my-semantic-config", new()
            {
                TitleField = new SemanticField("HotelName"),
                ContentFields =
                {
                    new SemanticField("Description")
                },
                KeywordsFields =
                {
                    new SemanticField("Category")
                }
            })
        }
    }
};

Opt in for prerelease semantic ranking models

Note

This feature is currently in 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 preview REST APIs and preview Azure SDKs that provide the property, you can optionally configure an index to use prerelease semantic ranking models if one is deployed in your region. There's no mechanism for knowing if a prerelease is available, or if it was used on specific query. For this reason, we recommend that you use this property in test environments, and only if you're interested in trying out the very latest semantic ranking models.

The configuration property is "flightingOptIn": true, and it's set in the semantic configuration section of an index. The property is null or false by default. You can set it true on a create or update request at any time, and it affects semantic queries moving forward, assuming the query stipulates a semantic configuration that includes the property.

PUT https://myservice.search.windows.net/indexes('hotels')?allowIndexDowntime=False&api-version=2026-05-01-preview

{
  "name": "hotels",
  "fields": [ ],
  "scoringProfiles": [ ],
  "defaultScoringProfile": "geo",
  "suggesters": [ ],
  "analyzers": [ ],
  "corsOptions": { },
  "encryptionKey": { },
  "similarity": { },
  "semantic": {
    "configurations": [
      {
        "name": "semanticHotels",
        "prioritizedFields": {
          "titleField": {
            "fieldName": "hotelName"
          },
        "prioritizedContentFields": [
            {
              "fieldName": "description"
            },
            {
              "fieldName": "description_fr"
            }
          ],
        "prioritizedKeywordsFields": [
            {
              "fieldName": "tags"
            },
            {
              "fieldName": "category"
            }
          ],
        "flightingOptIn": true
        }
      }
    ]
  },
  "vectorSearch": {  }
}

Next steps

Test your semantic configuration by running a semantic query.

Create a semantic query

Feedback

Was this page helpful?

Last updated on 2026-06-02