Русский | English
npm

Qdrant API на YDB

Qdrant‑совместимый REST API сервис и Node.js‑библиотека для хранения векторов в YDB с точным top‑k поиском поверх глобальной one-table схемы — без отдельного кластера векторной БД.

Изучить на GitHubАрхитектура и диаграммы →
Публичный demo‑endpoint: http://ydb-qdrant.tech:8080Проверяем…

Идеально как базовый URL Qdrant для IDE‑агентов (Roo Code, Cline), RAG‑сервисов и коллекций на миллионы векторов в YDB.

Почему YDB‑Qdrant

Персистентное хранение

Данные записываются в распределённое хранилище YDB. Локальный all-in-one образ может сохранять данные embedded YDB между рестартами при подключённом volume.

Транзакционность и консистентность

Сервис опирается на распределённые ACID‑транзакции YDB с изоляцией Serializable, поэтому векторы живут рядом с основными бизнес‑данными.

Единая платформа данных

Строки, события и векторы хранятся в одной базе YDB — запросы пишутся на YQL, векторы хранятся прямо в YDB.

Надёжность и эксплуатация

Используйте multi‑AZ, backup/restore и disaster recovery YDB вместо самостоятельной эксплуатации кластера Qdrant.

One-table модель хранения

Метаданные коллекций хранятся в qdr__collections, точки — в qdrant_all_points; сервис отслеживает время последнего доступа к коллекции.

Гибкая интеграция

Можно использовать как hosted HTTP‑endpoint, так и Node.js‑пакет ydb-qdrant прямо внутри вашего бэкенда.

Сравнение: YDB-Qdrant vs. Standalone Qdrant

ФункцияYDB-QdrantStandalone Qdrant
Движок храненияYDB (Distributed SQL)RocksDB / In-memory
КонсистентностьСтрогая (ACID Serializable)Eventual / Настраиваемая
МасштабируемостьГоризонтальная (YDB)Шардирование (ручное/managed)
Язык запросовQdrant REST API (YQL внутри)Qdrant API (gRPC/REST)
Сложность эксплуатацииНизкая (переиспользование YDB)Средняя (отдельный кластер)

Где лучше всего подходит

  • Для прототипов и экспериментов с векторным поиском на YDB.
  • Для коллекций на миллионы векторов в YDB с настройкой ресурсов и задержек под конкретный deployment.
  • Для IDE‑агентов (Roo Code, Cline), ожидающих Qdrant API.
  • Для сервисов, которые уже используют YDB и хотят быстро добавить векторный поиск (через HTTP или как Node.js‑пакет ydb-qdrant).

Планы

  • Усиление аутентификации по тенантам (IAM/OAuth, ACL на коллекции) поверх текущей namespace-изоляции через api-key/userUid.
  • Квоты и rate limiting по тенантам (коллекции, RPS, размеры payload и батчей) плюс расширенный аудит операций.
  • Операционные профили для deployment с миллионами векторов: capacity planning, load-тесты и SLO-дашборды.
  • Снижение задержек для высоконагруженных сценариев через тюнинг запросов, батчинг и scaling patterns.
  • Расширение покрытия Qdrant API на YDB (более широкие фильтры, facets, recommend/discover, batch‑поиск и др. расширенные режимы).
  • Гибридный поиск, сочетающий векторное сходство с фильтрацией по payload для более точной выборки.
Как это работает под капотом
Поток запросов: IDE/Agent → ydb-qdrant (Node.js) → глобальная таблица точек в YDB

Документация

Быстрый старт

Настройка в Roo Code/Kilo Code

Публичный demo‑endpoint для IDE: http://ydb-qdrant.tech:8080Проверяем…

Публичный demo‑endpoint для IDE: http://ydb-qdrant.tech:8080 (вставьте в IDE/агент как базовый URL Qdrant). Используйте api-key для стабильной изоляции.

Самостоятельный хостинг (Node.js)

  1. Клонируйте репозиторий и установите зависимости: npm install
  2. Укажите переменные окружения: YDB_QDRANT_ENDPOINT, YDB_QDRANT_DATABASE
  3. Настройте аутентификацию через переменные окружения: YDB_SERVICE_ACCOUNT_KEY_FILE_CREDENTIALS | YDB_METADATA_CREDENTIALS | YDB_ACCESS_TOKEN_CREDENTIALS | YDB_ANONYMOUS_CREDENTIALS
  4. Запустите: npm run dev (разработка) или npm start (прод)
  5. Укажите клиенту базовый URL: http://localhost:8080

Также можно запускать как контейнер (Docker или docker-compose) с публичным образом ghcr.io/astandrik/ydb-qdrant:latest.

