DOCSEARCHbyAlgolia
Submit Docs

Qdrant Skills

repository·main·Indexed 41 days ago

https://github.com/qdrant/skills

Specialized knowledge encoded for coding agents to assist with engineering decisions for Qdrant vector search, including scaling, performance optimization, and model migration. Provides the Qdrant Advisor meta-skill for live guidance via skills.qdrant.tech and supports integration with Claude Code, Cursor, and Model Context Protocol (MCP) servers.

Tokens
38.1K
Snippets
36
Records
183
Agent score
54%

What's inside Qdrant Skills

  1. Diagnose Qdrant search quality issues with the qdrant-search-quality-diagnosis skill

    main

    The qdrant-search-quality-diagnosis skill is designed to help identify why search results are irrelevant, missing matches, or experiencing low recall. It provides guidance for several specific failure modes:

    • Unknown cause: Use when results are irrelevant or missing expected matches. Isolate whether the problem is the embedding model (Exact search is bad) or the HNSW index (Exact search is good, but approximate search is bad).
    • Approximate search worse than exact: Use when HNSW misses results that exact KNN finds. This typically requires tuning HNSW parameters or quantization settings.
    • Wrong embedding model: Use when even exact search returns poor results. This indicates the vector representation itself is insufficient for the task.
    • Unoptimized search pipeline: Use when the model is correct but results are still suboptimal.
    • Missing evaluation baselines: Use when you need to establish a 'golden set' or ground truth to measure metrics like Recall, MRR, or NDCG.

    Key Diagnostic Rule:

    • Exact search bad $\rightarrow$ Problem with the embedding model or search pipeline.
    • Exact search good + Approximate search bad $\rightarrow$ Problem with HNSW/Index tuning.

  2. Choose the right Qdrant deployment option

    main

    Selecting a Qdrant deployment depends on your requirements for operational overhead, control, latency, and compliance. The four primary paths are:

    1. Prototyping/Testing: Use Local Mode (Python only) for zero-dependency, in-memory, or disk-persisted testing. Note that local mode data is not compatible with the Qdrant server and should not be used for production or benchmarking.
    2. Self-Hosted Production: Use Docker if you need full control over infrastructure and are prepared to manage upgrades, backups, scaling, and monitoring yourself. For multi-node clusters, you must manually set up distributed mode.
    3. Managed Production (Zero-Ops):
      • Qdrant Cloud: Best for managed infrastructure with automatic backups, scaling, and monitoring.
      • Hybrid Cloud: Best when you have data-residency or compliance requirements that prevent using Qdrant-operated infrastructure, but you still want a managed control plane on your own VPC/infrastructure.
    4. Low Latency/Edge: Use Qdrant EDGE for in-process search on edge devices where network round-trips are unacceptable. It uses the same data format as the server and can sync via shard snapshots, but it is limited to single-node features only (no distributed mode).

  3. Diagnose and improve Qdrant search relevance with the qdrant-search-quality skill

    main

    The qdrant-search-quality skill is designed to help developers diagnose and improve search relevance in Qdrant. It is specifically intended for scenarios involving 'bad' or 'irrelevant' results, low precision/recall, or uncertainty regarding embedding models and hybrid search strategies.

    Important Note: Most quality issues stem from the embedding model or the data (e.g., poor chunking strategies) rather than Qdrant's internal configuration. It is recommended to rule out data/model issues with exact search before tuning Qdrant parameters.

  4. What is a feedback model and how to choose one

    main

    A feedback model is any model that produces a float relevance score for (query, document) pairs, where higher scores must always mean higher relevance.

    Examples:

    • Cross-encoders
    • Embedding similarity (e.g., cosine similarity or max_sim for late interaction models)
    • LLM-based scorers
    • Custom rankers

    Requirements for success:

    • Consistency: The exact same model used during training (calibration) must be used during inference. Weights are calibrated to the model's specific score distribution.
    • Signal Quality: The model must actually improve ranking quality when used as a reranker. If it doesn't provide a meaningful signal to a reranker, it won't help RF.
    • Score Separation: The model should provide good score separation in the middle range (distinguishing between documents that are neither clearly relevant nor clearly irrelevant).

  6. Reduce redundancy using MMR (Maximal Marginal Relevance)

    main

    If your top results are redundant, near-duplicates, or lack diversity (common in academic papers or product catalogs), use MMR (available in v1.15+).

    MMR is a query parameter that uses a diversity value to balance relevance and diversity:

    • Start with diversity=0.5.
    • Lower values: Increase precision (more relevant, less diverse).
    • Higher values: Increase exploration (more diverse, potentially less precise).

    Note: MMR is slower than standard search. Only use it when redundancy is a documented problem.

  8. The Skill Evaluation Matrix and Execution

    main

    Every test prompt is evaluated across a 2×2 matrix using two models (Sonnet and Haiku) under two conditions (no skill and with skill).

    To ensure statistical reliability, each cell in the matrix is run k times (default k=2). The results are averaged over these repetitions, and the spread is reported.

    Execution Details:

    • Prompts: All *.json files in evals/test-prompts/ (excluding those with the discord- prefix).
    • With Skill Arm: The skill is explicitly installed into the container at ~/.claude/skills/<name>/ before the run.
    • No Skill Arm: The prompt is run in a fresh container with no skill installed.
    • Availability Check: A hard check ensures the skill appears in the run's init skill list. If absent, the run is marked invalid and excluded from scoring.

  10. Steer search results using Recommendation or Discovery APIs

    main

    When you can provide positive and negative example points to steer the search, use one of the following APIs:

    • Recommendation API: Uses positive and negative examples to recommend fitting vectors. Use the Best score strategy if you have diverse examples or want to support negative-only steering.
    • Discovery API: Uses context pairs (positive/negative) to constrain search regions without requiring a specific request target.

  11. Improve precision with Multistage queries or Reranking

    main

    Use this strategy when you have good recall (the right documents exist in the results) but poor precision (the right documents are not in the top-K results, e.g., they are in the top-100 but not the top-10).

    Implementation options:

    • Multistage queries: Use for example with late interaction rerankers through Multivectors.
    • Cross-encoder rerankers: Use FastEmbed Rerankers to re-score candidates.

  12. How scaling for query volume works in Qdrant

    main

    When performing high-limit queries across multiple shards, Qdrant can use a subsampling strategy to reduce inter-shard data transfer. Instead of every shard returning the full requested limit (which causes massive data transfer when multiplied by the number of shards), each shard returns a smaller subset of results calculated using Poisson distribution statistics. This is effective because auto-sharding ensures data is distributed randomly and independently across shards.

    Activation Criteria

    This scaling strategy activates automatically when the following conditions are met:

    • The collection has more than 1 shard.
    • Auto-sharding is in use (all queried shards share the same shard key).
    • The query is not an exact search.
    • The query's limit + offset is greater than or equal to the SHARD_QUERY_SUBSAMPLING_LIMIT (default is 128).

    Tradeoffs

    This method trades a very small probability of slightly incomplete results for a significant reduction in network overhead. The strategy uses a 1.2x safety factor and a 99.9% Poisson threshold to keep error rates extremely low, making the inaccuracy comparable to the approximation errors already present in HNSW indices.