How mironathome/qdrant-client works
Project type and purpose
• Type: Open-source Python client library / SDK
• Purpose: Provide a unified, typed, sync/async API to interact with the Qdrant vector search engine in three modes:
• Remote via REST
• Remote via gRPC
• Local (in-process)
File structure to uncover logical layers
• Top-level package: qdrant_client/
• Subpackages:
• async_* & client_base.py – Facade classes (QdrantClient, AsyncQdrantClient)
• connection.py – Strategy for HTTP vs gRPC vs local transport
• grpc/ – Auto-generated gRPC stubs & helpers
• http/ – REST API wrappers, models, configuration, exceptions
• local/ – In-process vector store, persistence, distance computations
• embed/ – Embedding framework (FastEmbed + ONNX runtime)
• auth/ – Bearer token support
• conversions/ – Serialization/deserialization (Python ↔ Protobuf/JSON)
• uploader/ – Chunked upload strategies for large payloads (gRPC & REST)
• hybrid/ – Hybrid search/reranking formulas
• migrate/ – Version-migration scripts
• Tools & docs: code generators (tools/async_client_generator), docs/, tests/
README for additional architectural hints
• Modes (host/port, URL, cloud_inference)
• Features: sync/async parity, type hints, minimal deps, local mode
• Inference API: local vs remote
Main components & their interactions
a. Facade layer:
• QdrantClient (sync) & AsyncQdrantClient (async)
• Exposes methods: create_collection, upsert, query_points, upload_collection, etc.
b. Transport layer (Strategy pattern):
• HTTP client (requests/urllib3) ↔ qdrant_client/http/api_client.py
• gRPC client (grpcio stubs in qdrant_client/grpc/)
• Local engine (qdrant_client/local/) implements same interface
c. API wrappers:
• HTTP/API modules (collections_api.py, points_api.py, …)
• gRPC wrappers (generated stubs + helper methods)
d. Serialization layer:
• conversion.py, common_types.py – map Python models to JSON/Protobuf
e. Embedding/inference subsystem:
• qdrant_client/embed/ – ONNX model loading, inference, caching
• Invoked by QdrantClient when Document(model=…) is passed
f. Uploader subsystem:
• grpc_uploader.py & rest_uploader.py – handle chunking, retries
g. Auth subsystem:
• bearer_auth.py – inject API keys into headers
h. Persistence / Local mode:
• qdrant_client/local/qdrant_local.py – file-based or in-memory store
• Implements distance calculations, indexing, filters
i. External systems:
• Qdrant server (REST/gRPC endpoint)
• ONNX Runtime (for fastembed)
• Qdrant Cloud (remote inference API)
Architectural patterns & design principles
• Facade: QdrantClient abstracts multiple transports & underlying API complexities
• Strategy: connection.py picks HTTP vs gRPC vs local at runtime
• Adapter: local modules adapt in-process storage to the same API contracts as remote
• Single Responsibility: separate packages for transport, serialization, embedding, uploading
Detailed breakdown
• Layer 1 (Facade):
• QdrantClient / AsyncQdrantClient
• Layer 2 (Configuration & Auth):
• configuration.py (timeout, retries, grpc_port, prefer_grpc)
• bearer_auth.py → HTTP headers or gRPC metadata
• Layer 3 (Transport Strategy):
– HTTPTransport → HTTP API modules
– GRPCTransport → gRPC stubs
– LocalTransport → Local modules
• Layer 4a (HTTP Path):
• api_client.py → requests.Session
• http/api/*.py → JSON endpoints
• models/models.py → Pydantic models for request/response
• Layer 4b (gRPC Path):
• grpc/collections_pb2_grpc.py → gRPC stub class
• grpc/points_pb2_grpc.py → gRPC stub class
• Conversion layer wraps stubs in Pythonic methods
• Layer 4c (Local Path):
• local/qdrant_local.py → in-memory DB
• local/persistence.py → file-based persistence
• local/distances.py, local/geo.py → vector ops
• Layer 5 (Embedding):
• embed/embedder.py → ModelEmbedder + ONNX Runtime backend
• Called by Query/Upload flows when Document(text, model) is passed
• Layer 6 (Uploader):
• grpc_uploader.py / rest_uploader.py for bulk data
• External:
• Qdrant Server (HTTP / gRPC endpoints)
• ONNX Runtime (backend for embedding)
• Filesystem or memory for local mode