Azure AI Search Vector Settings
explained simply
Every important setting, what it does, and why you would change it — based on the official Microsoft docs.
What is a vector index in Azure AI Search?
Azure AI Search (formerly Azure Cognitive Search) can store and search vector embeddings — long lists of numbers that represent the meaning of text or images.
To make vector search work you configure three layers:
- Vector fields — where the numbers live
- Algorithms + parameters — how the search engine finds similar vectors
- Profiles + compressions — which algorithm + optional size reduction each field uses
Basic terminology (in plain English)
| Term | Simple meaning |
|---|---|
| Embedding / Vector | A long list of numbers that captures the meaning of text (or an image). Similar meanings → similar numbers. |
| Dimensions | How many numbers are in each vector (e.g. 1536). Fixed by the embedding model. |
| Index | The “database” in Azure AI Search. Holds documents and their vectors. |
| Document | One row / record in the index (like a product, article, or support ticket). |
| Field | A column on the document (title, content, contentVector, etc.). |
| Nearest Neighbor | Finding the vectors that are closest (most similar) to your query vector. |
| HNSW | A smart graph structure that finds nearest neighbors fast without checking every vector. |
| Exhaustive KNN | The slow but exact way: compare the query to every vector. |
| Metric (cosine, etc.) | The formula used to measure “how similar” two vectors are. |
| Quantization / Compression | Making the numbers smaller (fewer bits) so the index uses less memory and disk. |
| Profile | A named combo of algorithm + compression that you attach to a vector field. |
| k | How many nearest neighbors you want back (top-k results). |
| Hybrid search | Combining classic keyword search + vector search in one query. |
Azure AI Search vs SQL — the simple comparison
If you already know SQL, this table maps the ideas.
| SQL concept | Azure AI Search equivalent | Key difference |
|---|---|---|
| Database | Search service | A service that can host many indexes. |
| Table | Index | Schema is more flexible; designed for search, not transactions. |
| Row | Document | JSON-like document, not a rigid row. |
| Column | Field | Fields have search behaviors (searchable, filterable, retrievable…). |
| Primary key | Key field | Every document needs a unique key (usually a string). |
| CREATE INDEX on a column | Making a field searchable / vectorSearchProfile | You declare search behavior in the schema itself. |
| B-tree / hash index | HNSW graph (for vectors) | HNSW is for high-dimensional similarity, not equality or range. |
| WHERE column = value | Filter (OData filter) | Filters work on non-vector fields. Vector fields themselves are not filterable. |
| ORDER BY column | Scoring / ranking | Results are ranked by similarity score (or hybrid RRF), not by a column value. |
| SELECT * | retrievable fields | You control which fields come back; vectors are often set retrievable=false to save space. |
| JOIN | Not really supported the same way | You usually denormalize data into the document. |
| Full-text search (LIKE / CONTAINS) | Searchable text fields + analyzers | Much stronger linguistic analysis (stemming, synonyms, etc.). |
| No direct equivalent | Vector field + HNSW | This is pure similarity search by meaning — SQL doesn’t do this natively. |
Tiny side-by-side example
-- SQL mindset SELECT * FROM Products WHERE category = 'shoes' ORDER BY price; -- Azure AI Search mindset (hybrid) Search for documents whose contentVector is close to the embedding of "comfortable running shoes for beginners" AND category eq 'shoes' → ranked by similarity + keyword score
1. Vector field settings
These go on the field itself inside the index schema.
| Setting | What it means | Why you set it |
|---|---|---|
| type | Usually Collection(Edm.Single) (float32). Can also be narrower types like float16, int8, or byte (binary). |
Must match what your embedding model outputs. Narrower types save memory and disk. |
| dimensions | How many numbers are in each vector (e.g. 1536 for text-embedding-ada-002). | Must exactly match the embedding model. Wrong value = indexing fails or search is meaningless. |
| vectorSearchProfile | Name of a profile defined in the index (links algorithm + compression). | Tells the engine which search method and compression this field uses. |
| searchable | Must be true for vector fields. |
Only searchable fields participate in vector queries. |
| retrievable | true or false. Controls whether the raw vector numbers are returned in search results. |
Set false to save disk space if you never need the actual numbers back (most apps don’t). |
| stored | Controls whether the vector is kept for retrieval (related to storage optimization). | Turn off when you don’t need to return vectors — can cut vector storage significantly. |
2. Algorithms (how search finds neighbors)
Defined under vectorSearch.algorithms.
| Algorithm | What it does | When to use it |
|---|---|---|
| HNSW | Builds a hierarchical graph of vectors for Approximate Nearest Neighbor search. Very fast. | Almost always. Best for large indexes and low latency. |
| exhaustiveKnn | Brute-force: compares the query to every vector. Exact results, slower. | Small indexes, accuracy testing, or when you need perfect recall. |
You can index a field with HNSW and still force exhaustive search at query time with "exhaustive": true.
3. HNSW parameters (the knobs)
These live inside hnswParameters.
| Parameter | What it controls | Typical values | Why change it |
|---|---|---|---|
| metric | How “similarity” is calculated. | cosine (most common), euclidean, dotProduct, hamming (binary) | Must match your embedding model. Azure OpenAI models → use cosine. |
| m | Number of bi-directional links per node in the graph. | 4 – 16 (default often 4) | Higher m = better recall, more memory and slower indexing. |
| efConstruction | How thoroughly the graph is built during indexing. | 100 – 1000 (common 400) | Higher = better quality graph, slower indexing, more memory. |
| efSearch | How thoroughly the graph is searched at query time. | 100 – 1000 (common 500) | Higher = better recall, higher latency. Trade accuracy vs speed. |
4. Compression (make vectors smaller)
Defined under vectorSearch.compressions. Optional but powerful for cost and scale.
| Setting | What it does | Why use it |
|---|---|---|
| scalarQuantization | Compresses float values into smaller numbers (usually int8). | Big reduction in memory and disk with only small accuracy loss. |
| binaryQuantization | Turns floats into 1-bit values. | Even smaller size. Best when you accept a bit more accuracy trade-off. |
| enableRescoring | After fast search on compressed vectors, re-rank top results with original vectors. | Recovers most of the accuracy lost by compression. |
| defaultOversampling | How many extra candidates to fetch before rescoring (e.g. 10). | Higher = better final ranking, slightly more work. |
| rescoreStorageMethod | preserveOriginals or discardOriginals |
Keep original vectors for rescoring, or discard them to save more space. |
You can also use narrower data types on the field itself and turn off stored / retrievable to save even more.
5. Profiles (the glue)
A profile simply links an algorithm + optional compression (+ optional vectorizer) and gives it a name.
| Part | Role |
|---|---|
| name | Unique name you reference from the vector field |
| algorithm | Which algorithm config to use |
| compression | (Optional) Which compression to apply |
| vectorizer | (Optional) Built-in way to turn text into vectors at query time |
{
"vectorSearch": {
"algorithms": [
{
"name": "hnsw-1",
"kind": "hnsw",
"hnswParameters": {
"m": 4,
"efConstruction": 400,
"efSearch": 500,
"metric": "cosine"
}
}
],
"compressions": [
{
"name": "scalar-quantization",
"kind": "scalarQuantization",
"scalarQuantizationParameters": { "quantizedDataType": "int8" },
"rescoringOptions": {
"enableRescoring": true,
"defaultOversampling": 10,
"rescoreStorageMethod": "preserveOriginals"
}
}
],
"profiles": [
{
"name": "my-profile",
"algorithm": "hnsw-1",
"compression": "scalar-quantization"
}
]
}
}
Then on the field you just write: "vectorSearchProfile": "my-profile"
6. Query-time settings
| Setting | What it does | Why use it |
|---|---|---|
| k | How many nearest neighbors to return. | Controls result size. Common values: 3–50. |
| exhaustive | Force brute-force search even on an HNSW field. | Useful for accuracy checks or very selective filters. |
| fields | Which vector field(s) to search (up to 10). | When you have multiple vector fields. |
| weight | Relative importance of this vector query in hybrid search. | Balance vector vs text scores. |
| vectorFilterMode | preFilter (default) or postFilter. | preFilter is safer for recall; postFilter can be faster with selective filters. |
Quick “why” summary
| Goal | What to change |
|---|---|
| Better accuracy / recall | Higher efSearch, higher m, enable rescoring, or use exhaustive |
| Faster queries / lower cost | Lower efSearch, use compression, turn off retrievable/stored |
| Smaller index size | Scalar or binary quantization, narrower data types, stored=false |
| Match embedding model | Correct dimensions + correct metric (usually cosine) |
| Hybrid search balance | Adjust vector weight |
Sources
All details taken from official Microsoft Learn documentation:
No comments:
Post a Comment