在 Elasticsearch 8.x 版本中，KNN 搜索已经成为向量检索的主流方案，Python 客户端通过官方 elasticsearch 库可以直接构造 knn 查询。不少人在迁移旧版向量检索逻辑时，仍然沿用 script_score 加 cosineSimilarity 的写法，结果不仅性能差，还容易因为字段类型不匹配而查不到数据。正确使用 KNN 搜索，需要从索引结构、数据写入和查询参数三个层面理解其工作机制。
一、索引映射与向量字段配置
KNN 搜索要求目标字段必须是 dense_vector 类型，并且在映射中声明维度与相似度算法。如果只在写入时传入列表，而没有在映射里定义类型，Elasticsearch 会拒绝创建索引或将该字段当作普通数组处理，导致后续 knn 查询报错或无效。
下面的示例创建了一个支持 KNN 的索引，向量维度为 3，使用 cosine 相似度。注意 index_options 里的 type 必须为 hnsw，这是 Elasticsearch 提供的近似最近邻索引结构。若使用 euclidean 或 dot_product，需保证数据已做相应归一化。
{
"mappings": {
"properties": {
"title": {
"type": "text"
},
"embedding": {
"type": "dense_vector",
"dims": 3,
"index": true,
"similarity": "cosine",
"index_options": {
"type": "hnsw",
"m": 16,
"ef_construction": 100
}
}
}
}
}
创建索引的 Python 代码应当先检查索引是否存在，避免重复创建引发异常。使用 client.indices.create 时，直接将上面的映射字典传入 mappings 参数即可。如果业务需要同时支持过滤和向量检索，可以将其他字段正常定义为 keyword 或 text。
二、使用 Python 客户端写入向量数据
写入文档时，embedding 字段应是一个普通的 Python 列表或 NumPy 数组转换后的列表。Elasticsearch 客户端会自动序列化为 JSON，不需要手动处理维度信息，因为映射已经固定了 dims。
以下代码演示了批量写入三条带向量的记录。这里用 helpers.bulk 提升写入效率，比单条 index 更合适于初始化场景。注意向量值应在 -1 到 1 之间以适配 cosine 计算，否则相似度结果会出现偏差。
from elasticsearch import Elasticsearch, helpers
client = Elasticsearch("https://127.0.0.1:9200", basic_auth=("user", "pass"))
docs = [
{"_index": "articles", "_source": {"title": "苹果", "embedding": [0.1, 0.2, 0.3]}},
{"_index": "articles", "_source": {"title": "香蕉", "embedding": [0.4, 0.5, 0.6]}},
{"_index": "articles", "_source": {"title": "猫", "embedding": [0.7, 0.8, 0.9]}},
]
helpers.bulk(client, docs)
写入完成后，可以通过 count API 确认文档数，并用 search 不带 knn 参数做简单匹配，验证 embedding 字段已正确存储。这一步排查能避免后续查询为空时无法定位是写入还是查询的问题。
三、构造正确的 KNN 查询
Elasticsearch Python 客户端从 8.0 起支持在 search 方法中直接传 knn 参数。该参数是一个字典，包含 field、query_vector、k 与 num_candidates。其中 k 是最终返回的近邻数量，num_candidates 是每张分片候选集大小，通常设为 k 的倍数以保证召回质量。
常见错误是把 num_candidates 设得过小，导致分布式下候选不足，或误将 query_vector 写成字符串。下面给出标准查询写法，并附带一个过滤条件，展示如何结合 filter 做混合检索。
resp = client.search(
index="articles",
knn={
"field": "embedding",
"query_vector": [0.15, 0.25, 0.35],
"k": 2,
"num_candidates": 10,
"filter": {
"term": {"title": "苹果"}
}
}
)
for hit in resp["hits"]["hits"]:
print(hit["_score"], hit["_source"]["title"])
如果需要在多个向量字段上检索，可以传 knn 列表而非单个字典，但需注意每个字段的相似度配置独立。查询返回的分数由相似度函数决定，cosine 下分数越接近 1 越相似，而 euclidean 则分数越低越好，客户端不会自动翻转，需要业务层处理。
四、与旧版 script_score 写法对比
在 KNN 原生支持之前，开发者常用 script_score 调用 cosineSimilarity 函数实现向量排序。这种方式每次查询都要遍历所有文档算分，无法利用 HNSW 图索引，数据量上万后延迟急剧上升。
下表列出两者核心差异，帮助判断何时该迁移到 knn 参数。
| 对比项 | knn 参数 | script_score |
|---|---|---|
| 索引结构 | 依赖 hnsw 图 | 无需特殊索引 |
| 查询性能 | 近似检索，毫秒级 | 暴力计算，随数据线性退化 |
| 语法复杂度 | 声明式参数 | 需写 Painless 脚本 |
因此，只要集群版本在 8.x 且字段已映射为 dense_vector，就应优先采用 knn 参数。对于必须做精确距离且数据量极小的场景，script_score 仍可作为补充，但不应作为主检索路径。
五、调试技巧与常见误区
当 KNN 搜索返回空列表时，先确认字段名拼写与映射一致，再检查 query_vector 维度是否等于 dims。另外一个隐蔽问题是索引创建时 index 设为 false，这会导致 knn 直接报错 field not indexed。
建议在开发期打开客户端的 log 配置，把请求体打印出来核对。也可以用 client.indices.get_mapping 回看线上索引实际结构，避免本地代码与集群不一致。只要遵循映射正确、写入规范、knn 参数完整的链路，Python 客户端中的 KNN 搜索就能稳定服务于语义检索与推荐系统。
ElasticsearchPython_clientk_nearest_neighbors修改时间：2026-08-04 04:42:34