qdrant-vector-storage 0.2.2

Sync/async Qdrant clients with Markdown chunking and pluggable embedding pipeline.

qdrant_vector_storage

Библиотека предоставляет синхронный и асинхронный клиент для Qdrant, а также готовый пайплайн: Markdown → чанки → эмбеддинги → загрузка в Qdrant.

Ключевая идея: библиотека не навязывает конкретную модель эмбеддингов.
Вы передаёте объект embedder (например, fastembed.TextEmbedding), а MarkdownProcessor использует его для расчёта векторов.

---

Установка

Базовая установка (клиенты + модели данных):

pip install qdrant_vector_storage

---

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

1) Создайте embedder (пример: fastembed)

from fastembed import TextEmbedding

embedder = TextEmbedding(model_name="jinaai/jina-embeddings-v3")

2) Создайте MarkdownProcessor

from qdrant_vector_storage import MarkdownProcessor

processor = MarkdownProcessor(
    embedder=embedder,
    expected_dim=1024,
    chunk_size=1024,
    chunk_overlap=300,
)

3) Асинхронная загрузка Markdown

import asyncio
from qdrant_vector_storage import QdrantAsyncClient, Distance

async def main():
    async with QdrantAsyncClient(url="http://localhost:6333") as client:
        await client.create_collection(
            collection_name="docs",
            vector_size=1024,
            distance=Distance.COSINE,
        )

        result = await client.upload_markdown(
            collection_name="docs",
            md_input="README.md",      # путь, строка Markdown или base64(Markdown)
            processor=processor,
            processor_kwargs={"add_passage_prefix": False},
        )

        print(result)

asyncio.run(main())

4) Синхронная загрузка Markdown

from qdrant_vector_storage import QdrantSyncClient, Distance

with QdrantSyncClient(url="http://localhost:6333") as client:
    client.create_collection(
        collection_name="docs",
        vector_size=1024,
        distance=Distance.COSINE,
    )

    result = client.upload_markdown(
        collection_name="docs",
        md_input="README.md",
        processor=processor,
        processor_kwargs={"add_passage_prefix": False},
    )

    print(result)

---

Поддерживаемые форматы входа для MarkdownProcessor

MarkdownProcessor.build_chunks(...) принимает:

• строку Markdown
• строку base64(Markdown) (авто-распознавание)
• путь к файлу .md

---

Требования к embedder

MarkdownProcessor ожидает объект, у которого есть один из методов:

• embed(texts: List[str]) -> Iterable[np.ndarray]
• encode(texts: List[str]) -> Iterable[np.ndarray]

---

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

Ниже перечислены все публичные классы и методы.

1) MarkdownProcessor

MarkdownProcessor выполняет:

• загрузку Markdown (строка / base64 / путь)
• нормализацию
• разбиение на чанки
• расчёт эмбеддингов через переданный embedder

Методы MarkdownProcessor

Метод	Входные параметры	Выход	Назначение
MarkdownProcessor()	embedder: объект с .embed(List[str], **kwargs) или .encode(List[str], **kwargs); chunk_size: int = 900; chunk_overlap: int = 120; keep_headings: bool = True; keep_code_blocks: bool = True; batch_size: int = 64; expected_dim: Optional[int] = None	MarkdownProcessor	Создание процессора Markdown
build_chunks()	source: Union[str, PathLike]; source_name: Optional[str] = None; assume_base64_if_looks_like: bool = True; **kwargs	List[TextChunk] (вектор заполнен)	Полный пайплайн: загрузка → чанки → эмбеддинги
embed_query()	query_text: str; **kwargs	List[float]	Эмбеддинг запроса

---

2) QdrantSyncClient / QdrantAsyncClient

Синхронный и асинхронный клиенты для Qdrant с идентичным набором методов. Различаются только синтаксисом вызова: синхронные методы vs async/await.

Конструктор

Метод	Входные параметры	Выход	Исключения	Описание
QdrantSyncClient() QdrantAsyncClient()	url: str; api_key: Optional[str]; timeout: int = 60; **kwargs	объект клиента	ConnectionError	Инициализация подключения к Qdrant

Управление коллекциями

Метод	Входные параметры	Выход	Исключения	Описание
create_collection()	collection_name: str; vector_size: int; distance: Distance = Distance.COSINE; on_disk_payload: bool = True; **kwargs	Dict[str, Any]	CollectionExistsError QdrantError	Создание новой коллекции
get_collection_info()	collection_name: str	Dict[str, Any] – информация о коллекции	CollectionNotFoundError QdrantError	Получение информации о коллекции
list_collections()	–	List[str]	QdrantError	Получение списка всех коллекций
delete_collection()	collection_name: str	bool – успех операции	–	Удаление коллекции

Загрузка данных

Метод	Входные параметры	Выход	Исключения	Описание
upload_points()	collection_name: str; points: List[Point]; batch_size: int = 100; wait: bool = True	List[str]	CollectionNotFoundError QdrantError	Загрузка точек в коллекцию
upload_markdown()	collection_name: str; md_input: Union[str, PathLike] – Markdown (текст/base64/путь); processor: MarkdownProcessor; source_name: Optional[str]; metadata: Optional[Dict]; batch_size: int = 100; wait: bool = True; processor_kwargs: Optional[Dict] = None	FileUploadResult – результат загрузки	CollectionNotFoundError FileProcessingError EmbeddingError QdrantError	Загрузка Markdown с автоматической векторизацией

Удаление данных

Метод	Входные параметры	Выход	Исключения	Описание
delete_points()	collection_name: str; point_ids: Optional[List[str]]; filter_condition: Optional[Dict]; wait: bool = True	int – количество удаленных точек	CollectionNotFoundError QdrantError	Удаление точек по ID или фильтру

Поиск (универсальный метод)

Метод	Входные параметры	Выход	Исключения	Описание
search()	collection_name: str; query_vector: Optional[List[float]]; query_point_id: Optional[Union[str, int]]; filter_condition: Optional[Dict]; limit: int = 10; score_threshold: Optional[float] = None; with_payload: bool = True; search_mode: Literal["vector", "id", "filter", "hybrid"]	List[SearchResult] – результаты поиска	CollectionNotFoundError QdrantError ValueError	Универсальный поиск – векторный, по ID, по фильтру или гибридный

Вспомогательные методы

Метод	Входные параметры	Выход	Исключения	Описание
count_points()	collection_name: str; filter_condition: Optional[Dict]; exact: bool = False	int – количество точек	CollectionNotFoundError QdrantError	Подсчет точек в коллекции
healthcheck()	–	bool – доступен ли Qdrant	–	Проверка подключения к Qdrant
close()	–	None	–	Закрытие соединения

3) Режимы поиска в методе search()

Режим	Обязательные параметры	Дополнительные параметры	Описание
'vector'	query_vector	filter_condition	Классический поиск по вектору с опциональной фильтрацией
'id'	query_point_id	filter_condition	Поиск точек, похожих на точку с указанным ID
'filter'	filter_condition	–	Поиск только по фильтру без вектора
'hybrid'	query_vector	filter_condition	Гибридный поиск с RRF (вектор + фильтр)

4) Утилиты

FilterBuilder

Метод	Входные параметры	Выход	Назначение
FilterBuilder.build_filter()	condition: Dict[str, Any]	`models.Filter	None`

Конвертеры

Функция	Входные параметры	Выход	Назначение
chunks_to_points()	chunks: List[TextChunk]; base_metadata: Optional[Dict[str, Any]] = None; id_factory: Optional[callable] = None	List[Point]	Преобразование чанков в точки для upsert