Elasticsearch：在隔离环境中安装 ELSER 模型

在我之前的文章 "Elasticsearch：部署 ELSER - Elastic Learned Sparse EncoderR"，我描述了如何安装 ELSER 模型。在今天的文章中，我来讲讲如何在隔离的环境中安装 ELSER 模型。如果你在有网路的情况下，最容易安装 ELSER 的方法是是使用 inference API。我们可以通过如下的方式来进行。为了测试的方便，我们可以使用如下的方法来删除已经安装好的 ELSER 模型：

复制代码

DELETE /_ml/trained_models/.elser_model_2?force=true

这样，我们确保在我们的安装中没有 ELSER 的安装：

我们接下来打入如下的命令来进行安装：

复制代码

PUT _inference/sparse_embedding/my_test_elser_inf_id
{
  "service": "elasticsearch",
  "service_settings": {
    "model_id": ".elser_model_2",
    "num_allocations": 1,
    "num_threads": 1
  }
}

等过一会儿，我们再查看 Trained Modesl 页面：

我们可以看到已经成功部署的 .elser_model_2 模型。

在网路隔离的环境中安装 ELSER

如果你想在受限或封闭网络中部署 ELSER ，你有两个选项：

创建你自己的 HTTP / HTTPS 端点并将模型文件放在上面，
把模型文件放到所有具备 master 资格节点的 config 目录里的某个子目录中。

我们首先按照之前的方法来卸载已经安装好的 ELSER 模型：

复制代码

DELETE /_ml/trained_models/.elser_model_2?force=true

模型工件文件

对于跨平台版本，你的系统里需要以下文件：

复制代码

https://ml-models.elastic.co/elser_model_2.metadata.json
https://ml-models.elastic.co/elser_model_2.pt
https://ml-models.elastic.co/elser_model_2.vocab.json

对于优化版本，你的系统里需要以下文件：

复制代码

https://ml-models.elastic.co/elser_model_2_linux-x86_64.metadata.json
https://ml-models.elastic.co/elser_model_2_linux-x86_64.pt
https://ml-models.elastic.co/elser_model_2_linux-x86_64.vocab.json

$ pwd
/Users/liuxg/elastic/elasticsearch-9.2.1/config/models
$ wget https://ml-models.elastic.co/elser_model_2.metadata.json
--2025-12-02 13:52:20--  https://ml-models.elastic.co/elser_model_2.metadata.json
Resolving ml-models.elastic.co (ml-models.elastic.co)... 34.120.127.120
Connecting to ml-models.elastic.co (ml-models.elastic.co)|34.120.127.120|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 621 [application/json]
Saving to: 'elser_model_2.metadata.json'

elser_model_2.metadata.json   100%[===============================================>]     621  --.-KB/s    in 0s      

2025-12-02 13:52:21 (37.0 MB/s) - 'elser_model_2.metadata.json' saved [621/621]

$ wget https://ml-models.elastic.co/elser_model_2.pt
--2025-12-02 13:52:27--  https://ml-models.elastic.co/elser_model_2.pt
Resolving ml-models.elastic.co (ml-models.elastic.co)... 34.120.127.120
Connecting to ml-models.elastic.co (ml-models.elastic.co)|34.120.127.120|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 438123914 (418M) [application/octet-stream]
Saving to: 'elser_model_2.pt'

elser_model_2.pt              100%[===============================================>] 417.83M  19.5MB/s    in 24s     

2025-12-02 13:52:53 (17.1 MB/s) - 'elser_model_2.pt' saved [438123914/438123914]

$ wget https://ml-models.elastic.co/elser_model_2.vocab.json
--2025-12-02 13:53:12--  https://ml-models.elastic.co/elser_model_2.vocab.json
Resolving ml-models.elastic.co (ml-models.elastic.co)... 34.120.127.120
Connecting to ml-models.elastic.co (ml-models.elastic.co)|34.120.127.120|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 329405 (322K) [application/json]
Saving to: 'elser_model_2.vocab.json'

elser_model_2.vocab.json      100%[===============================================>] 321.68K   433KB/s    in 0.7s    

