Velocirag

🦖 VelociRAG

为 AI Agent 打造的极速 RAG。

由 ONNX Runtime 驱动的四层检索融合。无需 PyTorch。温热搜索耗时不到 200ms。支持增量图更新。可用于 MCP。

---

大多数 RAG 解决方案要么依赖 2GB 以上的 PyTorch，要么将你限制在单层向量搜索中。VelociRAG 提供四种检索方法——向量相似度、BM25 关键词匹配、知识图谱遍历和元数据筛选，并通过倒数排名融合和交叉编码器重排进行融合。所有功能均基于 ONNX Runtime 运行，无需 GPU，也无需 API 密钥。它内置用于 Agent 集成的 MCP 服务、用于温热查询的 Unix 套接字守护进程，以及一个开箱即用的 CLI。

🚀 快速开始

MCP 服务（Claude、Cursor、Windsurf）

pip install "velocirag[mcp]"
velocirag index ./my-docs
velocirag mcp

Claude Code — 在项目根目录的 .mcp.json 中添加：

{
  "mcpServers": {
    "velocirag": {
      "command": "velocirag",
      "args": ["mcp"],
      "env": { "VELOCIRAG_DB": "/path/to/data" }
    }
  }
}

然后在 Claude Code 中打开 /mcp 并启用 velocirag 服务。如果使用虚拟环境，请使用二进制文件的完整路径（例如 .venv/bin/velocirag）。

Claude Desktop — 在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "velocirag": {
      "command": "velocirag",
      "args": ["mcp", "--db", "/path/to/data"]
    }
  }
}

Cursor — 在 .cursor/mcp.json 中添加：

{
  "mcpServers": {
    "velocirag": {
      "command": "velocirag",
      "args": ["mcp", "--db", "/path/to/data"]
    }
  }
}

Python API

from velocirag import Embedder, VectorStore, Searcher

embedder = Embedder()
store = VectorStore('./my-db', embedder)
store.add_directory('./my-docs')
searcher = Searcher(store, embedder)
results = searcher.search('query', limit=5)

CLI

pip install velocirag
velocirag index ./my-docs
velocirag search "your query here"

搜索守护进程（为 CLI 用户提供温热引擎）

velocirag serve --db ./my-data        # start daemon (background)
velocirag search "query"              # auto-routes through daemon
velocirag status                      # check daemon health
velocirag stop                        # stop daemon

守护进程通过 Unix 套接字保持 ONNX 模型和 FAISS 索引处于温热状态。首次查询会加载引擎（约 1s），后续查询在约 180ms 内返回，并使用完整的四层融合。

🎯 为什么选择 VelociRAG？

• 四层搜索 — 向量 + BM25 关键词 + 知识图谱 + 元数据，通过 RRF 融合
• 无需 LLM — 搜索完全由本地模型运行（MiniLM + TinyBERT，总计约 80MB）
• 无需 GPU — 纯 ONNX 推理，可在任何机器上运行
• 温热搜索约 3ms — 守护进程通过 Unix 套接字保持模型和索引处于温热状态
• 增量索引 — 添加文件时无需重建整个索引
• MCP 服务 — 可接入 Claude、Cursor、Windsurf 和任何 MCP 客户端

相关项目

• Memkoshi — Agent 记忆系统。使用 VelociRAG 作为搜索引擎。
• Stelline — 会话智能。从对话日志中提炼记忆。
• Glyph — MCP 安全扫描器和运行时防护。

🏗️ 工作原理

四层处理流程：

Query → expand (acronyms, variants)
      → [Vector]   FAISS cosine similarity (384d, MiniLM-L6-v2 via ONNX)
      → [Keyword]  BM25 via SQLite FTS5
      → [Graph]    Knowledge graph traversal
      → [Metadata] Structured SQL filters (tags, status, project)
      → RRF Fusion → Cross-encoder rerank → Results

各层的检索能力：

查询类型	向量	关键词	图谱	元数据
概念性（“改进错误处理”）	✅	—	—	—
精确匹配（“ERR_CONNECTION_REFUSED”）	—	✅	—	—
关联概念	—	—	✅	—
筛选（“#python status:active”）	—	—	—	✅
综合查询（“React 状态管理”）	✅	✅	✅	✅

✨ 功能

• ONNX Runtime — 冷启动耗时 184ms，缓存后耗时 3ms。无需 PyTorch，也无需 GPU
• 四层融合 — FAISS 向量相似度 + SQLite FTS5（BM25）+ 知识图谱 + 元数据筛选，通过倒数排名融合合并
• 交叉编码器重排 — 通过 ONNX Runtime 运行 TinyBERT 重排器，基础安装即包含，无需 PyTorch。首次使用时下载约 17MB 的模型
• 增量图更新 — 以文件为中心的来源追踪会检测变更，并且只重建受影响的节点和边。级联删除可确保所有存储（向量、图谱、元数据）保持一致。支持多来源，并为每个来源隔离追踪信息
• MCP 服务 — 提供五种工具（search、index、add_document、health、list_sources），适用于 Claude、Cursor、Windsurf
• 搜索守护进程 — Unix 套接字服务端可在查询之间保持 ONNX 模型和 FAISS 索引处于温热状态
• 知识图谱 — 分析器可从 Markdown 中构建实体、时间、主题和显式链接边。可选 GLiNER NER。2.1s 处理 418 个文件
• 智能分块 — 按标题切分，保留文档结构和父级上下文
• 查询扩展 — 支持缩写词注册表、大小写/空格变体，以及感知下划线的分词
• 随处运行 — 仅需 CPU、8GB RAM，无需 API 密钥或外部服务

🤖 MCP 服务

VelociRAG 提供 Model Context Protocol 服务，实现与 Agent 的无缝集成：

可用工具：

• search — 采用重排序的四层融合搜索
• index — 将文档添加到知识库
• add_document — 插入单个文档
• health — 系统诊断
• list_sources — 显示已索引的文档来源

MCP 服务进程会在查询之间持续运行，因此模型只需加载一次，后续每次搜索都能立即执行。适用于任何兼容 MCP 的客户端。

🐍 Python API

完整的四层统一搜索：

from velocirag import (
    Embedder, VectorStore, Searcher,
    GraphStore, MetadataStore, UnifiedSearch,
    GraphPipeline
)

# Build the full stack
embedder = Embedder()
store = VectorStore('./search-db', embedder)
graph_store = GraphStore('./search-db/graph.db')
metadata_store = MetadataStore('./search-db/metadata.db')

# Index with graph + metadata
store.add_directory('./docs')
pipeline = GraphPipeline(graph_store, embedder, metadata_store)
pipeline.build('./docs', source_name='my-docs')

# Unified search across all layers
searcher = Searcher(store, embedder)
unified = UnifiedSearch(searcher, graph_store, metadata_store)
results = unified.search(
    'machine learning algorithms',
    limit=5,
    enrich_graph=True,
    filters={'tags': ['python'], 'status': 'active'}
)

快速语义搜索：

from velocirag import Embedder, VectorStore, Searcher

embedder = Embedder()
store = VectorStore('./db', embedder)
store.add_directory('./docs')
searcher = Searcher(store, embedder)
results = searcher.search('neural networks', limit=10)

增量图更新：

from velocirag import Embedder, GraphStore, GraphPipeline

# First run — full build, populates provenance
gs = GraphStore('./db/graph.db')
pipeline = GraphPipeline(gs, embedder=Embedder())
pipeline.build('./docs', source_name='my-docs')  # full build

# Subsequent runs — only changed files get reprocessed
pipeline.build('./docs', source_name='my-docs')  # incremental (automatic)

# Force full rebuild
pipeline.build('./docs', source_name='my-docs', force_rebuild=True)

# Multi-source graphs
pipeline.build('./project-a', source_name='project-a')
pipeline.build('./project-b', source_name='project-b')  # isolated provenance

# Deleted files automatically cascade across all stores
# (vector, FTS5, graph, metadata) on next build

💻 CLI 参考

# Index documents (graph + metadata built by default)
velocirag index <path> [--no-graph] [--no-metadata] [--gliner] [--full-graph] [--force]
                       [--source NAME] [--db PATH]

# Search across all layers (auto-routes through daemon if running)
velocirag search <query> [--limit N] [--threshold F] [--format text|json]

# Search daemon
velocirag serve [--db PATH] [-f]         # start daemon (-f for foreground)
velocirag stop                            # stop daemon
velocirag status                          # check daemon health

# Metadata queries
velocirag query [--tags TAG] [--status S] [--project P] [--recent N]

# System health and status
velocirag health [--format text|json]

# Start MCP server
velocirag mcp [--db PATH] [--transport stdio|sse]

选项：

• --no-graph — 跳过知识图谱构建
• --no-metadata — 跳过元数据提取
• --full-graph — 构建包含语义相似度边的图（额外需要约 2GB RAM）
• --source NAME — 用于多来源溯源隔离的标签
• --force — 清除现有内容并从头重建
• --gliner — 使用 GLiNER 提取实体（需要 pip install "velocirag[ner]"）

📊 性能

在 ByteByteGo/system-design-101 上进行的真实基准测试（418 个文件，1,001 个分块）：

指标	数值
索引（418 个文件）	13.6s
搜索（热启动，5 个结果）	35–90ms
图构建（轻量）	2.1s → 2,397 个节点，8,717 条边
增量更新（1 个文件）	1.3s
重排序器	通过 ONNX 运行的 Cross-encoder TinyBERT
安装大小	约 80MB（无需 PyTorch）
RAM 使用量	加载所有模型后小于 1GB

生产部署（6,300+ 个分块，3 个来源，950 个文件）：

指标	数值
完整搜索（热启动）	平均 16ms，最低 2ms
完整搜索（首次运行）	平均 22ms，最低 4ms
搜索 P50 / P95	17ms / 55ms
命中率（100 次查询基准测试）	99/100
图	3,125 个节点，132,320 条边
重排序器	通过 ONNX 运行的 Cross-encoder TinyBERT
RAM	加载所有模型后小于 1GB

⚙️ 配置

环境变量	默认值	描述
VELOCIRAG_DB	./.velocirag	数据库目录
VELOCIRAG_SOCKET	/tmp/velocirag-daemon.sock	守护进程套接字路径
NO_COLOR	—	禁用彩色输出

依赖项（均包含在基础安装中）：

• onnxruntime — ONNX 推理（嵌入器 + 重排序器）
• tokenizers + huggingface-hub — 模型加载
• faiss-cpu — 向量相似度搜索
• networkx + scikit-learn — 知识图谱 + 主题聚类
• numpy、click、pyyaml、python-frontmatter

可选附加组件：

• pip install "velocirag[mcp]" — MCP 服务（添加 fastmcp）
• pip install "velocirag[ner]" — GLiNER 实体提取（添加 gliner，需要 PyTorch）

📚 参考文献

VelociRAG 基于以下奠基性研究：

核心融合与检索

互惠排名融合 — Cormack, G. V., Clarke, C. L. A., & Büttcher, S. (2009). “Reciprocal Rank Fusion outperforms Condorcet and individual Rank Learning Methods.” SIGIR '09.
用于合并不同检索层结果的核心融合算法。

BM25 — Robertson, S. E., Walker, S., Jones, S., Hancock-Beaulieu, M., & Gatford, M. (1994). “Okapi at TREC-3.” TREC-3.
通过 SQLite FTS5 实现的关键词搜索基础。

嵌入与神经信息检索

Sentence-BERT — Reimers, N., & Gurevych, I. (2019). “Sentence-BERT: Sentence Embeddings using Siamese BERT-Networks.” EMNLP 2019. 论文
使用 all-MiniLM-L6-v2 的稠密嵌入架构。

MiniLM — Wang, W., Wei, F., Dong, L., Bao, H., Yang, N., & Zhou, M. (2020). “MiniLM: Deep Self-Attention Distillation for Task-Agnostic Compression of Pre-Trained Transformers.” NeurIPS 2020. 论文
用于生产环境嵌入模型的高效 Transformer 蒸馏方法。

重排序与神经模型

Cross-Encoder 重排序 — Nogueira, R., & Cho, K. (2019). “Passage Re-ranking with BERT.” arXiv:1901.04085. 论文
使用 TinyBERT 在 MS MARCO 上进行交叉注意力重排序。

TinyBERT — Jiao, X., et al. (2020). “TinyBERT: Distilling BERT for Natural Language Understanding.” Findings of EMNLP 2020. 论文
压缩版 BERT，可实现快速重排序推理。

向量搜索与系统

FAISS — Johnson, J., Douze, M., & Jégou, H. (2019). “Billion-scale similarity search with GPUs.” IEEE Transactions on Big Data. 论文
高性能向量相似度搜索引擎。

GLiNER — Zaratiana, U., Nzeyimana, A., & Holat, P. (2023). “GLiNER: Generalist Model for Named Entity Recognition using Bidirectional Transformer.” arXiv:2311.08526. 论文
用于知识图谱实体抽取的通用 NER（可选依赖）。

📄 许可证

MIT — 随处使用，尽情构建。

需要 Agent 集成方面的帮助？ 查看 AGENTS.md，了解机器可读的项目上下文。

---

为思维敏捷、记忆更胜一筹的 Agent 而构建。