Чтобы выполнять поиск KNN, сначала нужно настроить таблицу. Вещественные векторы и поиск KNN поддерживаются только в таблицах real-time (не в plain-таблицах). В таблице должен быть как минимум один атрибут float_vector, который служит вектором данных. Нужно указать следующие свойства:

• knn_type: Обязательный параметр; сейчас поддерживается только hnsw.

• knn_dims: Обязательный параметр, задающий размерность индексируемых векторов.

• hnsw_similarity: Обязательный параметр, задающий функцию расстояния, используемую индексом HNSW. Допустимые значения:

  • L2 - Квадрат евклидова расстояния L2
  • IP - Скалярное произведение
  • COSINE - Косинусное сходство

  Примечание: При использовании сходства COSINE векторы автоматически нормализуются при вставке. Это означает, что сохраненные значения векторов могут отличаться от исходных входных значений, поскольку они будут преобразованы в единичные векторы (векторы с математической длиной/модулем 1.0), чтобы можно было эффективно вычислять косинусное сходство. Такая нормализация сохраняет направление вектора, одновременно стандартизируя его длину.

• hnsw_m: Необязательный параметр, задающий максимальное число исходящих связей в графе. Значение по умолчанию - 16.

• hnsw_ef_construction: Необязательный параметр, задающий компромисс между временем построения и точностью. Значение по умолчанию - 200.

ПРИМЕЧАНИЕ: Построение графа HNSW при сохранении чанков RT, при слиянии чанков OPTIMIZE TABLE / auto-optimize и при перестройке KNN через ALTER TABLE ... ADD/DROP/REBUILD выполняется параллельно по умолчанию на многопроцессорных хостах; число worker-потоков управляется настройкой searchd knn_parallel_build (установите 1, чтобы принудительно использовать последовательный путь). Это влияет только на скорость построения. Поскольку параллельное построение HNSW может вставлять векторы в другом порядке, итоговый граф может не быть побитово идентичен последовательной сборке.

Самый простой способ работать с векторными данными - использовать автоэмбеддинги. С этой функцией вы создаете таблицу с параметрами MODEL_NAME и FROM, а затем просто вставляете текстовые данные - Manticore автоматически генерирует эмбеддинги за вас.

При создании таблицы для автоэмбеддингов укажите:

