这篇文章是继之前文章 “Elasticsearch：搜索教程 - 全文搜索”。在继续本篇之前，请先阅读前文，以便更好地理解下面的示例代码与概念。

Embedding 简介 —— 为什么你会卡在向量表示上？

痛点 1：传统关键词搜索只能匹配文字本身。无法捕捉“相似”或“相关”概念，导致使用者常常找不到语义上匹配的结果。

在机器学习中。embedding 是一个由数字组成的向量，用来表示现实世界中的对象。如果两个实体在真实世界里相似，它们对应的向量也会在向量空间里彼此接近。于是可以向量之间的距离来实现语义相似搜索，而不必局限于精确的关键字匹配。

本教程将展示如何：

• 使用免费且易用的机器学习模型生成文本 embeddings；
• 把这些向量存入 Elasticsearch 并利用其向量检索能力；
• 将向量搜索与全文搜索结合，建立兼顾两者优势的混合检索方案。

生成 Embedding —— 从模型挑选到代码实现。你可能遇到的难点

安装 SentenceTransformers

痛点 2：许多开发者对 Python 环境管理和依赖安装感到困惑，特别是涉及深度学习库时。

SentenceTransformers 以 Python 包形式提供。只需在激活的 virtual environment 中执行：

pip install sentence-transformers
# 同步更新 requirements
pip freeze> requirements.txt

选择合适的模型 —— 质量 vs. 性能抉择

痛点 3：市面上模型众多，不知道该选哪个；是要兼顾向量维度、推理速度和精度。

官方提供了丰富的预训练模型列表，HuggingFace 上带有 sentence-transformers 标签的模型均可直接使用。对于大多数业务场景，推荐使用 all-MiniLM-L6-v2

• 质量：在所有公开模型中表现稳健；
• 速度：比更大的 all-mpnet-base-v2 快约 5 倍；
• 维度：384

加载模型并生成 Embedding —— 常见错误提示与调试技巧

from sentence_transformers import SentenceTransformer
# 第一次会自动下载模型，请耐心等待
model = SentenceTransformer

痛点 4：If you forget to install package or run script inside wrong environment。you'll see an ImportError.

# 生成单条文本的 embedding
text = "The quick brown fox jumps over lazy dog"
embedding = model.encode # 返回长度为 384 的 list/ndarray
print) # => 384

在 Elasticsearch 中存储 Embeddings —— 映射、字段类型与容量考量

从显式映射来看，为什么自动映射不够？

痛点 5：E​lasticsearch 能自动推断大多数字段类型。但对向量字段却只能提供默认行为，若不手动指定会导致查询报错或性能低下。

dense_vector 字段定义示例

class Search:
def create_index:
self.es.indices.delete
self.es.indices.create(
index='my_documents',mappings={
'properties': {
'embedding': {
再看'type'。'dense_vector',# dims 可省略，由首条文档自动确定
# index 默认为 true，可显式声明
# similarity 支持 cosine或 dot_product
}
}
}
)

Dense Vector 参数解读

• dims: 向量维度，首次写入时自动创建；
• index: 是否建立倒排索引用于 kNN 检索，默认 true；
• s​imilarity: 选择距离函数，'cosine' 或 'dot_product'。说起来，

把 Embedding 写入文档——一次性完成两件事！

痛点 6：E​lasticsearch 插入文档时忘记同步生成向量，会导致查询返回空或异常。

class Search:
def __init__:
from sentence_transformers import SentenceTransformer
self.model = SentenceTransformer
self.es = Elasticsearch(
cloud_id=os.getenv,api_key=os.getenv
)
def get_embedding:
return self.model.encode.tolist
def insert_document:
return self.es.index(
index='my_documents',document={**document,'embedding': self.get_embedding}
)
def insert_documents:
ops =
for doc in documents:
ops.append
ops.append({**doc。'embedding': self.get_embedding})
return self.es.bulk

# 重建索引并重新写入数据:

flask run # 首次启动会下载模型
flask reindex # 删除旧索引 → 创建新映射 → 批量写入 embedding

