Argomenti trattati
The semantic ranking feature in Azure AI Search rescales results using machine reading comprehension so that the entries most aligned with the meaning of a query appear first. In this guide you will learn how to add a semantic configuration to an existing index such as hotels-sample without taking the index offline or reloading documents. The approach is ideal when your corpus contains descriptive or informational text: the semantic ranking model looks at passages holistically rather than matching isolated tokens.
Why semantic ranking matters
Traditional full-text ranking, commonly powered by algorithms like BM25, ranks results by token matches and term frequency. By contrast, the semantic reranker employs machine reading comprehension to rescore candidates so that results reflect the overall intent of the query. Use semantic ranking when you need relevance that accounts for context and meaning — for example, when users ask multi-term, informational queries. The reranker exposes a reranker score in responses and can be combined with classical relevance to produce a balanced ranking.
Prepare your service and index
Before changing the index, verify that your Azure subscription and search service are ready. You need an Azure AI Search service with the semantic ranker enabled and an index that has descriptive fields marked as searchable and retrievable. The quickstart examples assume the hotels-sample index, but any index with suitable text fields will work. Obtain the service endpoint from the Azure portal (Overview) so you can point client libraries or REST calls at the right URL. Optionally clone the samples from GitHub to follow along with language-specific code.
Authentication and role-based access
For safety and automation, prefer keyless authentication via Microsoft Entra ID and the DefaultAzureCredential family rather than API keys. To assign the necessary permissions you (or an administrator) should enable role-based access on the search service and grant roles such as Search Service Contributor and Search Index Data Reader to the account that runs the tooling. If assigning roles is not possible in your environment, the samples also support key-based authentication. Use az login to populate CLI credentials for local runs.
Add a semantic configuration and run queries
Updating an index to include semantic behavior is a schema-level operation but does not require a full rebuild. The core change is adding a semantic configuration that lists titleField, contentFields, and keywordsFields (for example, set HotelName as the title and Description as content). Client libraries for .NET, Java, JavaScript/TypeScript, and Python demonstrate how to fetch the existing index, append a configuration named (for example) semantic-config, and call createOrUpdateIndex or the equivalent REST PUT. Common sample commands include cloning the repo with git clone and running language-specific examples (for instance, dotnet run, mvn exec:java, node, or python).
Types of semantic queries and expected output
Once the semantic configuration exists you can issue queries with queryType set to semantic. Start by comparing a baseline keyword query (simple) ranked by BM25 against a semantic query that returns a reranker score. You can also request extractive captions to surface the most relevant passages with hit highlights, or ask a question-style query that returns an extractive answer — a verbatim snippet pulled from the index (not a generated completion). Captions and answers are most reliable when your indexed text closely aligns with the user question; otherwise no answer is returned if the confidence threshold is not met.
Practical notes and cleanup
Sample projects use environment variables or configuration files to set the endpoint, index name, and the semantic configuration name. Commands such as az login grant CLI-based credentials for DefaultAzureCredential. After experimenting, consider removing unused resources in the Azure portal or deleting the resource group to avoid ongoing charges. For deeper customization, explore options like changing the rankingOrder or combining semantic signals with traditional scoring through scoring profiles. The samples on GitHub include complete working code and show how to inspect @search.captions, @search.answers, and @search.rerankerScore in responses.