关于 vector-search
介绍如何选择插件中的向量搜索路径：用于语料检索的 HNSW 嵌入，以及面向少量高优先级模式的 WASM 路由器。还涵盖量化搜索、层级嵌入、参数调优和 CLI 替代方式。
主要功能
- 01用于大型语料的 HNSW 搜索
- 02RaBitQ 量化搜索
- 03文本相似度比较
- 04面向层级数据的双曲嵌入
- 05最多 11 种模式的 WASM 路由
- 06搜索调优与 CLI 命令
适用场景
- 01搜索至少 500 篇文档的语料
- 02减少大型向量集合的内存占用
- 03将查询路由到少量模式
- 04检索代码树等层级数据
MCP 相关
介绍 Ruflo MCP 工具，用于生成和搜索嵌入、构建量化索引、跨命名空间搜索记忆，以及进行 WASM 模式路由。
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/vector-search确认已加载。
详细介绍
向量搜索
此插件中有两种不同的向量搜索路径。请选择合适的路径——两者不可互换。
| 路径 | 工具系列 | 后端 | 容量 | 延迟 |
|---|---|---|---|---|
| 大规模语料库 | embeddings_* | @claude-flow/memory HNSW（Rust/Native） | 最多数百万个向量 | N=20k 时约为暴力搜索的 1.9×，N=5k 时约为 3.2×–4.7×（实测；recall@10 ≈ 0.99）。超过交叉点后，ANN 更有优势 |
| 热路径路由器 | ruvllm_hnsw_* | 基于 WASM 的路由器（v2.0.1） | 最多约 11 个模式（ruvllm-tools.ts:58） | 亚毫秒级；专为高优先级路由设计，而非语料库搜索 |
“12,500×”这一宣传数据适用于大规模 embeddings_search 路径。WASM 路由器不是这条路径。
何时使用
| 需求 | 路径 |
|---|---|
| 搜索包含 N ≥ 500 份文档的语料库 | embeddings_search |
| 受内存限制的语料库（≥5,000 个向量） | RaBitQ 量化——参见下方“量化搜索” |
| 比较两个字符串 | embeddings_compare |
| 分层／分类数据 | embeddings_hyperbolic（Poincare 球） |
| 将查询路由到 ≤11 个热模式之一 | ruvllm_hnsw_route |
| 跨命名空间搜索 | memory_search_unified |
标准搜索
- 检查状态——运行
mcp__plugin_ruflo-core_ruflo__embeddings_status，验证嵌入引擎。 - 初始化——如果引擎未激活，运行
mcp__plugin_ruflo-core_ruflo__embeddings_init。 - 生成——对文本输入运行
mcp__plugin_ruflo-core_ruflo__embeddings_generate。 - 搜索——使用查询运行
mcp__plugin_ruflo-core_ruflo__embeddings_search。 - 比较——运行
mcp__plugin_ruflo-core_ruflo__embeddings_compare，衡量相似度。 - 统一搜索——跨命名空间搜索时运行
mcp__plugin_ruflo-core_ruflo__memory_search_unified。
量化搜索（内存减少 32×）
对于 ≥5,000 个向量的语料库和／或受内存限制的环境，请使用 RaBitQ 1-bit 量化工作流。向量少于 5,000 个时，重建成本高于节省的资源——请改用标准路径。
| 步骤 | 工具 | 用途 |
|---|---|---|
| 1 | embeddings_init | 预热引擎 |
| 2 | embeddings_rabitq_build | 加载语料库后，一次性构建 1-bit 索引 |
| 3 | embeddings_rabitq_search | 通过汉明距离预筛选，返回 top-N 候选 ID（开销低） |
| 4 | embeddings_search | 可选：对候选集进行精确重排（全精度） |
| 5 | embeddings_rabitq_status | 索引健康状态、内存占用、构建时间 |
注意：
embeddings_rabitq_search只返回候选 ID——第 4 步的重排由用户负责（与embeddings-tools.ts:911中的文档字符串一致）。不进行重排时，结果是近似的；进行重排后，可在内存减少 32× 的情况下获得全精度质量。
调优
HNSW 提供三个可在召回率与延迟之间权衡的参数。“12,500×”这一宣传数据以默认值为前提；请根据工作负载谨慎调优：
| 配置 | efSearch | M | 适用场景 |
|---|---|---|---|
recall-first | 200 | 32 | 规划时召回模式；质量比毫秒数更重要 |
balanced（默认） | 64 | 16 | 通用语义召回 |
latency-first | 16 | 8 | 关注 p99 延迟的热路径路由 |
efSearch 通过 ruvllm_hnsw_create 传入（ruvllm-tools.ts:64）。目前 M 是注册表级参数；如果应支持通过 MCP 调整，可在后续提高。lite 索引中的 efConstruction 默认为 200（hnsw-index.ts:537）。
HNSW 模式路由器（WASM，≤11 个模式）
用于路由少量高优先级模式：
mcp__plugin_ruflo-core_ruflo__ruvllm_hnsw_create— 创建 WASM 索引（容量约为 11）mcp__plugin_ruflo-core_ruflo__ruvllm_hnsw_add— 添加模式mcp__plugin_ruflo-core_ruflo__ruvllm_hnsw_route— 路由传入的查询
这不是语料库索引。请将其视为针对一组精选模式的快速分类器。
双曲嵌入
对于分层数据（代码树、组织架构图），使用 mcp__plugin_ruflo-core_ruflo__embeddings_hyperbolic，它会映射到庞加莱球空间。距离采用测地线距离，而非余弦距离。
CLI 替代方案
npx @claude-flow/cli@latest embeddings search --query "authentication patterns"
npx @claude-flow/cli@latest embeddings init
npx @claude-flow/cli@latest memory search --query "your query"
性能
实测数据（来源：scripts/benchmark-intelligence.mjs，ruvector NAPI 后端；recall@10 ≈ 0.99）。旧版“150×–12,500×”数据是暴力回退产生的假象，现已弃用——请参阅项目 CLAUDE.md 中的“V3 Performance Targets”。
| 方法 | 相较于暴力搜索的实测加速比 |
|---|---|
| 暴力扫描 | 基准 |
| HNSW（N=5,000） | 快约 3.2×–4.7× |
| HNSW（N=20,000） | 快约 1.9× |
| HNSW（低于交叉点，小 N） | 与暴力搜索持平或更慢 |
| RaBitQ 量化 | 内存减少 32×；N≈14.7k 时每次查询耗时 0.60 ms |
ruvllm_hnsw_route（n≤11） | 每次路由耗时不到 1 ms，固定开销 |