Недавно мы в Amvera Cloud запустили Qdrant как преднастроенный сервис с запуском одной кнопкой, и сегодня хотим рассказать о технологии подробнее.

Представьте, что вы создаёте умный поиск, который понимает не просто слова, а смысл текста. Или рекомендательную систему, способную угадывать желания пользователя на основе его действий и предпочтений. Для таких задач недостаточно обычных баз данных — нужны инструменты, способные оперировать векторами — числовыми представлениями смысла, визуальных образов или поведения. Здесь и появляется Qdrant.

Qdrant — это движок для поиска похожих векторов, который предоставляет готовый к промышленному использованию сервис с удобным API для хранения, поиска и управления векторами, обогащёнными метаданными.

Векторные базы данных

Векторные базы данных — это специализированные системы хранения и поиска, предназначенные для работы с векторными представлениями данных (эмбеддингами). Такие базы позволяют находить объекты не по точному совпадению значений, как в реляционных базах, а по смысловой близости.

Векторные базы данных принципиально отличаются от классических систем хранения данных, таких как OLTP (Online Transaction Processing) и OLAP (Online Analytical Processing). Если OLTP используется для обработки транзакций в реальном времени (например, в e-commerce или банковских системах), а OLAP — для аналитики и работы с агрегированными отчётами, то векторные базы решают совершенно иную задачу: поиск по смысловой близости объектов.

В традиционных базах данных OLTP и OLAP (как показано на изображении выше) данные организованы в строки и столбцы (и они называются таблицами ), а запросы выполняются на основе значений в этих столбцах. Векторные БД же оперируют векторами — многомерными числовыми представлениями объектов, полученными из моделей машинного обучения (например, из нейросетей).

Что такое вектор

Вектор – это числовое представление объекта, представленное упорядоченным набором чисел фиксированной длины. Как пример – 1,2,3. Только каждое число кодирует самостоятельно или в совокупности с другими числами “смысловую” информацию об объекте.

Например:

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

• В системе музыкальных рекомендаций песня представляется вектором, где численные значения могут учитывать такие параметры, как жанр, ритм, настроение, наличие вокала и даже тематику текста.

Но чаще это менее прямолинейное и интерпретируемое кодирование. Как пример, вектор, характеризующий биометрию человека.

Что такое эмбеддинг

Эмбреддинг — это способ получить такой вектор с помощью модели машинного обучения. Это не просто случайный набор признаков, это компактное, обученное представление, которое сохраняет семантику исходного объекта.

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

Довольно общей теории, рассмотрим сам Qdrant.

Ключевые концепции Qdrant

Чтобы эффективно работать с Qdrant, важно понимать, из каких базовых элементов он состоит и как они взаимодействуют. Ниже мы разберём ключевые концепции, на которых строится архитектура Qdrant.

Точка (Point)

В Qdrant точка — это ключевая единица данных, основа всех операций поиска и фильтрации. Под объектом понимается любой элемент: изображение, текст, товар, пользователь или трек — который вы хотите хранить и искать.

Что содержит точка?

1. Идентификатор (ID)
   Это может быть 64‑битное число или UUID — как "5c56c793-69f3-4fbf-87e6-c4bf54c28c26". При вставке вы можете использовать либо простой числовой ID, либо UUID-строку.

2. Вектор (vector)
   Числовой массив (например, [0.1, 0.2, 0.3, 0.4]), который отражает смысл объекта в многомерном пространстве. Именно по этим векторам Qdrant делает семантический поиск.

3. Payload (полезная нагрузка)
   Дополнительные метаданные в формате JSON — свойства объекта. Это могут быть:

   1. строки ("color": "red"),

   2. числа ("price": 19.99),

   3. списки ("tags": ["summer", "sale"]),

   4. геокоординаты,  даты и многое другое

Пример точки в JSON:

{
  "id": "5c56c793-69f3-4fbf-87e6-c4bf54c28c26",
  "vector": [0.9, 0.1, 0.1],
  "payload": {
    "color": "red",
    "price": 19.99,
    "tags": ["summer", "sale"]
  }
}

Payload

Payload — это дополнительная информация, связанная с точкой (Point) в Qdrant. Если вектор передаёт смысл объекта, то payload описывает его контекст. Это могут быть категории, характеристики, теги, даты, локации, статусы — всё, что важно для фильтрации или отображения результата.

Именно благодаря payload вы можете не просто найти "похожие объекты", а ограничить поиск по бизнес-условиям, например:

«Найди похожие товары, но только из категории одежда, со скидкой и в наличии».

Для чего нужен Payload?

Фильтрация результатов

Payload делает возможным поиск с условиями:

• Найти только товары в наличии

• Исключить определённую категорию

• Ограничить поиск по цене, дате, региону

• Сделать геопоиск по координатам

Пример фильтра:

"filter": {
  "must": [
    { "key": "category", "match": { "value": "electronics" }},
    { "key": "in_stock", "match": { "value": true }}
  ]
}

Хранение бизнес-данных

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

Обучение и анализ

Вы также можете использовать payload для постобработки, аналитики и дообучения моделей: например, собирать статистику по категориям или сравнивать поведение пользователей.

Фильтрация (Filtering)

Фильтрация — это механизм, с помощью которого Qdrant позволяет вам точно управлять выборкой точек (Points), с которой работает векторный поиск.

Когда вы ищете "похожие объекты", Qdrant сначала отбирает те, которые соответствуют заданным условиям, и только потом сравнивает векторы. Это позволяет комбинировать смысловой поиск с классической логикой.

Как работает фильтрация?

Фильтрация в Qdrant основана на значениях из payload. Вы можете задать:

• Точное совпадение: "category": "laptop"

• Диапазон: "price" < 1000

• Множественное условие: "tags": ["gaming", "portable"]

• Гео-фильтр: искать только точки внутри радиуса

• Логические операции: must, should, must_not

Структура фильтра

Фильтр — это JSON-объект с блоками:

• must — все условия должны выполниться (аналог AND)

• should — хотя бы одно должно выполниться (аналог OR)

• must_not — эти условия не должны быть выполнены (аналог NOT)

Пример:

{
  "must": [
    { "key": "category", "match": { "value": "laptop" } },
    { "key": "price", "range": { "lt": 1500 } }
  ],
  "must_not": [
    { "key": "tags", "match": { "value": "refurbished" } }
  ]
}

Геофильтрация

Qdrant позволяет фильтровать по географическим координатам, например:

• Найти ближайшие кафе в радиусе 2 км

• Искать события в определённом городе

Пример геофильтра:

{
  "key": "location",
  "geo_bounding_box": {
    "top_left": { "lat": 52.52, "lon": 13.405 },
    "bottom_right": { "lat": 52.50, "lon": 13.40 }
  }
}

Коллекции (Collections)

В Qdrant все данные группируются в коллекции — это изолированные пространства хранения, в которых находятся векторы, точки и связанные с ними данные (payload). Если провести аналогию с реляционными БД, то коллекция — это как таблица, только для векторных и семантических данных.

Что входит в коллекцию?

• Коллекция определяет структуру и поведение данных, которые в неё загружаются. При её создании задаются:

• Размер векторов — например, 768, если вы используете BERT.

• Метрика сравнения — Cosine, Euclidean или Dot. Выбор влияет на точность и смысл поиска.

• Типы и количество векторов — коллекция может содержать один или несколько векторов на точку (например, один — текст, другой — изображение).

• Payload — любые дополнительные данные, привязанные к точке.

• Индексы — настройки HNSW, фильтрации, геопоиска, текстовых индексов и др.

• Размер вектора (vector_size) — сколько признаков в одном векторе (например, 384, 768 или 1536).

• Тип расстояния (distance) — метрика сравнения векторов: Cosine, Euclidean, Dot.

• Настройки хранения и индексации — включение HNSW-индекса, реплик, сжатия, и др.

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

Метрика сравнения/расстояния

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

Qdrant поддерживает следующие наиболее популярные типы метрик:

Dot Product (Скалярное произведение)

• Суть: Измеряет степень сонаправленности и длину векторов. Чем больше значение, тем более похожи вектора.

• Используется, когда длина вектора имеет значение, например, в моделях, где высокая норма указывает на уверенность.

• Важно: чем выше значение, тем ближе точки — в отличие от других метрик, где «ближе» значит «меньше».

Подходит для рекомендательных систем, моделей с обучением через softmax.

Cosine Similarity (Косинусная схожесть)

• Суть: Сравнивает угол между векторами, игнорируя их длину. Значение варьируется от -1 до 1.

• Преимущество: Работает хорошо для текстов, где важна направленность, а не амплитуда признаков.

• Часто используется с BERT и другими языковыми моделями.

Подходит для поиска по смыслу, семантического поиска текста, документации.

Косинусная схожесть измеряет угол между двумя векторами в многомерном пространстве, игнорируя их длину. Чем меньше угол, тем более "похожи" вектора.

Формула выглядит так:

Результат находится в диапазоне от -1 до 1:

• 1 — вектора полностью сонаправлены (максимально похожи),

