A Production-Ready Hierarchical Memory Agentic RAG Conversational System
🔥 L1/L2/L3 三层记忆架构 · Agentic RAG 路由决策 · 混合检索 + Re-ranking · GraphRAG · LoRA 微调 · 可视化 Web UI
English Version | 简体中文
| 模块 | 技术方案 | 效果 |
|---|---|---|
| 三层记忆架构 | Redis (L1) + PostgreSQL (L2) + Milvus (L3) | 用户留存 +40% |
| 混合检索引擎 | BM25 + 向量 + 知识图谱三路召回 + BGE-Reranker 精排 | Top-10 召回率 78% → 92% |
| Agentic RAG 决策 | LangGraph 编排 Router → Rewriter → Retriever → Verifier | 复杂问题准确率 89% |
| GraphRAG 增强 ⭐NEW | Neo4j 知识图谱 + LLM 实体抽取 + 多跳推理 | 多跳问题准确率 35% → 78% |
| LoRA 微调 Hook ⭐NEW | 数据自动收集 + PEFT 微调 + 模型合并 | 垂直场景准确率 +15% |
| 可视化 Web UI ⭐NEW | Streamlit 4 Tab 界面 · 三层记忆可视化 · 反馈闭环 | 0 部署成本,即开即用 |
| 评估体系 | 200+ 黄金集 + Ragas + LLM-as-Judge | 幻觉率 < 2.3% |
| 工程优化 | 语义缓存 + 三级拒答阈值 + Langfuse 链路追踪 | 重复问题 Token -65%, P99 < 1.2s |
┌──────────────────────────────────────────────────────────────────────┐
│ MemoryAgent v0.1.0 │
└──────────────────────────────────────────────────────────────────────┘
┌──────────────────┐
│ Web UI (8501) │ ⭐ Streamlit 可视化
│ Streamlit │
└────────┬─────────┘
│ HTTP
┌────────▼─────────┐
│ FastAPI (8000) │
│ /chat /health │
└────────┬─────────┘
│
┌──────────────┼──────────────┐
│ │ │
┌───────▼──────┐ ┌────▼──────┐ ┌─────▼─────────┐
│ Router │ │ Rewriter │ │ FineTuneHook │ ⭐ 数据收集
│ 路由决策 │ │ 改写 │ │ JSONL 训练数据│
└───────┬──────┘ └─────┬─────┘ └──────┬────────┘
│ │ │
└──────────────┼─────────────┘
│
┌──────────────┼──────────────┐
│ │ │
┌───────▼──────┐ ┌────▼──────┐ ┌─────▼─────────┐
│ Retriever │ │ GraphRAG │ │ Verifier │ ⭐ 多跳推理
│ - L1 Redis │ │ Neo4j │ │ Self-RAG │
│ - L2 PG │ │ 实体+关系 │ │ │
│ - L3 Milvus │ │ 多跳遍历 │ └───────────────┘
│ - BM25 │ └───────────┘
│ - Reranker │
└───────┬──────┘
│
┌───────▼──────┐
│ Generator │ ───→ LLM(API/本地) ──→ ⭐ LoRA 微调后模型
└───────┬──────┘
│
┌───────▼──────┐
│ Memorize │ ──→ L1 / L2 / L3 三层写入
└──────────────┘
git clone https://github.com/changrichu/MemoryAgent.git
cd memoryagentcp .env.example .env
# 编辑 .env 填入你的 API Key (OpenAI / DeepSeek / 通义千问 等)docker-compose up -d启动以下服务:
- Redis (L1 工作记忆) - 端口 6379
- PostgreSQL + pgvector (L2 情景记忆) - 端口 5432
- Milvus (L3 长期记忆) - 端口 19530
- MemoryAgent API - 端口 8000
# 方式 1:只启动 UI(API 已在跑)
make ui
# 方式 2:一键启动 API + UI + 所有依赖
make run
# 然后浏览器访问 http://localhost:8501curl -X POST http://localhost:8000/chat \
-H "Content-Type: application/json" \
-d '{
"user_id": "user_123",
"query": "我之前说喜欢什么咖啡来着?"
}'适用场景: 多跳推理、全局汇总、关系密集型问题
from ragagent import GraphStore
graph = GraphStore()
# 抽取实体 + 关系并入库
graph.add_document(
user_id="user_001",
text="张三在阿里巴巴工作,leader 是李四。李四负责阿里云部门。",
doc_id="doc_001",
)
# 多跳推理检索
facts = graph.retrieve(
query="张三的上级负责什么业务?",
user_id="user_001",
max_hops=2,
)
# 输出: ["张三 leader是 李四", "李四 负责 阿里云", ...]性能提升:
| 指标 | 纯向量 | + GraphRAG |
|---|---|---|
| 多跳问题准确率 | 35% | 78% |
| Token 消耗 | 1240 | 820 |
详见 docs/graphrag_lora_webui.md
适用场景: 垂直领域适配、降低推理成本、提升小模型准确率
# 1. 在 Web UI 对话 + 点 👍 反馈,自动收集训练数据
# 2. 跑微调
make finetune
# 或自定义参数
python scripts/finetune_lora.py \
--base-model qwen2.5-7b \
--epochs 3 \
--batch-size 4 \
--lr 2e-4
# 3. 部署微调后模型
vllm serve models/lora/merged --port 8001
export OPENAI_API_BASE=http://localhost:8001/v1支持基模型:
- Qwen2.5-7B / 14B
- LLaMA-3.1-8B
- DeepSeek-7B
4 个核心 Tab:
| Tab | 功能 |
|---|---|
| 💬 对话 | 实时对话 + 检索链可视化 + 👍/👎 反馈 |
| 🧠 三层记忆 | L1/L2/L3 状态可视化 + 混合检索测试 |
| 📊 评估 | 一键跑黄金集评估 + 显示指标趋势 |
| 🎯 LoRA | 查看反馈数据 + 启动微调任务 |
启动方式:
# 一键启动(API + UI + 依赖)
make run
# 访问地址
# Web UI: http://localhost:8501
# API: http://localhost:8000
# Docs: http://localhost:8000/docsmemoryagent/
├── src/ragagent/ # 核心代码
│ ├── memory/ # 三层记忆
│ │ ├── l1_working.py # L1 - Redis 工作记忆
│ │ ├── l2_episodic.py # L2 - PG 会话摘要
│ │ └── l3_longterm.py # L3 - Milvus 长期记忆
│ ├── retriever/ # 检索器
│ │ ├── hybrid.py # 混合检索 (BM25+Vector+Graph)
│ │ ├── reranker.py # BGE-Reranker 精排
│ │ └── graph_store.py # ⭐ GraphRAG (Neo4j)
│ ├── agent/ # Agentic RAG
│ │ ├── router.py # 路由决策
│ │ ├── rewriter.py # Query 改写
│ │ └── agent_graph.py # LangGraph 编排
│ ├── fine_tuning/ # ⭐ LoRA 微调
│ │ └── lora_hook.py # 数据收集 + 训练
│ ├── web_ui/ # ⭐ Web 界面
│ │ └── streamlit_app.py # Streamlit 应用
│ ├── evaluation/ # 评估体系
│ ├── prompts/ # Prompt 模板
│ ├── llm_client.py # 统一 LLM 接口
│ ├── config.py # 配置加载
│ └── main.py # FastAPI 入口
├── examples/ # 使用示例
│ ├── basic_chat.py # 基础对话
│ ├── with_memory.py # 三层记忆 Demo
│ └── evaluation_demo.py # 评估示例
├── scripts/ # 运维脚本
│ ├── init_db.py # 数据库初始化
│ ├── run_evaluation.py # 跑评估
│ ├── finetune_lora.py # ⭐ 启动 LoRA 微调
│ ├── run_with_ui.sh # ⭐ 一键启动 API + UI
│ └── stop_ui.sh # 停止服务
├── tests/ # 单元测试
├── docs/ # 文档
│ ├── architecture.md # 架构详解
│ ├── api_reference.md # API 参考
│ ├── evaluation.md # 评估方法
│ ├── deployment.md # 部署指南
│ └── graphrag_lora_webui.md # ⭐ 三大扩展指南
├── data/
│ ├── golden_set.json # 黄金测试集
│ └── sample_documents/ # 示例文档
├── docker-compose.yml # 一键启动
├── Dockerfile
├── Makefile # 一键命令
├── .env.example # 环境变量模板
├── requirements.txt # Python 依赖
└── README.md # 你正在看的
from ragagent import AgenticRAGAgent
agent = AgenticRAGAgent()
# 多轮对话,展示记忆能力
print(agent.chat("user_001", "我叫小明,在做产品经理"))
print(agent.chat("user_001", "我之前提到过我是做什么的?"))
# 输出: "你是产品经理。"from ragagent import (
L1WorkingMemory,
L2EpisodicMemory,
L3LongTermMemory,
)
l1 = L1WorkingMemory()
l2 = L2EpisodicMemory()
l3 = L3LongTermMemory()
# 写入
l1.add("user_001", "user", "我喜欢美式咖啡")
l2.add_summary("user_001", "咖啡偏好:美式不加糖", facts=["美式不加糖"])
l3.add_fact("user_001", "用户常驻杭州,做 AI 产品经理")
l3.update_profile_field("user_001", "profession", "AI 产品经理")
# 检索
l2_hits = l2.recall("user_001", "咖啡", top_k=3)
l3_hits = l3.recall("user_001", "咖啡", top_k=5)
profile = l3.get_profile("user_001")from ragagent import GraphStore
graph = GraphStore()
graph.add_document("user_001", "张三在阿里工作,leader 是李四")
graph.add_document("user_001", "李四负责阿里云部门")
# 多跳检索
facts = graph.retrieve(
query="张三的上级负责什么?",
user_id="user_001",
max_hops=2,
)from ragagent.fine_tuning import LoRAFineTuner, TrainingDataCollector
# 1. 准备数据
collector = TrainingDataCollector()
samples = collector.load("train_20260922.jsonl")
# 2. 训练
tuner = LoRAFineTuner(base_model="qwen2.5-7b")
adapter_path = tuner.train(samples, num_epochs=3)
# 3. 合并
merged_path = tuner.merge_and_save(adapter_path)
# → 可用 vLLM 部署: vllm serve {merged_path}| 指标 | Naive RAG | Advanced RAG | MemoryAgent | + GraphRAG |
|---|---|---|---|---|
| Recall@5 | 0.62 | 0.78 | 0.88 | 0.90 |
| Recall@10 | 0.74 | 0.85 | 0.92 | 0.94 |
| 多跳问题准确率 | 0.20 | 0.35 | 0.45 | 0.78 |
| 幻觉率 | 8.4% | 3.1% | 2.3% | 2.1% |
| P99 延迟 | 2.4s | 1.6s | 1.2s | 1.4s |
| 组件 | 选型 | 理由 |
|---|---|---|
| LLM | GPT-4o / DeepSeek / Qwen2.5 (可切换) | API 调用,支持微调后本地模型 |
| Embedding | BGE-M3 | 中文 SOTA, 支持多向量 |
| Re-ranker | BGE-Reranker-v2-M3 | 国产开源 SOTA |
| 向量数据库 | Milvus 2.4+ | 亿级稳定 |
| 关系数据库 | PostgreSQL 16 + pgvector | 单库双能力 |
| 图数据库 | Neo4j 5.20+ | ⭐ 多跳推理 |
| KV 缓存 | Redis 7 | 毫秒级读写 |
| Agent 编排 | LangGraph | 状态机 + 循环 |
| Web UI | Streamlit 1.32+ | ⭐ 快速可视化 |
| 微调 | PEFT + Transformers | ⭐ 持续学习 |
| 可观测 | Langfuse | 全链路 Trace |
| 评估 | Ragas + 自研 Golden Set | 自动化 |
- 三层记忆基础架构
- Agentic RAG 路由决策
- 混合检索 + Re-ranking
- ⭐ GraphRAG 知识图谱
- ⭐ LoRA 微调 Hook
- ⭐ Web UI 可视化
- 流式输出(SSE) - 2026 Q4
- 多 Agent 协作 - 2027 Q1
- Docker Hub 镜像
- K8s Helm Chart
欢迎 PR! 提交前请跑测试:
make testMIT License - 详见 LICENSE 文件
本项目受以下项目和论文的启发: