qdrant-scaling-qps
Guides Qdrant query throughput (QPS) scaling. Use when someone asks 'how to increase QPS', 'need more throughput', 'queries per second too low', 'batch search', 'read replicas', or 'how to handle more concurrent queries'.
git clone --depth 1 https://github.com/qdrant/skills /tmp/qdrant-scaling-qps && cp -r /tmp/qdrant-scaling-qps/skills/qdrant-scaling/scaling-qps ~/.claude/skills/qdrant-scaling-qpsSKILL.md
# Scaling for Query Throughput (QPS) Throughput scaling means handling more parallel queries per second. This is different from latency - throughput and latency are opposite tuning directions and cannot be optimized simultaneously on the same node. High throughput favors fewer, larger segments so each query touches less overhead. ## Performance Tuning for Higher RPS - Use fewer, larger segments (`default_segment_number: 2`) [Maximizing throughput](https://skills.qdrant.tech/md/documentation/ops-optimization/optimize/?s=maximizing-throughput) - Enable quantization with `always_ram=true` to reduce disk IO [Quantization](https://skills.qdrant.tech/md/documentation/manage-data/quantization/) - Use batch search API to amortize overhead [Batch search](https://skills.qdrant.tech/md/documentation/search/search/?s=batch-search-api) ## Minimize impact of Update Workloads - Configure update throughput control (v1.17+) to prevent unoptimized searches degrading reads [Low latency search](https://skills.qdrant.tech/md/documentation/search/low-latency-search/) - Set `optimizer_cpu_budget` to limit indexing CPUs (e.g. `2` on an 8-CPU node reserves 6 for queries) - Configure delayed read fan-out (v1.17+) for tail latency [Delayed fan-outs](https://skills.qdrant.tech/md/documentation/search/low-latency-search/?s=use-delayed-fan-outs) ## Horizontal Scaling for Throughput If a single node is saturated on CPU after applying the tuning above, scale horizontally with read replicas. - Shard replicas serve queries from replicated shards, distributing read load across nodes - Each replica adds independent query capacity without re-sharding - Use `replication_factor: 2+` and route reads to replicas [Distributed deployment](https://skills.qdrant.tech/md/documentation/distributed_deployment/?s=replication) See also [Horizontal Scaling](../scaling-data-volume/horizontal-scaling/SKILL.md) for general horizontal scaling guidance. ## Disk I/O Bottlenecks If it is not possible to keep all vectors in RAM, disk I/O can become the bottleneck for throughput. In this case: - Upgrade to provisioned IOPS or local NVMe first. See impact of disk performance to vector search in [Disk performance article](https://qdrant.tech/articles/memory-consumption/) - Use `io_uring` on Linux (kernel 5.11+) [io_uring article](https://qdrant.tech/articles/io_uring/) - In case of quantized vectors, prefer global rescoring over per-segment rescoring to reduce disk reads. Example in the [tutorial](https://skills.qdrant.tech/md/documentation/tutorials-operations/large-scale-search/?s=search-query) - Configure higher number of search threads to parallelize disk reads. Default is `cpu_count - 1`, which is optimal for RAM-based search but may be too low for disk-based search. See [configuration reference](https://skills.qdrant.tech/md/documentation/ops-configuration/configuration/?s=configuration-options) - If still saturated, scale out horizontally (each node adds independent IOPS) ## What NOT to Do - Do not expect to optimize throughput and latency simultaneously on the same node - Do not use many small segments for throughput workloads (increases per-query overhead) - Do not scale horizontally when IOPS-bound without also upgrading disk tier - Do not run at >90% RAM (OS cache eviction = severe performance degradation)
Qdrant provides client SDKs for various programming languages, allowing easy integration with Qdrant deployments.
Guides Qdrant deployment selection. Use when someone asks 'how to deploy Qdrant', 'Docker vs Cloud', 'local mode', 'embedded Qdrant', 'Qdrant EDGE', 'which deployment option', 'self-hosted vs cloud', or 'need lowest latency deployment'. Also use when choosing between deployment types for a new project.
Guides embedding model migration in Qdrant without downtime. Use when someone asks 'how to switch embedding models', 'how to migrate vectors', 'how to update to a new model', 'zero-downtime model change', 'how to re-embed my data', or 'can I use two models at once'. Also use when upgrading model dimensions, switching providers, or A/B testing models.
Guides Qdrant monitoring and observability setup. Use when someone asks 'how to monitor Qdrant', 'what metrics to track', 'is Qdrant healthy', 'optimizer stuck', 'why is memory growing', 'requests are slow', or needs to set up Prometheus, Grafana, or health checks. Also use when debugging production issues that require metric analysis.
Diagnoses Qdrant production issues using metrics and observability tools. Use when someone reports 'optimizer stuck', 'indexing too slow', 'memory too high', 'OOM crash', 'queries are slow', 'latency spike', or 'search was fast now it's slow'. Also use when performance degrades without obvious config changes.
Guides Qdrant monitoring setup including Prometheus scraping, health probes, Hybrid Cloud metrics, alerting, and log centralization. Use when someone asks 'how to set up monitoring', 'Prometheus config', 'Grafana dashboard', 'health check endpoints', 'how to scrape Hybrid Cloud', 'what alerts to set', 'how to centralize logs', or 'audit logging'.
Different techniques to optimize the performance of Qdrant, including indexing strategies, query optimization, and hardware considerations. Use when you want to improve the speed and efficiency of your Qdrant deployment.
Diagnoses and fixes slow Qdrant indexing and data ingestion. Use when someone reports 'uploads are slow', 'indexing takes forever', 'optimizer is stuck', 'HNSW build time too long', or 'data uploaded but search is bad'. Also use when optimizer status shows errors, segments won't merge, or indexing threshold questions arise.