在实际项目中，很多开发者会遇到以下痛点：

• 传统的关键词搜索往往只能匹配字面上的词汇。难以理解使用者的真实意图，导致搜索结果不相关。
• 部署 Elasticsearch 时需要处理云端与本地环境的差异，配置过程繁琐。
• 将向量化模型与 Elasticsearch 集成后如何高效地进行语义搜索还有混合搜索仍是难点。
• 查询返回的原始 JSON 响应难以阅读，调试和展示效果受限。

至于快速上手。使用交互式 Notebook 实现语义搜索

本交互式 Notebook 将演示如何使用官方 Elasticsearch Python 客户端、sentence-transformers 进行文本嵌入，并完成语义检索。你将学会把传统关键词搜索和语义搜索结合起来建立混合搜索程序。

本地部署 VS Elastic Cloud

如果你倾向于自行在机器上搭建 Elasticsearch，请参考《》并查看对应的代码仓库。

创建 Elastic Cloud 部署

没有 Elastic Cloud 部署？现在可以免费注册试用，登录后进入“创建部署”页面点击 Create deployment 并保持默认设置，即可获得可直接使用的云端实例。

安装常用软件包并导入模块

安装 Elasticsearch Python 客户端还有 Sentence Transformers：

pip install -qU "elasticsearch<" sentence-transformers==0.4.1

再看随后加载模型。

from sentence_transformers import SentenceTransformer
model = SentenceTransformer
# 更多模型信息请访问 Hugging Face

初始化 Elasticsearch 客户端

from elasticsearch import Elasticsearch
from getpass import getpass
ELASTIC_CLOUD_ID = getpass
ELASTIC_API_KEY = getpass
client = Elasticsearch(
cloud_id=ELASTIC_CLOUD_ID,api_key=ELASTIC_API_KEY,)

如果你使用本地或自托管实例，只需将 hosts= 替换上述参数即可。

开启遥测

运行以下代码以收集匿名使用统计信息：

curl -O -s https://raw.githubusercontent.com/elastic/elasticsearch-labs/main/telemetry/telemetry.py

from telemetry import enable_telemetry
client = enable_telemetry

测试客户端连通性

print)

若返回类似如下信息，则说明已成功连接：

{
再看"name"，"instance-...","cluster_name": "...","cluster_uuid": "...","version": {
"number": "...",...
},"tagline": "You Know,for Search"
}

至于准备测试数据，图书索引结构

我们将创建一个包含以下字段的索引：

• title
• authors
• publish_date
• num_reviews
• publisher
• title_vector用于语义检索）

删除旧索引

client.indices.delete
# 输出示例:
# ObjectApiResponse

创建新索引并定义映射

mappings = {
"properties": {
"title_vector": {
再看"type"，"dense_vector","dims": 384,# all-MiniLM-L6-v2 的向量维度
"index": True。"similarity": "cosine"
}
}
}
client.indices.create
# 输出:
# ObjectApiResponse

批量导入测试图书数据并生成向量

import json
from urllib.request import urlopen
url = "https://raw.githubusercontent.com/elastic/elasticsearch-labs/main/notebooks/search/data.json"
books = json.loads.read)
operations =
for book in books:
# 将标题转为向量并存入 title_vector 字段
book = model.encode.tolist
operations.append
operations.append
client.bulk
# 返回示例略...

美化响应函数

def pretty_response:
hits = response
if not hits:
print
return
for hit in hits:
src = hit
print
print}")
print}")
print}")
print}")
print}")
print}")
print
)

执行语义搜索这方面，KNN 查询示例

下面的代码演示如何对查询 “javascript books” 进行向量化，接下来在 title_vector**字段上执行最近邻检索：

index”,knn={
“field”: “titlevector”,“queryvector”: model.encode.tolist,“k”: 5,“numcandidates”: 100
}
)
pretty_response

再看典型输出示例，

• JavaScript：优良部分 得分：#...
• You Don’t Know JS：入门 得分：#...
• Mastering JavaScript 得分：#...

再看过滤条件，结合结构化过滤与向量相似度

KNN 查询本身只关注向量相似度。 若需要在此基础上加入结构化过滤，例如限定出版社、出版日期等。可通过 {“filter”:…} 子句实现，

关键词过滤示例

下面的查询检索与 “javascript books” 向量相似的图书，同时只返回出版社为 addison‑wesley 的记录。

response = client.search(
index =" bookindex ",knn ={
“field ” : “ title _ vector ”,“query _ vector ” : model.encode.tolist,“k ” :5,“numcandidates ” :100,“filter ” :{
“term ” :{
“publisher.keyword ” :“ addison‑wesley ”
}
}
}
)
pretty_response

结果示例的观点是。

• 标题 ：The Pragmatic Programmer：Your Journey to Mastery 出版社 ：addison‑wesley
• 标题 ：设计模式：可复用面向对象软件的基础 出版社 ：addison‑wesley

说到混合搜索，同时利用关键词和向量

实际业务中往往需要同时考虑关键字匹配和语义相似度。下面展示一个混合查询，将传统 match 查询与 KNN 相结合。实现更精准、更符合使用者意图的结果。

response = client.search(
index =" bookindex ",query ={
“bool ” :{
“must ” :,“should ” :,# 可选：结构化过滤。如 publisher.keyword
#“filter”:
}
}
)
pretty_response