› › ›

API поиска kNN

Устарело в 8.4.0.

API поиска kNN заменён на knn опцию в API поиска.

Выполняет поиск k-ближайших соседей (kNN) и возвращает соответствующие документы.

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 права на доступ к индексу для целевого потока данных, индекса или псевдонима.

Описание

API поиска kNN выполняет поиск k-ближайших соседей (kNN) по полю dense_vector. Учитывая вектор запроса, он находит k ближайших векторов и возвращает соответствующие документы в качестве результатов поиска.

Elasticsearch использует алгоритм HNSW для обеспечения эффективного поиска kNN. Как и большинство алгоритмов kNN, HNSW является приближённым методом, жертвующим точностью результатов для повышения скорости поиска. Это означает, что возвращаемые результаты не всегда являются истинными k ближайшими соседями.

API поиска kNN поддерживает ограничение поиска с помощью фильтра. Поиск вернёт верхние k документов, которые также соответствуют запросу фильтра.

Параметры пути

<target>: (Необязательно, строка) Список потоков данных, индексов и псевдонимов для поиска, разделённых запятыми. Поддерживаются подстановки (*). Для поиска всех потоков данных и индексов используйте * или _all.

Параметры запроса

routing: (Необязательно, строка) Пользовательское значение, используемое для маршрутизации операций на определённый фрагмент.

Тело запроса

filter

(Необязательно, объект Query DSL) Запрос для фильтрации документов, которые могут соответствовать. Поиск kNN вернёт лучшие k документов, которые также соответствуют этому фильтру. Значение может быть одиночным запросом или списком запросов. Если filter не указан, все документы могут соответствовать.

knn

(Обязательно, объект) Определяет запрос kNN для выполнения.

Свойства объекта knn

field: (Обязательно, строка) Название векторного поля для поиска. Должно быть полем dense_vector с включенным индексированием.
k: (Необязательно, целое число) Количество ближайших соседей, которые нужно вернуть в качестве лучших результатов. Это значение должно быть меньше или равно num_candidates. По умолчанию size.
num_candidates: (Необязательно, целое число) Количество кандидатов на ближайших соседей для рассмотрения на каждый фрагмент. Должно быть больше k, или size если k опущено, и не должно превышать 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

Вы можете указать элементы в массиве как строку или объект. Смотрите параметр fields.

Свойства объектов fields

field

(Обязательно, строка) Поле для возврата. Поддерживает подстановки (*).

format

(Необязательно, строка) Формат для полей даты и геопространственных данных. Другие типы полей не поддерживают этот параметр.

Поля date и date_nanos принимают формат даты. Поля geo_point и geo_shape принимают:

geojson (по умолчанию)

GeoJSON

wkt

Well Known Text

mvt(<spec>)

Бинарная плитка Mapbox vector. 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, что указывает на точное значение.

© 2023-2025 Elasticsearch
As of September 2024, Elasticsearch is available under a choice of three licenses: the Server Side Public License (SSPL), the Elastic License, or the AGPLv3 (OSI approved).
Elasticsearch and the Elasticsearch logo are trademarks of Elasticsearch B.V., registered in the U.S. and in other countries.
https://www.elastic.co/guide/en/elasticsearch/reference/8.17/knn-search-api.html