×

Создание инстанса Qdrant и первое подключение

 

ВВЕДЕНИЕ

 
Qdrant — векторная база данных для поиска по сходству. Она хранит точки: у каждой есть идентификатор, вектор (эмбеддинг) и необязательная полезная нагрузка (payload) с обычными атрибутами. По векторам Qdrant находит семантически близкие объекты, а по payload — одновременно фильтрует результаты. Типовые задачи: семантический и гибридный поиск, RAG и память AI-приложений, рекомендации, поиск дубликатов.
 
Qdrant не строит эмбеддинги сам: приложение получает их от выбранной модели и записывает в коллекцию. Исходные документы обычно хранят отдельно — так векторный индекс можно пересобрать заново.
 
В DevSpace Qdrant — управляемый сервис. Вы заполняете одну форму, а платформа разворачивает готовую к работе базу: один или несколько узлов Qdrant с постоянными дисками, сгенерированным API-ключом и, при внешнем доступе, TLS.
 
Чем это отличается от привычной установки на VM:
 
  • не нужно ставить Qdrant, настраивать службу и собирать кластер руками — при двух и более узлах кластерный режим включается автоматически
  • API-ключ генерируется платформой и хранится в секрете, а не в конфигурационном файле
  • TLS-сертификаты выпускает и продлевает платформа
  • данные каждого узла лежат на отдельном постоянном диске и переживают перезапуск
 
Здесь легко спутать две разные настройки, поэтому запомните сразу. replicas в форме создания — это число узлов Qdrant: при значении больше единицы узлы объединяются в кластер и делят данные между собой. Сколько копий будет у самих данных, задаёт не форма, а коллекция: при её создании через API указывается replication_factor, и по умолчанию он равен единице.
 
Из этого следует неочевидное: кластер из двух узлов сам по себе данные не дублирует. Пока у коллекции replication_factor: 1, каждый её кусок (шард) лежит на одном узле, и при потере узла эти шарды станут недоступны. Чтобы данные пережили отказ узла, коллекцию создают с replication_factor от 2 — пример команды есть в разделе «Проверка».
 

ПЕРЕД НАЧАЛОМ

 
Понадобятся:
 
  • доступ к пространству DevSpace и право создавать в нём сервисы
  • curlили клиент Qdrant для проверки подключения
 
Заранее прикиньте объём данных: Qdrant держит векторы и индексы в памяти, поэтому пресет ресурсов подбирают по числу и размерности векторов. Методика оценки — в руководстве Qdrant по capacity planning.
 

ПОШАГОВОЕ РУКОВОДСТВО

 

Шаг 1. Откройте Marketplace и выберите Qdrant

 
Войдите в дашборд DevSpace и откройте раздел Marketplace. Найдите карточку Qdrant (категория PaaS, подпись «Managed Qdrant vector database service») и откройте её. У формы две вкладки: Form (поля) и YAML (та же конфигурация текстом). Под полем имени показан tenant-id вашего пространства.
 

Шаг 2. Заполните поля

 
Для примера в этой статье используются значения:
 
Поле
Значение
Зачем
 Name
demo01
Имя инстанса: строчные латинские буквы, цифры, дефисы. Станет частью имён сервисов и секрета (qdrant-<name>-…).
 replicas
2
Два узла Qdrant — включается кластерный режим. 1 — одиночный узел без кластера.
 resourcesPreset
t1.small
Типовой пресет CPU и памяти каждого узла (справочник пресетов).
 size
10Gi
Постоянный диск каждого узла.
 storageClass
local
Класс хранилища. Выбор зависит от того, сколько экземпляров у сервиса и реплицирует ли он данные сам — подробнее в разделе «Параметры». После создания изменить нельзя.
 external
включено
Опубликовать Qdrant наружу через LoadBalancer. Если клиенты живут в том же пространстве — оставьте выключенным.
 tls.enabled
отмечено
Шифровать подключения к Qdrant и обмен между его узлами.
 
Дальше в статье <name> — это имя, которое вы задали в поле Name: платформа подставляет его в имена сервисов, секретов и компонентов инстанса.
Если external включён, а флажок tls.enabled вы не трогали, TLS включится автоматически, хотя флажок останется снятым. Но если флажок отметить и снять, форма запишет enabled: false — и внешний доступ пойдёт без шифрования, вместе с API-ключом. Поэтому при включённом external отмечайте tls.enabled явно и перед развёртыванием сверьте вкладку YAML: в ней должно быть enabled: true.
Подсказка: поля cpu и memory в группе resources позволяют задать ресурсы точнее пресета — заполняйте их, только когда типовых пресетов не хватает: явные значения имеют приоритет. Память указывайте с единицами измерения: 512Mi, 2Gi.
 

Шаг 3. Запустите развёртывание

 
Нажмите Deploy. Откроется карточка созданного инстанса — дождитесь статуса Ready в шапке.
 