2025-12-02 13:53:13 (433 KB/s) - 'elser_model_2.vocab.json' saved [329405/329405]
$ pwd
/Users/liuxg/elastic/elasticsearch-9.2.1/config/models
$ ls
elser_model_2.metadata.json elser_model_2.pt            elser_model_2.vocab.json

使用 HTTP 服务器

INFO：如果你使用现有的 HTTP 服务器，要注意模型下载器只支持无密码的 HTTP 服务器。

你可以使用任意 HTTP 服务来部署 ELSER 。这个示例使用官方的 Nginx Docker 镜像来搭建一个新的 HTTP 下载服务。

1）下载模型工件文件。如上所示，下载上面的三个文件，并把他们放入到 config 目录下的 models 子目录下。

2）把文件放到你选择的某个子目录里。

3）运行以下命令：

复制代码

export ELASTIC_ML_MODELS="/path/to/models"
docker run --rm -d -p 8080:80 --name ml-models -v ${ELASTIC_ML_MODELS}:/usr/share/nginx/html nginx

针对我的情况：

复制代码

export ELASTIC_ML_MODELS="/Users/liuxg/elastic/elasticsearch-9.2.1/config/models"
docker run --rm -d -p 8080:80 --name ml-models -v ${ELASTIC_ML_MODELS}:/usr/share/nginx/html nginx

$ export ELASTIC_ML_MODELS="/Users/liuxg/elastic/elasticsearch-9.2.1/config/models"
$ docker run --rm -d -p 8080:80 --name ml-models -v ${ELASTIC_ML_MODELS}:/usr/share/nginx/html nginx
Unable to find image 'nginx:latest' locally
latest: Pulling from library/nginx
b89cf3ec7a3e: Pull complete 
2254fb813b11: Pull complete 
40b6fc5618c6: Pull complete 
bb8ecb62799c: Pull complete 
cc57e8335c98: Pull complete 
cf9a807fe41d: Pull complete 
88770be1d442: Pull complete 
Digest: sha256:553f64aecdc31b5bf944521731cd70e35da4faed96b2b7548a3d8e2598c52a42
Status: Downloaded newer image for nginx:latest
9697b5bef2ffd721babcef106e723d2ffe3990235276ff29ce27325210b75afc

别忘了把 /path/to/models 改成模型工件文件所在子目录的路径。

这些命令会启动一个带有 Nginx 服务器的本地 Docker 镜像，并把包含模型文件的子目录挂载进去。因为需要下载和构建 Docker 镜像，第一次启动可能会花更长时间，之后的运行会更快。

4）通过在浏览器中访问下面这个 URL 来验证 Nginx 是否正常运行：

复制代码

http://{IP_ADDRESS_OR_HOSTNAME}:8080/elser_model_2.metadata.json

ifconfig | grep inet

$ ifconfig | grep inet
	inet 127.0.0.1 netmask 0xff000000
	inet6 ::1 prefixlen 128 
	inet6 fe80::1%lo0 prefixlen 64 scopeid 0x1 
	inet6 fe80::c24:187e:e0e5:7cb6%en0 prefixlen 64 secured scopeid 0xe 
	inet 192.168.101.209 netmask 0xffffff00 broadcast 192.168.101.255
	inet6 2408:8207:2495:24c1:e5:a50c:16e5:6aed prefixlen 64 autoconf secured 
	inet6 2408:8207:2495:24c1:d568:879a:8d00:583b prefixlen 64 autoconf temporary 
	inet6 2408:8207:2495:24c1:1451:2091:5ea6:3 prefixlen 64 dynamic 
	inet6 fe80::74cb:fcff:fee0:5914%awdl0 prefixlen 64 scopeid 0x10 
	inet6 fe80::74cb:fcff:fee0:5914%llw0 prefixlen 64 scopeid 0x11 
	inet6 fe80::893f:7412:e4ba:cb1e%utun0 prefixlen 64 scopeid 0x12 
	inet6 fe80::4192:8070:e906:4697%utun1 prefixlen 64 scopeid 0x13 
	inet6 fe80::2a44:3b1c:bca:64bc%utun2 prefixlen 64 scopeid 0x14 
	inet6 fe80::ce81:b1c:bd2c:69e%utun3 prefixlen 64 scopeid 0x15 
	inet 198.18.192.51 --> 198.18.192.51 netmask 0xfffff800
	inet 10.211.55.2 netmask 0xffffff00 broadcast 10.211.55.255
	inet6 fe80::80a9:97ff:fe43:7964%bridge100 prefixlen 64 scopeid 0x17 
	inet6 fdb2:2c26:f4e4::1 prefixlen 64 
	inet 10.37.129.2 netmask 0xffffff00 broadcast 10.37.129.255
	inet6 fe80::80a9:97ff:fe43:7965%bridge101 prefixlen 64 scopeid 0x19 
	inet6 fdb2:2c26:f4e4:1::1 prefixlen 64

如果 Nginx 运行正常，你会看到模型的 metadata 文件内容。

5）在 config/elasticsearch.yml 文件中加入下面这一行，把你的 Elasticsearch 部署指向 HTTP 服务器上的模型工件：

复制代码

xpack.ml.model_repository: http://{IP_ADDRESS_OR_HOSTNAME}:8080

如果你使用你自己的 HTTP 或 HTTPS 服务器，请相应地修改地址。要确保写明协议（"http://" 或 "https://"）。确保所有具备 master 资格的节点都能访问你指定的服务器。

6）在所有具备 master 资格的节点上重复步骤 5。

7）逐个重启这些 master 资格节点。

8）在 Kibana 主菜单中进入 Trained Models 页面，或者使用全局搜索。你会在训练模型列表中看到 ELSER。

9）点击 Add trained model 按钮，选择你在步骤 1 下载并想部署的 ELSER 模型版本，然后点击 Download。所选模型会从你配置的 HTTP/HTTPS 服务器下载。

10）下载完成后，点击 Start deployment 按钮来启动部署。

11）填写一个 deployment ID，选择优先级，并设置 allocations 数量和每个 allocation 的线程数。

12）点击 Start。

HTTP 服务器只在下载模型时需要。下载完成后，你可以停止并删除这个服务。

在本示例中，你可以运行下面的命令来停止使用的 Docker 镜像：

复制代码

docker stop ml-models

$ docker stop ml-models
ml-models
$ docker ps
CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    PORTS     NAMES

使用基于文件的访问

要使用基于文件的访问，请按以下步骤操作：

1）下载模型工件文件。我们可以按照上面的步骤来进行。

2）把这些文件放到 Elasticsearch 部署的 config 目录里的 models 子目录中。

复制代码

$ pwd
/Users/liuxg/elastic/elasticsearch-9.2.1/config/models
$ ls
elser_model_2.metadata.json elser_model_2.pt            elser_model_2.vocab.json

3）在 config/elasticsearch.yml 文件中加入下面这一行，把你的 Elasticsearch 部署指向这个模型目录：

复制代码

xpack.ml.model_repository: file://${path.home}/config/models/

4）在所有具备 master 资格的节点上重复步骤 2 和步骤 3。

5）逐个重启这些 master 资格节点。

6）在 Kibana 主菜单中进入 Trained Models 页面，或者使用全局搜索。你会在训练模型列表中看到 ELSER。

7）点击 Add trained model 按钮，选择你在步骤 1 下载并想部署的 ELSER 模型版本，然后点击 Download。所选模型会从你在步骤 2 放置的模型目录中下载。

8）下载完成后，点击 Start deployment 按钮来启动部署。

9）填写一个 deployment ID，选择优先级，并设置 allocations 数量和每个 allocation 的线程数。

10）点击 Start。

测试 ELSER

你可以在 Kibana 中测试已部署的模型。进入主菜单的 Trained Models 页面，或者使用全局搜索，在训练模型列表中找到已部署的 ELSER 模型，然后在 Actions 菜单中选择 Test model。

你可以使用现有索引中的数据来测试模型。选择索引，然后选择要在其上测试 ELSER 的字段。输入搜索查询并点击 Test。使用与文档相关的查询可以更方便地评估模型的召回率。

结果会显示所选字段的十个随机值，以及每个文档与查询的相关性得分。得分越高，文档与查询的相关性越强。你可以点击 Reload examples 来重新加载示例文档。