一个面向本地知识库的 RAG + Agent 工程化项目,支持 Markdown 文档管理、双存储索引、DeepSeek 问答、工具调用、Workflow、LangGraph、Memory、Human-in-the-loop 与可观测性。
项目不仅提供后端 API,还包含 Vue 3 Web 工作台,可用于本地演示、源码学习和 Agent 开发面试讲解。
离线验收演示:用 mock LLM + 临时 SQLite/ChromaDB 跑通「文档 → 索引 → 检索 → 生成 → HITL 审批」核心链路,不需要 DeepSeek Key、不联网:
python scripts/demo_acceptance.py真实 Web 工作台(Dashboard / Knowledge Base / AI Assistant / Agent Workflow / Approval Center / Trace Monitor)的启动方式见 快速开始。
- RAG 问答:Markdown 文档加载、切分、Embedding、混合检索和 DeepSeek 生成。
- 文档生命周期:上传、列表、详情、更新、删除,并同步维护 SQLite 与 ChromaDB。
- Agent 工具调用:模型可自主调用知识库检索、文档列表、文档详情等工具。
- 手写 Workflow:节点定义、条件路由、有限补充检索和失败处理。
- LangGraph 对照实现:保留手写 Workflow,同时提供 LangGraph 版本。
- Memory:短期会话历史裁剪 + SQLite 长期记忆读写与检索。
- Human-in-the-loop:高风险工具需人工批准、拒绝或修改参数后执行。
- 可观测性:Trace 记录、失败分析、评估和回归测试。
- Web 工作台:Dashboard、Knowledge Base、AI Assistant、Agent Workflow、Approval Center、Trace Monitor。
一条「RAG 问答 + 高风险工具 HITL 审批」的完整时序:
sequenceDiagram
autonumber
participant U as 用户
participant API as FastAPI
participant R as 混合检索器
participant LLM as DeepSeek
participant T as 工具分发器
participant H as HITL
participant S as SQLite / ChromaDB
U->>API: 提问(/chat)
API->>R: BM25 + 向量混合检索
R-->>API: top_k 文档 Chunk
API->>LLM: 带上下文生成
LLM-->>API: 回答
API-->>U: 返回
Note over API,T: Agent 模式:模型自主决定调用工具
U->>API: 请求 Agent 执行(/agent/chat)
API->>T: 分发工具
T->>H: 高风险工具,需人工确认
H-->>U: 推送待审批项
U->>H: 批准 / 修改参数 / 拒绝
H->>T: 放行或拦截
T-->>S: 执行(更新 SQLite + ChromaDB)
T-->>API: 结果 + Trace
API-->>U: 最终答复 + 可观测 Trace
- Python 3.12 ARM64
- FastAPI / Uvicorn
- SQLite
- ChromaDB
- Sentence Transformers /
BAAI/bge-small-zh-v1.5 - DeepSeek Chat Completions
- LangGraph
- Vue 3 / TypeScript / Vite / Element Plus / Pinia
flowchart TB
Client[Vue 3 Web 工作台 / Swagger UI] --> API[FastAPI src/main.py]
API --> Documents[文档管理 /documents]
API --> Chat[RAG 问答 /chat]
API --> Agent[Agent /agent/chat]
API --> Workflow[Workflow /agent/workflow]
API --> Graph[LangGraph /agent/langgraph]
Documents --> DocService[document_service]
Documents --> Indexing[indexing_service]
Indexing --> SQLite[(SQLite)]
Indexing --> Chroma[(ChromaDB)]
Chat --> RAGService[rag_service]
RAGService --> Retriever[Hybrid Retriever]
Retriever --> Chroma
RAGService --> LLM[DeepSeek]
Agent --> State[AgentState / Session]
Agent --> Tools[Tool Registry / Dispatcher]
Agent --> HITL[HITL Service]
Agent --> Memory[Memory Service]
Agent --> LLM
Tools --> DocService
Tools --> Chroma
HITL --> Tools
Memory --> SQLite
Workflow --> State
Workflow --> Retriever
Workflow --> LLM
Graph --> State
Graph --> Retriever
Graph --> LLM
API --> Trace[Trace Store]
State --> Trace
.
├── frontend/ # Vue 3 Web 工作台
├── src/
│ ├── agent/ # Agent、AgentState、Session、Workflow、LangGraph
│ ├── database/ # SQLite 数据访问
│ ├── hitl/ # Human-in-the-loop
│ ├── memory/ # 短期与长期记忆
│ ├── observability/ # Trace、评估、失败分析
│ ├── rag/ # 文档加载、切分、Embedding、检索、LLM
│ ├── services/ # 文档与索引服务
│ ├── tools/ # 工具注册与分发
│ ├── config.py # 配置管理
│ └── main.py # FastAPI 入口
├── tests/ # 单元测试与集成测试
├── docs/ # 架构、验收与已知限制
├── scripts/ # 演示脚本
├── .env.example # 环境变量示例
└── requirements.txt # Python 依赖
- macOS Apple Silicon(ARM64)
- Python 3.12 ARM64
- Node.js 18+,建议 20+
- 可用的 DeepSeek API Key
- 本地或可下载的
BAAI/bge-small-zh-v1.5Embedding 模型
python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env编辑 .env,至少填写:
DEEPSEEK_API_KEY=your-deepseek-api-key如果本机尚未缓存 Embedding 模型,可先下载一次:
python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('BAAI/bge-small-zh-v1.5')"随后启动服务:
uvicorn src.main:app --reload访问地址:
- Swagger UI:
http://127.0.0.1:8000/docs - 健康检查:
http://127.0.0.1:8000/health
cd frontend
npm ci
npm run dev前端默认运行在 http://127.0.0.1:5173,Vite 会将 /api 代理到 http://127.0.0.1:8000。
生产构建:
cd frontend
npm run build完整示例见 .env.example。
| 变量 | 必填 | 默认值 | 说明 |
|---|---|---|---|
DEEPSEEK_API_KEY |
是 | 无 | DeepSeek API Key |
DEEPSEEK_MODEL |
否 | deepseek-chat |
生成模型 |
DEEPSEEK_API_URL |
否 | https://api.deepseek.com/chat/completions |
DeepSeek API 地址 |
EMBEDDING_MODEL_NAME |
否 | BAAI/bge-small-zh-v1.5 |
Embedding 模型 |
EMBEDDING_LOCAL_FILES_ONLY |
否 | true |
是否只使用本地模型文件 |
MIN_SIMILARITY |
否 | 0.60 |
最低相似度阈值 |
TOP_K |
否 | 3 |
默认检索数量 |
CHUNK_SIZE |
否 | 200 |
Chunk 大小 |
CHUNK_OVERLAP |
否 | 40 |
Chunk 重叠长度 |
AGENT_MAX_TOOL_CALLS |
否 | 5 |
Agent 单轮最大工具调用次数 |
APP_LOG_LEVEL |
否 | INFO |
日志级别 |
APP_LOG_FORMAT |
否 | 见示例 | 日志格式 |
| 路由 | 页面 | 说明 |
|---|---|---|
/dashboard |
Dashboard | 系统状态、文档统计、最近 Trace、待审批数量 |
/knowledge-base |
Knowledge Base | Markdown 上传、列表、详情、更新、删除 |
/assistant |
AI Assistant | RAG、Agent、Workflow、LangGraph 多模式对话 |
/workflow |
Agent Workflow | 手写 Workflow 与 LangGraph 执行轨迹 |
/approval |
Approval Center | HITL 待确认操作审批 |
/trace |
Trace Monitor | Trace 列表、详情与失败分析 |
| 方法 | 路径 | 说明 |
|---|---|---|
POST |
/chat |
RAG 知识库问答 |
POST |
/agent/chat |
Agent 问答,可自主调用工具 |
POST |
/agent/workflow |
手写 Workflow 执行 |
POST |
/agent/langgraph |
LangGraph Workflow 执行 |
POST |
/documents |
上传 Markdown 文档 |
GET |
/documents |
文档列表 |
GET |
/documents/{id} |
文档详情与 Chunk |
PUT |
/documents/{id} |
更新文档并重新索引 |
DELETE |
/documents/{id} |
删除文档及双存储数据 |
GET |
/agent/confirmations |
待确认操作列表 |
POST |
/agent/confirmations/{id}/approve |
批准操作 |
POST |
/agent/confirmations/{id}/modify |
修改操作参数 |
POST |
/agent/confirmations/{id}/reject |
拒绝操作 |
GET |
/agent/traces |
Trace 列表 |
GET |
/agent/traces/{trace_id} |
Trace 详情 |
GET |
/agent/traces/{trace_id}/analysis |
Trace 失败分析 |
示例:
curl -X POST http://127.0.0.1:8000/chat \
-H 'Content-Type: application/json' \
-d '{"question":"什么是 RAG?"}'不依赖真实模型和外部 API 的回归门禁:
python run_tests.py
python run_tests.py --category unit
python run_tests.py --category integration
python run_tests.py --category regression真实数据冒烟与验收:
# 检查真实 SQLite 与 ChromaDB 一致性
python -m tests.test_indexing_service --verify
# 从 data/documents 重新构建并同步索引
python -m tests.test_indexing_service --real
# 查看真实 SQLite 与 ChromaDB 的文档和 Chunk 数量
python -m tests.test_storage_status测试矩阵见 TEST_MATRIX.md。
- Markdown 文件是原始内容来源。
- SQLite 管理文档记录、Chunk 内容和元数据。
- ChromaDB 保存向量索引,可从 Markdown 重新生成 Embedding 重建。
- 文档更新和删除采用补偿机制,失败时尝试恢复文件与数据库状态。
- Memory 长期记忆持久化在 SQLite。
- Trace、HITL 待确认操作和 Agent Session 当前为进程内存储,服务重启后丢失。
持久化边界见 PERSISTENCE_MATRIX.md。
# 离线验收演示,不依赖真实 DeepSeek
python scripts/demo_acceptance.py
# 真实服务演示,需先启动 Uvicorn 并配置 DeepSeek
./scripts/demo_live.sh- 当前只支持 Markdown,不支持 PDF、Word、HTML。
- Trace、HITL、Agent Session 为进程内存储。
- SQLite 与 ChromaDB 是补偿机制,不是跨数据库强一致事务。
- 长期记忆目前使用关键词/BM25 检索,尚未向量化。
- 尚未实现用户认证、多租户和细粒度权限。
- 当前面向本地小规模知识库,未做分布式索引或异步任务队列。
详细说明见 docs/known_issues.md。
- 系统架构:
docs/architecture.md - 验收报告:
docs/acceptance_report.md - 已知限制:
docs/known_issues.md - 测试矩阵:
TEST_MATRIX.md - 持久化边界:
PERSISTENCE_MATRIX.md
- 为 Trace 和 HITL 增加 SQLite 持久化。
- 为高风险工具增加执行幂等记录。
- 增加用户认证、多租户和工具权限。
- 扩展 PDF、Word 等文档格式。
- 引入 Rerank 和向量化长期记忆。
- 增加前端 E2E 测试和 CI。