🌌 OntoAgent

Modern Engineering & Learning RAG Pipeline

基于 LangChain + LangGraph + ChromaDB + 混合检索 (Dense + BM25 + RRF) 的全链路工程级检索增强生成与自反思智能体系统。

---

📖 项目背景与设计哲学

在构建企业级 RAG 系统时，初学者与工程团队常常遇到三大核心痛点：

1. 专有名词与型号漏检：纯向量检索（Dense Retrieval）依靠余弦相似度，对特定错误码（如 504 Gateway Timeout）、系统术语（如 Cache-Aside、Raft、P0事故）经常匹配失灵。
2. 上下文信息割裂：传统定长切块（Fixed Chunking）往往将段落中途切断，丢失了章节标题和父级业务上下文。
3. 模型幻觉与答非所问：传统单向线性 Chain（检索 $\rightarrow$ 塞入 Prompt $\rightarrow$ 生成）缺乏自省与纠错能力，一旦召回了无关噪音，大模型容易凭空捏造。

OntoAgent 的解决方案：

打造一套最小闭环、具备真实落地能力且学习曲线友好的 RAG 全链路工程系统：

• 结构感知切分：保留 Markdown 标题层级路径并注入元数据；
• 双路融合检索：Chroma 稠密语义检索 + BM25 稀疏关键字检索，由 RRF (Reciprocal Rank Fusion) 倒数排名融合算法统一定位；
• LangGraph Self-RAG：通过状态机实现“相关度自审 $\rightarrow$ 自适应查询改写 $\rightarrow$ 约束生成 $\rightarrow$ 幻觉校验”的完整反思闭环；
• 统一模型协议：全面兼容 OpenAI 标准协议，无缝接入 DeepSeek、阿里云百炼 (Bailian)、硅基流动或本地 Ollama。

---

🏛️ 架构全景图

graph TD
    subgraph Ingestion["1. 数据摄入与结构解析"]
        Files["文档源 (Markdown / TXT / PDF)"] --> Loader["DocumentLoader"]
        Loader --> Splitter["HierarchicalSplitter"]
        Splitter --> EnrichedChunks["结构增强切片 (注入 heading_path 与元数据)"]
    end

    subgraph Storage["2. 存储与多路索引"]
        EnrichedChunks --> Chroma["ChromaDB 本地向量库 (Dense Embedding)"]
        EnrichedChunks --> BM25["BM25 倒排索引 (Sparse Keyword Index)"]
    end

    subgraph Retrieval["3. 混合检索与 RRF 融合"]
        UserQuery["用户查询"] --> DenseSearch["向量相似度检索"]
        UserQuery --> SparseSearch["BM25 关键词匹配"]
        Chroma --> DenseSearch
        BM25 --> SparseSearch
        DenseSearch & SparseSearch --> RRF["RRF 倒数排名融合 (Reciprocal Rank Fusion)"]
        RRF --> Candidates["Top-K 高质候选上下文"]
    end

    subgraph AgenticGraph["4. LangGraph Self-RAG 智能体工作流"]
        Candidates --> GradeDocs["节点 1: 文档相关性自检"]
        GradeDocs -->|无有效证据 & 未超重试上限| RewriteQuery["节点 2: 查询自适应改写 (Query Rewrite)"]
        RewriteQuery --> UserQuery
        GradeDocs -->|命中相关证据| Generate["节点 3: 约束生成 (带明确引用标号 [1][2])"]
        Generate --> CheckHallucination["节点 4: 事实幻觉校验"]
        CheckHallucination --> FinalAnswer["最终高质量交付结果"]
    end

Loading

---

🚀 快速上手

1. 环境准备

推荐使用 Python 3.10+ 环境：

git clone https://github.com/your-username/Onto-agent.git
cd Onto-agent

# 安装依赖
pip install -r requirements.txt

# 以可编辑模式安装当前包
pip install -e .

2. 配置环境变量

复制配置模板并填入您的模型 API Key（支持 DeepSeek / 阿里云百炼 / 硅基流动 / 本地 Ollama 等）：

cp .env.example .env

在 .env 中根据您的实际 Provider 填写：

OPENAI_API_KEY=your_api_key_here
OPENAI_API_BASE=https://api.deepseek.com/v1
LLM_MODEL=deepseek-chat

# Embedding 配置 (留空则默认复用上述配置，也可使用硅基流动 BGE-M3 或 OpenAI text-embedding-3-small)
EMBEDDING_MODEL=text-embedding-3-small

---

💻 命令行使用 (CLI)

OntoAgent 提供了直观美观的终端交互工具：

1. 文档入库 (Ingest)

将技术文档、操作手册或设计文档解析切块并存入本地知识库：

onto-agent ingest ./data/samples

控制台将输出切片数量及 Chroma / BM25 索引统计。

2. 单次检索问答 (Query)

执行单次问答，查看 LangGraph 智能体的完整推理轨迹、相关度打分与引用来源：

onto-agent query "分布式系统的断路器熔断条件是什么？"

3. 终端多轮交互式对话 (Chat)

进入沉浸式知识问答模式：

onto-agent chat

4. 知识库状态与清空

# 查看知识库切片总量与当前配置
onto-agent status

# 清空本地向量库与 BM25 倒排索引
onto-agent reset

---

📚 阶梯式教学实战教程 (tutorials/)

本项目为 RAG 初学者提供了 4 个递进式独立实验脚本，每个脚本均可单文件直接运行：

教程脚本	核心内容	学习目标
01_naive_rag.py	Naive RAG 50行极简跑通	彻底搞懂 Document -> Splitter -> Chroma -> Retrieval -> Prompt 基础全链路。
02_chunking_and_metadata.py	分块策略与元数据增强	直观对比固定字数切块与 Markdown 标题层级切块的差异，理解元数据在消除语义漂移中的价值。
03_hybrid_retrieval_rrf.py	多路召回与 RRF 融合	剖析专有名词场景下 BM25 与向量检索的互补性，运行并计算 RRF 倒数排名融合打分。
04_self_rag_langgraph.py	LangGraph Self-RAG 状态机	掌握 StateGraph、Node、Conditional Edge 设计，观察查询自适应改写与防幻觉机制。

运行任意教程：

python tutorials/01_naive_rag.py
python tutorials/02_chunking_and_metadata.py
python tutorials/03_hybrid_retrieval_rrf.py
python tutorials/04_self_rag_langgraph.py

---

🧪 自动化测试

运行测试套件验证全链路各组件：

pytest tests/test_rag.py -v

---

📜 开源协议

本项目采用 Apache-2.0 许可证。