qdrant-search-quality-diagnosis

Diagnose Qdrant vector search quality issues using recall metrics and HNSW tuning.

3|1|Updated Nov 30, 2025
One-click install
npx skills add https://github.com/PALabs-v1/AI_friend --skill qdrant-search-quality-diagnosis-palabs-v1
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: qdrant-search-quality-diagnosis
Source: https://github.com/PALabs-v1/AI_friend/tree/main/.claude/skills/qdrant-search-quality/diagnosis
Command: npx skills add https://github.com/PALabs-v1/AI_friend --skill qdrant-search-quality-diagnosis-palabs-v1

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Vector search results that are irrelevant, missing expected matches, or degraded after configuration changes are hard to debug without a systematic method. This Skill provides a structured diagnostic workflow for Qdrant search quality problems, starting from baseline measurement and narrowing down to the root cause. ## Core Features & Use Cases - Baseline Recall Measurement: Compare approximate HNSW search against exact KNN ground truth to compute recall@k, targeting over 95% for production. - Root Cause Isolation: Distinguish between embedding model problems, HNSW parameter issues, quantization degradation, and overly restrictive filters. - Tuning Guidance: Adjust hnsw_ef, ef_construct, m, oversampling, and rescore settings, and apply ACORN for filtered queries. - Use Case: A team notices their RAG pipeline returns wrong documents after enabling binary quantization. Use this Skill to confirm quantization is the cause, then enable oversampling with rescore to recover recall. ## Quick Start Ask the assistant to diagnose why your Qdrant search results are irrelevant and measure recall@k against exact search.

Frequently Asked Questions about qdrant-search-quality-diagnosis

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I measure recall@k for Qdrant search?

Run each query twice, once with approximate HNSW search and once with exact=true, then compute recall@k from the overlap between result sets. You can also use the Qdrant Web UI ANN Recall tab for a no-code comparison.

Why is approximate search worse than exact search in Qdrant?

Approximate search underperforms when HNSW parameters are too low. Increase hnsw_ef at query time, raise ef_construct to 200 or more, and set m to 32 for high recall workloads.

Does binary quantization reduce Qdrant search quality?

Yes, binary quantization causes severe quality loss without rescoring. Always enable rescore and use oversampling of 3-5x minimum to recover recall, and test the impact on your data before production.

How do I choose the right embedding model for vector search?

Test the top MTEB models on 100-1000 sample queries from your domain and score them against a labeled set. Most search quality issues trace back to the embedding model rather than index configuration.

Why do filtered queries return poor results in Qdrant?

Filtered queries degrade when payload indexes are missing, because HNSW cannot traverse filtered-out nodes efficiently. Create payload indexes on filtered fields and consider the ACORN algorithm in Qdrant v1.16+ for filtered search.

How do I build a golden dataset to evaluate retrieval quality?

Build a labeled query set from human annotation, search logs, or LLM-synthetic data, then score retrieval with ranx. Use Recall@k for RAG, MRR for single-answer search, or NDCG@k for re-ranking, and gate CI on a metric threshold.