🦖 VelociRAG
用于AI代理的闪电般快速的RAG。
_由ONNX Runtime提供支持的四层检索融合。没有PyTorch。Sub-200ms热搜索。增量图形更新。MCP准备就绪。_
______________________________________________________________________
大多数RAG解决方案要么拖动2GB以上的PyTorch，要么限制您进行单层矢量搜索。VelociRAG为您提供了四种检索方法——向量相似性、BM25关键字匹配、知识图遍历和元数据过滤——通过相互排名融合和交叉编码器重新排名进行融合。所有运行在ONNX运行时，没有GPU，没有API键。附带一个用于代理集成的MCP服务器、一个用于热查询的Unix套接字守护进程和一个正常工作的CLI。
🚀 快速开始
MCP服务器（Claude、Cursor、Windsurf）
pip install "velocirag[mcp]"
velocirag index ./my-docs
velocirag mcp克劳德代码 --添加到 .mcp.json 在项目根目录中：
{
"mcpServers": {
"velocirag": {
"command": "velocirag",
"args": ["mcp"],
"env": { "VELOCIRAG_DB": "/path/to/data" }
}
}
}然后打开 /mcp 在克劳德代码中启用 velocirag 服务器。如果使用virtualenv，请使用二进制文件的完整路径（例如。 .venv/bin/velocirag).
克劳德桌面 --添加到 claude_desktop_config.json:
{
"mcpServers": {
"velocirag": {
"command": "velocirag",
"args": ["mcp", "--db", "/path/to/data"]
}
}
}光标 --添加到 .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)命令行界面
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内返回，并进行完整的4层融合。
🎯 为什么选择VelociRAG？
- 4层搜索 --向量+BM25关键字+知识图+元数据，与RRF融合
- 无需法学硕士 --搜索完全在本地模型上运行（MiniLM+TinyBERT，总计约80MB）
- 无需GPU --纯ONNX推理，在任何机器上运行
- ~3ms热搜索 --守护进程通过Unix套接字保持模型+索引的温暖
- 增量索引 --添加文件而不重建整个索引
- MCP服务器 --插入Claude、Cursor、Windsurf、任何MCP客户端
相关项目
🏗️ 运作原理
4层管道：
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_CONNECION_REFUSED”） | -- | ✅ | — | — |
| 相互关联的概念 | -- | -- | ✅ | — |
| 已筛选（“#python状态：活动”） | -- | -- | -- | ✅ |
| 组合（“React状态管理”） | ✅ | ✅ | ✅ | ✅ |
✨ 特性
- ONNX 运行时 --184ms冷启动，3ms缓存。没有PyTorch，没有GPU
- 四层融合 --FAISS向量相似度+SQLite FTS5（BM25）+知识图+元数据过滤，通过倒排融合合并
- 交叉编码器重新排序 --TinyBERT通过ONNX运行时重新登录——包含在基本安装中，不需要PyTorch。首次使用时下载约17MB型号
- 增量图形更新 --以文件为中心的来源跟踪可以检测更改的内容，并且只重建受影响的节点/边缘。级联删除可保持所有存储（向量、图形、元数据）的一致性。多源支持，每个来源都有独立的来源
- MCP服务器 --Claude、Cursor、Windsurf的五个工具（搜索、索引、add_document、健康、list_source）
- 搜索守护进程 --Unix套接字服务器在查询之间保持ONNX模型+FAISS索引温暖
- 知识图谱 --分析器从markdown构建实体、时态、主题和显式链接边。可选GLiNER NER。418张图片，耗时2.1秒
- 智能分块 --标题感知拆分保留了文档结构和父上下文
- 查询扩展 --首字母缩略词注册表、大小写/间距变体、下划线感知标记化
- 随时随地奔跑 -仅CPU，8GB RAM，无API密钥，无外部服务
🤖 MCP服务器
VelociRAG公开了一个模型上下文协议服务器，用于无缝代理集成：
可用工具：
search--四层融合搜索与重排序index--将文档添加到知识库add_document--插入单个文档health--系统诊断list_sources--显示索引文档源
MCP服务器进程在查询之间保持活动状态，因此模型加载一次，每次后续搜索都是热的。适用于任何兼容MCP的客户端。
🐍 Python API
全4层统一搜索：
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
[--no-graph] [--no-metadata] [--gliner] [--full-graph] [--force]
[--source NAME] [--db PATH]
# Search across all layers (auto-routes through daemon if running)
velocirag search [--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/系统设计-101 （418个文件，1001个块）：
| 度量 | 值 |
|---|---|
| 索引（418个文件） | 13.6秒 |
| 搜索（温暖，5结果） | 35-90毫秒 |
| 图形构建（轻量级） | 2.1秒 → 2,397个节点，8717条边 |
| 增量更新（1个文件） | 1.3秒 |
| 重排序器 | 通过ONNX交叉编码器TinyBERT |
| 安装尺寸 | 约80MB（无PyTorch） |
| 内存占用 | 加载所有型号后小于1GB |
生产部署（6300多个块，3个源，950个文件）：
| 度量 | 值 |
|---|---|
| 全面搜索（温暖） | 平均16ms，最小2ms |
| 完整搜索（首次运行） | 平均22ms，最小4ms |
| 搜索P50/P95 | 17毫秒/55毫秒 |
| 点击率（100查询基准） | 99/100 |
| 图 | 3125个节点，132320条边 |
| 重排序器 | 通过ONNX交叉编码器TinyBERT |
| 随机存取存储器 | 加载所有型号后小于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建立在以下基础工作之上：
核心融合与检索
Reciprocal Rank Fusion：RRF（相互排名融合） --Cormack，G.V.、Clarke，C.L.A.和Büttcher，S.（2009）。“互惠排名融合优于孔多塞和个体排名学习方法。” _签名'09_.\ 用于跨检索层合并结果的核心融合算法。
BM25 --Robertson，S.E.，Walker，S.，Jones，S.，Hancock Beaulieu，M.和Gatford，M.（1994）。“霍加皮在TREC-3。” _TREC-3_.\ 通过SQLite FTS5建立关键字搜索基础。
嵌入和神经红外
BERT句子 --Reimers，N.和Gurevych，I.（2019）。“句子BERT：使用暹罗BERT网络的句子嵌入。” _EMNLP 2019_. 纸\ 使用密集嵌入架构 all-MiniLM-L6-v2.MiniLM --王伟，魏，董，包，杨，周（2020）。“MiniLM：深度自我注意力蒸馏，用于预训练变压器的任务无关压缩。” _NeurIPS 2020_. 纸\ 用于生产嵌入模型的高效变压器蒸馏。
重新排序和神经模型
交叉编码器重新排序 --Nogueira，R.和Cho，K.（2019）。“通过BERT重新排名。” _arXiv:1901.04085_. 纸\ 在MS MARCO上与TinyBERT进行交叉注意力重新排序。
TinyBERT --焦等（2020）。TinyBERT：提取BERT用于自然语言理解 _EMNLP 2020的研究结果_. 纸\ 压缩BERT用于快速重新排序推理。
矢量搜索与系统
FAISS --Johnson，J.、Douze，M.和Jégou，H.（2019）。“使用GPU进行十亿级相似性搜索。” _IEEE大数据汇刊_. 纸\ 高性能向量相似度搜索引擎。
GLiNER --Zaratiana，U.，Nzeyimana，A.和Holat，P.（2023）。“GLiNER：使用双向变换器进行命名实体识别的泛化模型。” _arXiv:2311.08526_. 纸\ 用于知识图实体提取的泛化NER（可选依赖关系）。
📄 许可证
麻省理工学院 --在任何地方使用它，建造任何东西。
需要代理集成帮助吗？ 检查 代理商.md 用于机器可读的项目上下文。
______________________________________________________________________
_专为思维敏捷、记忆更快的特工打造。_