1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | qdrant-model-migration-qdrant-skills |
| 项目自述名称 | qdrant-model-migration（仓库内子技能标识） |
| 作者/维护者 | Qdrant 官方仓库 qdrant/skills；核心提交者包括 Qdrant CTO Andrey Vasnetsov（GitHub: generall） |
| 来源链接 | https://github.com/qdrant/skills/tree/main/skills/qdrant-model-migration |
| 许可证 | Apache License 2.0（来自 GitHub API） |
| GitHub Stars | 208（仓库整体，来自 GitHub API；该数字属整个 qdrant/skills 合集仓库，不代表本技能自身热度） |
| Forks | 23（来自 GitHub API） |
| 最新版本 | 无独立版本号，随仓库持续滚动更新；本技能最近一次提交为 2026-07-08，仓库唯一正式发布标签为 v0.1.0（2026-03-30） |
| 安装方式 | npx skills add qdrant/skills（安装全部技能）或 Claude Code 插件市场 /plugin marketplace add qdrant/skills |
2. 功能介绍与亮点
qdrant-model-migration 是 Qdrant 官方“Solutions Architect 手册”系列技能之一，专门解决一个具体问题：如何在不中断线上服务的前提下更换或升级向量检索所用的 Embedding 模型。它不是通用文档的复述，而是一份按场景组织的决策树：
- 判断何时必须重新生成向量（更换模型服务商、更换模型架构、维度不兼容、新增稀疏向量），何时可以用 Matryoshka 降维或量化转换等方式绕开重新生成
- 给出零停机迁移的两条路径：Qdrant 1.18 及以上版本可直接在现有集合上增删具名向量字段；更早版本需新建集合并通过别名原子切换
- 覆盖“新旧模型并存”（A/B 测试、稠密+稀疏混合检索）、“稠密转混合检索”、“重新生成向量速度太慢”等衍生场景，并各自给出具体操作步骤与官方文档锚点链接
- 结尾“不应做的事”清单点出常见误区，例如迁移期间将 ColBERT 等大体积多向量与稠密向量共置会拖慢所有查询（实测案例：百万级数据点上从 13 秒降到 2 秒）
内容随 Qdrant 产品版本演进持续更新——2026 年 5 月的一次提交专门加入了 1.18 版本“直接增删具名向量”的新能力说明，显示这份技能与产品特性保持同步，而非一次性写完就搁置。
3. 适用场景
固定分类：DevOps 与基础设施
适用于已经在生产环境使用 Qdrant 向量数据库、且需要更换或升级 Embedding 模型的团队与个人开发者，典型触发场景包括：从 OpenAI 切换到 Cohere 等其他模型服务商、把模型升级到更高精度版本、为已有的纯稠密向量集合新增稀疏向量以支持混合检索，或是想在不影响线上查询的前提下对两个模型做 A/B 对比测试。
4. 跨 Agent 兼容性
- Claude Code：✅ 原生支持。官方提供
/plugin marketplace add qdrant/skills插件市场安装方式，也可克隆仓库后手动复制到~/.claude/skills/ - Codex：✅ 支持。Qdrant 官方博客明确列出 OpenAI Codex 为受支持平台之一，仓库 README 也给出
~/.codex/skills/的手动安装路径 - OpenClaw：✅ 支持。该仓库经
npx skills安装器分发，其源码中含 OpenClaw 专属适配逻辑（探测~/.openclaw、~/.clawdbot、~/.moltbot三种可能路径） - Hermes Agent：✅ 支持。同一安装器源码中含 Hermes Agent 专属配置项（探测
~/.hermes路径），但仓库官方博客与 README 未直接点名 Hermes Agent，判断依据仅为安装器源码
5. 推荐理由
多数向量数据库的官方资料停留在“如何调用 API”层面，而这份技能回答的是“该在什么情况下用什么策略”——这正是模型迁移这类一次性、高风险操作最容易踩坑的地方。它把版本兼容性、停机要求、数据规模等多个变量拆解成清晰的判断分支，并随 Qdrant 版本更新保持内容同步，对已经在用 Qdrant 但缺乏迁移经验的团队是一份可直接复制使用的操作手册。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 5 | 仓库本身 208 stars、23 forks，规模有限；子技能自身有 10 次提交、3 次官方合并的功能性 PR，参与者包含 Qdrant CTO 本人，但尚无第三方平台的独立讨论 |
| 可用性 | 8 | 无需额外配置，纯文本决策指南，近期（2026-07-08）仍有维护，历史提交显示随产品版本持续更新；仅需使用者已具备 Qdrant 环境 |
| 安全性 | 9 | 纯提示词/参考文档类内容，不含任何可执行 shell 命令，不发起网络请求，许可证明确 |
安全检查清单： ① 不执行 shell 命令；② 运行时不联网外发数据；③ 不要求任何 API key 或凭据；④ 全文核查未发现可疑指令或 prompt injection 迹象；⑤ 作者为 Qdrant 官方仓库，无造假迹象；⑥ License（Apache-2.0）明确；⑦ 最近一次提交为 2026-07-08，维护活跃
综合评分：7.3（三项均值）
7. 跟同类 Skills 相比的优势
| 项目 | 定位 | 与本技能的差异 |
|---|---|---|
| pinecone-io/skills（Pinecone 官方技能库） | 覆盖查询、全文检索、CLI、快速上手等功能层面的操作指南 | 未见针对“更换 Embedding 模型”这一具体场景的专项技能，覆盖面偏功能操作而非迁移类决策问题 |
| qdrant-scaling / qdrant-performance-optimization（同仓库姊妹技能） | 分别解决横向扩容与检索性能调优问题 | 与本技能同属 Qdrant 官方“按场景决策”系列，但聚焦点不同——本技能专注于模型更换这一独立且高风险的操作环节 |
8. 用户评价
该技能目前在 Reddit、Hacker News 等第三方社区平台尚无独立具名用户评价；可查到的相关传播内容主要为 Qdrant 官方账号发布的技能发布信息与性能对比数据，不构成独立第三方评价。
9. 安装使用方式
- 完整安装（含本技能）：运行
npx skills add qdrant/skills，会安装仓库内全部技能，包括 qdrant-model-migration - Claude Code 插件市场：依次执行
/plugin marketplace add qdrant/skills与/plugin install qdrant@qdrant - 手动安装：克隆仓库后，将
skills/qdrant-model-migration/目录复制到对应 Agent 的技能目录（Claude Code 为~/.claude/skills/，Codex 为~/.codex/skills/） - 安装后无需重启，Agent 会根据用户提问中的关键词（如“如何切换 Embedding 模型”“零停机迁移向量”）自动触发该技能
10. 注意事项
- 内容聚焦于决策与操作步骤本身，不包含完整代码示例，实际执行仍需结合 Qdrant 官方 API 文档
- 涉及 Qdrant 1.17 及更早版本与 1.18 及以上版本的行为差异，使用前需确认自己的集群版本
- 仓库尚无正式的版本发布节奏，内容可能随 Qdrant 产品迭代而调整，建议定期关注仓库更新