Manifold — Gaussian-Clef RAG

它是什么

一个用于检索增强生成（RAG）的Python库（3.10+）——这种技术让AI在回答问题前先从文档集合中搜索相关段落。不同之处在于：它不是将每个文本块表示为高维空间中的单个点（标准方法），而是将每个块表示为高斯分布——一个具有中心（平均含义）和扩散（不确定性）的“云”。检索变成了两个云重叠程度的问题。

它100%本地运行，基本使用无需任何API密钥。可选云集成用于额外功能。

核心思想

每个文本块被映射到一个概率分布𝒩(μ, Σ)：

• μ（均值） — 语义含义，来自本地SentenceTransformer或Gemini嵌入
• Σ（协方差） — 方向不确定性，建模为对角加低秩分解（默认秩为8）

搜索计算查询分布对每个文档分布的概率质量——这个度量称为期望似然核（ELK）。

为什么快

比较两个高维分布通常需要求逆大矩阵（O(d³)操作）。本项目使用Woodbury矩阵恒等式和Sylvester行列式定理将其降低到O(d·r²)，其中r=8——将150毫秒的操作变成不到3毫秒。结合其他优化，该项目声称端到端检索亚100毫秒。

关键组件

组件	功能	声称的影响
Woodbury ELK加速	快速核评估的数学技巧	150ms → <3ms
Cloudflare Clef决策路由	使用Cloudflare的AI模型检测模糊查询并提出澄清问题	1,500ms → <40ms
双存储摄取	每个块索引两次：密集向量存储 + SQLite全文搜索（FTS5）	亚2ms候选搜索
分类分支剪枝	层次聚类在重排序前跳过不相关分支	剪枝60–80%的候选
Clef 4问题段落门	并行过滤相关性、证据和矛盾	剪枝约30个候选 → 前5–8个
通用摄取引擎	接受原始文本、Markdown、JSON/JSONL、CSV、文件和目录	零预处理样板
灵活语料库生成器	将杂乱文本（HTML、OCR扫描、聊天记录）清理为结构化语料库并缓存	即时创建干净语料库

如何使用

from gaussian_rag import GaussianRAG

rag = GaussianRAG.create()
rag.add_texts(["Passage 1", "Passage 2", "Passage 3"])

results = rag.search("your question", top_k=3)
answer = rag.query("your question")  # 可选LLM生成的答案

还支持：

• 摄取：add_markdown()、add_records()（JSON/JSONL）、add_file()、add_directory()、add_raw_text()（脏文本自动清理）
• 持久化：rag.save("path") 和 GaussianRAG.load("path")
• CLI：python -m gaussian_rag.main ingest/query，以及语料库生成脚本（data/generate_corpus.py）
• 评估：python test_48_laws_e2e.py 在《权力的48条法则》上验证完整流程；pytest 运行测试套件，包括延迟基准测试

可选集成

• Cloudflare Workers AI — 启用Clef决策路由和段落门控（设置CLOUDFLARE_ACCOUNT_ID和CLOUDFLARE_API_TOKEN）
• OpenAI / Gemini / Mistral — 用于LLM答案生成（设置相应的API密钥）

配置位于config/config.yaml（嵌入后端、维度、低秩大小、检索度量、分块参数）。

额外功能

• 3D仪表板：FastAPI后端（端口8001）+ Vite前端（端口5173），显示交互式高斯椭球体、通过Server-Sent Events的实时逐阶段延迟遥测，以及Clef决策轨迹
• 文档：docs/中的大量文档，涵盖架构、设计决策、理论和用法

许可证

GNU Affero通用公共许可证v3.0（AGPL-3.0）。