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

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)
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 <目标>/_knn_search

POST <目标>/_knn_search

先决条件

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

描述

编辑

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

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

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

路径参数

编辑
<目标>
（可选，字符串）要搜索的数据流、索引和别名的逗号分隔列表。支持通配符（*）。要搜索所有数据流和索引，请使用 * 或 _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
众所周知的文本
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 检索器 »