--- metadata: - name: generator content: Diplodoc Platform v5.52.0 alternate: - https://ydb-platform--ydb.viewer.diplodoc.com/en/dev/vector-indexes.md?version=v25.1 - https://ydb-platform--ydb.viewer.diplodoc.com/ru/dev/vector-indexes.md?version=v25.1 - href: ru/dev/vector-indexes.md type: text/markdown title: Markdown version - href: ../llms.txt type: text/markdown title: llms.txt sourcePath: ru/core/dev/vector-indexes.md --- > **Documentation Index:** Fetch the complete configuration index at https://ydb-platform--ydb.viewer.diplodoc.com/ru/llms.txt # Векторные индексы {% note alert %} Фукциональность векторных индексов доступна, начиная с версии `25.1.2`. Для включения векторных индексов необходимо установить значение feature flag `enable_vector_index` в `true`. В настоящее время не поддерживается: * Обновление индекса: модифицировать основную таблицу можно, но существующий индекс не обновится. Нужно построить новый индекс, чтобы учесть изменения. При необходимости, можно [атомарно заменить](https://ydb-platform--ydb.viewer.diplodoc.com/ru/reference/ydb-cli/commands/secondary_index.md?version=v25.1#rename) существующий индекс на вновь построенный. * Построение индекса для векторов c [битовым квантованием](https://ydb-platform--ydb.viewer.diplodoc.com/ru/yql/reference/udf/list/knn.md?version=v25.1#functions-convert). Эти ограничения могут быть устранены в будущих версиях. {% endnote %} [Векторные индексы](https://ydb-platform--ydb.viewer.diplodoc.com/ru/concepts/glossary.md?version=v25.1#vector-index) — это специализированные структуры данных, которые позволяют эффективно выполнять [векторный поиск](https://ydb-platform--ydb.viewer.diplodoc.com/ru/concepts/vector_search.md?version=v25.1) в многомерных пространствах. В отличие от [вторичных индексов](https://ydb-platform--ydb.viewer.diplodoc.com/ru/concepts/glossary.md?version=v25.1#secondary-index), которые оптимизируют поиск по равенству или диапазону, векторные индексы позволяют выполнять приближенный поиск на основе [функций схожести или расстояния](https://ydb-platform--ydb.viewer.diplodoc.com/ru/yql/reference/udf/list/knn.md?version=v25.1#functions). Данные в таблице YDB хранятся и сортируются по первичному ключу, что обеспечивает эффективный поиск по точному совпадению и сканирование диапазонов. Векторные индексы предоставляют аналогичную эффективность для поиска ближайших соседей в векторных пространствах. ## Характеристики векторных индексов {#characteristics} Векторные индексы в YDB решают задачу поиска ближайших соседей с использованием [функций схожести или расстояния](https://ydb-platform--ydb.viewer.diplodoc.com/ru/yql/reference/udf/list/knn.md?version=v25.1#functions). Поддерживается несколько функций расстояния/схожести: "inner_product", "cosine" (схожесть) и "cosine", "euclidean", "manhattan" (расстояние). В текущей реализации доступен один тип индекса: `vector_kmeans_tree`. ## Векторный индекс типа `vector_kmeans_tree` {#kmeans-tree-type} Индекс `vector_kmeans_tree` реализует иерархическую кластеризацию данных. Структура индекса включает: 1. Иерархическая кластеризация: * индекс строит несколько уровней k-means кластеров; * на каждом уровне векторы распределяются по заданному количеству кластеров в степени уровня; * первый уровень кластеризует весь набор данных; * последующие уровни рекурсивно кластеризуют содержимое каждого родительского кластера. 2. Процесс поиска: * поиск идет рекурсивно от первого уровня к последующим; * при выполнении запросов индекс анализирует только наиболее перспективные кластеры; * такое усечение пространства поиска позволяет избежать полного перебора всех векторов. 3. Параметры: * `levels`: число уровней в дереве, задает глубину поиска (рекомендуется 1-3); * `clusters`: количество кластеров в k-means, определяющее ширину поиска (рекомендуется 64-512). Внутри векторный индекс состоит из скрытых индексных таблиц вида `indexImpl*Table`. В [запросах на выборку](#select) с использованием векторного индекса эти таблицы отображаются в [статистике запросов](https://ydb-platform--ydb.viewer.diplodoc.com/ru/dev/query-plans-optimization.md?version=v25.1). Подробнее об устройстве векторного индекса см. в отдельной статье [Векторный индекс вида vector_kmeans_tree](https://ydb-platform--ydb.viewer.diplodoc.com/ru/dev/vector-indexes-kmeans-tree-type.md?version=v25.1). ## Виды векторных индексов {#types} Векторный индекс может быть **покрывающим**, что означает включение дополнительных колонок для возможности чтения из индекса без обращения к основной таблице. Или же он может быть с поддержкой **фильтрации**, что позволяет учитывать дополнительные колонки для быстрой фильтрации при выполнении чтения. Ниже приведены примеры создания векторного индекса различных типов. ### Базовый векторный индекс {#basic} Глобальный векторный индекс по колонке `embedding`: ```yql ALTER TABLE my_table ADD INDEX my_index GLOBAL USING vector_kmeans_tree ON (embedding) WITH (distance=cosine, vector_type="uint8", vector_dimension=512, levels=2, clusters=128); ``` ### Векторный индекс с покрывающими колонками {#covering} Покрывающий векторный индекс, включающий дополнительную колонку `data`, чтобы избежать чтения из основной таблицы при поиске: ```yql ALTER TABLE my_table ADD INDEX my_index GLOBAL USING vector_kmeans_tree ON (embedding) COVER (data) WITH (distance=cosine, vector_type="uint8", vector_dimension=512, levels=2, clusters=128); ``` ### Векторный индекс с фильтрацией {#filtered} Векторный индекс с фильтрацией, позволяющий фильтровать по колонке `user` в момент выполнения векторного поиска: ```yql ALTER TABLE my_table ADD INDEX my_index GLOBAL USING vector_kmeans_tree ON (user, embedding) WITH (distance=cosine, vector_type="uint8", vector_dimension=512, levels=2, clusters=128); ``` ### Векторный индекс с фильтрацией и покрывающими колонками {#filtered-covering} Векторный индекс с фильтрацией и покрывающими колонками: ```yql ALTER TABLE my_table ADD INDEX my_index GLOBAL USING vector_kmeans_tree ON (user, embedding) COVER (data) WITH (distance=cosine, vector_type="uint8", vector_dimension=512, levels=2, clusters=128); ``` ## Создание векторных индексов {#creation} Векторные индексы можно создавать: * при создании таблицы с помощью YQL-оператора [CREATE TABLE](https://ydb-platform--ydb.viewer.diplodoc.com/ru/yql/reference/syntax/create_table/vector_index.md?version=v25.1); * добавлять к существующей таблице с помощью YQL-оператора [ALTER TABLE](https://ydb-platform--ydb.viewer.diplodoc.com/ru/yql/reference/syntax/alter_table/indexes.md?version=v25.1). ## Использование векторных индексов {#select} Запросы к векторным индексам выполняются с использованием синтаксиса `VIEW` в YQL: ```yql DECLARE $query_vector AS List; SELECT user, data FROM my_table VIEW my_index ORDER BY Knn::CosineSimilarity(embedding, $query_vector) DESC LIMIT 10; ``` Для индексов с фильтрацией укажите соответствующие колонки в условии `WHERE`: ```yql DECLARE $query_vector AS List; SELECT user, data FROM my_table VIEW my_index WHERE user = 'john' ORDER BY Knn::CosineSimilarity(embedding, $query_vector) DESC LIMIT 10; ``` Подробнее о выполнении запросов `SELECT` с использованием векторных индексов можно прочитать в разделе [VIEW VECTOR INDEX](https://ydb-platform--ydb.viewer.diplodoc.com/ru/yql/reference/syntax/select/vector_index.md?version=v25.1). {% note info %} Если не использовать выражение `VIEW`, запрос выполнит полное сканирование таблицы с попарным сравнением векторов. Рекомендуется проверять оптимальность написанного запроса, используя [статистику запросов](https://ydb-platform--ydb.viewer.diplodoc.com/ru/dev/query-plans-optimization.md?version=v25.1). В частности, следует следить за отсутствием полного сканирования (full scan) основной таблицы. {% endnote %} ## Рецепты работы с векторным индексом {#vector-index-recipes} Для начала работы с векторным индексом можно воспользоваться следующими рецептами: * [YDB CLI & YQL](https://ydb-platform--ydb.viewer.diplodoc.com/ru/recipes/vector-search.md?version=v25.1) * [YDB SDK: Python, C++](https://ydb-platform--ydb.viewer.diplodoc.com/ru/recipes/ydb-sdk/vector-search.md?version=v25.1)