Qdrant - Vector Database
Universal Query API
Три API вместо одного - это три раза больше кода, тестов и потенциальных несоответствий. Universal Query унифицирует всё и добавляет возможности, которых раньше не было.
- Hybrid search (dense + sparse) за один network round-trip вместо двух
- A/B тестирование стратегий поиска без изменения клиентского кода
- Постепенный переход от simple search к multi-stage RAG пайплайну
Предварительные знания
Universal Query: единый endpoint вместо трёх
До Qdrant v1.10 существовали три отдельных endpoint: `/points/search` (поиск по вектору), `/points/recommend` (рекомендации), `/points/discover` (discovery). Каждый принимал разные параметры и возвращал немного разный формат. В v1.10 появился **Universal Query API** - единый `POST /collections/{name}/points/query`, который умеет всё.
Universal Query не просто синтаксический сахар - он открывает возможности, которые раньше были невозможны: **prefetch** (многоэтапный поиск в одном запросе) и **fusion** нескольких стратегий поиска без дополнительных round-trip'ов.
Ключевой параметр - `query`. Его тип определяет режим работы: - `float[]` → поиск ближайших соседей (ANN search) - `string` (UUID точки) → рекомендация: усредняет все векторы этой точки - `{positive: [...], negative: [...]}` → рекомендация/discovery с примерами - `{fusion: "rrf"}` → объединение результатов prefetch-запросов - `null` / отсутствует → scroll (возврат точек без ранжирования)
Что происходит, когда в Universal Query передают строку (UUID) вместо вектора?
Режимы Universal Query: от поиска до discovery
Universal Query поддерживает четыре принципиально разных режима в одном API. Разберём каждый с практическим примером.
| Режим | Тип query | Когда использовать |
|---|---|---|
| ANN Search | float[] | Есть вектор запроса (от embedder) |
| Recommend by ID | string (UUID) | «Ещё такое же» по существующему item |
| Recommend +/- | {recommend: {positive, negative}} | Персонализация с историей лайков/дизлайков |
| Discovery | {discover: {target, context}} | Exploration: похоже на A, не похоже на B |
Старые endpoint `/search`, `/recommend`, `/discover` в v1.10+ всё ещё работают для обратной совместимости, но новый код лучше писать через Universal Query - он развивается активнее.
Universal Query - это просто новое название для /points/search
Universal Query объединяет search, recommend, discover и добавляет принципиально новую возможность - prefetch для multi-stage retrieval
Prefetch позволяет выполнить несколько поисков на первом этапе и объединить их результаты (fusion) за один round-trip. Это невозможно было с предыдущими endpoint'ами.
Какой тип `query` нужен, чтобы найти продукты «похожие на A, но не такие как B», используя существующие точки в коллекции?
Prefetch: multi-stage retrieval за один round-trip
**Prefetch** - самая мощная возможность Universal Query. Он позволяет описать многоэтапный поиск как единый запрос. Классический hybrid search (dense + sparse) раньше требовал двух отдельных запросов и ручного слияния результатов на клиенте. С prefetch это происходит внутри Qdrant за один round-trip.
Prefetch поддерживает **вложенность до 2 уровней**. Это позволяет строить трёхэтапные пайплайны: сначала грубый поиск по квантизованным векторам, потом re-ranking по полным float32 векторам.
Производительность: prefetch выполняется параллельно внутри Qdrant. Два параллельных prefetch-запроса занимают столько же времени, сколько один. Это делает hybrid search с prefetch значительно быстрее, чем последовательные клиентские запросы.
Что такое `{fusion: 'rrf'}` в поле `query` Universal Query?
Итоги
- Universal Query (`POST /points/query`) — единый endpoint, заменяющий search/recommend/discover
- Тип поля `query` определяет режим: float[] = ANN, UUID = recommend, объект = recommend/discover/fusion
- Prefetch позволяет описать multi-stage retrieval в одном запросе с параллельным выполнением
- Fusion (`rrf`, `dbsf`) объединяет результаты нескольких prefetch-этапов без кода на клиенте
- Вложенные prefetch (до 2 уровней) позволяют строить трёхэтапные пайплайны reranking'а
Что дальше
Universal Query - фундамент для более сложных паттернов поиска и exploration.
- FastEmbed: эмбеддинги без GPU — Генерация dense и sparse векторов для prefetch запросов
- Discovery Search — Режим discovery в Universal Query - детальный разбор
- Hybrid Search — Предпосылки: понимание dense + sparse для prefetch
Вопросы для размышления
- Когда prefetch выгоднее двух последовательных клиентских запросов? Всегда ли это так?
- Какую стратегию fusion (rrf или dbsf) вы бы выбрали для гибридного поиска документации? Почему?
- Как бы вы спроектировали A/B тест между ANN search и hybrid search, используя Universal Query?