当前位置：首页 > news >正文

Elasticsearch：如何部署文本嵌入模型并将其用于语义搜索

news 来源：原创 2025/7/23 23:10:13

你可以按照这些说明在 Elasticsearch 中部署文本嵌入模型，测试模型并将其添加到推理提取管道。它使你能够生成文本的向量表示并对生成的向量执行向量相似性搜索。示例中使用的模型在 HuggingFace上公开可用。

该示例使用来自 MS MARCO Passage Ranking Task 的公共数据集。它由来自 Microsoft Bing 搜索引擎的真实问题和人工生成的答案组成。该示例使用此数据集的样本，使用模型生成文本嵌入，然后对其运行向量搜索。

你可以使用 elasticsearch-labs repo 中的 Python 客户端以 Jupyter 笔记本的形式找到此示例。

注意：针对 8.15 及以后得版本，我们可以直接使用 semantic_text 字段来代替本文中的 dense_vector 字段。我们甚至直接使用 semantic query 来进行查询。有关细节，请详细阅读文章 “Elasticsearch：使用 semantic_text 进行语义搜索”。

要求

要按照本页上的流程操作，你必须具备：

已正确设置 Elasticsearch Cloud 集群以使用机器学习功能。请参阅设置和安全。你也可以参阅文章 “如何在 Linux，MacOS 及 Windows 上进行安装 Elasticsearch” 在本地创建自己的 Elasticsearch 集群。
已激活适当的订阅级别或免费试用期。如果激活免费使用，请参阅文章 “Elasticsearch：如何部署 NLP：文本嵌入和向量搜索”。
已安装 Docker。

部署文本嵌入模型

你可以使用 Eland 客户端安装自然语言处理模型。使用预构建的 Docker 映像运行 Eland 安装模型命令。使用以下命令获取最新映像：

docker pull docker.elastic.co/eland/eland

拉取完成后，你的 Eland Docker 客户端即可使用。

从第三方模型参考列表中选择一个文本嵌入模型。此示例使用 msmarco-MiniLM-L-12-v3 句子转换器模型。

通过在 Docker 映像中运行 eland_import_model_hub 命令来安装模型：

docker run -it --rm docker.elastic.co/eland/eland \eland_import_hub_model \--cloud-id $CLOUD_ID \-u <username> -p <password> \--hub-model-id sentence-transformers/msmarco-MiniLM-L-12-v3 \--task-type text_embedding \--start

你需要提供管理员用户名和密码，并将 $CLOUD_ID 替换为你的云部署的 ID。此云 ID 可以从你的云网站上的部署页面复制。

由于在 Eland 导入命令末尾使用了 --start 选项，Elasticsearch 会部署随时可用的模型。如果你有多个模型并想选择要部署的模型，你可以使用 Kibana 中的 Machine Learning > Model Management 用户界面来管理模型的启动和停止。

转到 Machine Learning > Trained Models 页面并同步你的训练模型。页面顶部会显示一条警告消息，提示 “ML job and trained model synchronization required”。按照链接 “ynchronize your jobs and trained models.”。然后单击同步。你也可以等待每小时发生的自动同步，或使用 sync machine learning objects API。

注意：如果你是在本地部署自己的 Elasticsearch，你可以参考文章 “Elasticsearch：如何部署 NLP：文本嵌入和向量搜索” 来上传模型。

测试文本嵌入模型

可以在 Kibana 中的 “Machine Learning > Trained Models” 下选择相应模型的 “Test model ” 操作来评估已部署的模型。

使用 _infer API 测试模型

你还可以使用 _infer API 评估模型。在以下请求中，text_field 是模型期望找到输入的字段名称，如模型配置中定义的那样。默认情况下，如果模型是通过 Eland 上传的，则输入字段为 text_field。

POST /_ml/trained_models/sentence-transformers__msmarco-minilm-l-12-v3/_infer
{"docs": {"text_field": "How is the weather in Jamaica?"}
}

API 返回类似以下内容的响应：

{"inference_results": [{"predicted_value": [0.39521875977516174,-0.3263707458972931,0.26809820532798767,0.30127981305122375,0.502890408039093,...]}]
}

结果是从示例文本转换而来的预测密集向量。

加载数据

在此步骤中，你将加载稍后在提取管道中用于获取嵌入的数据。

数据集 msmarco-passagetest2019-top1000 是 MS MARCO Passage Ranking 数据集的子集，该数据集用于 2019 TREC 深度学习轨道的测试阶段。它包含 200 个查询，每个查询都有一个由简单信息检索 (IR) 系统提取的相关文本段落列表。从该数据集中，提取了所有具有其 ID 的唯一段落并将其放入 tsv 文件中，共计 182469 个段落。在下文中，此文件用作示例数据集。

使用数据可视化工具上传文件。将第一列命名为 id，将第二列命名为 text。索引名称为 collection。上传完成后，你可以看到一个名为 collection 的索引，其中包含 182469 个文档。

提示：如果你想要了解详细的步骤来装载数据，请详细阅读文章 “Elasticsearch：使用 ELSER 进行语义搜索 - sparse_vector” 中的相关章节。

将文本嵌入模型添加到推理摄取管道

使用 inference processor 处理初始数据。它为每个段落添加一个嵌入。为此，创建一个文本嵌入摄取管道，然后使用此管道重新索引初始数据。

现在在 Stack Management UI 中或使用 API 创建摄取管道：

PUT _ingest/pipeline/text-embeddings
{"description": "Text embedding pipeline","processors": [{"inference": {"model_id": "sentence-transformers__msmarco-minilm-l-12-v3","target_field": "text_embedding","field_map": {"text": "text_field"}}}],"on_failure": [{"set": {"description": "Index document to 'failed-<index>'","field": "_index","value": "failed-{{{_index}}}"}},{"set": {"description": "Set error message","field": "ingest.failure","value": "{{_ingest.on_failure_message}}"}}]
}

段落位于名为 text 的字段中。field_map 将 text 映射到模型所需的字段 text_field。on_failure 处理程序设置为将失败索引到不同的索引中。

在通过管道提取数据之前，请创建目标索引的映射，特别是针对提取处理器存储嵌入的字段 text_embedding.predicted_value。dense_vector 字段必须配置为与模型生成的文本嵌入相同的维度 (dims)。该值可以在模型配置中的 embedding_size 选项中找到，位于 Kibana 中的 “ Trained Models” 页面下或 “Get trained models API” API 调用的响应主体中。msmarco-MiniLM-L-12-v3 模型的 embedding_size 为 384，因此 dims 设置为 384。

PUT collection-with-embeddings
{"mappings": {"properties": {"text_embedding.predicted_value": {"type": "dense_vector","dims": 384},"text": {"type": "text"}}}
}

通过推理管道将数据重新索引到带嵌入的集合索引中，从而创建文本嵌入。推理摄取处理器将嵌入向量插入到每个文档中。

POST _reindex?wait_for_completion=false
{"source": {"index": "collection","size": 50  /* 1 */},"dest": {"index": "collection-with-embeddings","pipeline": "text-embeddings"}
}

重新索引的默认批次大小为 1000。将大小减小到较小的数字可以加快重新索引过程的更新速度，从而使你能够密切跟踪进度并尽早发现错误。

API 调用返回一个任务 ID，可用于监控进度：

GET _tasks/<task_id>

你还可以打开模型统计 UI 来跟踪进度。

重新索引完成后，新索引中的文档包含推理结果 - 向量嵌入。

语义搜索 - semantic search

使用向量嵌入丰富数据集后，你可以使用语义搜索查询数据。将 query_vector_builder 传递给 k-最近邻 (kNN) 向量搜索 API，并提供查询文本和你用于创建向量嵌入的模型。此示例搜索 “How is the weather in Jamaica?”：

GET collection-with-embeddings/_search
{"knn": {"field": "text_embedding.predicted_value","query_vector_builder": {"text_embedding": {"model_id": "sentence-transformers__msmarco-minilm-l-12-v3","model_text": "How is the weather in Jamaica?"}},"k": 10,"num_candidates": 100},"_source": ["id","text"]
}

结果，你将从 collection-with-embedings 索引中收到与查询含义最接近的前 10 个文档，这些文档按与查询的接近程度排序：

"hits" : [{"_index" : "collection-with-embeddings","_id" : "47TPtn8BjSkJO8zzKq_o","_score" : 0.94591534,"_source" : {"id" : 434125,"text" : "The climate in Jamaica is tropical and humid with warm to hot temperatures all year round. The average temperature in Jamaica is between 80 and 90 degrees Fahrenheit. Jamaican nights are considerably cooler than the days, and the mountain areas are cooler than the lower land throughout the year. Continue Reading."}},{"_index" : "collection-with-embeddings","_id" : "3LTPtn8BjSkJO8zzKJO1","_score" : 0.94536424,"_source" : {"id" : 4498474,"text" : "The climate in Jamaica is tropical and humid with warm to hot temperatures all year round. The average temperature in Jamaica is between 80 and 90 degrees Fahrenheit. Jamaican nights are considerably cooler than the days, and the mountain areas are cooler than the lower land throughout the year"}},{"_index" : "collection-with-embeddings","_id" : "KrXPtn8BjSkJO8zzPbDW","_score" :  0.9432083,"_source" : {"id" : 190804,"text" : "Quick Answer. The climate in Jamaica is tropical and humid with warm to hot temperatures all year round. The average temperature in Jamaica is between 80 and 90 degrees Fahrenheit. Jamaican nights are considerably cooler than the days, and the mountain areas are cooler than the lower land throughout the year. Continue Reading"}},(...)
]

如果你想快速验证结果，请按照本博文快速验证部分的步骤进行。

要求