Neural Search plugin

The Neural Search plugin is an experimental feature. For updates on the progress of the Neural Search plugin, or if you want to leave feedback that could help improve the feature, join the discussion in the Neural Search forum.

The OpenSearch Neural Search plugin enables the integration of machine learning (ML) language models into your search workloads. During ingestion and search, the Neural Search plugin transforms text into vectors. Then, Neural Search uses the transformed vectors in vector-based search.

The Neural Search plugin comes bundled with OpenSearch. For more information, see Managing plugins.

In order to ingest vectorized documents, you need to create a Neural Search pipeline. A pipeline consists of a series of processors that manipulate documents during ingestion, allowing the documents to be vectorized. The following API operation creates a Neural Search pipeline:

  1. PUT _ingest/pipeline/<pipeline_name>

In the pipeline request body, The text_embedding processor, the only processor supported by Neural Search, converts a document’s text to vector embeddings. text_embedding uses field_maps to determine what fields from which to generate vector embeddings and also which field to store the embedding.

Path parameter

Use pipeline_name to create a name for your Neural Search pipeline.

Request fields

FieldData typeDescription
descriptionstringA description of the processor.
model_idstringThe ID of the model that will be used in the embedding interface. The model must be indexed in OpenSearch before it can be used in Neural Search. For more information, see Model Serving Framework
input_field_namestringThe field name used to cache text for text embeddings.
output_field_namestringThe name of the field in which output text is stored.

Example request

Use the following example request to create a pipeline:

  1. PUT _ingest/pipeline/nlp-pipeline
  2. {
  3.   "description": "An example neural search pipeline",
  4.   "processors" : [
  5.     {
  6.       "text_embedding": {
  7.         "model_id": "bxoDJ7IHGM14UqatWc_2j",
  8.         "field_map": {
  9.            "passage_text": "passage_embedding"
  10.         }
  11.       }
  12.     }
  13.   ]
  14. }

Example response

OpenSearch responds with an acknowledgment of the pipeline’s creation.

  1. PUT _ingest/pipeline/nlp-pipeline
  2. {
  3.   "acknowledged" : true
  4. }

Create an index for ingestion

In order to use the text embedding processor defined in your pipelines, create an index with mapping data that aligns with the maps specified in your pipeline. For example, the output_fields defined in the field_map field of your processor request must map to the k-NN vector fields with a dimension that matches the model. Similarly, the text_fields defined in your processor should map to the text_fields in your index.

Example request

The following example request creates an index that attaches to a Neural Search pipeline. Because the index maps to k-NN vector fields, the index setting field index-knn is set to true. Furthermore, mapping settings use k-NN method definitions to match the maps defined in the Neural Search pipeline.

  1. PUT /my-nlp-index-1
  2. {
  3.     "settings": {
  4.         "index.knn": true,
  5.         "default_pipeline": "<pipeline_name>"
  6.     },
  7.     "mappings": {
  8.         "properties": {
  9.             "passage_embedding": {
  10.                 "type": "knn_vector",
  11.                 "dimension": int,
  12.                 "method": {
  13.                     "name": "string",
  14.                     "space_type": "string",
  15.                     "engine": "string",
  16.                     "parameters": json_object
  17.                 }
  18.             },
  19.             "passage_text": { 
  20.                 "type": "text"            
  21.             },
  22.         }
  23.     }
  24. }

Example response

OpenSearch responds with information about your new index:

  1. {
  2.   "acknowledged" : true,
  3.   "shards_acknowledged" : true,
  4.   "index" : "my-nlp-index-1"
  5. }

Document ingestion is managed by OpenSearch’s Ingest API, similarly to other OpenSearch indexes. For example, you can ingest a document that contains the passage_text: "Hello world" with a simple POST method:

  1. POST /my-nlp-index-1/_doc
  2. {
  3.    "passage_text": "Hello world"
  4. }

With the text_embedding processor in place through a Neural Search pipeline, the example indexes “Hello world” as a text_field and converts “Hello world” into an associated k-NN vector field.

Search a neural index

If you want to use a language model to convert a text query into a k-NN vector query, use the neural query fields in your query. The neural query request fields can be used in both the k-NN plugin API and Query DSL. Furthermore, you can use a k-NN search filter to refine your neural search query.

Neural request fields

Include the following request fields under the neural field in your query:

FieldData typeDescription
vector_fieldstringThe vector field against which to run a search query.
query_textstringThe query text from which to produce queries.
model_idstringThe ID of the model that will be used in the embedding interface. The model must be indexed in OpenSearch before it can be used in Neural Search.
kintegerThe number of results the k-NN search returns.

Example request

The following example request uses a search query that returns vectors for the “Hello World” query text:

  1. GET my_index/_search
  2. {
  3.   "query": {
  4.     "bool" : {
  5.       "filter": {
  6.         "range": {
  7.           "distance": { "lte" : 20 }
  8.         }
  9.       },
  10.       "should" : [
  11.         {
  12.           "script_score": {
  13.             "query": {
  14.               "neural": {
  15.                 "passage_vector": {
  16.                   "query_text": "Hello world",
  17.                   "model_id": "xzy76xswsd",
  18.                   "k": 100
  19.                 }
  20.               }
  21.             },
  22.             "script": {
  23.               "source": "_score * 1.5"
  24.             }
  25.           }
  26.         }
  27.         ,
  28.         {
  29.           "script_score": {
  30.             "query": {
  31.               "match": { "passage_text": "Hello world" }
  32.             },
  33.             "script": {
  34.               "source": "_score * 1.7"
  35.             }
  36.           }
  37.         }
  38.       ]
  39.     }
  40.   }
  41. }