« 时间点 API 检索器 »
Elastic 文档 ›Elasticsearch 指南 [8.16] ›REST APIs ›搜索 APIs

kNN 搜索 API

编辑

kNN 搜索 API

编辑

在 8.4.0 版本中已弃用。

kNN 搜索 API 已被搜索 API 中的 knn 选项 替代。

执行 k 近邻 (kNN) 搜索并返回匹配的文档。

resp = client.knn_search(
    index="my-index",
    knn={
        "field": "image_vector",
        "query_vector": [
            0.3,
            0.1,
            1.2
        ],
        "k": 10,
        "num_candidates": 100
    },
    source=[
        "name",
        "file_type"
    ],
)
print(resp)
const response = await client.knnSearch({
  index: "my-index",
  knn: {
    field: "image_vector",
    query_vector: [0.3, 0.1, 1.2],
    k: 10,
    num_candidates: 100,
  },
  _source: ["name", "file_type"],
});
console.log(response);
GET my-index/_knn_search
{
  "knn": {
    "field": "image_vector",
    "query_vector": [0.3, 0.1, 1.2],
    "k": 10,
    "num_candidates": 100
  },
  "_source": ["name", "file_type"]
}

请求

编辑

GET <target>/_knn_search

POST <target>/_knn_search

先决条件

编辑
  • 如果启用了 Elasticsearch 安全功能，则必须对目标数据流、索引或别名具有 read 索引权限。

描述

编辑

kNN 搜索 API 对 dense_vector 字段执行 k 近邻 (kNN) 搜索。给定一个查询向量，它会找到 _k_ 个最接近的向量，并将这些文档作为搜索结果返回。

Elasticsearch 使用 HNSW 算法 来支持高效的 kNN 搜索。与大多数 kNN 算法一样，HNSW 是一种近似方法，它牺牲了结果精度以提高搜索速度。这意味着返回的结果并非总是真正的 _k_ 个最近邻。

kNN 搜索 API 支持使用过滤器限制搜索。搜索将返回也匹配过滤器查询的顶级 k 个文档。

路径参数

编辑
<target>
(可选，字符串) 要搜索的数据流、索引和别名的逗号分隔列表。支持通配符 (*)。要搜索所有数据流和索引，请使用 * 或 _all。

查询参数

编辑
routing
(可选，字符串) 用于将操作路由到特定分片的自定义值。

请求体

编辑
filter
(可选，查询 DSL 对象) 用于过滤可以匹配的文档的查询。kNN 搜索将返回也匹配此过滤器的顶级 k 个文档。该值可以是单个查询或查询列表。如果未提供 filter，则允许所有文档匹配。
knn

(必需，对象) 定义要运行的 kNN 查询。

knn 对象的属性
field
(必需，字符串) 要搜索的向量字段的名称。必须是 已启用索引的 dense_vector 字段。
k
(可选，整数) 要作为顶级命中返回的最近邻的数量。此值必须小于或等于 num_candidates。默认为 size。
num_candidates
(可选，整数) 每个分片要考虑的最近邻候选数。需要大于 k，或者如果省略 k 则为 size，并且不能超过 10,000。Elasticsearch 从每个分片收集 num_candidates 个结果，然后将它们合并以找到顶级 k 个结果。增加 num_candidates 往往可以提高最终 k 个结果的准确性。默认为 Math.min(1.5 * k, 10_000)。
query_vector
(必需，浮点数数组或字符串) 查询向量。必须与您要搜索的向量字段的维度相同。必须是浮点数数组或十六进制编码的字节向量。
docvalue_fields

(可选，字符串和对象的数组) 字段模式的数组。请求在响应的 hits.fields 属性中返回与这些模式匹配的字段名称的值。

您可以将数组中的项指定为字符串或对象。参见 文档值字段。

docvalue_fields 对象的属性
field
(必需，字符串) 通配符模式。请求返回与该模式匹配的字段名称的文档值。
format

(可选，字符串) 返回文档值的格式。

对于 日期字段，您可以指定日期 日期 format。对于 数字字段 字段，您可以指定 DecimalFormat 模式。

对于其他字段数据类型，不支持此参数。

fields

(可选，字符串和对象的数组) 字段模式的数组。请求在响应的 hits.fields 属性中返回与这些模式匹配的字段名称的值。

您可以将数组中的项指定为字符串或对象。参见 fields 选项。

fields 对象的属性
field
(必需，字符串) 要返回的字段。支持通配符 (*)。
format

(可选，字符串) 日期和地理空间字段的格式。其他字段数据类型不支持此参数。

date 和 date_nanos 字段接受 日期格式。 geo_point 和 geo_shape 字段接受

geojson (默认)
GeoJSON
wkt
Well Known Text (WKT)
mvt(<spec>)

二进制 Mapbox 矢量瓦片。API 将瓦片作为 base64 编码的字符串返回。<spec> 的格式为 <zoom>/<x>/<y>，并带有两个可选后缀：@<extent> 和/或 :<buffer>。例如，2/0/1 或 2/0/1@4096:5。

mvt 参数
<zoom>
(必需，整数) 瓦片的缩放级别。接受 0-29。
<x>
(必需，整数) 瓦片的 X 坐标。
<y>
(必需，整数) 瓦片的 Y 坐标。
<extent>
(可选，整数) 瓦片边长的像素大小。矢量瓦片是正方形，边长相等。默认为 4096。
<buffer>
(可选，整数) 瓦片外部裁剪缓冲区的像素大小。这允许渲染器避免来自延伸到瓦片范围之外的几何图形的轮廓伪影。默认为 5。
_source

(可选) 指示为匹配的文档返回哪些 源字段。这些字段在搜索响应的 hits._source 属性中返回。默认为 true。参见 源过滤。

_source 的有效值
true
(布尔值) 返回整个文档源。
false
(布尔值) 不返回文档源。
<wildcard_pattern>
(字符串或字符串数组) 包含要返回的源字段的通配符 (*) 模式或模式数组。
<object>

(对象) 包含要包含或排除的源字段列表的对象。

<object> 的属性
excludes

(字符串或字符串数组) 包含要从响应中排除的源字段的通配符 (*) 模式或模式数组。

您还可以使用此属性从 includes 属性中指定的子集中排除字段。

includes

(字符串或字符串数组) 包含要返回的源字段的通配符 (*) 模式或模式数组。

如果指定此属性，则仅返回这些源字段。您可以使用 excludes 属性从此子集中排除字段。

stored_fields

(可选，字符串) 要作为命中的一部分返回的已存储字段的逗号分隔列表。如果未指定任何字段，则响应中不包含任何已存储字段。参见 已存储字段。

如果指定此选项，则 _source 参数默认为 false。您可以传递 _source: true 以在搜索响应中同时返回源字段和已存储字段。

响应体

编辑

kNN 搜索响应具有与 搜索 API 响应 完全相同的结构。但是，某些部分具有 kNN 搜索特有的含义。

  • 文档 _score 由查询向量和文档向量之间的相似度决定。参见 similarity。
  • hits.total 对象包含已考虑的最近邻候选总数，即 num_candidates * num_shards。hits.total.relation 将始终为 eq，表示精确值。
« 时间点 API 检索器 »