Azure AI Search Python SDK — Facets, Scoring Profiles, Semantic Ranking, and Vector Search
Introduction
In the previous article of this series, we covered the foundational workflow: installing azure-search-documents, authenticating, creating an index, uploading documents, and running full-text queries with filters, sorting, and pagination.
Now we move into the capabilities that make Azure AI Search genuinely powerful for modern AI applications:
- Faceted navigation — aggregate counts by field for drill-down filtering.
- Scoring profiles — customise relevance ranking with field weights and boosts.
- Semantic ranking — re-rank results using deep language understanding and return AI-generated captions and answers.
- Vector search — store and query dense embeddings for semantic similarity retrieval.
- Hybrid search — combine keyword BM25 and vector search in a single query using Reciprocal Rank Fusion (RRF).
All examples use azure-search-documents against a real Azure AI Search resource.
Facets aggregate document counts grouped by a field value. It is the backbone of drill-down filtering in e-commerce and document search UIs.
Requesting facets
Pass a list of field names to the facets parameter. The field must be marked facetable=True in the index schema:
|
|
There are several facet syntax options.
| Syntax | Meaning |
|---|---|
"category" |
All distinct values with counts |
"rating,count:5" |
Top 5 values by count |
"rating,interval:1" |
Numeric range buckets of width 1 |
"lastRenovationDate,interval:year" |
Date buckets by year |
"rating,sort:value" |
Sort buckets by the field value |
Once a user selects a facet value, convert it to a filter expression:
|
|
By default, Azure AI Search uses BM25 to rank results. A scoring profile lets you boost the relevance score based on field weights, function-based boosts (distance, freshness, magnitude, tag), or both.
The following Python example demonstrates adding a scoring profile to the index.
|
|
You can apply a scoring profile at the query time as well.
|
|
Semantic ranking uses deep language models hosted in Azure AI Search to re-rank BM25 results by semantic relevance. It also generates captions (highlighted excerpts) and answers (direct responses to question-style queries).
Tier requirement: Semantic ranking is available on the Basic tier and above. Enable it in Azure Portal → Azure AI Search resource → Semantic ranker.
We need to add a semantic configuration to the index.
|
|
The search_client.search is used to run a semantic query.
|
|
Each result includes a @search.reranker_score (0–4) alongside the BM25 @search.score. Sort or filter on the reranker score for the most semantically relevant results:
|
|
Vector search stores dense embedding vectors alongside your documents and retrieves results by nearest-neighbour similarity rather than keyword matching. This enables semantic retrieval even when the user’s query shares no words with the document.
Adding a vector field to the index
A vector field requires three additional properties: vector_search_dimensions, vector_search_profile_name, and the vector search algorithm configuration.
|
|
Use cosine for text embeddings from OpenAI models; use dotProduct for unit-normalised vectors.
Generating embeddings with Azure OpenAI
|
|
Uploading documents with embeddings
|
|
Running a vector query
|
|
The @search.score for vector queries is the cosine similarity (0–1; higher values indicate greater similarity).
Hybrid search runs a keyword (BM25) query and a vector query simultaneously, then merges the ranked results using Reciprocal Rank Fusion (RRF). This reliably outperforms either approach alone because keyword search excels at exact matches while vector search excels at semantic similarity.
Basic hybrid query
Simply provide both search_text and vector_queries in the same call:
|
|
The @search.score in hybrid mode is the RRF fusion score, not a raw BM25 or cosine score.
Hybrid search with semantic reranking
For the highest quality results, add semantic reranking on top of the hybrid RRF results. The pipeline becomes: BM25 + vector → RRF fusion → semantic reranker:
|
|
Filtering within vector and hybrid queries
Filters narrow the vector search candidate pool before nearest-neighbour retrieval — much more efficient than post-filtering:
|
|
The following script creates a vector-enabled index with a semantic configuration, uploads documents with embeddings, and demonstrates all four query types in sequence:
|
|
In this part, we covered the five advanced pillars of the Azure AI Search Python SDK:
- Faceted navigation — requesting facets on filterable fields, parsing bucket counts, and applying selections as filter expressions.
- Scoring profiles — boosting relevance with field text weights, magnitude functions (numeric range), and freshness functions (date proximity).
- Semantic ranking — adding a
SemanticConfigurationto an index and usingQueryType.SEMANTICto re-rank results, extract captions, and retrieve direct answers. - Vector search — defining a vector field with
HnswAlgorithmConfiguration, generating embeddings with Azure OpenAI, uploading documents with vector data, and querying withVectorizedQuery. - Hybrid search — combining BM25 keyword search and vector retrieval with RRF fusion, and optionally layering semantic reranking on top for the highest possible relevance.
In the next part of this series on Azure AI Search, we will move up the stack: managing indexers and data sources via SearchIndexerClient, building skill set pipelines in Python (OCR, entity recognition, key phrase extraction), and integrating vectorization so that embeddings are generated automatically during indexing.
Comments
Comments Require Consent
The comment system (Giscus) uses GitHub and may set authentication cookies. Enable comments to join the discussion.