Vector DB tool

Introduced 2.13

The VectorDBTool performs dense vector retrieval. For more information about OpenSearch vector database capabilities, see neural search.

Step 1: Register and deploy a sparse encoding model

OpenSearch supports several pretrained models. You can use one of those models, use your own custom model, or create a connector for an externally hosted model. For a list of supported pretrained models, see OpenSearch-provided pretrained models. For more information about custom models, see Custom local models. For information about integrating an externally hosted model, see Connecting to externally hosted models.

In this example, you’ll use the huggingface/sentence-transformers/all-MiniLM-L12-v2 pretrained model for both ingestion and search. To register and deploy the model to OpenSearch, send the following request:

  1. POST /_plugins/_ml/models/_register?deploy=true
  2. {
  3.   "name": "huggingface/sentence-transformers/all-MiniLM-L12-v2",
  4.   "version": "1.0.1",
  5.   "model_format": "TORCH_SCRIPT"
  6. }

copy

OpenSearch responds with a task ID for the model registration and deployment task:

  1. {
  2.   "task_id": "M_9KY40Bk4MTqirc5lP8",
  3.   "status": "CREATED"
  4. }

You can monitor the status of the task by calling the Tasks API:

  1. GET _plugins/_ml/tasks/M_9KY40Bk4MTqirc5lP8

copy

Once the model is registered and deployed, the task state changes to COMPLETED and OpenSearch returns a model ID for the model:

  1. {
  2.   "model_id": "Hv_PY40Bk4MTqircAVmm",
  3.   "task_type": "REGISTER_MODEL",
  4.   "function_name": "TEXT_EMBEDDING",
  5.   "state": "COMPLETED",
  6.   "worker_node": [
  7.     "UyQSTQ3nTFa3IP6IdFKoug"
  8.   ],
  9.   "create_time": 1706767869692,
  10.   "last_update_time": 1706767935556,
  11.   "is_async": true
  12. }

Step 2: Ingest data into an index

First, you’ll set up an ingest pipeline to encode documents using the sparse encoding model set up in the previous step:

  1. PUT /_ingest/pipeline/test-pipeline-local-model
  2. {
  3.   "description": "text embedding pipeline",
  4.   "processors": [
  5.     {
  6.       "text_embedding": {
  7.         "model_id": "Hv_PY40Bk4MTqircAVmm",
  8.         "field_map": {
  9.           "text": "embedding"
  10.         }
  11.       }
  12.     }
  13.   ]
  14. }

copy

Next, create a k-NN index specifying the pipeline as the default pipeline:

  1. PUT my_test_data
  2. {
  3.   "mappings": {
  4.     "properties": {
  5.       "text": {
  6.         "type": "text"
  7.       },
  8.       "embedding": {
  9.         "type": "knn_vector",
  10.         "dimension": 384
  11.       }
  12.     }
  13.   },
  14.   "settings": {
  15.     "index": {
  16.       "knn.space_type": "cosinesimil",
  17.       "default_pipeline": "test-pipeline-local-model",
  18.       "knn": "true"
  19.     }
  20.   }
  21. }

copy

Last, ingest data into the index by sending a bulk request:

  1. POST _bulk
  2. {"index": {"_index": "my_test_data", "_id": "1"}}
  3. {"text": "Chart and table of population level and growth rate for the Ogden-Layton metro area from 1950 to 2023. United Nations population projections are also included through the year 2035.\nThe current metro area population of Ogden-Layton in 2023 is 750,000, a 1.63% increase from 2022.\nThe metro area population of Ogden-Layton in 2022 was 738,000, a 1.79% increase from 2021.\nThe metro area population of Ogden-Layton in 2021 was 725,000, a 1.97% increase from 2020.\nThe metro area population of Ogden-Layton in 2020 was 711,000, a 2.16% increase from 2019."}
  4. {"index": {"_index": "my_test_data", "_id": "2"}}
  5. {"text": "Chart and table of population level and growth rate for the New York City metro area from 1950 to 2023. United Nations population projections are also included through the year 2035.\\nThe current metro area population of New York City in 2023 is 18,937,000, a 0.37% increase from 2022.\\nThe metro area population of New York City in 2022 was 18,867,000, a 0.23% increase from 2021.\\nThe metro area population of New York City in 2021 was 18,823,000, a 0.1% increase from 2020.\\nThe metro area population of New York City in 2020 was 18,804,000, a 0.01% decline from 2019."}
  6. {"index": {"_index": "my_test_data", "_id": "3"}}
  7. {"text": "Chart and table of population level and growth rate for the Chicago metro area from 1950 to 2023. United Nations population projections are also included through the year 2035.\\nThe current metro area population of Chicago in 2023 is 8,937,000, a 0.4% increase from 2022.\\nThe metro area population of Chicago in 2022 was 8,901,000, a 0.27% increase from 2021.\\nThe metro area population of Chicago in 2021 was 8,877,000, a 0.14% increase from 2020.\\nThe metro area population of Chicago in 2020 was 8,865,000, a 0.03% increase from 2019."}
  8. {"index": {"_index": "my_test_data", "_id": "4"}}
  9. {"text": "Chart and table of population level and growth rate for the Miami metro area from 1950 to 2023. United Nations population projections are also included through the year 2035.\\nThe current metro area population of Miami in 2023 is 6,265,000, a 0.8% increase from 2022.\\nThe metro area population of Miami in 2022 was 6,215,000, a 0.78% increase from 2021.\\nThe metro area population of Miami in 2021 was 6,167,000, a 0.74% increase from 2020.\\nThe metro area population of Miami in 2020 was 6,122,000, a 0.71% increase from 2019."}
  10. {"index": {"_index": "my_test_data", "_id": "5"}}
  11. {"text": "Chart and table of population level and growth rate for the Austin metro area from 1950 to 2023. United Nations population projections are also included through the year 2035.\\nThe current metro area population of Austin in 2023 is 2,228,000, a 2.39% increase from 2022.\\nThe metro area population of Austin in 2022 was 2,176,000, a 2.79% increase from 2021.\\nThe metro area population of Austin in 2021 was 2,117,000, a 3.12% increase from 2020.\\nThe metro area population of Austin in 2020 was 2,053,000, a 3.43% increase from 2019."}
  12. {"index": {"_index": "my_test_data", "_id": "6"}}
  13. {"text": "Chart and table of population level and growth rate for the Seattle metro area from 1950 to 2023. United Nations population projections are also included through the year 2035.\\nThe current metro area population of Seattle in 2023 is 3,519,000, a 0.86% increase from 2022.\\nThe metro area population of Seattle in 2022 was 3,489,000, a 0.81% increase from 2021.\\nThe metro area population of Seattle in 2021 was 3,461,000, a 0.82% increase from 2020.\\nThe metro area population of Seattle in 2020 was 3,433,000, a 0.79% increase from 2019."}