• MODEL_NAME: Модель эмбеддингов, которую нужно использовать
• FROM: Какие поля использовать для генерации эмбеддингов (пустое значение означает все текстовые/строковые поля)
• API_KEY: Обязателен для удаленных моделей (OpenAI, Voyage, Jina). API-ключ проверяется при создании таблицы путем выполнения реального запроса к API.
• API_URL: Необязателен. Пользовательский URL конечной точки API. Если не указан, используется конечная точка провайдера по умолчанию (например, https://api.openai.com/v1/embeddings для OpenAI).
• API_TIMEOUT: Необязателен. Таймаут HTTP-запросов к API в секундах. Значение по умолчанию - 10 секунд. Установите '0', чтобы использовать таймаут по умолчанию. Применяется и к проверочным запросам при создании таблицы, и к генерации эмбеддингов во время операций INSERT.

Для удаленных моделей MODEL_NAME можно записывать в двух формах:

• Устаревшая форма с префиксом провайдера: openai/text-embedding-ada-002, voyage/voyage-3.5-lite, jina/jina-embeddings-v4
• Явная форма provider-signal для пользовательских endpoint'ов: openai:text-embedding-ada-002, openai:openai/text-embedding-ada-002, voyage:custom-model, jina:custom-model

Когда вы используете форму provider:model вместе с API_URL, часть перед : только выбирает формат запроса. Часть после : отправляется на удаленную конечную точку без изменений. Это полезно для шлюзов, совместимых с OpenAI, таких как OpenRouter или LiteLLM.

Поддерживаемые модели эмбеддингов:

Требования к формату локальной модели:

• Должна быть сохранена в формате safetensors (только один файл)
• Поддерживаемые семейства: Qwen, Llama, Mistral, Gemma
• Проверенные модели: TinyLlama/TinyLlama-1.1B-Chat-v1.0, Locutusque/TinyMistral-248M-v2, Qwen/Qwen3-Embedding-0.6B, h2oai/embeddinggemma-300m
• Другие модели safetensors тоже могут работать, но это не гарантируется

Дополнительную информацию о настройке атрибута float_vector можно найти здесь.

При использовании автоэмбеддингов вы можете:

• Не указывать поле вектора и позволить Manticore сгенерировать эмбеддинги из полей, перечисленных в FROM
• Явно передать свой вектор для строки
• Передать (), чтобы пропустить генерацию и сохранить нулевой вектор

Если позже вы выполните ALTER TABLE ... REBUILD EMBEDDINGS, строки, которые сейчас содержат нулевые векторы из (), тоже будут пересозданы.

Поиск работает так же - передайте текст запроса, и Manticore сгенерирует эмбеддинги и найдет похожие документы:

В качестве альтернативы вы можете вручную вставлять предварительно вычисленные векторные данные, убедившись, что они соответствуют размерности, указанной при создании таблицы. Вы также можете вставить пустой вектор; это означает, что документ будет исключен из результатов векторного поиска.

Важно: При использовании hnsw_similarity='cosine' векторы автоматически нормализуются при вставке до единичных векторов (векторов с математической длиной/модулем 1.0). Такая нормализация сохраняет направление вектора, одновременно стандартизируя его длину, что требуется для эффективных вычислений косинусного сходства. Это означает, что сохраненные значения будут отличаться от исходных входных значений.

Теперь вы можете выполнять поиск KNN с помощью предложения knn как в формате SQL, так и в формате JSON. Оба интерфейса поддерживают одни и те же основные параметры, обеспечивая единообразный опыт независимо от выбранного формата:

• SQL: select ... from <table name> where knn ( <field>, <query vector> [,<options>] )
• JSON:

  POST /search
  {
      "table": "<table name>",
      "knn":
      {
          "field": "<field>",
          "query": "<text or vector>",
          "ef": <ef>,
          "rescore": <rescore>,
          "oversampling": <oversampling>
      }
  }

Параметры:

• field: Имя атрибута float_vector, содержащего векторные данные.
• k: Устаревший параметр. Вместо него используйте limit в запросе. Он использовался для задания количества документов, которое должен вернуть один индекс HNSW. Однако фактическое число документов в итоговых результатах может отличаться. Например, если система работает с таблицами real-time, разделенными на disk chunks, каждый chunk может вернуть k документов, что приведет к итоговому числу больше указанного k (так как суммарное количество будет num_chunks * k). С другой стороны, итоговое число документов может оказаться меньше k, если после запроса k документов часть из них будет отфильтрована по определенным атрибутам. Важно отметить, что параметр k не применяется к ramchunks. В контексте ramchunks процесс получения работает иначе, и поэтому влияние параметра k на число возвращаемых документов неприменимо.
• query: (Рекомендуемый параметр) Поисковый запрос, который может быть:
  • Текстовой строкой: автоматически преобразуется в эмбеддинги, если для поля настроены автоэмбеддинги. Вернет ошибку, если у поля нет автоэмбеддингов.
  • Массивом векторов: работает так же, как query_vector.
• query_vector: (Устаревший параметр) Поисковый вектор в виде массива чисел. По-прежнему поддерживается для обратной совместимости. Примечание: Используйте либо query, либо query_vector, но не оба параметра в одном запросе.
• ef: необязательный размер динамического списка, используемого во время поиска. Более высокое значение ef дает более точный, но более медленный поиск. Значение по умолчанию - 10.
• rescore: Включает повторное оценивание KNN (по умолчанию включено). Установите 0 в SQL или false в JSON, чтобы отключить повторное оценивание. После завершения поиска KNN с использованием квантизованных векторов (с возможным oversampling) расстояния пересчитываются по исходным (full-precision) векторам, и результаты пересортировываются для повышения точности ранжирования.
• oversampling: Задает коэффициент (значение float), на который умножается k при выполнении поиска KNN, из-за чего с использованием квантизованных векторов извлекается больше кандидатов, чем требуется. По умолчанию применяется oversampling=3.0. Эти кандидаты можно затем переоценить, если повторное оценивание включено. Oversampling также работает и с неквантизованными векторами. Поскольку он увеличивает k, а это влияет на работу индекса HNSW, он может вызвать небольшое изменение точности результатов.
• early_termination: Включает или отключает адаптивное раннее завершение при обходе графа HNSW. По умолчанию включено. Установите 0 в SQL или false в JSON, чтобы отключить. Подробности см. в разделе Раннее завершение.

Когда задан текстовый запрос (то есть Manticore сначала встраивает строку перед поиском), число потоков, используемых библиотекой embeddings, можно переопределить для каждого запроса в SQL с помощью OPTION embeddings_threads = N. Это значение ограничивает вызов embeddings только для этого запроса, переопределяя глобальную настройку embeddings_threads; 0 означает отсутствие ограничения. Эта опция не влияет на запрос, если он передан в виде массива векторов.

Документы всегда сортируются по расстоянию до вектора поиска. Любые дополнительные критерии сортировки, которые вы укажете, будут применяться после этого основного условия сортировки. Чтобы получить расстояние, есть встроенная функция knn_dist().

Индексы HNSW должны быть полностью загружены в память, чтобы выполнять поиск KNN, что может приводить к значительному потреблению памяти. Чтобы снизить использование памяти, можно применить скалярное квантование - технику, которая сжимает многомерные векторы, представляя каждую компоненту (размерность) ограниченным числом дискретных значений. Manticore поддерживает 8-битное и 1-битное квантование, то есть каждая компонента вектора сжимается с 32-битного float до 8 бит или даже до 1 бита, уменьшая использование памяти в 4 раза или 32 раза соответственно. Эти сжатые представления также позволяют быстрее вычислять расстояния, поскольку больше компонент вектора можно обработать одной SIMD-инструкцией. Хотя скалярное квантование вносит некоторую погрешность аппроксимации, часто это оправданный компромисс между точностью поиска и эффективностью использования ресурсов. Для еще более высокой точности квантование можно сочетать с повторным оцениванием и oversampling: запрашивается больше кандидатов, чем нужно, а расстояния для этих кандидатов пересчитываются с использованием исходных 32-битных float-векторов.

Поддерживаемые типы квантования:

• 8bit: Каждая компонента вектора квантуется до 8 бит.
• 1bit: Каждая компонента вектора квантуется до 1 бита. Используется асимметричное квантование: векторы запроса квантуются до 4 бит, а сохраненные векторы - до 1 бита. Такой подход дает более высокую точность, чем более простые методы, но с некоторым компромиссом по производительности.
• 1bitsimple: Каждая компонента вектора квантуется до 1 бита. Этот метод быстрее, чем 1bit, но обычно менее точен.

ПРИМЕЧАНИЕ: Поиск похожих документов по id требует Manticore Buddy. Если он не работает, убедитесь, что Buddy установлен.

Поиск документов, похожих на конкретный документ по его уникальному ID, - распространенная задача. Например, когда пользователь просматривает определенный товар, Manticore Search может эффективно определить и показать список товаров, которые наиболее похожи на него в векторном пространстве. Вот как это сделать:

• SQL: select ... from <table name> where knn ( <field>, <k>, <document id> )
• JSON:

  POST /search
  {
      "table": "<table name>",
      "knn":
      {
          "field": "<field>",
          "doc_id": <document id>,
          "k": <k>
      }
  }

Параметры:

• field: Имя атрибута float_vector, содержащего векторные данные.
• k: Это число документов, которые нужно вернуть, и ключевой параметр для индексов Hierarchical Navigable Small World (HNSW). Он задает количество документов, которое должен вернуть один индекс HNSW. Однако фактическое число документов в итоговых результатах может отличаться. Например, если система работает с таблицами real-time, разделенными на disk chunks, каждый chunk может вернуть k документов, что приведет к итоговому числу больше указанного k (так как суммарное количество будет num_chunks * k). С другой стороны, итоговое число документов может оказаться меньше k, если после запроса k документов часть из них будет отфильтрована по определенным атрибутам. Важно отметить, что параметр k не применяется к ramchunks. В контексте ramchunks процесс получения работает иначе, и поэтому влияние параметра k на число возвращаемых документов неприменимо.
• document id: ID документа для KNN-поиска похожих документов.

Manticore также поддерживает дополнительную фильтрацию документов, возвращаемых поиском KNN, либо по полнотекстовому совпадению, либо по фильтрам атрибутов, либо по обоим сразу.

При объединении векторного поиска KNN с фильтрами атрибутов Manticore поддерживает две стратегии, которые отличаются тем, когда фильтр применяется относительно обхода графа HNSW.

• Предварительная фильтрация (по умолчанию; prefilter=1 (SQL) или "prefilter": true (JSON, default)) передает фильтр непосредственно в обход HNSW. Каждый кандидат проверяется на соответствие фильтру до добавления в результирующую кучу - в итоговые k результатов попадают только подходящие документы. Это уменьшает число бесполезных вычислений расстояния и гарантирует, что будет возвращено ровно k подходящих документов (если существует k подходящих документов).

• Постфильтрация (prefilter=0 (SQL) или "prefilter": false (JSON)) сначала выполняет поиск KNN по всему набору данных, а затем применяет фильтр к результатам. Это безопасно и предсказуемо: граф HNSW обходится без вмешательства, а фильтр влияет только на то, какие результаты возвращаются клиенту. Недостаток в том, что на кандидатов, которые в итоге будут отброшены, граф может потратить ресурсы. При жестком фильтре, который совпадает лишь с небольшой долей документов, возвращаемые k результатов могут оказаться значительно меньше запрошенного числа, потому что большинство кандидатов KNN не пройдет фильтр.

Внутри Manticore использует алгоритм на основе ACORN-1 для предварительной фильтрации. Наивная предварительная фильтрация просто пропускала бы несовпадающие узлы, что создает риск потерять "bridge"-узлы, соединяющие разъединенные части графа HNSW, из-за чего полнота резко падает по мере ужесточения фильтра. ACORN-1 избегает этого: когда узел не проходит фильтр, его соседи все равно добавляются в очередь обхода. Это позволяет обходу обходить отфильтрованные узлы и сохранять связность графа. Обход ACORN-1 автоматически включается, когда фильтр проходит менее 60% всех документов.

Автоматический переход на brute-force: Когда включена предварительная фильтрация, Manticore оценивает, что дешевле - выполнить полный перебор расстояний по отфильтрованному подмножеству или обходить граф HNSW. Оценка сравнивает ожидаемое число узлов, посещаемых HNSW, с числом документов, прошедших фильтр. Если отфильтрованное множество достаточно мало, чтобы его прямой перебор был быстрее, Manticore автоматически переключается на brute-force, полностью пропуская HNSW. Это обеспечивает корректность и хорошую производительность даже при экстремальной селективности.

Чтобы явно управлять ранним завершением, используйте параметр early_termination: