[DOCS] Adds elser service to the inference tutorial (#111406) (#111450)

* [DOCS] Adds elser service to the inference tutorial. * [DOCS] Amends search intro text. * [DOCS] Addresses feedback.
elastic · Jul 30, 2024 · edfbd5d · edfbd5d
1 parent fd02519
commit edfbd5d
Show file tree

Hide file tree

Showing 13 changed files with 274 additions and 10 deletions.
diff --git a/docs/reference/search/search-your-data/semantic-search-inference.asciidoc b/docs/reference/search/search-your-data/semantic-search-inference.asciidoc
@@ -11,8 +11,7 @@ IMPORTANT: For the easiest way to perform semantic search in the {stack}, refer
 
 The following examples use Cohere's `embed-english-v3.0` model, the `all-mpnet-base-v2` model from HuggingFace, and OpenAI's `text-embedding-ada-002` second generation embedding model.
 You can use any Cohere and OpenAI models, they are all supported by the {infer} API.
-For a list of supported models available on HuggingFace, refer to
-<<inference-example-hugging-face-supported-models, the supported model list>>.
+For a list of recommended models available on HuggingFace, refer to <<inference-example-hugging-face-supported-models, the supported model list>>.
 
 Azure based examples use models available through https://ai.azure.com/explore/models?selectedTask=embeddings[Azure AI Studio]
 or https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models[Azure OpenAI].
@@ -40,17 +39,15 @@ include::{es-ref-dir}/tab-widgets/inference-api/infer-api-task-widget.asciidoc[]
 ==== Create the index mapping
 
 The mapping of the destination index - the index that contains the embeddings that the model will create based on your input text - must be created.
-The destination index must have a field with the <<dense-vector, `dense_vector`>>
-field type to index the output of the used model.
+The destination index must have a field with the <<dense-vector, `dense_vector`>> field type for most models and the <<sparse-vector, `sparse_vector`>> field type for the sparse vector models like in the case of the `elser` service to index the output of the used model.
 
 include::{es-ref-dir}/tab-widgets/inference-api/infer-api-mapping-widget.asciidoc[]
 
 [discrete]
 [[infer-service-inference-ingest-pipeline]]
 ==== Create an ingest pipeline with an inference processor
 
-Create an <<ingest,ingest pipeline>> with an
-<<inference-processor,{infer} processor>> and use the model you created above to infer against the data that is being ingested in the pipeline.
+Create an <<ingest,ingest pipeline>> with an <<inference-processor,{infer} processor>> and use the model you created above to infer against the data that is being ingested in the pipeline.
 
 include::{es-ref-dir}/tab-widgets/inference-api/infer-api-ingest-pipeline-widget.asciidoc[]
 
@@ -103,8 +100,8 @@ POST _tasks/<task_id>/_cancel
 ==== Semantic search
 
 After the data set has been enriched with the embeddings, you can query the data using {ref}/knn-search.html#knn-semantic-search[semantic search].
-Pass a
-`query_vector_builder` to the k-nearest neighbor (kNN) vector search API, and provide the query text and the model you have used to create the embeddings.
+In case of dense vector models, pass a `query_vector_builder` to the k-nearest neighbor (kNN) vector search API, and provide the query text and the model you have used to create the embeddings.
+In case of a sparse vector model like ELSER, use a `sparse_vector` query, and provide the query text with the model you have used to create the embeddings.
 
 NOTE: If you cancelled the reindexing process, you run the query only a part of the data which affects the quality of your results.
 

diff --git a/docs/reference/tab-widgets/inference-api/infer-api-ingest-pipeline-widget.asciidoc b/docs/reference/tab-widgets/inference-api/infer-api-ingest-pipeline-widget.asciidoc
@@ -7,6 +7,12 @@
             id="infer-api-ingest-cohere">
       Cohere
     </button>
+    <button role="tab"
+            aria-selected="false"
+            aria-controls="infer-api-ingest-elser-tab"
+            id="infer-api-ingest-elser">
+      ELSER
+    </button>
     <button role="tab"
             aria-selected="false"
             aria-controls="infer-api-ingest-hf-tab"
@@ -52,6 +58,17 @@
 
 include::infer-api-ingest-pipeline.asciidoc[tag=cohere]
 
+++++
+  </div>
+  <div tabindex="0"
+       role="tabpanel"
+       id="infer-api-ingest-elser-tab"
+       aria-labelledby="infer-api-ingest-elser"
+       hidden="">
+++++
+
+include::infer-api-ingest-pipeline.asciidoc[tag=elser]
+
 ++++
   </div>
   <div tabindex="0"

diff --git a/docs/reference/tab-widgets/inference-api/infer-api-ingest-pipeline.asciidoc b/docs/reference/tab-widgets/inference-api/infer-api-ingest-pipeline.asciidoc
@@ -35,6 +35,32 @@ and the `output_field` that will contain the {infer} results.
 
 // end::cohere[]
 
+// tag::elser[]
+
+[source,console]
+--------------------------------------------------
+PUT _ingest/pipeline/elser_embeddings
+{
+  "processors": [
+    {
+      "inference": {
+        "model_id": "elser_embeddings", <1>
+        "input_output": { <2>
+          "input_field": "content",
+          "output_field": "content_embedding"
+        }
+      }
+    }
+  ]
+}
+--------------------------------------------------
+<1> The name of the inference endpoint you created by using the
+<<put-inference-api>>, it's referred to as `inference_id` in that step.
+<2> Configuration object that defines the `input_field` for the {infer} process
+and the `output_field` that will contain the {infer} results.
+
+// end::elser[]
+
 // tag::hugging-face[]
 
 [source,console]

diff --git a/docs/reference/tab-widgets/inference-api/infer-api-mapping-widget.asciidoc b/docs/reference/tab-widgets/inference-api/infer-api-mapping-widget.asciidoc
@@ -7,6 +7,12 @@
             id="infer-api-mapping-cohere">
       Cohere
     </button>
+    <button role="tab"
+            aria-selected="false"
+            aria-controls="infer-api-mapping-elser-tab"
+            id="infer-api-mapping-elser">
+      ELSER
+    </button>
     <button role="tab"
             aria-selected="false"
             aria-controls="infer-api-mapping-hf-tab"
@@ -52,6 +58,17 @@
 
 include::infer-api-mapping.asciidoc[tag=cohere]
 
+++++
+  </div>
+  <div tabindex="0"
+       role="tabpanel"
+       id="infer-api-mapping-elser-tab"
+       aria-labelledby="infer-api-mapping-elser"
+       hidden="">
+++++
+
+include::infer-api-mapping.asciidoc[tag=elser]
+
 ++++
   </div>
   <div tabindex="0"

diff --git a/docs/reference/tab-widgets/inference-api/infer-api-mapping.asciidoc b/docs/reference/tab-widgets/inference-api/infer-api-mapping.asciidoc
@@ -31,6 +31,34 @@ the {infer} pipeline configuration in the next step.
 
 // end::cohere[]
 
+// tag::elser[]
+
+[source,console]
+--------------------------------------------------
+PUT elser-embeddings
+{
+  "mappings": {
+    "properties": {
+      "content_embedding": { <1>
+        "type": "sparse_vector" <2>
+      },
+      "content": { <3>
+        "type": "text" <4>
+      }
+    }
+  }
+}
+--------------------------------------------------
+<1> The name of the field to contain the generated tokens. It must be refrenced
+in the {infer} pipeline configuration in the next step.
+<2> The field to contain the tokens is a `sparse_vector` field for ELSER.
+<3> The name of the field from which to create the dense vector representation.
+In this example, the name of the field is `content`. It must be referenced in
+the {infer} pipeline configuration in the next step.
+<4> The field type which is text in this example.
+
+// end::elser[]
+
 // tag::hugging-face[]
 
 [source,console]

diff --git a/docs/reference/tab-widgets/inference-api/infer-api-reindex-widget.asciidoc b/docs/reference/tab-widgets/inference-api/infer-api-reindex-widget.asciidoc
@@ -7,6 +7,12 @@
             id="infer-api-reindex-cohere">
       Cohere
     </button>
+    <button role="tab"
+            aria-selected="false"
+            aria-controls="infer-api-reindex-elser-tab"
+            id="infer-api-reindex-elser">
+      ELSER
+    </button>
     <button role="tab"
             aria-selected="false"
             aria-controls="infer-api-reindex-hf-tab"
@@ -52,6 +58,17 @@
 
 include::infer-api-reindex.asciidoc[tag=cohere]
 
+++++
+  </div>
+  <div tabindex="0"
+       role="tabpanel"
+       id="infer-api-reindex-elser-tab"
+       aria-labelledby="infer-api-reindex-elser"
+       hidden="">
+++++
+
+include::infer-api-reindex.asciidoc[tag=elser]
+
 ++++
   </div>
   <div tabindex="0"

diff --git a/docs/reference/tab-widgets/inference-api/infer-api-reindex.asciidoc b/docs/reference/tab-widgets/inference-api/infer-api-reindex.asciidoc
@@ -25,6 +25,29 @@ may affect the throughput of the reindexing process.
 
 // end::cohere[]
 
+// tag::elser[]
+
+[source,console]
+----
+POST _reindex?wait_for_completion=false
+{
+  "source": {
+    "index": "test-data",
+    "size": 50 <1>
+  },
+  "dest": {
+    "index": "elser-embeddings",
+    "pipeline": "elser_embeddings"
+  }
+}
+----
+// TEST[skip:TBD]
+<1> The default batch size for reindexing is 1000. Reducing `size` to a smaller
+number makes the update of the reindexing process quicker which enables you to
+follow the progress closely and detect errors early.
+
+// end::elser[]
+
 // tag::hugging-face[]
 
 [source,console]

diff --git a/docs/reference/tab-widgets/inference-api/infer-api-requirements-widget.asciidoc b/docs/reference/tab-widgets/inference-api/infer-api-requirements-widget.asciidoc
@@ -7,6 +7,12 @@
             id="infer-api-requirements-cohere">
       Cohere
     </button>
+    <button role="tab"
+            aria-selected="false"
+            aria-controls="infer-api-requirements-elser-tab"
+            id="infer-api-requirements-elser">
+      ELSER
+    </button>
     <button role="tab"
             aria-selected="false"
             aria-controls="infer-api-requirements-hf-tab"
@@ -52,6 +58,17 @@
 
 include::infer-api-requirements.asciidoc[tag=cohere]
 
+++++
+  </div>
+  <div tabindex="0"
+       role="tabpanel"
+       id="infer-api-requirements-elser-tab"
+       aria-labelledby="infer-api-requirements-elser"
+       hidden="">
+++++
+
+include::infer-api-requirements.asciidoc[tag=elser]
+
 ++++
   </div>
   <div tabindex="0"

diff --git a/docs/reference/tab-widgets/inference-api/infer-api-requirements.asciidoc b/docs/reference/tab-widgets/inference-api/infer-api-requirements.asciidoc
@@ -5,6 +5,13 @@ the Cohere service.
 
 // end::cohere[]
 
+// tag::elser[]
+
+ELSER is a model trained by Elastic. If you have an {es} deployment, there is no
+further requirement for using the {infer} API with the `elser` service.
+
+// end::elser[]
+
 // tag::hugging-face[]
 
 A https://huggingface.co/[HuggingFace account] is required to use the {infer}

diff --git a/docs/reference/tab-widgets/inference-api/infer-api-search-widget.asciidoc b/docs/reference/tab-widgets/inference-api/infer-api-search-widget.asciidoc
@@ -7,6 +7,12 @@
             id="infer-api-search-cohere">
       Cohere
     </button>
+    <button role="tab"
+            aria-selected="false"
+            aria-controls="infer-api-search-elser-tab"
+            id="infer-api-search-elser">
+      ELSER
+    </button>
     <button role="tab"
             aria-selected="false"
             aria-controls="infer-api-search-hf-tab"
@@ -52,6 +58,17 @@
 
 include::infer-api-search.asciidoc[tag=cohere]
 
+++++
+  </div>
+  <div tabindex="0"
+       role="tabpanel"
+       id="infer-api-search-elser-tab"
+       aria-labelledby="infer-api-search-elser"
+       hidden="">
+++++
+
+include::infer-api-search.asciidoc[tag=elser]
+
 ++++
   </div>
   <div tabindex="0"

diff --git a/docs/reference/tab-widgets/inference-api/infer-api-search.asciidoc b/docs/reference/tab-widgets/inference-api/infer-api-search.asciidoc
@@ -72,6 +72,67 @@ query from the `cohere-embeddings` index sorted by their proximity to the query:
 
 // end::cohere[]
 
+// tag::elser[]
+
+[source,console]
+--------------------------------------------------
+GET elser-embeddings/_search
+{
+  "query":{
+    "sparse_vector":{
+      "field": "content_embedding",
+      "inference_id": "elser_embeddings",
+      "query": "How to avoid muscle soreness after running?"
+    }
+  },
+  "_source": [
+    "id",
+    "content"
+  ]
+}
+--------------------------------------------------
+// TEST[skip:TBD]
+
+As a result, you receive the top 10 documents that are closest in meaning to the
+query from the `cohere-embeddings` index sorted by their proximity to the query:
+
+[source,consol-result]
+--------------------------------------------------
+"hits": [
+      {
+        "_index": "elser-embeddings",
+        "_id": "ZLGc_pABZbBmsu5_eCoH",
+        "_score": 21.472063,
+        "_source": {
+          "id": 2258240,
+          "content": "You may notice some muscle aches while you are exercising. This is called acute soreness. More often, you may begin to feel sore about 12 hours after exercising, and the discomfort usually peaks at 48 to 72 hours after exercise. This is called delayed-onset muscle soreness.It is thought that, during this time, your body is repairing the muscle, making it stronger and bigger.You may also notice the muscles feel better if you exercise lightly. This is normal.his is called delayed-onset muscle soreness. It is thought that, during this time, your body is repairing the muscle, making it stronger and bigger. You may also notice the muscles feel better if you exercise lightly. This is normal."
+        }
+      },
+      {
+        "_index": "elser-embeddings",
+        "_id": "ZbGc_pABZbBmsu5_eCoH",
+        "_score": 21.421381,
+        "_source": {
+          "id": 2258242,
+          "content": "Photo Credit Jupiterimages/Stockbyte/Getty Images. That stiff, achy feeling you get in the days after exercise is a normal physiological response known as delayed onset muscle soreness. You can take it as a positive sign that your muscles have felt the workout, but the pain may also turn you off to further exercise.ou are more likely to develop delayed onset muscle soreness if you are new to working out, if you’ve gone a long time without exercising and start up again, if you have picked up a new type of physical activity or if you have recently boosted the intensity, length or frequency of your exercise sessions."
+        }
+      },
+      {
+        "_index": "elser-embeddings",
+        "_id": "ZrGc_pABZbBmsu5_eCoH",
+        "_score": 20.542095,
+        "_source": {
+          "id": 2258248,
+          "content": "They found that stretching before and after exercise has no effect on muscle soreness. Exercise might cause inflammation, which leads to an increase in the production of immune cells (comprised mostly of macrophages and neutrophils). Levels of these immune cells reach a peak 24-48 hours after exercise.These cells, in turn, produce bradykinins and prostaglandins, which make the pain receptors in your body more sensitive. Whenever you move, these pain receptors are stimulated.hey found that stretching before and after exercise has no effect on muscle soreness. Exercise might cause inflammation, which leads to an increase in the production of immune cells (comprised mostly of macrophages and neutrophils). Levels of these immune cells reach a peak 24-48 hours after exercise."
+        }
+      },
+    (...)
+  ]
+--------------------------------------------------
+// NOTCONSOLE
+
+// end::elser[]
+
 // tag::hugging-face[]
 
 [source,console]