尧图网站设计 尧图网站设计YAOTU DESIGN
ARTICLE DETAIL

资讯详情

深耕网站设计与一线实操的经验洞察。

ruflo-ruvector vector-embed 技能实战:用 ruvector@0.2.25 生成 384 维 ONNX 嵌入并写入 HNSW 索引

ruflo-ruvector vector-embed 技能实战:用 ruvector@0.2.25 生成 384 维 ONNX 嵌入并写入 HNSW 索引 ruflo-ruvector vector-embed 技能实战用 ruvector0.2.25 生成 384 维 ONNX 嵌入并写入 HNSW 索引【免费下载链接】ruflo The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo导读vector-embed是 ruflo-ruvector 插件中负责向量嵌入生成与落库的核心技能它把ruvector0.2.25的embed text子命令封装为一条可复现的 Agent 工作流将文本、代码或文档转化为 384 维的 ONNX 归一化向量并接入 HNSW 索引与 AgentDB 元数据存储。读完本文你将掌握该技能的完整调用链如何固定版本、如何生成基础与 LoRA 自适应嵌入、如何在无--batch标志的情况下批量处理文件、如何将向量写入 HNSW 数据库或 RVF 认知容器以及遇到ONNX WASM files not bundled时的标准排错路径。技能定位一条「嵌入 → 归一化 → 索引」的标准化流水线vector-embed技能定义在 plugins/ruflo-ruvector/skills/vector-embed/SKILL.md其 frontmatter 明确声明了职责边界Generate embeddings vianpx ruvector0.2.25 embed text(ONNX all-MiniLM-L6-v2, 384-dim), normalize, and store in HNSW index也就是说这条技能的输出物有三件维度384、归一化后的向量、以及写入 HNSW 索引的存储动作。它不负责聚类那是vector-cluster技能的hooks graph-cluster职责、也不负责双曲空间投影那是vector-hyperbolic技能的职责专注解决「把任意文本变成可检索向量」这一最底层的需求。从插件整体看ruflo-ruvector 围绕ruvector0.2.25构建了完整的能力矩阵vector-setup负责首启安装、vector-embed负责嵌入、vector-cluster负责图聚类、vector-hyperbolic负责层级数据投影而/vector斜杠命令见 plugins/ruflo-ruvector/commands/vector.md则暴露了 80 子命令的完整 CLI 面。vector-embed处于整条数据流水线的最前端——后续的一切检索、聚类、RAG、路由都建立在它生成的向量之上。为什么必须固定版本ADR-0001 的约束vector-embed的每一步命令都带0.2.25版本后缀这不是随意选择而是插件级架构决策的产物。仓库中的 ADR-0001Pin ruflo-ruvector to ruvector0.2.25 记录了原因早期文档曾引用了一批「理想化功能」FlashAttention-3、Graph RAG、DiskANN、ColBERT 等但 0.2.25 的 CLI 实际并未提供对应子命令只有attention list能枚举底层机制未固定版本时用户解析到ruvector0.1.x会静默得到一个完全不同、缺少brain/route/sona的 CLI 面真实事故举例npx ruvector embed TEXT报unknown command TEXT正确形态是embed text TEXT、npx ruvector compare A B命令不存在等。因此 ADR 的决策是所有 npx 调用必须形如npx -y ruvector0.2.25 subcommand [args]其中-y抑制 npm 交互提示版本钉死防止上游升级静默破坏契约。这条规则贯穿 README、技能、命令规范与 smoke 测试vector-embed技能严格遵循之。前置条件安装核心包与 ONNX 运行时vector-embed技能的第一步是确保ruvector0.2.25可用并给出了幂等检查写法npm ls ruvector 2/dev/null | grep 0.2.25 || npm install ruvector0.2.25这里用npm ls | grep判断版本是否已安装未命中才执行安装避免重复拉包。随后技能特别指出一个关键前提如果embed text报ONNX WASM files not bundled需要额外安装 ONNX 运行时npm install ruvector-onnx-embeddings-wasm这个坑在 README 与vector-setup技能中被反复强调ruvector0.2.25默认不捆绑ONNX 运行时缺失时embed text直接失败。完整依赖关系见 plugins/ruflo-ruvector/README.md 的 Prerequisites 一节除上述两个包外还有可选扩展包启用功能依赖它的子命令ruvector-onnx-embeddings-wasmONNX 运行时embed text、embed adaptive、llm embedruvector/pi-brain集体大脑brain *ruvector/ruvllmRuvLLM 与 SONA JS 回退sona *、llm *ruvector/graph-node图数据库Cyphergraph -q ...ruvector/router语义路由router --route ...ADR-0001 明确这些 add-on 是可选扩展而非强制依赖——ONNX 运行时体积很大对只使用 hooks 路由或 RVF 存储的用户不应强制安装。技能中给出了错误信息 → 缺失包的映射表vector-setup技能方便按错误精准补装。核心操作embed text的四种调用形态技能第 2 步列出embed text的全部有效形态注意是text子命令 位置参数不是embed 文本直接传参1. 单条字符串最基础npx -y ruvector0.2.25 embed text your text here2. 带输出文件npx -y ruvector0.2.25 embed text your text here -o vec.json-o把向量落盘为 JSON便于后续insert入库。3. 文件输入ruvector0.2.25没有embed --file标志技能的既定做法是先用 Read 工具读文件内容再把内容作为位置参数传入npx -y ruvector0.2.25 embed text $(cat src/module.ts) -o src/module.ts.vec.json4. 批量处理技能明确警告「ruvector0.2.25 没有内置--batch/--glob标志」因此批量必须自己用 shell 循环。这与 ADR-0001 第 4 条「已移除的表面保持移除」embed --file、embed --batch --glob不得以任何形式复活完全一致。embed benchmark是技能之外的一个补充能力见commands/vector.md第 4 条用于对比基础嵌入与自适应嵌入的性能差异。自适应 LoRA 变体领域微调嵌入技能第 3 步给出 LoRA 变体npx -y ruvector0.2.25 embed text ... --adaptive --domain code--adaptive启用 LoRA 自适应嵌入--domain指定领域如code。在/vector命令中对应embed-adaptive text见 plugins/ruflo-ruvector/commands/vector.md 第 2 条。从 README 的能力表看这属于「Adaptive LoRA embeddings」能力——用 LoRA 微调将通用嵌入适配到特定领域适合代码语义等专用场景。配套的embed benchmark可用于量化「基础 vs 自适应」的差异。确认环节维度、范数与输出路径技能第 4 步要求 Agent 在执行后确认三件事向量维度——固定为 384all-MiniLM-L6-v2 的输出维度数据库create时必须以-d 384创建才能匹配范数——嵌入输出是归一化向量与 README 端到端示例中search -v直接用查询向量一致HNSW 的 cosine 度量在归一化向量上才能正确工作输出路径——若使用了-o需汇报落盘位置。这一步是技能的可审计性设计每个嵌入操作都留下「维度 范数 路径」的确定性记录方便下游insert与排错。存储层HNSW 索引、RVF 容器与 AgentDB 元数据vector-embed技能的目标是「store in HNSW index」但技能本身的存储动作分为两层A. 元数据存入 AgentDB技能第 5 步mcp__plugin_ruflo-core_ruflo__memory_store({ key: embed-SOURCE, value: VECTOR_METADATA, namespace: vector-patterns })通过ruflo-core插件的memory_storeMCP 工具把「来源 → 向量元数据」登记到vector-patterns命名空间供后续memory_search检索模式复用。B. 向量本体入库完整链路在 README 的 End-to-End Example 中给出# 1. 以 384 维 cosine 度量创建 HNSW 数据库 npx -y ruvector0.2.25 create project.db -d 384 -m cosine # 2. 批量嵌入所有 TS 源文件shell 循环替代 --batch mkdir -p .vec for f in $(find src -name *.ts); do npx -y ruvector0.2.25 embed text $(cat $f) -o .vec/${f//\//_}.json done # 3. 聚合成 JSON 数组并插入 jq -s [.[] | {id: input_filename, vector: .vector}] .vec/*.json corpus.json npx -y ruvector0.2.25 insert project.db corpus.json # 4. 用查询嵌入搜索-k 5 返回 Top-5 QV$(npx -y ruvector0.2.25 embed text JWT refresh-token rotation --output -) npx -y ruvector0.2.25 search project.db -v $QV -k 5 # 5. 检查索引健康度 npx -y ruvector0.2.25 stats project.dbcreate -m cosine|euclidean|dot决定距离度量且必须在建库时确定search -v接受 JSON 向量stats用于查看索引规模。README 记录的 HNSW 性能基线为插入 52,000 次/秒、搜索延迟约 0.045ms约 8,800 倍于 ONNX 推理耗时每向量内存约 50 字节——这些数字来自ruvector/core的 Rust 后端。C. 替代方案RVF 认知容器带血缘追踪的存储格式npx -y ruvector0.2.25 rvf create project.rvf npx -y ruvector0.2.25 rvf ingest project.rvf corpus.json npx -y ruvector0.2.25 rvf query project.rvfRVF 容器支持derive parent child做 lineage 追踪、compact回收删除空间且rvf examples提供 45 个参考存储如agent_memory、swarm_knowledge适合需要溯源能力的场景。MCP 替代方案把嵌入能力挂进 Claude Code 工具面技能第 36-42 行的 MCP 一节给出两种等价路径。注册一次保持版本钉死claude mcp add ruvector -- npx -y ruvector0.2.25 mcp start注册后可直接调用 MCP 工具技能点名了四个与嵌入生态直接相关的hooks_rag_context语义上下文检索、brain_search集体大脑搜索、hooks_ast_analyzeAST 分析、hooks_route智能路由。ADR-0001 强调 MCP 传输层在 ruvector 次版本之间会变化因此 MCP 启动命令同样必须带0.2.25钉死保证下游 Agent 看到的工具面稳定91 个工具经ruvector mcp tools验证。验证注册成功可用claude mcp list | grep ruvector。排错手册从错误信息到标准修复路径vector-embed技能的 Caveats 一节是宝贵的实战沉淀与 plugins/ruflo-ruvector/skills/vector-setup/SKILL.md 的错误映射表相互印证错误信息原因修复ONNX WASM files not bundled. The onnx/ directory is missing.ONNX 运行时未捆绑npm install ruvector-onnx-embeddings-wasmBrain commands require ruvector/pi-brain缺集体大脑包npm install ruvector/pi-brainSONA not available. Native error: Cannot find module ...缺 RuvLLMnpm install ruvector/ruvllmJS 回退LLM commands require ruvector/ruvllm缺 RuvLLMnpm install ruvector/ruvllm标准诊断命令npx -y ruvector0.2.25 doctor npx -y ruvector0.2.25 infodoctor检查 Node、npm、原生绑定与 Rust 环境info应报告CLI Version: 0.2.25。技能还明确列出0.2.25 中不存在、不应调用的表面与 ADR-0001 第 4 条一致embed --batch --glob与embed --file标志不存在只有embed text textembed --model poincare不存在双曲投影需在用户代码中后处理见vector-hyperbolic技能顶层compare、midstream、index子命令不存在optimize自报「not yet shipped in this release」。如果doctor之后仍报错vector-setup技能的建议是原样粘贴输出再排查不要盲目重装。契约守护smoke.sh 如何兜底vector-embed技能所述的一切命令形态最终由 plugins/ruflo-ruvector/scripts/smoke.sh 以脚本形式固化为契约运行方式bash plugins/ruflo-ruvector/scripts/smoke.sh # Expected: 11 passed, 0 failed该脚本逐项验证版本钉死--version返回0.2.25、顶层子命令可见性hooks/embed/rvf/attention/gnn/brain/sona/create/stats/search/insert、hooks route位置参数、hooks ast-analyze位置参数、attention list含 FlashAttention、rvf examples至少 10 个示例、gnn info报告 Available、info报告 0.2.25、doctor退出码为 0以及「已移除表面保持移除」compare/midstream/index必须返回unknown command。任何一项漂移都会导致脚本非零退出——这就是vector-embed技能里每条命令都能放心复制运行的底气。与同级技能的衔接在 ruflo-ruvector 插件内vector-embed产出的向量是其他技能的输入vector-cluster/SKILL.md对嵌入集合做谱聚类/Louvain 社区发现输出簇分配、社区标签与边vector-hyperbolic/SKILL.md把 384 维向量投影到 Poincare 球x_i / (||x|| * (1 epsilon))归一化到单位球内用测地距离d(u, v) arcosh(1 2·||u−v||² / ((1−||u||²)(1−||v||²)))捕捉层级关系vector-setup/SKILL.md一键完成本文全部前置安装。若要在 Ruflo 生态中做跨模块组合ruflo-agentdb提供 AgentDB 内的 HNSW 存储后端、ruflo-rag-memory提供基于 ruvector 的简单语义搜索、ruflo-knowledge-graph提供多跳检索的 Graph RAG——vector-embed生成的 384 维向量是这些模块共同的数据底座。掌握本文的嵌入工作流就等于掌握了 Ruflo 语义检索体系的入口。【免费下载链接】ruflo The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表