onto-agent
by rinDBeans
README.md
# 🌌 OntoAgent
> **Modern Engineering & Learning RAG Pipeline**
>
> 基于 **LangChain + LangGraph + ChromaDB + 混合检索 (Dense + BM25 + RRF)** 的全链路工程级检索增强生成与自反思智能体系统。
[](https://www.python.org/downloads/)
[](https://github.com/langchain-ai/langchain)
[](https://github.com/langchain-ai/langgraph)
[](https://www.trychroma.com/)
[](LICENSE)
---
## 📖 项目背景与设计哲学
在构建企业级 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。
---
## 🏛️ 架构全景图
```mermaid
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
```
---
## 🚀 快速上手
### 1. 环境准备
推荐使用 Python 3.10+ 环境：
```bash
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 等）：
```bash
cp .env.example .env
```
在 `.env` 中根据您的实际 Provider 填写：
```ini
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)
将技术文档、操作手册或设计文档解析切块并存入本地知识库：
```bash
onto-agent ingest ./data/samples
```
控制台将输出切片数量及 Chroma / BM25 索引统计。
### 2. 单次检索问答 (Query)
执行单次问答，查看 LangGraph 智能体的完整推理轨迹、相关度打分与引用来源：
```bash
onto-agent query "分布式系统的断路器熔断条件是什么？"
```
### 3. 终端多轮交互式对话 (Chat)
进入沉浸式知识问答模式：
```bash
onto-agent chat
```
### 4. 知识库状态与清空
```bash
# 查看知识库切片总量与当前配置
onto-agent status
# 清空本地向量库与 BM25 倒排索引
onto-agent reset
```
---
## 📚 阶梯式教学实战教程 (`tutorials/`)
本项目为 RAG 初学者提供了 4 个递进式独立实验脚本，每个脚本均可单文件直接运行：
| 教程脚本 | 核心内容 | 学习目标 |
| :--- | :--- | :--- |
| [`01_naive_rag.py`](tutorials/01_naive_rag.py) | **Naive RAG 50行极简跑通** | 彻底搞懂 Document -> Splitter -> Chroma -> Retrieval -> Prompt 基础全链路。 |
| [`02_chunking_and_metadata.py`](tutorials/02_chunking_and_metadata.py) | **分块策略与元数据增强** | 直观对比固定字数切块与 Markdown 标题层级切块的差异，理解元数据在消除语义漂移中的价值。 |
| [`03_hybrid_retrieval_rrf.py`](tutorials/03_hybrid_retrieval_rrf.py) | **多路召回与 RRF 融合** | 剖析专有名词场景下 BM25 与向量检索的互补性，运行并计算 RRF 倒数排名融合打分。 |
| [`04_self_rag_langgraph.py`](tutorials/04_self_rag_langgraph.py) | **LangGraph Self-RAG 状态机** | 掌握 StateGraph、Node、Conditional Edge 设计，观察查询自适应改写与防幻觉机制。 |
运行任意教程：
```bash
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
```
---
## 🧪 自动化测试
运行测试套件验证全链路各组件：
```bash
pytest tests/test_rag.py -v
```
---
## 📜 开源协议
本项目采用 [Apache-2.0](LICENSE) 许可证。
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo issues