K 最近邻搜索 —— 从参数调优到实际业务需求落地

KNN 查询结构及常见配置项

KNN 痛点 7：KNN 查询需要同时调节 K、num_candidates、similarity 等参数，否则要么召回不足，要么响应慢。

results = es.search(
knn={
'field': 'embedding','query_vector': es.get_embedding,'k': 10,# 返回前10条最相近结果
'num_candidates': 1000 # 每个分片候选集大小。可根据硬件调高/调低
},size=10,from_=0
)

KNN 与过滤器结合使用

KNN 痛点 8：KNN 本身不支持传统过滤，需要手动把 filter 条件嵌入 knn 查询中，否则分类筛选失效。不过，

filters,parsed_query = extract_filters
results = es.search(
knn={
'field': 'embedding','query_vector': es.get_embedding,'k': 10,'num_candidates': 1000。**filters # 将 category:xxx 等过滤直接注入 knn 部分
},size=10,from_=0,aggs={...} # 聚合仍然可以保留
)

Pain Point 汇总：单一搜索方式难以满足全部需求

• KNN 优势： 能够捕捉语义相似，即使关键词不存在也能命中相关文档；但缺乏精准过滤和高亮显示能力。
• CROSS‑TEXT 优势： 支持布尔逻辑、高亮、分词等高级特性，却对同义词、概念层面的匹配力不足。
• Pain Point 9： 业务实际往往需要两者兼容——既要语义召回。又要精准过滤，这就需要混合搜索方案。

MIXED / Hybrid 搜索：结合全文检索 & KNN 的常用方法

The Reciprocal Rank Fusion —— 把两个排名列表“融合”成一个

D​efault RRF 在没有任何调参情况下已经能提供不错效果，但仍可通过以下参数微调： - 'rank_constant': 融合时每个位置加权系数 - 'window_size': 考虑多少条结果进行融合等。

Merged Search 示例代码

@app.post
def handle_search:
query = request.form.get
filters,parsed_query = extract_filters
from_ = request.form.get
# ---- Full‑text 部分 ----
if parsed_query:
ft_query = {
再看"must"，{
"multi_match": {
"query": parsed_query,"fields":
}
}
}
说到else，ft_query = {"must": {"match_all": {}}}
results = es.search(
query={"bool": {**ft_query,**filters}},knn={
"field": "embedding","query_vector": es.get_embedding,"k": 20,"num_candidates": 1000,**filters
},rank={"rrf": {}},# <-- RRF 融合入口
        aggs={                  # 保持原有聚合功能不变
            "category-agg": {"terms": {"field": "category.keyword"}},
            "year-agg": {
                "date_histogram": {
                    "field": "updated_at",
                    "calendar_interval": "year",
                    "format": "yyyy"
                }
            },
        },
        size=20,
        from_=from_
    )
    aggs = {
      "Category":
          {b: b for b in results},
      "Year":
          {b: b
           for b in results
           if b> 0}
}
return render_template(
"index.html",results=results,query=query,from_=from_,total=results。aggs=aggs)

This implementation now returns a single ranked list that benefits from both semantic similarity and exact keyword relevance . The UI can stay unchanged – users simply type ir query and receive richer results.

Pain Point 10：部署与安全注意事项

• If you run Elasticsearch on a self‑signed TLS cluster,ensure your Python client trusts certificate .
• The model download may be throttled by HuggingFace without an access token – set $HF_TOKEN.
• The dense_vector field consumes storage proportional to . For large corpora consider using,or external vector DBs.

---

Synsizing all steps above gives you a production‑ready pipeline:

1. Create an index with a dense_vector field;
.
2. Select and load a SentenceTransformers model;
.
3. Add embeddings to each document during ingestion;
.
4. Tune kNN parameters;Use filters when needed;
.
5. If business needs demand both semantic recall and precise filtering → enable RRF hybrid search.
.
6. Troubleshoot common pitfalls .
. \end{enumerate}

If you are using a self‑signed Elasticsearch cluster or want to explore complete source code。refer to repository:

---

---