Шаг 4. Убедитесь, что все компоненты запущены

 
Статус Ready означает, что платформа применила конфигурацию сервиса, но сами компоненты после этого ещё могут запускаться. Поэтому, прежде чем подключаться, проверьте фактическое состояние развёртывания на вкладке Workloads карточки — по смыслу это аналог systemctl status на сервере: видно, что реально запущено и готово к работе.
 
В разделе Pods этой вкладки — по строке на каждый запущенный экземпляр компонента, справа в строке — статус и счётчик готовности в формате «готово/всего». Состав строк зависит от конфигурации. Для примера из этой статьи их две:
 
  • qdrant-<name>-0и qdrant-<name>-1 — узлы Qdrant, по одному на replicas
 
Сервис готов к работе, когда в каждой строке статус Running, а числа в счётчике совпадают: 1/1, 2/2, 3/3. Значение «всего» у разных компонентов своё — важно только, чтобы числа были равны.
 
Строки со статусом Succeeded и счётчиком 0/1 — это нормально: разовая задача автоматики отработала и завершилась.
Если строка со статусом Running показывает 0/1, 1/2, 1/3, развёртывание ещё не завершилось — даже если в шапке уже Ready. Сразу после создания это нормально: компонентам нужно время на запуск. Если картина долго не меняется, откройте вкладку Events: там отображаются события запуска компонентов, по ним обычно видно, на чём запуск остановился. Если причина непонятна, обратитесь в поддержку и укажите имя инстанса. Возвращайтесь к вкладке Workloads и после изменений конфигурации: если изменение перезапускает компоненты, часть строк какое-то время будет не готова.
 

Шаг 5. Получите адрес подключения

 
На вкладке Services карточки инстанса:
 
  • qdrant-<name>— адрес для клиентов. При включённом external это LoadBalancer с внешним IP в колонке External IP
  • qdrant-<name>-headless— служебный адрес для обмена между узлами, приложениям он не нужен
 
Порты:
 
  • 6333— REST API, он же адрес веб-интерфейса
  • 6334— gRPC API, для интенсивного обмена из приложений
  • 6335— обмен между узлами Qdrant. Приложения к нему не обращаются
 
Подставьте свой адрес, и получатся рабочие ссылки:
 
Что
Адрес
 REST API
https://<внешний-IP>:6333
 Веб-интерфейс
https://<внешний-IP>:6333/dashboard
 gRPC API
<внешний-IP>:6334
 Проверка живости, без ключа
https://<внешний-IP>:6333/healthz
 
Простейшее обращение к API — список коллекций. Ключ передаётся заголовком api-key, его вы получите на шаге 6:
curl -k -H "api-key: <ключ>" https://<внешний-IP>:6333/collections
 
При включённом TLS адрес начинается с https:// — и для внешних клиентов, и для приложений из того же пространства.
При включённом external снаружи доступен и служебный порт 6335. API-ключ его не защищает, поэтому не отключайте TLS у инстанса с внешним доступом: с TLS узлы проверяют друг друга по сертификатам инстанса.
 

Шаг 6. Получите API-ключ

 
1. Откройте вкладку Secrets карточки инстанса.
2. Выберите секрет qdrant-<name>-apikey.
3. Раскройте значение api-key кнопкой с иконкой глаза и скопируйте его. Второй ключ секрета, local.yaml, — служебный, для подключения он не нужен.
 
Ключ даёт полный доступ к базе. Рекомендуем передавать его приложению через хранилище секретов, а не хранить в коде.
 

ПАРАМЕТРЫ

 
Параметр
Что делает
Значение по умолчанию
Когда менять
 replicas
Число узлов Qdrant. При значении больше 1 включается кластерный режим.
1
Больше 1 для отказоустойчивости и распределения нагрузки. Существующие шарды на новые узлы автоматически не переносятся.
 resourcesPreset
Типовой пресет CPU и памяти каждого узла (справочник пресетов).
t1.small
По объёму векторов и индексов: нехватка памяти приводит к перезапускам и медленному поиску.
 resources.cpu / resources.memory
Явные ресурсы вместо пресета.
не заданы
Когда типовых пресетов не хватает. Явные значения имеют приоритет над resourcesPreset. Память указывайте с единицами измерения: 512Mi, 2Gi.
 size
Постоянный диск каждого узла: векторы, payload, индексы.
10Gi
Под объём данных с запасом. Уменьшить диск нельзя.
 storageClass
Класс постоянного хранилища.
local — копии тома только на одном сервере
При одном экземпляре — replicated, при двух и больше обычно local, потому что ввод-вывод у replicated медленнее. Параметр неизменяемый — смена потребует нового инстанса и переноса данных. Разбор — в подсказке в конце раздела.
 external
Публикует Qdrant наружу: LoadBalancer с внешним IP и портами 6333, 6334, 6335.
false
Включайте, только если клиенты работают вне пространства через публичные сети.
 tls.enabled
TLS для REST, gRPC и обмена между узлами. Если не задан — повторяет значение external.
не задан
При внешнем доступе задавайте true явно. false при внешнем доступе пустит API-ключ и данные открытым текстом.
 
