Skip to content

Commit 63741aa

Browse files
American-DipperAmerican-Dipper
authored
Merge pull request #244304 from HeidiSteen/heidist-docs
[azure search] QS fix for vectors array
2 parents d119c72 + d958d2e commit 63741aa

File tree

4 files changed

+111
-103
lines changed

4 files changed

+111
-103
lines changed

‎articles/search/search-get-started-vector.md

Lines changed: 107 additions & 93 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ author: HeidiSteen
77
ms.author: heidist
88
ms.service: cognitive-search
99
ms.topic: quickstart
10-
ms.date: 06/29/2023
10+
ms.date: 07/07/2023
1111
---
1212

1313
# Quickstart: Use preview REST APIs for vector search queries
@@ -248,24 +248,26 @@ There are several queries to demonstrate the patterns. We use the same query str
248248

249249
In this vector query, which is shortened for brevity, the "value" contains the vectorized text of the query input, "fields" determines which vector fields are searched, and "k" specifies the number of nearest neighbors to return.
250250

251-
Recall that the vector query was generated from this string: "what Azure services support full text search". The search targets the `contentVector` field.
251+
Recall that the vector query was generated from this string: `"what Azure services support full text search"`. The search targets the `contentVector` field.
252252

253253
```http
254254
POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version={{api-version}}
255255
Content-Type: application/json
256256
api-key: {{admin-api-key}}
257257
{
258-
"vector": {
259-
"value": [
260-
-0.009154141,
261-
0.018708462,
262-
. . .
263-
-0.02178128,
264-
-0.00086512347
265-
],
266-
"fields": "contentVector",
267-
"k": 5
268-
}
258+
"vectors": [
259+
{
260+
"value": [
261+
-0.009154141,
262+
0.018708462,
263+
. . .
264+
-0.02178128,
265+
-0.00086512347
266+
],
267+
"fields": "contentVector",
268+
"k": 5
269+
}
270+
]
269271
}
270272
```
271273

@@ -275,54 +277,59 @@ The response includes 5 results, and each result provides a search score, title,
275277

276278
You can add filters, but the filters are applied to the nonvector content in your index. In this example, the filter applies to the "category" field.
277279

278-
The response is 10 Azure services, with a search score, title, and category for each one. You'll also notice the `select` property here to visually only see the fields are necessary in my the response.
280+
The response is 10 Azure services, with a search score, title, and category for each one. Notice the `select` property. It's used to select specific fields for the response.
279281

280282
```http
281283
POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version={{api-version}}
282284
Content-Type: application/json
283285
api-key: {{admin-api-key}}
284286
{
285-
"vector": {
286-
"value": [
287-
-0.009154141,
288-
0.018708462,
289-
. . .
290-
-0.02178128,
291-
-0.00086512347
292-
],
293-
"fields": "contentVector",
294-
"select": "title, content, category"
295-
"k": 10
296-
},
287+
"vectors": [
288+
{
289+
"value": [
290+
-0.009154141,
291+
0.018708462,
292+
. . .
293+
-0.02178128,
294+
-0.00086512347
295+
],
296+
"fields": "contentVector",
297+
"select": "title, content, category"
298+
"k": 10
299+
},
300+
],
297301
"filter": "category eq 'Databases'"
298302
}
299303
```
300304

301-
302305
### Cross-field vector search
303-
Cross-field vector search allows you to send a single query across multiple vector fields in your vector index. For this example, I want to calculate the similarity across both `titleVector` and `contentVector`:
306+
307+
A cross-field vector query sends a single query across multiple vector fields in your search index. This query example looks for similarity in both `titleVector` and `contentVector`:
304308

305309
```http
306310
POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version={{api-version}}
307311
Content-Type: application/json
308312
api-key: {{admin-api-key}}
309313
{
310-
"vector": {
311-
"value": [
312-
-0.009154141,
313-
0.018708462,
314-
. . .
315-
-0.02178128,
316-
-0.00086512347
317-
],
318-
"fields": "titleVector, contentVector",
319-
"k": 5
320-
}
314+
"vectors": [
315+
{
316+
"value": [
317+
-0.009154141,
318+
0.018708462,
319+
. . .
320+
-0.02178128,
321+
-0.00086512347
322+
],
323+
"fields": "titleVector, contentVector",
324+
"k": 5
325+
}
326+
]
321327
}
322328
```
323329

324330
### Multi-query vector search
325-
Multi-query vector search allows you to send a multiple queries across multiple vector fields in your vector index. For this example, I want to calculate the similarity across both `titleVector` and `contentVector` but will send in two different query embeddings respectively. This scenario is ideal for multi-modal use cases where you want to search over a `textVector` field and an `imageVector` field. You can also use this scenario if you have different embedding models with different dimensions in your search index.
331+
332+
Multi-query vector search sends multiple queries across multiple vector fields in your search index. This query example looks for similarity in both `titleVector` and `contentVector`, but sends in two different query embeddings respectively. This scenario is ideal for multi-modal use cases where you want to search over a `textVector` field and an `imageVector` field. You can also use this scenario if you have different embedding models with different dimensions in your search index.
326333

327334
```http
328335
POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version={{api-version}}
@@ -358,36 +365,38 @@ api-key: {{admin-api-key}}
358365

359366
### Hybrid search
360367

361-
Hybrid search allows to compose keyword queries and vector queries in a single search request.
368+
Hybrid search consists of keyword queries and vector queries in a single search request.
362369

363-
The response includes the top 10 ordereded by search score. Both vector queries and free text queries are assigned a search score according to the scoring or similarity functions configured on the fields (BM25 for text fields). The scores are merged using Reciprocal Rank Fusion (RRF) to weight each document with the inverse of its position in the ranked result set.
370+
The response includes the top 10 ordered by search score. Both vector queries and free text queries are assigned a search score according to the scoring or similarity functions configured on the fields (BM25 for text fields). The scores are merged using [Reciprocal Rank Fusion (RRF)](vector-search-ranking.md#reciprocal-rank-fusion-rrf-for-hybrid-queries) to weight each document with the inverse of its position in the ranked result set.
364371

365372
```http
366373
POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version={{api-version}}
367374
Content-Type: application/json
368375
api-key: {{admin-api-key}}
369376
{
370-
"vector": {
371-
"value": [
372-
-0.009154141,
373-
0.018708462,
374-
. . .
375-
-0.02178128,
376-
-0.00086512347
377-
],
378-
"fields": "contentVector",
379-
"k": 10
380-
},
377+
"vectors": [
378+
{
379+
"value": [
380+
-0.009154141,
381+
0.018708462,
382+
. . .
383+
-0.02178128,
384+
-0.00086512347
385+
],
386+
"fields": "contentVector",
387+
"k": 10
388+
}
389+
],
381390
"search": "what azure services support full text search",
382391
"top": "10"
383392
}
384393
```
385394

386-
Compare the responses between Single Vector Search and Simple Hybrid Search for the top result. The different ranking algorithms produce scores that may seem in different magnitudes. This is by design of the RRF algorithm. When using Hybrid search, it's important to note that the reciprocal of the ranked documents are taken given the relatively smaller score vs pure vector search.
395+
Compare the responses between Single Vector Search and Simple Hybrid Search for the top result. The different ranking algorithms, HNSW's similarity metric and RRF respectively, produce scores that have different magnitudes. This is by design. Note that RRF scores may appear quite low, even with a high similarity match. This is a characteristic of the RRF algorithm. When using hybrid search and RRF, more of the reciprocal of the ranked documents are included in the results, given the relatively smaller score of the RRF ranked documents, as opposed to pure vector search.
387396

388-
**Single Vector Search**: Results ordered by cosine similarity (default vector similarity distance function)
397+
**Single Vector Search**: Results ordered by cosine similarity (default vector similarity distance function).
389398

390-
```
399+
```json
391400
{
392401
"@search.score": 0.8851871,
393402
"title": "Azure Cognitive Search",
@@ -398,7 +407,7 @@ Compare the responses between Single Vector Search and Simple Hybrid Search for
398407

399408
**Hybrid Search**: Combined keyword and vector search results using Reciprocal Rank Fusion.
400409

401-
```
410+
```json
402411
{
403412
"@search.score": 0.03333333507180214,
404413
"title": "Azure Cognitive Search",
@@ -409,24 +418,26 @@ Compare the responses between Single Vector Search and Simple Hybrid Search for
409418

410419
### Hybrid search with filter
411420

412-
This example adds a filter, which is applied to the non-vector content of the search index.
421+
This example adds a filter, which is applied to the nonvector content of the search index.
413422

414423
```http
415424
POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version={{api-version}}
416425
Content-Type: application/json
417426
api-key: {{admin-api-key}}
418427
{
419-
"vector": {
420-
"value": [
421-
-0.009154141,
422-
0.018708462,
423-
. . .
424-
-0.02178128,
425-
-0.00086512347
426-
],
427-
"fields": "contentVector",
428-
"k": 10
429-
},
428+
"vectors": [
429+
{
430+
"value": [
431+
-0.009154141,
432+
0.018708462,
433+
. . .
434+
-0.02178128,
435+
-0.00086512347
436+
],
437+
"fields": "contentVector",
438+
"k": 10
439+
}
440+
],
430441
"search": "what azure services support full text search",
431442
"filter": "category eq 'Databases'",
432443
"top": "10"
@@ -442,17 +453,19 @@ POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/d
442453
Content-Type: application/json
443454
api-key: {{admin-api-key}}
444455
{
445-
"vector": {
446-
"value": [
447-
-0.009154141,
448-
0.018708462,
449-
. . .
450-
-0.02178128,
451-
-0.00086512347
452-
],
453-
"fields": "contentVector",
454-
"k": 10
455-
},
456+
"vectors": [
457+
{
458+
"value": [
459+
-0.009154141,
460+
0.018708462,
461+
. . .
462+
-0.02178128,
463+
-0.00086512347
464+
],
465+
"fields": "contentVector",
466+
"k": 10
467+
}
468+
],
456469
"search": "what azure services support full text search",
457470
"select": "title, content, category",
458471
"queryType": "semantic",
@@ -466,24 +479,26 @@ api-key: {{admin-api-key}}
466479

467480
### Semantic hybrid search with filter
468481

469-
Here's the last query in the collection. It's the same hybrid query as above, with a filter.
482+
Here's the last query in the collection. It's the same hybrid query as the previous example, but with a filter.
470483

471484
```http
472485
POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version={{api-version}}
473486
Content-Type: application/json
474487
api-key: {{admin-api-key}}
475488
{
476-
"vector": {
477-
"value": [
478-
-0.009154141,
479-
0.018708462,
480-
. . .
481-
-0.02178128,
482-
-0.00086512347
483-
],
484-
"fields": "contentVector",
485-
"k": 10
486-
},
489+
"vectors": [
490+
{
491+
"value": [
492+
-0.009154141,
493+
0.018708462,
494+
. . .
495+
-0.02178128,
496+
-0.00086512347
497+
],
498+
"fields": "contentVector",
499+
"k": 10
500+
}
501+
],
487502
"search": "what azure services support full text search",
488503
"select": "title, content, category",
489504
"queryType": "semantic",
@@ -509,4 +524,3 @@ Azure Cognitive Search is a billable resource. If it's no longer needed, delete
509524
## Next steps
510525

511526
As a next step, we recommend reviewing the demo code for [Python](https://github.com/Azure/cognitive-search-vector-pr/tree/main/demo-python), or [C#](https://github.com/Azure/cognitive-search-vector-pr/tree/main/demo-dotnet).
512-

‎articles/search/vector-search-how-to-chunk-documents.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ This article describes several approaches for chunking large documents so that y
1919

2020
## Why is chunking important?
2121

22-
The models used to generate embedding vectors have maximum limits on the text fragments provided as input. For example, the maximum length of input text for the [Azure OpenAI](/azure/cognitive-services/openai/how-to/embeddings) embedding models is 8,191 tokens (equivalent to around 6000 words of text). If you're using these models to generate embeddings, it's critical that the input text stays under the limit. Partitioning your content into chunks ensures that your data can be processed by the Large Language Models (LLM) used for indexing and queries.
22+
The models used to generate embedding vectors have maximum limits on the text fragments provided as input. For example, the maximum length of input text for the [Azure OpenAI](/azure/cognitive-services/openai/how-to/embeddings) embedding models is 8,191 tokens. Given that each token is around 4 tokens for common OpenAI models, this maximum limit is equivalent to around 6000 words of text. If you're using these models to generate embeddings, it's critical that the input text stays under the limit. Partitioning your content into chunks ensures that your data can be processed by the Large Language Models (LLM) used for indexing and queries.
2323

2424
## How chunking fits into the workflow
2525

‎articles/search/vector-search-how-to-create-index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -230,4 +230,4 @@ api-key: {{admin-api-key}}
230230

231231
As a next step, we recommend [Query vector data in a search index](vector-search-how-to-query.md).
232232

233-
You might also consider reviewing the demo code for [Python](https://github.com/Azure/cognitive-search-vector-pr/tree/main/demo-python), [JavaScript](https://github.com/Azure/cognitive-search-vector-pr/tree/main/demo-javascript), or [C#](https://github.com/Azure/cognitive-search-vector-pr/tree/main/demo-dotnet).
233+
You might also consider reviewing the demo code for [Python](https://github.com/Azure/cognitive-search-vector-pr/tree/main/demo-python) or [C#](https://github.com/Azure/cognitive-search-vector-pr/tree/main/demo-dotnet).

‎articles/search/vector-search-how-to-generate-embeddings.md

Lines changed: 2 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ Dimension attributes have a minimum of 2 and a maximum of 2048 dimensions per ve
2525

2626
+ We used **text-embedding-ada-002** to generate text embeddings and [Image Retrieval REST API](/rest/api/computervision/2023-02-01-preview/image-retrieval/vectorize-image) for image embeddings.
2727

28-
+ To avoid [rate limiting](https://learn.microsoft.com/azure/cognitive-services/openai/quotas-limits), we implemented retry logic in our workload. For the Python demo, we used [tenacity](https://pypi.org/project/tenacity/).
28+
+ To avoid [rate limiting](/azure/cognitive-services/openai/quotas-limits), we implemented retry logic in our workload. For the Python demo, we used [tenacity](https://pypi.org/project/tenacity/).
2929

3030
+ Query outputs are any matching documents found in a search index. Your search index must have been previously loaded with documents having one or more vector fields with embeddings. Whatever model you used for indexing, use the same model for queries.
3131

@@ -63,14 +63,8 @@ print(embeddings)
6363

6464
## Tips and recommendations for embedding model integration
6565

66-
<!-- + Python and JavaScript demos offer more scalability than the REST APIs for generating embeddings. As of this writing, the REST API doesn't currently support batching. -->
67-
<!--
68-
+ We've done proof-of-concept testing with indexers and skillsets, where a custom skill calls a machine learning model to generate embeddings. There's currently no tutorial or walkthrough, but we intend to provide this content as part of the public preview launch, if not sooner. -->
69-
<!--
70-
+ We've done proof-of-concept testing of embeddings for a thousand images using [image retrieval vectorization in Cognitive Services](/azure/cognitive-services/computer-vision/how-to/image-retrieval). We hope to provide a demo of this soon. -->
71-
7266
+ **Identify use cases:** Evaluate the specific use cases where embedding model integration for vector search features can add value to your search solution. This can include matching image content with text content, cross-lingual searches, or finding similar documents.
73-
+ **Optimize cost and performance**: Vector search can be resource-intensive, so consider only vectorizing the fields that contain semantic meaning
67+
+ **Optimize cost and performance**: Vector search can be resource-intensive and is subject to maximum limits, so consider only vectorizing the fields that contain semantic meaning.
7468
+ **Choose the right embedding model:** Select an appropriate model for your specific use case, such as word embeddings for text-based searches or image embeddings for visual searches. Consider using pre-trained models like **text-embedding-ada-002** from OpenAI or **Image Retreival** REST API from [Azure AI Computer Vision](/azure/cognitive-services/computer-vision/how-to/image-retrieval).
7569
+ **Normalize Vector lengths**: Ensure that the vector lengths are normalized before storing them in the search index to improve the accuracy and performance of similarity search. Most pre-trained models already are normalized but not all.
7670
+ **Fine-tune the model**: If needed, fine-tune the selected model on your domain-specific data to improve its performance and relevance to your search application.

0 commit comments

Comments
 (0)