Запуск через Docker / docker-compose

  1. Скачайте образ: docker pull ghcr.io/astandrik/ydb-qdrant:latest
  2. Запустите через Docker:
    docker run -d --name ydb-qdrant \
  -p 8080:8080 \
  -e YDB_QDRANT_ENDPOINT=grpcs://ydb.serverless.yandexcloud.net:2135 \
  -e YDB_QDRANT_DATABASE=/ru-central1/<cloud>/<db> \
  -e YDB_SERVICE_ACCOUNT_KEY_FILE_CREDENTIALS=/sa-key.json \
  -v /abs/path/sa-key.json:/sa-key.json:ro \
  ghcr.io/astandrik/ydb-qdrant:latest
  3. Или через docker-compose: docker-compose up -d с примером конфигурации из README.

Подробнее и все примеры: GitHub README

Использование как Node.js библиотеки

  1. Установка: npm install ydb-qdrant
  2. Использование:
    import { createYdbQdrantClient } from "ydb-qdrant";

const client = await createYdbQdrantClient({
  apiKey: "my-stable-namespace-key",
  endpoint: "grpcs://ydb.serverless.yandexcloud.net:2135",
  database: "/ru-central1/...",
  // Аутентификация через YDB_*_CREDENTIALS env vars
});

См. npm package для подробностей.

Всё-в-одном: локальный YDB + ydb-qdrant (Docker)

  1. Запустите один контейнер со встроенным локальным YDB:
    docker run -d --name ydb-qdrant-local \
  -p 8080:8080 -p 8765:8765 \
  ghcr.io/astandrik/ydb-qdrant-local:latest
  2. Порты: 8080 — API ydb-qdrant, 8765 — YDB Embedded UI
  3. Укажите клиенту базовый URL: http://localhost:8080

Идеально для локальной разработки без внешнего кластера YDB. См. GitHub README для подробностей.

API кратко

Назначение

Используйте как базовый URL Qdrant для IDE‑агентов или приложений; векторы хранятся в YDB.

Особенности

  • Совместимые с Qdrant эндпоинты (коллекции, точки, search/query aliases)
  • Точный top‑k поиск по сериализованным векторам в YDB
  • Пакетные upsert и delete для массовых операций
  • Коллекции на миллионы векторов в YDB при настройке ресурсов deployment
  • Изоляция namespace через api-key с опциональным суффиксом X‑Tenant‑Id
  • Фильтры pathSegments.* для search, query и delete
  • Отслеживание последнего доступа к коллекциям для управления тенантами
  • Самохостинг или публичный demo‑endpoint
  • Также доступен как Node.js‑библиотека (createYdbQdrantClient)

Использование как HTTP‑сервис

curl -X PUT http://ydb-qdrant.tech:8080/collections/mycol \
  -H 'Content-Type: application/json' \
  -H 'api-key: demo-key' \
  -d '{"vectors":{"size":384,"distance":"Cosine","data_type":"float"}}'


curl -X POST http://ydb-qdrant.tech:8080/collections/mycol/points/upsert \
  -H 'Content-Type: application/json' \
  -H 'api-key: demo-key' \
  -d '{"points":[{"id":"1","vector":[0.1,0.2,...384 vals...]}]}'


curl -X POST http://ydb-qdrant.tech:8080/collections/mycol/points/search \
  -H 'Content-Type: application/json' \
  -H 'api-key: demo-key' \
  -d '{"vector":[0.1,0.2,...],"top":10,"with_payload":true,"score_threshold":0.4}'

Использование как Node.js‑пакет

// Установка: npm install ydb-qdrant
import { createYdbQdrantClient } from "ydb-qdrant";


async function main() {
  const client = await createYdbQdrantClient({
    apiKey: "my-stable-namespace-key",
    endpoint: "grpcs://lb.etn01g9tcilcon2mrt3h.ydb.mdb.yandexcloud.net:2135",
    database: "/ru-central1/b1ge4v9r1l3h1q4njclp/etn01g9tcilcon2mrt3h",
  });


  await client.createCollection("documents", {
    vectors: {
      size: 1536,
      distance: "Cosine",
      data_type: "float",
    },
  });


  await client.upsertPoints("documents", {
    points: [
      { id: "doc-1", vector: [/* embedding */], payload: { title: "Doc 1" } },
    ],
  });


  const result = await client.searchPoints("documents", {
    vector: [/* query embedding */],
    top: 10,
    with_payload: true,
  });


  console.log(result.points);
}
Проверка состояния: GET /health → {"status":"ok"}