Как выбрать класс хранилища. replicated держит копии тома на нескольких серверах платформы и переживает потерю сервера, но пишет синхронно в несколько мест, поэтому ввод-вывод у него всегда медленнее, чем у local. Критерий выбора — сколько экземпляров у сервиса и реплицирует ли он данные сам между репликами:
 
  • один экземпляр — берите replicated: другой копии данных нет, и потеря сервера означает потерю тома
  • два и больше — подходит local: копия данных уже есть на других экземплярах, а replicated под таким сервисом только замедлит запись, дублируя то, что и так продублировано
Важная оговорка: коллекция Qdrant реплицируется между узлами, только если при её создании задан фактор репликации больше единицы. По умолчанию копия одна, поэтому с одним узлом и с коллекциями без репликации берите replicated.
 

ПРИМЕР КОНФИГУРАЦИИ

 
Итоговый ресурс, соответствующий шагам выше. Вкладка YAML формы показывает и принимает ту же конфигурацию.
apiVersion: apps.cozystack.io/v1alpha1
kind: Qdrant
metadata:
  name: demo01
spec:
  # Два узла: кластерный режим включается автоматически.
  replicas: 2
 
  # Типовой пресет CPU/памяти каждого узла.
  resourcesPreset: t1.small
 
  # Постоянный диск каждого узла.
  size: 10Gi
 
  # Неизменяемый параметр. В примере local, но под коллекции без репликации берите replicated.
  storageClass: local
 
  # Внешний LoadBalancer: 6333 (REST), 6334 (gRPC), 6335 (узлы).
  external: true
 
  # TLS задан явно: не зависит от случайного снятия флажка в форме.
  tls:
    enabled: true
Производные ресурсы получают префикс qdrant-: секрет qdrant-<name>-apikey, сервисы qdrant-<name> и qdrant-<name>-headless.
 

ПРОВЕРКА

 
Сначала проверьте, что Qdrant отвечает, — этот адрес работает без API-ключа. Параметр -k отключает проверку TLS-сертификата, для первой проверки этого достаточно:
curl -k https://<внешний-IP>:6333/healthz
 
Ожидаемый ответ: healthz check passed.
 
Затем запросите список коллекций с API-ключом:
curl -k -H "api-key: <ключ>" https://<внешний-IP>:6333/collections
 
В ответе должно быть "status":"ok" и пустой список collections — у нового инстанса коллекций ещё нет.
 
Теперь создайте коллекцию — и сразу с копиями данных, если узлов в инстансе больше одного. shard_number задаёт, на сколько кусков делятся данные, replication_factor — сколько копий каждого куска хранится в кластере:
curl -k -X PUT -H "api-key: <ключ>" -H "Content-Type: application/json" \
  https://<внешний-IP>:6333/collections/docs \
  -d '{"vectors": {"size": 384, "distance": "Cosine"}, "shard_number": 2, "replication_factor": 2}'
 
В ответе будет "result":true и "status":"ok". Настройки созданной коллекции покажет запрос https://<внешний-IP>:6333/collections/docs — в поле replication_factor должно стоять заданное значение.
 
replication_factorне может превышать число узлов: на инстансе из одного узла копия будет только одна. Увеличить его у существующей коллекции можно, но данные при этом перераспределяются — закладывайте время и запас места.
 
Типовые ошибки подключения: Must provide an API key or an Authorization bearer token (код 401) — не передан заголовок api-key или ключ неверный. Received HTTP/0.9 when not allowed — запрос по http:// к инстансу с TLS, используйте https://. Таймаут — внешний IP ещё не выдан или нет маршрута до него.
 

ЧТО ДАЛЬШЕ

 
  • Подключение из приложения — Qdrant работает по REST, поэтому подойдёт любой HTTP-клиент. Например, на Python — создание коллекции с копией каждого шарда на двух узлах:
    import requests
     
    url = "https://<адрес>:6333"
    headers = {"api-key": "<ключ>"}
     
    requests.put(f"{url}/collections/docs", headers=headers, verify=False,
                 json={"vectors": {"size": 384, "distance": "Cosine"}, "replication_factor": 2})
    print(requests.get(f"{url}/collections", headers=headers, verify=False).json())
     
    Параметр verify=False отключает проверку сертификата, как -k в curl. Для интенсивного обмена есть gRPC на порту 6334 и официальные клиентские библиотеки Qdrant.
     
  • Коллекции и отказоустойчивость — число шардов и число копий задаются при создании коллекции, пример команды есть в разделе «Проверка». Форма сервиса на это не влияет: она управляет только числом узлов
  • Масштабирование — replicas и пресет ресурсов меняются в той же форме. После добавления узлов перенесите на них шарды через API Qdrant. Диск можно только увеличивать, storageClass неизменяем
  • Удаление — удаление инстанса удаляет и диски с данными. Выгрузите нужные данные заранее