Elasticsearch 8.x 中 KNN 搜索的正确用法详解

本文详解 elasticsearch 8.x（如 8.12）在 python 中执行 knn 搜索时常见的 `parsing_exception: unknown key for a start_array in [knn]` 错误原因与修复方案，涵盖原生 `elasticsearch-py` 和高级封装库 `elasticsearch-dsl-py` 的两种规范写法。

在 Elasticsearch 8.x 中，KNN（k-nearest neighbors）搜索是原生支持的核心功能，但其查询结构有严格要求：knn 必须作为顶层查询字段直接置于请求 body 中，且不能与其他顶级查询字段（如 query、fields、aggs 等）并列存在。你遇到的 parsing_exception: Unknown key for a START_ARRAY in [knn] 错误，根本原因正是将 "fields" 字段与 "knn" 同级放置——这会导致 Elasticsearch 解析器误判 knn 的上下文结构（例如将其当作数组或嵌套对象的一部分），从而抛出语法异常。

✅ 正确做法（使用 elasticsearch-py 官方客户端）：
knn 必须是 request body 的唯一顶层键（或与 size、_source 等非查询类参数共存），禁止混用 fields、query 等其他顶层查询字段。若需返回特定字段，请改用 _source 过滤：

绘蛙-多图成片

绘蛙新推出的AI图生视频工具

from elasticsearch import Elasticsearch

client = Elasticsearch("http://localhost:9200")

body = {
    "knn": {
        "field": "image-vector",
        "query_vector": [-5.0, 9.0, -12.0],  # 注意：浮点数更稳妥（ES 要求 numeric 类型）
        "k": 10,
        "num_candidates": 100
    },
    "_source": ["title", "file-type"]  # ✅ 替代已移除的 'fields' 参数
}

response = client.search(index="db-test", body=body)

⚠️ 注意事项：

• query_vector 中的数值必须为 float（如 -5.0），整数可能触发类型不匹配；
• num_candidates 建议 ≥ k * 10（官方推荐），确保近似搜索精度；
• fields 参数在 ES 8.x 的 KNN 查询中已被弃用，强行使用会直接报错；

✅ 进阶方案（使用 elasticsearch-dsl-py >= 8.12）：
该库提供了面向对象的 Search.knn() 方法，自动处理语法合规性，大幅提升可读性与可维护性：

from elasticsearch_dsl import Search, connections

connections.create_connection(hosts=["http://localhost:9200"])

s = Search(index="db-test")
s = s.knn(
    field="image-vector",
    query_vector=[-5.0, 9.0, -12.0],
    k=10,
    num_candidates=100
)
s = s.source(["title", "file-type"])  # 等效于 _source

response = s.execute()

? 总结：
该错误本质是 Elasticsearch 8.x 对 KNN 查询 DSL 的强约束所致，而非客户端版本兼容问题（因此降级至 8.7/8.10 无效）。关键原则是——KNN 查询必须“独占”查询体结构，所有辅助参数（如字段过滤、排序、高亮）需通过 _source、sort、highlight 等独立顶层键声明，绝不可与 knn 并列于同一层级。遵循此规范，即可稳定运行向量相似性搜索。