Create a semantic query in Azure AI Search
In this article, learn how to invoke a semantic ranking over a result set, promoting 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.
Prerequisites
A search service, Basic tier or higher, with semantic ranking.
An existing search index with a semantic configuration and rich text content.
Review semantic ranking if you need an introduction to the feature.
Note
Captions and answers are extracted verbatim from text in the search document. The semantic subsystem uses machine reading comprehension to recognize content having the characteristics of a caption or answer, but doesn't compose new sentences or phrases. For this reason, content that includes explanations or definitions work best for semantic ranking. If you want chat-style interaction with generated responses, see Retrieval Augmented Generation (RAG).
Choose a client
Choose a search client that supports semantic ranking. Here are some options:
- Azure portal, using the index designer to add a semantic configuration.
- Visual Studio Code with a REST client
- Azure SDK for .NET
- Azure SDK for Python
- Azure SDK for Java
- Azure SDK for JavaScript
Avoid features that bypass relevance scoring
Several query capabilities in Azure AI Search bypass relevance scoring or are otherwise incompatible with semantic ranking. If your query logic includes the following features, you can't semantically rank your results:
A query with
search=*
or an empty search string, such as pure filter-only query, won't work because there's nothing to measure semantic relevance against. The query must provide terms or phrases that can be assessed during processing.A query composed in the full Lucene syntax (
queryType=full
) is incompatible with semantic ranking (queryType=semantic
). The semantic model doesn't support the full Lucene syntax.Sorting (orderBy clauses) on specific fields overrides search scores and a semantic score. Given that the semantic score is supposed to provide the ranking, adding an orderby clause results in an HTTP 400 error if you apply semantic ranking over ordered results.
Set up the query
In this step, add parameters to the query request. To be successful, your query should be full text search (using the search
parameter to pass in a string), and the index should contain text fields with rich semantic content and a semantic configuration.
Search explorer includes options for semantic ranking.
Sign in to the Azure portal.
Open a search index and select Search explorer.
Select Query options. If you already defined a semantic configuration, it's selected by default. If you don't have one, create a semantic configuration for your index.
Enter a query, such as "historic hotel with good food", and select Search.
Alternatively, select JSON view and paste definitions into the query editor:
Here's some JSON text that you can paste into the view:
{ "queryType": "semantic", "search": "historic hotel with good food", "semanticConfiguration": "my-semantic-config", "answers": "extractive|count-3", "captions": "extractive|highlight-true", "highlightPreTag": "<strong>", "highlightPostTag": "</strong>", "select": "HotelId,HotelName,Description,Category", "count": true }
Evaluate the response
Only the top 50 matches from the initial results can be semantically ranked. As with all queries, a response is composed of all fields marked as retrievable, or just those fields listed in the select parameter. A response includes the original relevance score, and might also include a count, or batched results, depending on how you formulated the request.
In semantic ranking, the response has more elements: a new semantically ranked relevance score, an optional caption in plain text and with highlights, and an optional answer. If your results don't include these extra elements, then your query might be misconfigured. As a first step towards troubleshooting the problem, check the semantic configuration to ensure it's specified in both the index definition and query.
In a client app, you can structure the search page to include a caption as the description of the match, rather than the entire contents of a specific field. This approach is useful when individual fields are too dense for the search results page.
The response for the above example query returns the following match as the top pick. Captions are returned because the "captions" property is set, with plain text and highlighted versions. Answers are omitted from the example because one couldn't be determined for this particular query and corpus.
"@odata.count": 35,
"@search.answers": [],
"value": [
{
"@search.score": 1.8810667,
"@search.rerankerScore": 1.1446577133610845,
"@search.captions": [
{
"text": "Oceanside Resort. Luxury. New Luxury Hotel. Be the first to stay. Bay views from every room, location near the pier, rooftop pool, waterfront dining & more.",
"highlights": "<strong>Oceanside Resort.</strong> Luxury. New Luxury Hotel. Be the first to stay.<strong> Bay</strong> views from every room, location near the pier, rooftop pool, waterfront dining & more."
}
],
"HotelName": "Oceanside Resort",
"Description": "New Luxury Hotel. Be the first to stay. Bay views from every room, location near the pier, rooftop pool, waterfront dining & more.",
"Category": "Luxury"
},
...
]
Next steps
Semantic ranking can be used in hybrid queries that combine keyword search and vector search into a single request and a unified response.
Feedback
https://aka.ms/ContentUserFeedback.
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see:Submit and view feedback for