1. 基本信息
| 项目 | 内容 | 数据来源 |
|---|---|---|
| 名称 | qdrant-search-quality-qdrant-skills | — |
| 项目自述名称 | SKILL.md 中自身命名为 qdrant-search-quality |
GitHub |
| 作者/维护者 | Qdrant 官方（qdrant/skills 仓库）；该子技能由 8 位贡献者共同维护，其中包括 Qdrant CTO Andrey Vasnetsov 本人 |
GitHub API |
| 来源链接 | https://github.com/qdrant/skills/tree/main/skills/qdrant-search-quality | — |
| 许可证 | Apache License 2.0 | GitHub API |
| GitHub Stars / Forks | 所属仓库 208★ / 23 forks（该数字属于整个 Qdrant Agent Skills 合集，不代表本子技能个体热度，仅供了解所属仓库规模） | GitHub API |
| 最新版本 | 仓库整体 v0.1.0（2026-03-30 发布）；本子技能最近一次提交 2026-07-07，仓库整体最近推送 2026-07-21 | GitHub API |
| 安装方式 | 见第 10 章 | 官方 README |
2. 功能介绍与亮点
qdrant-search-quality 是 Qdrant 官方技能合集里专门诊断与改善向量检索相关性的参考型 skill，内容分两支：
- 诊断分支（diagnosis）：判断问题到底出在嵌入模型、Qdrant 配置还是数据管道——先用精确检索（exact KNN）建立基线，再与近似检索（HNSW）结果对比来定位问题层级；给出 HNSW 参数（
ef/m/ef_construct）调优思路、量化后质量损失的排查方法、文档切分（chunking）不当可致召回下降 30-40% 等具体经验值；并指导如何用标注数据集计算 Recall@k、MRR、NDCG 等检索质量指标。 - 搜索策略分支（search-strategies）：覆盖混合检索（向量+关键词）、多阶段查询与交叉编码器重排序、结果多样性控制（MMR）、基于正负样例的推荐/发现 API、业务权重打分等策略的适用场景与取舍。
主要亮点：
- 按“症状”而非“按功能”组织内容，每节开头即给出触发条件（如“结果不相关”“召回不足”“结果太相似”），便于 agent 直接定位到对应指导
- 每节附“不该做什么”清单，记录容易被误用的调优技巧
- Qdrant CTO 本人参与提交维护，近 4 个月内持续更新（33 次提交、8 位贡献者、3 个专属 PR）
- 纯本地静态 Markdown 内容，不依赖运行时联网抓取，离线也可使用
3. 适用场景
所属分类：工程效率与代码质量。适合用 Claude Code、Codex 等 agent 构建基于 Qdrant 的向量检索、RAG 应用的开发者与数据团队，尤其在生产环境出现“检索结果不相关”“质量随数据增长或量化后下降”“不确定该换嵌入模型还是上混合检索/重排序”等具体问题时，为 agent 提供诊断路径与处置步骤，减少盲目调参。
4. 跨 Agent 兼容性
- Claude Code：原生支持——官方仓库 README 的 Installation 章节列出
~/.claude/skills/目录，并提供插件市场一条命令安装路径 - Codex：原生支持——同一张表格明确列出 OpenAI Codex 及其技能目录
~/.codex/skills/ - OpenClaw：未验证——已抓取材料中未提及
- Hermes Agent：未验证——已抓取材料中未提及
5. 推荐理由
Qdrant 官方出品、CTO 亲自参与维护的向量检索质量诊断参考技能，把“搜索结果不相关”这类常见却难排查的问题变成结构化的诊断决策树，帮助 agent 更准确地定位问题出在嵌入模型、配置还是数据管道，而不是盲目试参数。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | 该子技能自身有 33 次提交、8 位贡献者（含 CTO 本人）参与，另有 3 个专属 PR 与 3 个 issue 讨论其内容；所属仓库 208★ 仅供背景参考，不计入本技能个体评分 |
| 可用性 | 9 | 整包一条命令或手动复制目录即可安装；SKILL.md 结构清晰、含具体诊断步骤与外部文档链接；最近一次提交在近期，仓库整体持续更新；无付费依赖 |
| 安全性 | 9 | 见下方检查清单 |
安全检查清单：
① 执行 shell 命令——不涉及，front matter 声明的 allowed-tools 仅为 Read/Grep/Glob，无 Bash 执行权限
② 联网外发数据——不涉及，内容为本地静态参考文档，文中的外部链接指向 Qdrant 官方文档镜像站，需使用者自行选择是否访问，技能本身不会自动外发数据
③ API key/凭据——不需要，纯诊断建议类内容
④ 可疑指令——检查 SKILL.md 及嵌套子文件原文，未见 prompt injection 或混淆代码迹象
⑤ 作者信誉——Qdrant 官方组织出品，CTO 本人具名参与提交
⑥ License——Apache-2.0，明确
⑦ 维护时间——近期仍有提交，非弃置项目
综合评分：8.3（三项均值）
7. 跟同类 Skills 相比的优势
| 项目 | 定位 | 与 qdrant-search-quality 的差异 |
|---|---|---|
| pgvector-semantic-search（timescale/pg-aiguide） | 面向 PostgreSQL + pgvector 扩展的检索调优参考，覆盖索引选型、量化、容量规划 | 聚焦“如何正确搭建”（选索引、给默认配置），不是针对已上线系统“结果为什么不对”的诊断决策树；且面向的是 Postgres 数据库扩展，而非专用向量数据库 |
| Mixedbread Skills（mixedbread-ai/skills） | 全托管语义搜索与文档解析平台的官方技能包 | 把检索能力封装成远端 API，用户既不需要也无法调整底层索引参数，遇到质量问题时没有本地可诊断的配置层 |
qdrant-search-quality 的差异化在于面向一个已实际部署的开源向量数据库，提供从“结果不对”这一现象反推到嵌入模型、HNSW 参数、量化、数据管道等根因的诊断路径，而不是一次性的建库配置指南或黑盒托管服务。
8. 用户评价
该技能目前在第三方平台尚无具名用户评价。
9. 其他补充
该子技能所属的 qdrant/skills 合集共含 10 个静态专项技能（涵盖 SDK 使用、扩缩容、性能优化、监控、多租户、部署选型、模型迁移、版本升级等）与 1 个动态入口技能（qdrant-advisor）。GitHub 官方维护的 Copilot 技能合集仓库 github/awesome-copilot（36,987★）也原样收录了 qdrant-search-quality，说明其内容已被其他技能分发渠道二次采纳。
10. 安装使用方式
- npx（完整安装，含本技能在内的全部专项技能）：
npx skills add qdrant/skills - Claude Code 插件市场：
/plugin marketplace add qdrant/skills，再/plugin install qdrant@qdrant - 手动安装：clone 仓库后，将
skills/qdrant-search-quality/整个目录复制到对应 agent 的技能目录——Claude Code 为~/.claude/skills/，Codex 为~/.codex/skills/，OpenCode 为~/.config/opencode/skill/ - 注意事项：安装后无需重启，下次对话涉及 Qdrant 搜索结果不相关、召回下降等问题时会自动触发；该技能为纯本地静态内容，运行时不需要网络连接（区别于同仓库的
qdrant-advisor需要联网动态取数）
11. 注意事项
- 该技能随整包一起安装最省事；若只想要这一个专项技能，需手动挑选目录复制——官方 npx CLI 未对此类静态子技能提供单独安装参数（仅入口技能
qdrant-advisor有专门的单独安装路径） - 内容假设使用者已部署 Qdrant 并具备基本使用经验，不含 Qdrant 入门教程
- OpenClaw、Hermes Agent 上的兼容性未经验证
- 仓库整体仍处于早期版本（v0.1.0），作者在文档中声明内容与结构可能随版本演进调整