Qdrant: установка и первый векторный поиск на Python

Qdrant — открытая векторная база данных, написанная на Rust и изначально созданная российской командой (сейчас проект международный). В 2026 году это один из самых частых выборов для RAG-систем: быстрый HNSW-поиск, гибкая фильтрация по метаданным и щедрый бесплатный тир для self-hosted запуска. В статье поднимаем Qdrant локально через Docker, устанавливаем python-клиент, создаем коллекцию и делаем первый поиск похожих векторов с кодом.

Qdrant поднимается локально одной командой Docker за минуту, а первый рабочий поиск на Python занимает три шага: создать коллекцию, загрузить точки, отправить запрос. Разбираем весь путь с кодом, частой ошибкой новичков и таблицей цен на сентябрь 2026.

Что такое Qdrant и почему его берут для RAG

Qdrant — векторная база на Rust с открытым исходным кодом, заточенная под поиск по схожести и построение рекомендательных систем поверх embeddings.

Qdrant хранит не строки и колонки, а точки: у каждой точки есть ID, вектор (embedding) и payload — произвольные метаданные вроде названия документа или даты. Поиск идет не по точному совпадению, а по расстоянию между векторами в многомерном пространстве, обычно через косинусную близость.

Для RAG это то что нужно. Загружаешь embeddings своих документов, а на запрос пользователя получаешь не точное совпадение слов, а семантически близкие куски текста. Один из авторов туториалов по Qdrant прямо показывает на живом примере: запрос "seaside" находит фрагмент про "beach", хотя слова разные. По ссылке векторная база данных — что это и зачем вайбкодеру разбираем эту механику детальнее.

Как быстро запустить Qdrant через Docker

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

Для теста хватает: docker run -p 6333:6333 qdrant/qdrant. Порт 6333 — это REST API и встроенный веб-дашборд, через который видно коллекции и можно создавать их руками, без кода.

Для чего-то более серьезного добавляй volume, иначе после остановки контейнера все данные исчезнут:

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

Порт 6334 нужен для gRPC, он быстрее REST на больших нагрузках, но для первого теста не обязателен. После запуска дашборд открывается на http://localhost:6333/dashboard. Отдельно про self-hosted через Docker Compose и Kubernetes — в статье Qdrant в Docker и self-hosted: локально и в облаке.

Как установить qdrant-client для Python

Официальный python-клиент ставится одной командой pip и умеет работать как с локальным Docker-инстансом, так и с облаком без изменения кода.

pip install qdrant-client

По состоянию на август 2026 актуальная версия клиента — 1.19.0, требует Python 3.10 и выше. Библиотека содержит типы для всего API Qdrant и поддерживает как синхронные, так и асинхронные запросы.

Есть режим без сервера вообще — QdrantClient(":memory:") держит данные в оперативной памяти процесса, либо QdrantClient(path="./local_qdrant") пишет на диск. Такой local mode удобен для тестов и CI, когда поднимать Docker избыточно. Но для полноценной работы с дашбордом и persistence между запусками все же нужен сервер:

from qdrant_client import QdrantClient

client = QdrantClient(host="localhost", port=6333)

Как создать коллекцию в Qdrant

Коллекция в Qdrant — аналог таблицы, но обязательно требует указать размерность векторов и метрику расстояния при создании, иначе загрузка данных упадет с ошибкой.

Размерность вектора должна точно совпадать с размерностью модели эмбеддингов, которую используешь дальше. Это самая частая ошибка новичков: создали коллекцию с размером 384, а модель отдает вектор на 768 — Qdrant откажется грузить точки.

from qdrant_client.models import VectorParams, Distance

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

Метрика Distance.COSINE подходит для большинства текстовых embeddings, DOT и EUCLID нужны реже, под конкретные модели. Если экспериментируешь и хочешь пересоздать коллекцию с чистого листа, есть recreate_collection — удаляет старую и создает новую с теми же параметрами.

Как загрузить вектора в коллекцию

Данные в Qdrant загружаются через upsert: одна точка — это ID, вектор и опциональный payload с метаданными, загружать выгоднее батчами.

Каждая точка = PointStruct с тремя полями. Payload может содержать что угодно: текст документа, URL источника, дату, категорию. Главное — не пихать туда сам вектор, для этого есть отдельное поле.

from qdrant_client.models import PointStruct

points = [
    PointStruct(id=1, vector=[0.12, 0.05, ...], payload={"text": "первый документ", "source": "docs"}),
    PointStruct(id=2, vector=[0.31, 0.44, ...], payload={"text": "второй документ", "source": "wiki"}),
]

client.upsert(collection_name="my_collection", points=points)

На больших объемах загружай не по одной точке, а пачками через client.upload_points() или циклом по chunks — это в разы быстрее, чем по одному upsert на запрос. Для длинных текстов их сначала разбивают на куски по 300-400 символов, иначе одна embedding-модель просто не переварит документ целиком.

Как сделать первый поиск похожих векторов

Поиск в Qdrant — это запрос вектора и лимита результатов, актуальный метод в клиенте 1.19.0 — query_points, старый search еще работает, но помечен устаревшим.

