Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[8.13] [DOCS] Adds air-gapped install instructions to E5 docs (backport #2666) #2667

Merged
merged 1 commit into from
Mar 6, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions docs/en/stack/ml/index-custom-title-page.html
Original file line number Diff line number Diff line change
Expand Up @@ -151,6 +151,9 @@ <h4 class="mt-3">
<li>
<a href="ml-nlp-elser.html">ELSER - Elastic Learned Sparse EncodeR</a>
</li>
<li>
<a href="ml-nlp-e5.html">E5</a>
</li>
<li>
<a href="ml-nlp-model-ref.html">Supported third-party models</a>
</li>
Expand Down
117 changes: 114 additions & 3 deletions docs/en/stack/ml/nlp/ml-nlp-e5.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -150,13 +150,124 @@ POST _ml/trained_models/.multilingual-e5-small/deployment/_start?deployment_id=f
----------------------------------
--


[discrete]
[[air-gapped-install-e5]]
== Deploy the E5 model in an air-gapped environment

If you want to deploy the E5 model in a restricted or closed network, follow the
instructions
https://www.elastic.co/guide/en/elasticsearch/client/eland/current/machine-learning.html#ml-nlp-pytorch-air-gapped[in the Eland client documentation].
If you want to install E5 in an air-gapped environment, you have the following
options:
* put the model artifacts into a directory inside the config directory on all
master-eligible nodes (for `multilingual-e5-small` and
`multilingual-e5-small-optimized`)
* install the model by using HuggingFace (for `multilingual-e5-small` model
only).


[discrete]
[[e5-model-artifacts]]
=== Model artifact files

For the `multilingual-e5-small` model, you need the following files in your
system:
```
https://ml-models.elastic.co/multilingual-e5-small.metadata.json
https://ml-models.elastic.co/multilingual-e5-small.pt
https://ml-models.elastic.co/multilingual-e5-small.vocab.json
```

For the optimized version, you need the following files in your system:
```
https://ml-models.elastic.co/multilingual-e5-small-optimized.metadata.json
https://ml-models.elastic.co/multilingual-e5-small-optimized.pt
https://ml-models.elastic.co/multilingual-e5-small-optimized.vocab.json
```


[discrete]
=== Using file-based access

For a file-based access, follow these steps:

. Download the <<e5-model-artifacts,model artifact files>>.
. Put the files into a `models` subdirectory inside the `config` directory of
your {es} deployment.
. Point your {es} deployment to the model directory by adding the following line
to the `config/elasticsearch.yml` file:
+
--
```
xpack.ml.model_repository: file://${path.home}/config/models/`
```
--
. Repeat step 2 and step 3 on all master-eligible nodes.
. {ref}/restart-cluster.html#restart-cluster-rolling[Restart] the
master-eligible nodes one by one.
. Navigate to the **Trained Models** page in {kib}, E5 can be found in the
list of trained models.
. Click the **Add trained model** button, select the E5 model version you
downloaded in step 1 and want to deploy and click **Download**. The selected
model will be downloaded from the model directory where you put in step 2.
. After the download is finished, start the deployment by clicking the
**Start deployment** button.
. Provide a deployment ID, select the priority, and set the number of
allocations and threads per allocation values.
. Click **Start**.


[discrete]
=== Using the HuggingFace repository

You can install the `multilingual-e5-small` model in a restricted or closed
network by pointing the `eland_import_hub_model` script to the model's local
files.

For an offline install, the model first needs to be cloned locally, Git and
https://git-lfs.com/[Git Large File Storage] are required to be installed in
your system.

1. Clone the E5 model from Hugging Face by using the model URL.
+
--
[source,bash]
----
git clone https://huggingface.co/elastic/multilingual-e5-small
----
The command results in a local copy of the model in the `multilingual-e5-small`
directory.
--

2. Use the `eland_import_hub_model` script with the `--hub-model-id` set to the
directory of the cloned model to install it:
+
--
[source,bash]
----
eland_import_hub_model \
--url 'XXXX' \
--hub-model-id /PATH/TO/MODEL \
--task-type text_embedding \
--es-username elastic --es-password XXX \
--es-model-id multilingual-e5-small
----

If you use the Docker image to run `eland_import_hub_model` you must bind mount
the model directory, so the container can read the files.
[source,bash]
----
docker run --mount type=bind,source=/PATH/TO/MODELS,destination=/models,readonly -it --rm docker.elastic.co/eland/eland \
eland_import_hub_model \
--url 'XXXX' \
--hub-model-id /models/multilingual-e5-small \
--task-type text_embedding \
--es-username elastic --es-password XXX \
--es-model-id multilingual-e5-small
----
Once it's uploaded to {es}, the model will have the ID specified by
`--es-model-id`. If it is not set, the model ID is derived from
`--hub-model-id`; spaces and path delimiters are converted to double
underscores `__`.
--


[discrete]
Expand Down