RAGent

基于 Agent 的多步检索增强生成（Agentic RAG）工作空间

---

🌟 简介

RAGent 是一个结合了代理逻辑的检索增强生成（Agentic RAG）知识问答平台。系统包含多步规划、并行检索、上下文校验的完整回路机制，基于用户上传的本地文档进行结构化知识检索与问答。

界面设计采用了基于和风色彩（无氯化纸白、木炭墨黑、汉章红）的极简风格，通过精细的排版布局与负空间，提供清晰、专注的操作与阅读体验。

---

✨ 核心特性

• 🤖 Agentic RAG 推理机制：系统实现了从规划（Planner）、检索（Retrieval）、校验（Validator）到生成（Synthesis）的多步自治循环。当初始检索结果不满足回答要求时，系统将自动基于缺口信息进行补充检索。
• 📊 可视化执行链路 (Execution Trail)：通过界面侧边抽屉实时展示 Agent 的内部推理过程，包括子查询拆解、文档分块匹配度以及多轮检索的流转记录。
  
• 📝 文档分块管理：提供可视化的分块工作台，展示单篇文档的切分状态，包括总块数、字符统计及 LanceDB 向量化索引情况。
• ⚙️ 模型参数配置：支持配置兼容 OpenAI API 标准的各类大语言模型（如 Gemini、DeepSeek 等）和嵌入模型。支持对 Temperature、Top K 阈值以及分块字符长度等参数进行自定义。
• 🗃️ 多会话记录隔离：支持创建多个会话空间，并通过本地 SQLite 数据库独立归档历史会话、上下文引用及推理步骤数据。

---

🏗️ 系统架构

RAGent 采用了前后端分离的单体架构设计，便于在本地环境快速部署运行。

1. 系统模块架构图

graph LR
    User["前端界面 (React/Vite)"] <--> API["后端服务 (Express)"]
    API --> Agent["Agentic RAG 核心"]
    API --> Worker["异步文档处理队列"]
    Agent <--> LLM["大模型 & 向量 API"]
    Agent <--> VectorDB[LanceDB 向量库]
    Worker --> VectorDB
    Worker --> DB[(SQLite 元数据)]
    API <--> DB

Loading

2. 技术栈

• 前端框架：React 19, Vite 6, TypeScript, Tailwind CSS
• 后端服务：Node.js 22, Express 4, Multer
• 关系型存储：Better-SQLite3 (用于存储文档元数据及会话记录)
• 向量数据库：@lancedb/lancedb (嵌入式向量库)
• 文本编码处理：iconv-lite, jschardet

---

🔍 内部运行机制

1. Agentic RAG 推理工作流

系统的问答引擎（定义于 server/services.ts）采用了闭环反思的代理模型，核心步骤如下：

graph TD
    Query["1. 用户提问"] --> Planner["2. Planner (查询规划)"]
    Planner -->|生成多维子查询| Retrieval["3. Retrieval (向量检索)"]
    Retrieval --> Validator{"4. Validator (上下文校验)"}
    Validator -- "信息不足 (记录缺口)" --> Planner
    Validator -- "信息充足 / 达到轮次上限" --> Synthesis["5. Synthesis (答复生成)"]
    Synthesis --> Output["6. SSE 流式输出"]

Loading

1. Planner（规划）：根据用户提问（或前一轮反馈的缺失信息），大模型生成 1~3 个多维度的并行检索子查询。
2. Retrieval（检索）：将子查询转化为向量并向 LanceDB 请求检索，合并去重后归入全局上下文。
3. Validator（校验）：将当前累积的上下文和用户提问一并交给大模型进行客观评估。如果不满足回答要求，则总结出缺失信息并进入下一轮迭代；如果满足，则放行。
4. Synthesis（生成）：基于充足的上下文与提示词生成最终答复，并通过 SSE (Server-Sent Events) 向前端流式传输。

2. 数据处理与智能分块 (Semantic Chunker)

对于上传的文件，系统通过后台轮询器 (server/worker.ts) 依次进行文本提取、分块和批量向量化，状态通过 SSE 同步给前端。

其核心的分块算法 (server/chunker.ts) 具备以下特性：

• Markdown 结构感知：在切分时保持代码块、表格、HTML 块及列表结构在单个 Chunk 内的完整性。
• 层级上下文注入 (Header Injection)：解析过程中记录 H1-H6 的树状层级，并在最终生成的文本块首部自动注入对应路径（如 [Context: 第一章 > 介绍]），提供额外的语义上下文。
• 递归细分与聚合：对超过字符上限的超长段落采用标点符号递归回退切分；对相邻分块实施自适应的重叠（Overlap）；当末尾残留分块过小（如小于 80 字）时，将其合并至前一分块中。

---

🗃️ 数据库模型

• documents：文档元数据记录（ID、名称、上传时间、处理进度与状态）。
• chat_sessions：会话配置记录。
• chat_history：具体对话记录，支持扩展字段保存来源片段与 Agent 链路流转数据。
• chunks（LanceDB）：实际的向量文本块（ID、关联文档 ID、携带层级前缀的纯文本、Embedding 浮点数组）。

---

🚀 快速启动

1. 获取代码与依赖

git clone https://github.com/SilenceEchoLab/RAGent.git
cd docqa-rag-assistant
pnpm install

2. 配置环境变量 在项目根目录创建 .env 文件，配置 API Key：

GEMINI_API_KEY="您的 API Key"

3. 启动服务

pnpm run dev

打开浏览器访问 http://localhost:8000 即可。

4. 数据库清理指令 执行以下命令可重置知识库，这将清除 SQLite 的 documents 表记录及所有物理向量文件，但保留环境设置：

pnpm run reset-kb