Логика простая: считаешь embedding своего запроса той же моделью, что использовал для загрузки данных, и отправляешь его в Qdrant. База возвращает ближайшие точки с оценкой похожести (score).

results = client.query_points(
    collection_name="my_collection",
    query=[0.15, 0.08, ...],
    limit=5
)

for point in results.points:
    print(point.score, point.payload["text"])

Можно сразу добавить фильтр по payload — например искать только среди документов из определенного источника:

from qdrant_client.models import Filter, FieldCondition, MatchValue

results = client.query_points(
    collection_name="my_collection",
    query=[0.15, 0.08, ...],
    query_filter=Filter(must=[FieldCondition(key="source", match=MatchValue(value="wiki"))]),
    limit=5
)

Максим: «Мог просто засесть до пяти ночи и просто там править одну функцию, которая не работала. В моменте уже испотел, хотелось всё закрыть. Но понимал, что это можно решить и нужно решить, чтобы идти дальше.»

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

Qdrant Cloud или self-hosted: что выбрать в 2026

Self-hosted Qdrant бесплатен всегда, Qdrant Cloud дает постоянный бесплатный тир 0.5 vCPU / 1 GB RAM / 4 GB диска, дальше — почасовая оплата ресурсов.

Для пет-проекта или прототипа бесплатного облачного тира хватает без ограничений по времени. Self-hosted вариант выгоднее становится при больших объемах: по расчетам аналитиков рынка, на 5+ млн векторов self-hosted на VM за $150–300/мес обходится на 70–85% дешевле управляемого облака. При этом высокая доступность и резервное копирование в Qdrant Cloud входят в Standard-тир без доплаты. Из плюсов self-hosted — лицензия Apache 2.0 без ограничений, из минусов — бэкапы и мониторинг на своих плечах.

Каких ошибок избегать новичкам

Три самые частые проблемы у тех, кто впервые запускает Qdrant: несовпадение размерности вектора, отсутствие volume при Docker-запуске и загрузка точек по одной вместо батчей.

1. Первая — уже разобранная ошибка размерности.
2. Вторая: запустил Docker без -v, перезапустил контейнер, все коллекции исчезли — volume не опция, а обязательный пункт для чего угодно серьезнее теста.
3. Третья: цикл с одним upsert на точку вместо батча — работает, но на тысячах документов растягивается в разы дольше, чем должно.

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

Итог: стоит ли использовать Qdrant для своего проекта

Для любого RAG-проекта на Python, где важна скорость и гибкая фильтрация по метаданным, Qdrant — один из самых безопасных выборов на сентябрь 2026: бесплатный self-hosted вариант без ограничений, понятный python-клиент и облачный тир для тех, кто не хочет администрировать сервер. Разница с конкурентами чувствуется на масштабе — начинать проще с локального Docker-контейнера, а решение про облако принимать уже когда появится реальная нагрузка.

Глоссарий

• Embedding (вектор) — числовое представление текста, изображения или другого объекта в многомерном пространстве, обычно получают из модели глубокого обучения.
• Коллекция — аналог таблицы в Qdrant, набор точек с одинаковой размерностью векторов.
• Payload — метаданные точки: текст, дата, категория, любая дополнительная информация.
• HNSW — алгоритм приближенного поиска ближайших соседей, на нем строится быстрый поиск в Qdrant.
• Косинусная близость (cosine similarity) — метрика расстояния между векторами, самая частая для текстовых embeddings.
• Upsert — операция загрузки точек: создает новую запись или обновляет существующую по ID.

FAQ

Нужен ли Docker, чтобы начать работу с Qdrant?
Нет, для тестов есть local mode — QdrantClient(":memory:") или с сохранением на диск. Но для дашборда и полноценной работы сервер через Docker удобнее.

Какая размерность вектора нужна для коллекции?
Ровно такая, какую отдает модель эмбеддингов, которую используешь. У популярных моделей размерность обычно от 384 до 1536, точное число смотри в документации модели.

Чем query_points отличается от search?
Search — старый метод, все еще работает, но помечен устаревшим в клиенте 1.19.0. Query_points — актуальный способ делать поиск, рекомендован в текущей документации.

Можно ли фильтровать результаты поиска по метаданным?
Да, через query_filter с условиями по полям payload — например искать только среди документов одной категории или одного источника.

Сколько стоит Qdrant Cloud?
Бесплатный тир — 0.5 vCPU, 1 GB RAM, 4 GB диска навсегда без карты. Дальше — почасовая оплата ресурсов на Standard и Premium тирах.

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

Подходит ли Qdrant для продакшна или только для тестов?
Подходит для продакшна: self-hosted вариант используют компании любого размера, а Standard-тир облака дает SLA 99.5% с автобэкапами.

Источники: официальная документация Qdrant, репозиторий qdrant-client на GitHub, страница цен Qdrant Cloud.

Больше практических гайдов по AI-инструментам — в каталоге AI-инструментов VibeCoderz. Если нужна консультация по внедрению векторного поиска в свой продукт — пишите Максиму: t.me/maxnagovitsyn.

Обновлено: сентябрь 2026.