From 8d3169921ea08fe8aebd0ac8549613bd1a63fe96 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Wed, 6 Dec 2023 11:44:50 +0100 Subject: [PATCH 1/7] [DOCS] Adds inference API end-to-end example. --- .../semantic-search-inference.asciidoc | 260 ++++++++++++++++++ .../search-your-data/semantic-search.asciidoc | 1 + 2 files changed, 261 insertions(+) create mode 100644 docs/reference/search/search-your-data/semantic-search-inference.asciidoc diff --git a/docs/reference/search/search-your-data/semantic-search-inference.asciidoc b/docs/reference/search/search-your-data/semantic-search-inference.asciidoc new file mode 100644 index 0000000000000..bcb56b53ceb9d --- /dev/null +++ b/docs/reference/search/search-your-data/semantic-search-inference.asciidoc @@ -0,0 +1,260 @@ +[[semantic-search-inference]] +=== Tutorial: semantic search with the {infer} API +++++ +Semantic search with the {infer} API +++++ + +The instructions in this tutorial shows you how to use the {infer} API with the +Open AI service to perform semantic search on your data. The following example +uses OpenAI's `text-embedding-ada-002` second generation embedding model. You +can use any OpenAI models, they are all supported by the {infer} API. + + +[discrete] +[[infer-openai-requirements]] +==== Requirements + +An https://openai.com/[OpenAI account] is required to use the {infer} API with +the OpenAI service. + + +[discrete] +[[infer-text-embedding-task]] +==== Create the inference task + +Create the {infer} task by using the <>: + +[source,console] +------------------------------------------------------------ +PUT _inference/text_embedding/openai_embeddings <1> +{ + "service": "openai", + "service_settings": { + "api_key": "" <2> + }, + "task_settings": { + "model": "text-embedding-ada-002" <3> + } +} +------------------------------------------------------------ +// TEST[skip:TBD] +<1> The task type is `text_embedding` in the path. +<2> The API key of your OpenAI account. You can find your OpenAI API keys in +your OpenAI account under the +https://platform.openai.com/api-keys[API keys section]. You need to provide +your API key only once. The <> does not retrieve your API +key. +<3> The name of the embedding model to use. You can find the list of OpenAI +embedding models +https://platform.openai.com/docs/guides/embeddings/embedding-models[here]. + + +[discrete] +[[infer-openai-mappings]] +==== 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 <> +field type to index the output of the OpenAI model. + +[source,js] +-------------------------------------------------- +PUT openai-embeddings +{ + "mappings": { + "properties": { + "content_embedding": { <1> + "type": "dense_vector", <2> + "dims": 1536 <3> + }, + "content": { <4> + "type": "text" <5> + } + } + } +} +-------------------------------------------------- +<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 `dense_vector` field. +<3> The output dimensions of the model. Find this value in the +https://platform.openai.com/docs/guides/embeddings/embedding-models[OpenAI documentation] +of the model you use. +<4> The name of the field from which to create the sparse 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. +<5> The field type which is text in this example. + + +[discrete] +[[infer-openai-inference-ingest-pipeline]] +==== Create an ingest pipeline with an inference processor + +Create an <> with an +<> to use the OpenAI model you referenced +in the {infer} task to infer against the data that is being ingested in the +pipeline. + +[source,js] +-------------------------------------------------- +PUT _ingest/pipeline/openai_embeddings +{ + "processors": [ + { + "inference": { + "model_id": "openai_embeddings", <1> + "input_output": { <2> + "input_field": "content", + "output_field": "content_embedding" + } + } + } + ] +} +-------------------------------------------------- +<1> The name of the inference task you created by using the +<>. +<2> Configuration object that defines the `input_field` for the {infer} process +and the `output_field` that will contain the {infer} results. + +[discrete] +[[infer-load-data]] +==== Load data + +In this step, you load the data that you later use in the {infer} ingest +pipeline to create embeddings from it. + +Use the `msmarco-passagetest2019-top1000` data set, which is a subset of the MS +MARCO Passage Ranking data set. It consists of 200 queries, each accompanied by +a list of relevant text passages. All unique passages, along with their IDs, +have been extracted from that data set and compiled into a +https://github.com/elastic/stack-docs/blob/main/docs/en/stack/ml/nlp/data/msmarco-passagetest2019-unique.tsv[tsv file]. + +Download the file and upload it to your cluster using the +{kibana-ref}/connect-to-elasticsearch.html#upload-data-kibana[Data Visualizer] +in the {ml-app} UI. Assign the name `id` to the first column and `content` to +the second column. The index name is `test-data`. Once the upload is complete, +you can see an index named `test-data` with 182469 documents. + + +[discrete] +[[reindexing-data-infer]] +==== Ingest the data through the {infer} ingest pipeline + +Create the embeddings from the text by reindexing the data throught the {infer} +pipeline that uses the OpenAI model as the inference model. + +[source,console] +---- +POST _reindex?wait_for_completion=false +{ + "source": { + "index": "test-data", + "size": 50 <1> + }, + "dest": { + "index": "openai-embeddings", + "pipeline": "openai_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. + +The call returns a task ID to monitor the progress: + +[source,console] +---- +GET _tasks/ +---- +// TEST[skip:TBD] + +NOTE: The +https://platform.openai.com/account/limits[rate limit of your OpenAI account] +may affect the throughput of the reindexing process. If this happens, change +`size` to `3` or a similar value in magnitude. + +You can also cancel the reindexing process if you don't want to wait until the +reindexing process is fully complete which might take hours: + +[source,console] +---- +POST _tasks//_cancel +---- +// TEST[skip:TBD] + + +[discrete] +[[infer-semantic-search]] +==== Semantic search + +After the dataset 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. + +NOTE: If you cancelled the reindexing process, you run the query only a part of +the data which affects the quality of your results. + +[source,js] +-------------------------------------------------- +GET openai-embeddings/_search +{ + "knn": { + "field": "content_embedding", + "query_vector_builder": { + "text_embedding": { + "model_id": "openai_embeddings", + "model_text": "Calculate fuel cost" + } + }, + "k": 10, + "num_candidates": 100 + }, + "_source": [ + "id", + "content" + ] +} +-------------------------------------------------- + +As a result, you receive the top 10 documents that are closest in meaning to the +query from the `openai-embeddings` index sorted by their proximity to the query: + +[source,js] +-------------------------------------------------- +"hits": [ + { + "_index": "openai-embeddings", + "_id": "DDd5OowBHxQKHyc3TDSC", + "_score": 0.83704096, + "_source": { + "id": 862114, + "body": "How to calculate fuel cost for a road trip. By Tara Baukus Mello • Bankrate.com. Dear Driving for Dollars, My family is considering taking a long road trip to finish off the end of the summer, but I'm a little worried about gas prices and our overall fuel cost.It doesn't seem easy to calculate since we'll be traveling through many states and we are considering several routes.y family is considering taking a long road trip to finish off the end of the summer, but I'm a little worried about gas prices and our overall fuel cost. It doesn't seem easy to calculate since we'll be traveling through many states and we are considering several routes." + } + }, + { + "_index": "openai-embeddings", + "_id": "ajd5OowBHxQKHyc3TDSC", + "_score": 0.8345704, + "_source": { + "id": 820622, + "body": "Home Heating Calculator. Typically, approximately 50% of the energy consumed in a home annually is for space heating. When deciding on a heating system, many factors will come into play: cost of fuel, installation cost, convenience and life style are all important.This calculator can help you estimate the cost of fuel for different heating appliances.hen deciding on a heating system, many factors will come into play: cost of fuel, installation cost, convenience and life style are all important. This calculator can help you estimate the cost of fuel for different heating appliances." + } + }, + { + "_index": "openai-embeddings", + "_id": "Djd5OowBHxQKHyc3TDSC", + "_score": 0.8327426, + "_source": { + "id": 8202683, + "body": "Fuel is another important cost. This cost will depend on your boat, how far you travel, and how fast you travel. A 33-foot sailboat traveling at 7 knots should be able to travel 300 miles on 50 gallons of diesel fuel.If you are paying $4 per gallon, the trip would cost you $200.Most boats have much larger gas tanks than cars.uel is another important cost. This cost will depend on your boat, how far you travel, and how fast you travel. A 33-foot sailboat traveling at 7 knots should be able to travel 300 miles on 50 gallons of diesel fuel." + } + }, + (...) + ] +-------------------------------------------------- + diff --git a/docs/reference/search/search-your-data/semantic-search.asciidoc b/docs/reference/search/search-your-data/semantic-search.asciidoc index 96281d12102bb..f4768e5c3a23d 100644 --- a/docs/reference/search/search-your-data/semantic-search.asciidoc +++ b/docs/reference/search/search-your-data/semantic-search.asciidoc @@ -135,3 +135,4 @@ include::{es-repo-dir}/tab-widgets/semantic-search/hybrid-search-widget.asciidoc ** The https://github.com/elastic/elasticsearch-labs[`elasticsearch-labs`] repo contains a number of interactive semantic search examples in the form of executable Python notebooks, using the {es} Python client include::semantic-search-elser.asciidoc[] +include::semantic-search-inference.asciidoc[] From 310d5b547a7f50b951c146514ceb4109085dde2c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Wed, 6 Dec 2023 11:58:39 +0100 Subject: [PATCH 2/7] [DOCS] Converts snippets. --- .../search-your-data/semantic-search-inference.asciidoc | 7 ++++--- 1 file changed, 4 insertions(+), 3 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 index bcb56b53ceb9d..4cfca1dbb50f1 100644 --- a/docs/reference/search/search-your-data/semantic-search-inference.asciidoc +++ b/docs/reference/search/search-your-data/semantic-search-inference.asciidoc @@ -58,7 +58,7 @@ that the model will create based on your input text - must be created. The destination index must have a field with the <> field type to index the output of the OpenAI model. -[source,js] +[source,console] -------------------------------------------------- PUT openai-embeddings { @@ -96,7 +96,7 @@ Create an <> with an in the {infer} task to infer against the data that is being ingested in the pipeline. -[source,js] +[source,console] -------------------------------------------------- PUT _ingest/pipeline/openai_embeddings { @@ -220,6 +220,7 @@ GET openai-embeddings/_search ] } -------------------------------------------------- +// TEST[skip:TBD] As a result, you receive the top 10 documents that are closest in meaning to the query from the `openai-embeddings` index sorted by their proximity to the query: @@ -257,4 +258,4 @@ query from the `openai-embeddings` index sorted by their proximity to the query: (...) ] -------------------------------------------------- - +// NOTCONSOLE From 922b65551da9f1737a9ac3177b3c6f80712d3614 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Wed, 6 Dec 2023 12:07:18 +0100 Subject: [PATCH 3/7] [DOCS] Fixes CI. --- .../semantic-search-inference.asciidoc | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 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 index 4cfca1dbb50f1..647ff565da116 100644 --- a/docs/reference/search/search-your-data/semantic-search-inference.asciidoc +++ b/docs/reference/search/search-your-data/semantic-search-inference.asciidoc @@ -118,6 +118,15 @@ PUT _ingest/pipeline/openai_embeddings <2> Configuration object that defines the `input_field` for the {infer} process and the `output_field` that will contain the {infer} results. +//// +[source,console] +---- +DELETE _ingest/pipeline/elser-v2-test +---- +// TEST[continued] +//// + + [discrete] [[infer-load-data]] ==== Load data @@ -199,7 +208,7 @@ provide the query text and 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. -[source,js] +[source,console] -------------------------------------------------- GET openai-embeddings/_search { @@ -225,7 +234,7 @@ GET openai-embeddings/_search As a result, you receive the top 10 documents that are closest in meaning to the query from the `openai-embeddings` index sorted by their proximity to the query: -[source,js] +[source,consol-result] -------------------------------------------------- "hits": [ { From d0b1e192d737753d7b5a4dfa6da88ebe89105dfd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Wed, 6 Dec 2023 13:01:42 +0100 Subject: [PATCH 4/7] [DOCS] Fixes CI. --- .../search/search-your-data/semantic-search-inference.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/search/search-your-data/semantic-search-inference.asciidoc b/docs/reference/search/search-your-data/semantic-search-inference.asciidoc index 647ff565da116..3536294341c2d 100644 --- a/docs/reference/search/search-your-data/semantic-search-inference.asciidoc +++ b/docs/reference/search/search-your-data/semantic-search-inference.asciidoc @@ -121,7 +121,7 @@ and the `output_field` that will contain the {infer} results. //// [source,console] ---- -DELETE _ingest/pipeline/elser-v2-test +DELETE _ingest/pipeline/openai_embeddings ---- // TEST[continued] //// From 64bedb0942993bc11b09f0a9968fa1ec1206feea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Thu, 7 Dec 2023 12:21:17 +0100 Subject: [PATCH 5/7] Apply suggestions from code review Co-authored-by: David Kyle --- .../search-your-data/semantic-search-inference.asciidoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 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 index 3536294341c2d..b38d417889e64 100644 --- a/docs/reference/search/search-your-data/semantic-search-inference.asciidoc +++ b/docs/reference/search/search-your-data/semantic-search-inference.asciidoc @@ -42,7 +42,7 @@ PUT _inference/text_embedding/openai_embeddings <1> <2> The API key of your OpenAI account. You can find your OpenAI API keys in your OpenAI account under the https://platform.openai.com/api-keys[API keys section]. You need to provide -your API key only once. The <> does not retrieve your API +your API key only once. The <> does not return your API key. <3> The name of the embedding model to use. You can find the list of OpenAI embedding models @@ -92,8 +92,8 @@ the {infer} pipeline configuration in the next step. ==== Create an ingest pipeline with an inference processor Create an <> with an -<> to use the OpenAI model you referenced -in the {infer} task to infer against the data that is being ingested in the +<> and use the OpenAI model you created +above to infer against the data that is being ingested in the pipeline. [source,console] @@ -113,7 +113,7 @@ PUT _ingest/pipeline/openai_embeddings ] } -------------------------------------------------- -<1> The name of the inference task you created by using the +<1> The name of the inference model you created by using the <>. <2> Configuration object that defines the `input_field` for the {infer} process and the `output_field` that will contain the {infer} results. From 93f4e153b326190584e1634860e80d5c1dbfb8e9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Thu, 7 Dec 2023 12:27:02 +0100 Subject: [PATCH 6/7] [DOCS] Addresses feedback. --- .../semantic-search-inference.asciidoc | 26 ++++++++++++------- 1 file changed, 16 insertions(+), 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 index b38d417889e64..e46ef5bb5d7e6 100644 --- a/docs/reference/search/search-your-data/semantic-search-inference.asciidoc +++ b/docs/reference/search/search-your-data/semantic-search-inference.asciidoc @@ -66,10 +66,12 @@ PUT openai-embeddings "properties": { "content_embedding": { <1> "type": "dense_vector", <2> - "dims": 1536 <3> + "dims": 1536, <3> + "element_type": "byte", + "similarity": "dot_product", <4> }, - "content": { <4> - "type": "text" <5> + "content": { <5> + "type": "text" <6> } } } @@ -81,10 +83,14 @@ in the {infer} pipeline configuration in the next step. <3> The output dimensions of the model. Find this value in the https://platform.openai.com/docs/guides/embeddings/embedding-models[OpenAI documentation] of the model you use. -<4> The name of the field from which to create the sparse vector representation. +<4> The faster` dot_product` function can be used to calculate similarity +because OpenAI embeddings are normalised to unit length. You can check the +https://platform.openai.com/docs/guides/embeddings/which-distance-function-should-i-use[OpenAI docs] +about which similarity function to use. +<5> The name of the field from which to create the sparse 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. -<5> The field type which is text in this example. +<6> The field type which is text in this example. [discrete] @@ -173,6 +179,11 @@ POST _reindex?wait_for_completion=false number makes the update of the reindexing process quicker which enables you to follow the progress closely and detect errors early. +NOTE: The +https://platform.openai.com/account/limits[rate limit of your OpenAI account] +may affect the throughput of the reindexing process. If this happens, change +`size` to `3` or a similar value in magnitude. + The call returns a task ID to monitor the progress: [source,console] @@ -181,11 +192,6 @@ GET _tasks/ ---- // TEST[skip:TBD] -NOTE: The -https://platform.openai.com/account/limits[rate limit of your OpenAI account] -may affect the throughput of the reindexing process. If this happens, change -`size` to `3` or a similar value in magnitude. - You can also cancel the reindexing process if you don't want to wait until the reindexing process is fully complete which might take hours: From a5dcf6346f581c1eac6baff1fc56bcf960aa897c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Thu, 7 Dec 2023 12:36:29 +0100 Subject: [PATCH 7/7] [DOCS] Fixes JSON. --- .../search/search-your-data/semantic-search-inference.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/search/search-your-data/semantic-search-inference.asciidoc b/docs/reference/search/search-your-data/semantic-search-inference.asciidoc index e46ef5bb5d7e6..7fbdecc0aebce 100644 --- a/docs/reference/search/search-your-data/semantic-search-inference.asciidoc +++ b/docs/reference/search/search-your-data/semantic-search-inference.asciidoc @@ -68,7 +68,7 @@ PUT openai-embeddings "type": "dense_vector", <2> "dims": 1536, <3> "element_type": "byte", - "similarity": "dot_product", <4> + "similarity": "dot_product" <4> }, "content": { <5> "type": "text" <6>