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

Источник: https://modelium.tech/zhurnal/qdrant-lokalno/

Qdrant можно запустить в контейнере и обратиться к его REST API на локальном порту 6333. Сначала создайте коллекцию, загрузите синтетические точки с текстом в payload и убедитесь, что запрос возвращает нужный документ. Векторы в этом тесте заданы вручную: он проверяет хранилище и API, но не качество embedding-модели или RAG; доступ к незащищённому экземпляру нельзя открывать в сеть.

**Источники просмотрены 26 сентября 2026 года.** Инструкция ниже — протокол для читателя, не отчёт о собственном запуске Modelium. На этой машине нет Docker, Podman или Qdrant, поэтому работающий поиск и требования к железу здесь не измерялись. Запрос «qdrant локально» найден в Google Suggest; частотность и динамика неизвестны.

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

Qdrant хранит точки: вектор для поиска, идентификатор и полезную нагрузку (*payload*) — например, фрагмент текста и ссылку на исходный документ [s3](#src-s3)[s4](#src-s4). Это звено между подготовкой документов и ответом локальной модели: поиск возвращает кандидатов, а модель потом может формулировать ответ. Сам Qdrant не создаёт embeddings текста и не гарантирует правильных цитат или доступа только разрешённым пользователям. Для рабочего RAG отдельно нужны модель векторизации, разграничение прав и [проверка качества поиска](/zhurnal/ocenka-kachestva-rag/) [s7](#src-s7).

Здесь задача уже́, чем в [гайде гибридного поиска](/zhurnal/gibridnyy-poisk-rag/): получить локальный ответ API, создать коллекцию, записать два **синтетических** документа и извлечь нужную точку. Векторы заданы вручную и **не являются embeddings русского текста**. Поэтому совпадение в примере проверяет проводку «вектор → точка → payload», а не смысловую близость предложений.

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

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

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

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

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

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

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

Схема коллекции задаёт `size` и метрику `distance`; в документации есть `Cosine` [s2](#src-s2)[s6](#src-s6). Здесь размерность **3 только для искусственных векторов**. Для реальной embedding-модели определите длину ответа `/api/embed` и создайте отдельную коллекцию с совпадающей размерностью [s6](#src-s6)[s7](#src-s7). Не вставляйте в одну коллекцию случайные векторы разных моделей или размеров.

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](#src-s3). Проверяйте поле `status` у обеих операций и не путайте удачный HTTP с доказательством качества поиска. Повторный upsert того же ID обновляет соответствующую точку; при тестировании сохраняйте отдельную коллекцию, чтобы не смешать её с другими данными [s3](#src-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](#src-s4). **Ожидаемый контроль для этой синтетики:** в `result.points` есть точка `id: 1` с `payload.doc_id: "demo-1"`, её следует увидеть раньше `id: 2`. Если ответ пуст, сперва проверьте создание коллекции, статус upsert и длину вектора; если payload отсутствует, проверьте `with_payload` [s2](#src-s2)[s3](#src-s3)[s4](#src-s4). Это *ожидание, выведенное из вручную заданных ортогональных векторов*, не результат измерения Modelium и не гарантия для любого набора данных.

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

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

- `connection refused` на 6333: проверьте `docker ps`, `docker logs qdrant-local-demo`, порт и интерфейс привязки [s1](#src-s1).

- Ошибка размерности при upsert/query: используйте вектор той же длины, что `size` коллекции; для реальной модели спросите длину её ответа, а не подгоняйте данные вручную [s2](#src-s2)[s6](#src-s6)[s7](#src-s7).

- Нет текста в ответе: он лежит в payload, который в Query API запрашивается явно через `with_payload` [s4](#src-s4).

- Неверный документ в предметном тесте: синтетическая проверка API не проверяет качество embedding-модели; размечайте собственные запросы и оценивайте retrieval отдельно [s7](#src-s7).

docker rm -f qdrant-local-demo

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

## Источники

1. [Qdrant — Local Quickstart](https://qdrant.tech/documentation/quickstart/) — получено 2026-09-26
2. [Qdrant API v1.18 — Create a collection](https://api.qdrant.tech/v-1-18-x/api-reference/collections/create-collection) — получено 2026-09-26
3. [Qdrant API v1.18 — Upsert points](https://api.qdrant.tech/v-1-18-x/api-reference/points/upsert-points) — получено 2026-09-26
4. [Qdrant API v1.18 — Query points](https://api.qdrant.tech/v-1-18-x/api-reference/search/query-points) — получено 2026-09-26
5. [Qdrant — Security](https://qdrant.tech/documentation/security/) — получено 2026-09-26
6. [Qdrant — Collections](https://qdrant.tech/documentation/manage-data/collections/) — получено 2026-09-26
7. [Ollama — Embeddings](https://docs.ollama.com/capabilities/embeddings.md) — получено 2026-09-26
8. [Docker Hub — официальный тег qdrant/qdrant:v1.19.1](https://hub.docker.com/v2/repositories/qdrant/qdrant/tags/v1.19.1) — получено 2026-09-26