• 0 — вектора ортогональны (нет сходства),

• -1 — противоположны.

Euclidean Distance (Евклидово расстояние)

• Суть: Классическое геометрическое расстояние между точками в пространстве.

• Интерпретация: Чем меньше расстояние, тем ближе вектора.

• Хорошо работает, когда эмбеддинги спроектированы так, чтобы близость отражалась геометрически.

Подходит для изображений и геометрически интерпретируемых признаков.

Manhattan Distance (Манхэттенское расстояние)

• Суть: Сумма абсолютных разностей координат — как если бы вы шли по сетке города.

• Реже используется в практике, но полезна, когда важны отдельные оси/признаки.

Подходит для данных с независимыми признаками, где важна "дробная" разница.

Создание коллекции

При создании вы определяете ключевые параметры: размерность векторов, метрику расстояния (например, Cosine или Dot), а также, при необходимости, конфигурации для фильтрации и индексирования. Это можно сделать как через REST API, так и с помощью клиента на Python или другой поддерживаемой библиотеке

Пример кода на Python:

from qdrant_client import QdrantClient, models

client = QdrantClient(url="http://localhost:6333")

client.create_collection(
    collection_name="{collection_name}",
    vectors_config=models.VectorParams(size=100, distance=models.Distance.COSINE),
)

ВАЖНО! Для выполнения данного кода требуется заранее запустить Qdrant на локальной машине.

Индексация (Indexing)

Когда вы работаете с миллионами векторов, линейный поиск (сравнение каждого вектора с запросом) становится невозможным — он слишком медленный. Чтобы ускорить поиск, Qdrant использует механизм приближённой векторной индексации, основанный на структуре под названием HNSW (Hierarchical Navigable Small World Graph).

HNSW — это граф, в котором вектора соединены между собой на основе их близости (схожести). Этот граф состоит из нескольких уровней:

• Верхние уровни содержат лишь часть точек и обеспечивают быстрый грубый поиск.

• Нижние уровни — более плотные и точные.

Поиск происходит сверху вниз: сначала Qdrant находит приближенную область, где находится ближайший вектор, а затем уточняет результат на нижнем уровне. Это позволяет за миллисекунды найти наиболее подходящие вектора без перебора всей базы.

Настройка индекса

Индекс по payload в Qdrant похож на индекс в традиционных документно-ориентированных базах данных. Этот индекс создаётся для конкретного поля и типа и используется для быстрого поиска точек по соответствующему условию фильтрации.

Индекс также применяется для точной оценки мощности фильтра (кардинальности), что помогает планировщику запросов выбрать оптимальную стратегию поиска.

Создание индекса требует дополнительных вычислительных ресурсов и памяти, поэтому важно внимательно выбирать поля для индексирования.

Чтобы пометить поле как индексируемое, вы можете использовать следующее:

client.create_payload_index(
    collection_name="{collection_name}",
    field_name="name_of_the_field_to_index",
    field_schema="keyword",
)

Доступные типы полей:

• keyword- для полезной нагрузки ключевых слов влияет на условия фильтрации совпадений .

• integer- для целочисленной полезной нагрузки влияет на условия фильтрации «Соответствие» и «Диапазон» .

• float- для плавающей полезной нагрузки влияет на условия фильтрации по дальности .

• bool- для полезной нагрузки bool влияет на условия фильтрации Match (доступно с версии 1.4.0).

• geo- для геоданных влияет на условия фильтрации Geo Bounding Box и Geo Radius .

• datetime- для полезной нагрузки datetime влияет на условия фильтрации диапазона (доступно с версии 1.8.0).

• text- специальный вид индекса, доступный для полезных нагрузок ключевых слов или строк, влияет на условия фильтрации полнотекстового поиска .

uuid- специальный тип индекса, похожий на keyword, но оптимизированный для значений UUID . Влияет на условия фильтрации Match .

Обновление и удаление данных в Qdrant

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

Обновление векторов

Каждая точка (point) в Qdrant, это комбинация:

• уникального id,

• вектора (или нескольких),

• полезной нагрузки (payload).

Если вы хотите изменить вектор по уже существующему id, вы можете просто повторно записать точку с тем же ID — вектор будет заменён. Это особенно полезно, если вы дообучили модель и хотите заменить эмбеддинги без удаления всего объекта.

client.upsert(
    collection_name="my_collection",
    points=[PointStruct(id=42, vector=new_vector, payload={"label": "cat"})]
)

Обновление payload

Qdrant позволяет обновлять только payload без изменения вектора. Это удобно, если вы хотите поменять метаданные (например, категорию, метку, дату и т.д.).

