[DOCS] Adds Hugging Face service to the inference API docs (elastic#1…

…04190)

docs/reference/inference/put-inference.asciidoc

@@ -25,6 +25,7 @@ own model, use the <<ml-df-trained-models-apis>>.
 
 * Requires the `manage` <<privileges-list-cluster,cluster privilege>>.
 
+
 [discrete]
 [[put-inference-api-desc]]
 ==== {api-description-title}
@@ -33,10 +34,12 @@ The create {infer} API enables you to create and configure an {infer} model to
 perform a specific {infer} task.
 
 The following services are available through the {infer} API:
+
 * ELSER
 * OpenAI
 * Hugging Face
 
+
 [discrete]
 [[put-inference-api-path-params]]
 ==== {api-path-parms-title}
@@ -63,7 +66,8 @@ The type of service supported for the specified task type.
 Available services:
 * `elser`: specify the `sparse_embedding` task type to use the ELSER service.
 * `openai`: specify the `text_embedding` task type to use the OpenAI service.
-* `hugging_face`: specify the `text_embedding` task type to use the Hugging Face service.
+* `hugging_face`: specify the `text_embedding` task type to use the Hugging Face 
+service.
 
 `service_settings`::
 (Required, object)
@@ -108,6 +112,26 @@ https://platform.openai.com/account/organization[**Settings** > **Organizations*
 The URL endpoint to use for the requests. Can be changed for testing purposes.
 Defaults to `https://api.openai.com/v1/embeddings`.
 =====
++
+.`service_settings` for `hugging_face`
+[%collapsible%closed]
+=====
+`api_key`:::
+(Required, string)
+A valid access token of your Hugging Face account. You can find your Hugging 
+Face access tokens or you can create a new one 
+https://huggingface.co/settings/tokens[on the settings page].
+
+IMPORTANT: You need to provide the API key only once, during the {infer} model 
+creation. The <<get-inference-api>> does not retrieve your API key. After 
+creating the {infer} model, you cannot change the associated API key. If you 
+want to use a different API key, delete the {infer} model and recreate it with 
+the same name and the updated API key.
+
+`url`:::
+(Required, string)
+The URL endpoint to use for the requests.
+=====
 
 `task_settings`::
 (Optional, object)
@@ -124,10 +148,18 @@ https://platform.openai.com/docs/guides/embeddings/what-are-embeddings[OpenAI do
 for the list of available text embedding models.
 =====
 
+
 [discrete]
 [[put-inference-api-example]]
 ==== {api-examples-title}
 
+This section contains example API calls for every service type.
+
+
+[discrete]
+[[inference-example-elser]]
+===== ELSER service
+
 The following example shows how to create an {infer} model called
 `my-elser-model` to perform a `sparse_embedding` task type.
 
@@ -164,6 +196,10 @@ Example response:
 // NOTCONSOLE
 
 
+[discrete]
+[[inference-example-openai]]
+===== OpenAI service
+
 The following example shows how to create an {infer} model called
 `openai_embeddings` to perform a `text_embedding` task type.
 
@@ -180,4 +216,35 @@ PUT _inference/text_embedding/openai_embeddings
     }
 }
 ------------------------------------------------------------
-// TEST[skip:TBD]
+// TEST[skip:TBD]
+
+
+[discrete]
+[[inference-example-hugging-face]]
+===== Hugging Face service
+
+The following example shows how to create an {infer} model called
+`hugging-face_embeddings` to perform a `text_embedding` task type.
+
+[source,console]
+------------------------------------------------------------
+PUT _inference/text_embedding/hugging-face-embeddings 
+{
+  "service": "hugging_face",
+  "service_settings": {
+    "api_key": "<access_token>", <1>
+    "url": "<url_endpoint>" <2>
+  }
+}
+------------------------------------------------------------
+// TEST[skip:TBD]
+<1> A valid Hugging Face access token. You can find on the 
+https://huggingface.co/settings/tokens[settings page of your account].
+<2> The {infer} endpoint URL you created on Hugging Face. 
+
+Create a new {infer} endpoint on 
+https://ui.endpoints.huggingface.co/[the Hugging Face endpoint page] to get an 
+endpoint URL. Select the model you want to use on the new endpoint creation page 
+- for example `intfloat/e5-small-v2` - then select the `Sentence Embeddings` 
+task under the Advanced configuration section. Create the endpoint. Copy the URL 
+after the endpoint initialization has been finished.