copy

Step 3: Register a flow agent that will run the VectorDBTool

A flow agent runs a sequence of tools in order and returns the last tool’s output. To create a flow agent, send the following request, providing the model ID for the model set up in Step 1. This model will encode your queries into vector embeddings:

  1. POST /_plugins/_ml/agents/_register
  2. {
  3.   "name": "Test_Agent_For_VectorDB",
  4.   "type": "flow",
  5.   "description": "this is a test agent",
  6.   "tools": [
  7.     {
  8.       "type": "VectorDBTool",
  9.       "parameters": {
  10.         "model_id": "Hv_PY40Bk4MTqircAVmm",
  11.         "index": "my_test_data",
  12.         "embedding_field": "embedding",
  13.         "source_field": ["text"],
  14.         "input": "${parameters.question}"
  15.       }
  16.     }
  17.   ]
  18. }

copy

For parameter descriptions, see Register parameters.

OpenSearch responds with an agent ID:

  1. {
  2.   "agent_id": "9X7xWI0Bpc3sThaJdY9i"
  3. }

Step 4: Run the agent

Before you run the agent, make sure that you add the sample OpenSearch Dashboards Sample web logs dataset. To learn more, see Adding sample data.

Then, run the agent by sending the following request:

  1. POST /_plugins/_ml/agents/9X7xWI0Bpc3sThaJdY9i/_execute
  2. {
  3.   "parameters": {
  4.     "question": "what's the population increase of Seattle from 2021 to 2023"
  5.   }
  6. }

copy

OpenSearch performs vector search and returns the relevant documents:

  1. {
  2.   "inference_results": [
  3.     {
  4.       "output": [
  5.         {
  6.           "name": "response",
  7.           "result": """{"_index":"my_test_data","_source":{"text":"Chart and table of population level and growth rate for the Seattle metro area from 1950 to 2023. United Nations population projections are also included through the year 2035.\\n
  8.           The current metro area population of Seattle in 2023 is 3,519,000, a 0.86% increase from 2022.\\n
  9.           The metro area population of Seattle in 2022 was 3,489,000, a 0.81% increase from 2021.\\n
  10.           The metro area population of Seattle in 2021 was 3,461,000, a 0.82% increase from 2020.\\n
  11.           The metro area population of Seattle in 2020 was 3,433,000, a 0.79% increase from 2019."},"_id":"6","_score":0.8173238}
  12.         {"_index":"my_test_data","_source":{"text":"Chart and table of population level and growth rate for the New York City metro area from 1950 to 2023. United Nations population projections are also included through the year 2035.\\n
  13.         The current metro area population of New York City in 2023 is 18,937,000, a 0.37% increase from 2022.\\n
  14.         The metro area population of New York City in 2022 was 18,867,000, a 0.23% increase from 2021.\\n
  15.         The metro area population of New York City in 2021 was 18,823,000, a 0.1% increase from 2020.\\n
  16.         The metro area population of New York City in 2020 was 18,804,000, a 0.01% decline from 2019."},"_id":"2","_score":0.6641471}
  17.         """
  18.         }
  19.       ]
  20.     }
  21.   ]
  22. }

Register parameters

The following table lists all tool parameters that are available when registering an agent.

ParameterTypeRequired/OptionalDescription
model_idStringRequiredThe model ID of the model to use at search time.
indexStringRequiredThe index to search.
embedding_fieldStringRequiredWhen the model encodes raw text documents, the encoding result is saved in a field. Specify this field as the embedding_field. Neural search matches documents to the query by calculating the similarity score between the query text and the text in the document’s embedding_field.
source_fieldStringRequiredThe document field or fields to return. You can provide a list of multiple fields as an array of strings, for example, [“field1”, “field2”].
inputStringRequired for flow agentRuntime input sourced from flow agent parameters. If using a large language model (LLM), this field is populated with the LLM response.
doc_sizeIntegerOptionalThe number of documents to fetch. Default is 2.
kIntegerOptionalThe number of nearest neighbors to search for when performing neural search. Default is 10.

Execute parameters

The following table lists all tool parameters that are available when running the agent.

ParameterTypeRequired/OptionalDescription
questionStringRequiredThe natural language question to send to the LLM.