Есть три основные операции:

1. set_payload — установить или заменить поля.

2. overwrite_payload — полностью заменить payload (удалив старые поля).

3. delete_payload — удалить одно или несколько полей payload по id.

Удаление точек

Удаление можно производить:

• По конкретному id

• По фильтру (например, удалить все объекты пользователя)

Пример удаления по фильтру:

client.delete(
    collection_name="my_collection",
    points_selector=FilterSelector(
        filter=Filter(
            must=[FieldCondition(key="user_id", match=MatchValue(value=1234))]
        )
    )
)

Запускаем Qdrant локально через Docker

Для разработки, тестирования или небольших проектов Qdrant можно легко запустить на своём компьютере  без необходимости использовать облачные сервисы. Это занимает буквально пару минут и требует минимальных настроек.

Самый быстрый и универсальный способ — через Docker. Qdrant официально распространяется как Docker-образ.

Установка Docker

Если Docker ещё не установлен:

• macOS: brew install --cask docker

• Linux: следуйте официальной инструкции

• Windows: скачайте Docker Desktop

Запуск Qdrant

docker run -p 6333:6333 qdrant/qdrant

Это запустит Qdrant локально на порту 6333.

REST API и Web UI будут доступны по адресу: http://localhost:6333

По умолчанию данные сохраняются внутри контейнера. Чтобы сохранить их на диск выполните команду:

docker run -p 6333:6333 \
  -v $(pwd)/qdrant_storage:/qdrant/storage \
  qdrant/qdrant

Теперь даже после перезапуска контейнера ваши коллекции сохранятся.

Запуск Qdrant на удалённом сервере Amvera

Если вы не хотите вручную разворачивать и настраивать инфраструктуру, Amvera Cloud предоставляет возможность быстро поднять Qdrant как преднастроенный сервис одной кнопкой. Это отличный способ начать использовать векторную базу в продакшене без DevOps-рутины.

Что такое преднастроенные  сервисы в Amvera?

В Amvera вы можете выбрать один из готовых компонентов, таких как PostgreSQL (управляемая БД), Redis, Directus или Qdrant. Они запускаются в изолированных контейнерах с уже преднастроенной конфигурацией: с бесплатными https-доменами, открытым API, логированием, переменными окружения, поддержкой масштабирования и безопасным доступом.

Создание преднастроенного сервиса

Для начала войдите в личный кабинет Amvera.

В главном меню в панели “Cоздать преднастроенный сервис” выбираем Qdrant.

Выбираем название и тариф (желательно выбирать тариф повыше для первого запуска).

Нажимаем Далее - Завершить.

Немного ожидаем запуска сервиса.

Готово! Мы имеем развернутый сервис на сервере, готовый к использованию в наших проектах через внутреннее доменное имя.

Для того, чтобы получить доменное имя нам требуется перейти в настройки проекта, в раздел “Инфо”.

Доменное имя мы можем использовать с проектами, также развернутыми в Amvera. Если требуется доступ извне, можно создать бесплатный https-домен в разделе “Домены”.

Пример инциализации

Если у нас имеется приложение, использующее Qdrant, и мы успешно развернули сам Qdrant в Amvera, то нам стоит правильно провести инциализацию Qdrant, чтобы наше приложение работало корректно.

В этом случае нам требуется Внутреннее доменное имя - его мы получали в разделе ранее.

Доменное имя мы вставляем в URL и выставляем порт 6333.

Пример инциализации на Python:

from qdrant_client import QdrantClient

client = QdrantClient(url="http://amvera-exampleuser-run-exampleproject:6333")

Далее мы можем начать работу с Qdrant, например, создать коллекцию:

from qdrant_client.http.models import VectorParams, Distance

client.create_collection(
    collection_name="texts",
    vectors_config=VectorParams(size=384, distance=Distance.COSINE)
)

И далее расширять возможности приложения с помощью Qdrant.

Заключение

В этой статье мы рассмотрели общие концепции векторной базы данных Qdrant. В следующей, рассмотрим пример использования Qdrant на конкретном проекте.

---

Развернуть Qdrant одной кнопкой вы можете в Amvera Cloud.

Amvera Cloud – это облако со встроенным CI/CD (деплой идёт через Git или перетягивание файлов в интерфейсе), управлением секретами, бесплатным логированием с семантическим поиском, бесплатными https-доменами, мониторингом работы приложений, и встроенным проксированием до ведущих LLM. Вам не нужно думать о настройке NGINX, виртуальных машин и другой инфраструктуре. Достаточно загрузить ваш код удобным вам способом, Amvera всё настроит и запустит.