Veloci Rag

🦖 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客户端

相关项目

• 梅科什 --代理存储系统。使用VelociRAG作为其搜索引擎。
• 碑林 --会话智能。从对话日志中提取记忆。
• 字形 --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

每一层捕获的内容：

✨ 特性

• 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个块）：

生产部署（6300多个块，3个源，950个文件）：

⚙️ 配置

依赖关系（全部包含在基本安装中）：

• 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 用于机器可读的项目上下文。

______________________________________________________________________

_专为思维敏捷、记忆更快的特工打造。_