Qdrant локально: установка и проверка поиска по документам

Что делает Qdrant и когда он нужен?

Qdrant хранит точки: вектор для поиска, идентификатор и полезную нагрузку (payload) — например, фрагмент текста и ссылку на исходный документ s3s4. Это звено между подготовкой документов и ответом локальной модели: поиск возвращает кандидатов, а модель потом может формулировать ответ. Сам Qdrant не создаёт embeddings текста и не гарантирует правильных цитат или доступа только разрешённым пользователям. Для рабочего RAG отдельно нужны модель векторизации, разграничение прав и проверка качества поиска s7.

Здесь задача уже́, чем в гайде гибридного поиска: получить локальный ответ API, создать коллекцию, записать два синтетических документа и извлечь нужную точку. Векторы заданы вручную и не являются embeddings русского текста. Поэтому совпадение в примере проверяет проводку «вектор → точка → payload», а не смысловую близость предложений.

Что подготовить и как не открыть хранилище наружу?

Нужны запущенный Docker, доступ к загрузке образа и свободный локальный порт 6333. В quickstart Qdrant данные сохраняются в каталоге, смонтированном в /qdrant/storage; REST API работает на 6333, а gRPC — на 6334 s1. Для этого REST-примера второй порт не нужен. Проверяйте права к каталогу и свободное место на своей машине; минимальные RAM/VRAM из размера образа или этой демонстрации не выводятся.

Официальный quickstart предупреждает: self-hosted Qdrant по умолчанию без аутентификации и шифрования s1s5. Демонстрация привязывает 6333 только к 127.0.0.1 хоста. Это не заменяет изоляцию контейнера, firewall и политику доступа: на общем или удалённом сервере не используйте реальную клиентскую базу, пока не настроены private network, ключи и TLS s5. Если Docker запущен в виртуальной машине или удалённо, 127.0.0.1 относится к хосту демона Docker, а не обязательно к вашему ноутбуку.

Тег qdrant/qdrant:v1.19.1 существует в официальном Docker Hub; опубликованный digest multi-platform манифеста зафиксирован в источнике. Для воспроизводимой установки на конкретной платформе следует фиксировать и проверять соответствующий digest перед рабочим деплоем; плавающий latest не используем s8. Команды базовых REST-операций сверены с версионированной веткой API 1.18 и текущей веткой 1.19 s2s3s4.

mkdir -p qdrant_storage
docker pull qdrant/qdrant:v1.19.1
docker run -d --name qdrant-local-demo \
-p 127.0.0.1:6333:6333 \
-v "$PWD/qdrant_storage:/qdrant/storage" \
qdrant/qdrant:v1.19.1
curl -fsS http://127.0.0.1:6333/

Если образ не стартует, смотрите docker logs qdrant-local-demo, проверьте занятость порта и доступ контейнера к каталогу. На Linux с SELinux для bind mount может потребоваться суффикс :z, как в официальном quickstart s1. Не подставляйте в диагностическую команду URL публичного сервера, если не готовы защищать API.

Как создать коллекцию и загрузить тестовые документы?

Схема коллекции задаёт size и метрику distance; в документации есть Cosine s2s6. Здесь размерность 3 только для искусственных векторов. Для реальной embedding-модели определите длину ответа /api/embed и создайте отдельную коллекцию с совпадающей размерностью s6s7. Не вставляйте в одну коллекцию случайные векторы разных моделей или размеров.

curl -fsS -X PUT 'http://127.0.0.1:6333/collections/demo_docs' \
-H 'Content-Type: application/json' \
-d '{"vectors":{"size":3,"distance":"Cosine"}}'

curl -fsS -X PUT 'http://127.0.0.1:6333/collections/demo_docs/points?wait=true' \
-H 'Content-Type: application/json' \
-d '{"points":[
{"id":1,"vector":[1,0,0],"payload":{"doc_id":"demo-1","text":"Синтетический документ о клапане","source":"fixture-1"}},
{"id":2,"vector":[0,1,0],"payload":{"doc_id":"demo-2","text":"Синтетический документ о насосе","source":"fixture-2"}}
]}'

Endpoint upsert принимает points с id, vector и payload; флаг wait=true просит дождаться завершения операции s3. Проверяйте поле status у обеих операций и не путайте удачный HTTP с доказательством качества поиска. Повторный upsert того же ID обновляет соответствующую точку; при тестировании сохраняйте отдельную коллекцию, чтобы не смешать её с другими данными s3.

Как проверить выдачу и отличить её от качества RAG?

curl -fsS -X POST 'http://127.0.0.1:6333/collections/demo_docs/points/query' \
-H 'Content-Type: application/json' \
-d '{"query":[1,0,0],"limit":2,"with_payload":true}'

По контракту Query API запрос включает вектор и может вернуть payload, если передать with_payload: true s4. Ожидаемый контроль для этой синтетики: в result.points есть точка id: 1 с payload.doc_id: "demo-1", её следует увидеть раньше id: 2. Если ответ пуст, сперва проверьте создание коллекции, статус upsert и длину вектора; если payload отсутствует, проверьте with_payload s2s3s4. Это ожидание, выведенное из вручную заданных ортогональных векторов, не результат измерения Modelium и не гарантия для любого набора данных.

Для предметной проверки RAG подготовьте набор вопросов и известных исходных фрагментов, посчитайте embeddings одной и той же моделью и для записи, и для запроса, затем сравните top-k с эталоном s7. Ollama документирует локальный /api/embed и пример embeddinggemma, но реальная размерность зависит от выбранной модели и её версии s7. После проверки простого API перейдите к гибридному поиску и отдельно проверьте цитату в ответе, права на документ и сеть. Такой маршрут связывает задачу, embedding-модель, доступное железо, runtime, инструкцию и измеримый результат; никакой процент точности мы не обещаем.

Что делать при ошибке и как удалить демонстрацию?

• connection refused на 6333: проверьте docker ps, docker logs qdrant-local-demo, порт и интерфейс привязки s1.
• Ошибка размерности при upsert/query: используйте вектор той же длины, что size коллекции; для реальной модели спросите длину её ответа, а не подгоняйте данные вручную s2s6s7.
• Нет текста в ответе: он лежит в payload, который в Query API запрашивается явно через with_payload s4.
• Неверный документ в предметном тесте: синтетическая проверка API не проверяет качество embedding-модели; размечайте собственные запросы и оценивайте retrieval отдельно s7.

docker rm -f qdrant-local-demo

Если тестовые данные больше не нужны, после проверки pwd и содержимого qdrant_storage удалите именно созданный в текущем каталоге тестовый каталог (rm -rf -- qdrant_storage). Производственные данные и резервные копии в него не входят.