版本：2.0.0 | Python：3.11+ | 状态：稳定版
基于 LangGraph 工作流 + 混合检索 + LLM 评测的 Agentic RAG 知识问答系统。前后端分离：后端 FastAPI 提供 /api/v1 接口，前端 Next.js 提供聊天门面。系统核心是一条 4 节点 LangGraph 工作流（查询路由 → 检索协调 → 答案生成 → 质量检查，带 Self-RAG 反思重试），配合向量 / BM25 / 混合三种检索策略与启发式重排序，并通过 LLM Judge 评测与 A/B 测试框架保障回答质量。
- LangGraph 工作流：4 节点图（query_router → retrieval_coordinator → answer_generator → quality_checker），条件边驱动 Self-RAG 反思重试，状态对象内嵌
QueryState - 混合检索：
RetrievalRouter按规则选择 Vector / BM25 / Hybrid 策略，HybridFusion使用 RRF（k=60）融合，Reranker启发式 + 外部 API 降级精排 - LLM 评测：
Evaluator用 LLM Judge 多维度评分 + 启发式降级，输出结构化EvaluationResult - A/B 测试：
ABTestFramework一致性分组 + 统计分析（scipy 可选，缺失时纯 Python 兜底） - 容错存储：
QdrantStore/MySQLStore/RedisCache全异步，lifespan 容错初始化（无外部服务也能启动） - 集成测试：
TestClient(create_app())系统级端到端，真实工作流不 mock
| 模块 | 职责 |
|---|---|
config/ |
Pydantic v2 配置中心（必填校验 + 计算属性） |
models/ |
8 枚举 + 11 数据模型 + 对话记忆模型 |
agents/ |
LangGraph 工作流（graph/）+ QueryRouter / RetrievalCoordinator 两个 Agent |
storage/ |
QdrantStore / MySQLStore / RedisCache（全异步） |
retrieval/ |
RetrievalRouter + 三策略（Vector / BM25 / Hybrid）+ Reranker |
evaluation/ |
Evaluator（LLM Judge）+ ABTestFramework |
api/v2/ |
FastAPI 应用工厂（create_app + lifespan）+ routes（health / query） |
frontend/ |
Next.js 16 + React 19 聊天门面（App Router） |
tests/ |
单元测试 + integration/ 系统级端到端 |
main.py |
uvicorn 入口（加载 create_app） |
数据流：用户查询 → QueryRouter（LLM 分析意图 + 策略，规则降级）→ RetrievalCoordinator（调度 Vector/BM25/Hybrid + 重排序）→ LangGraph 工作流生成答案 → Evaluator（LLM 评测）→ ABTestFramework（配置对比）
# 克隆项目
git clone <repo-url>
cd Agentic-RAG-Knowledge-Assistant
# 创建虚拟环境（推荐）
python -m venv venv
# Windows
venv\Scripts\activate
# Linux/Mac
source venv/bin/activatecp .env.example .env
# 编辑 .env，至少填入 OPENAI_API_KEY主要配置项：
| 配置项 | 说明 | 必填 |
|---|---|---|
OPENAI_API_KEY |
LLM 调用密钥（OpenAI / DeepSeek / 通义千问等兼容 API 均可） | 是 |
OPENAI_BASE_URL |
LLM API 地址 | 是 |
OPENAI_MODEL |
模型名称 | 是 |
SECRET_KEY |
应用密钥（JWT / 会话签名等） | 是 |
QDRANT_HOST / QDRANT_PORT |
Qdrant 服务地址 | 是 |
MYSQL_* |
MySQL 连接信息 | 否 |
REDIS_* |
Redis 连接信息 | 否 |
RERANKER_MODEL / SERPER_API_KEY / NEO4J_* |
高级功能 | 否 |
未配置外部服务时系统仍可启动（lifespan 容错初始化），但检索 / 缓存相关功能不可用。
pip install -r requirements.txt
python main.py后端启动在 http://localhost:8000，交互式 API 文档：http://localhost:8000/docs
cd frontend
npm install
npm run dev前端启动在 http://localhost:3000，通过代理转发 /api/v1 请求到后端。
一键拉起后端 + 前端 + Qdrant + MySQL + Redis：
cp .env.example .env # 填入 OPENAI_API_KEY 等敏感配置
docker compose up -d --build服务拓扑：frontend(3000) → app(8000) → qdrant(6333) / mysql(3306) / redis(6379)
常用命令：
docker compose ps # 查看服务状态
docker compose logs -f app # 跟踪后端日志
docker compose down # 停止（保留数据卷）完整部署细节（环境变量、网络、健康检查、Neo4j 启用等）见 docs/deployment.md。
# 全套件（单元 + 集成）
python -m pytest tests/ --no-cov -q
# 仅集成测试（系统级端到端）
python -m pytest tests/integration/ -v --no-cov
# 覆盖率报告
python -m pytest tests/ --cov集成测试以 TestClient(create_app()) 启动完整应用，跑真实 LangGraph 工作流（不 mock），覆盖 health、完整查询、问候分支、错误处理、多轮无状态泄漏等系统级场景。工作流为占位实现（不调真实 LLM），无外部服务也能稳定运行。
启动后端后访问 Swagger UI：
- Swagger：http://localhost:8000/docs
- ReDoc：http://localhost:8000/redoc
当前端点：
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/v1/health |
健康检查（status / version / services 状态） |
| POST | /api/v1/query |
知识问答（执行 LangGraph 工作流，返回 answer + sources + confidence） |
POST /api/v1/query 请求体示例：
{
"query": "什么是机器学习",
"user_id": 1,
"conversation_context": null
}响应示例：
{
"query_id": "a1b2c3...",
"answer": "机器学习是...",
"sources": ["doc_001", "doc_002"],
"confidence": 0.85,
"processing_time": 0.42,
"retrieved_count": 2
}Agentic-RAG-Knowledge-Assistant/
├── main.py # uvicorn 入口（加载 create_app）
├── requirements.txt # Python 依赖
├── Dockerfile # 后端镜像（python:3.11-slim）
├── docker-compose.yml # 一键编排（app + frontend + 三个数据服务）
├── .env.example # 环境变量模板
│
├── config/ # 配置
│ └── settings.py # Pydantic v2 配置中心
│
├── models/ # 数据模型
│ ├── enums.py # 8 个枚举（QueryIntent / TaskStatus / DocumentSource 等）
│ ├── schemas.py # 11 个模型（QueryState / Document / AnswerResult 等）
│ └── memory.py # 对话记忆模型
│
├── agents/ # LangGraph 工作流 + Agent
│ ├── graph/ # 4 节点工作流（workflow.py + state.py）
│ ├── query_router.py # 查询路由 Agent（LLM 分析 + 规则降级）
│ └── retrieval_coordinator.py # 检索协调 Agent（策略调度 + 重排序）
│
├── storage/ # 异步存储层
│ ├── qdrant_store.py # Qdrant 向量存储
│ ├── mysql_store.py # MySQL 异步访问
│ └── redis_cache.py # Redis 缓存
│
├── retrieval/ # 检索系统
│ ├── router.py # RetrievalRouter（规则选策略）
│ ├── strategies.py # Vector / BM25 / Hybrid（RRF 融合）
│ └── reranker.py # 启发式 + 外部 API 重排序
│
├── evaluation/ # 评测体系
│ ├── evaluator.py # LLM Judge 多维度评测
│ └── ab_testing.py # A/B 测试框架（统计分析）
│
├── api/v2/ # FastAPI 应用
│ ├── app.py # create_app + lifespan + 异常处理
│ └── routes/
│ ├── health.py # GET /api/v1/health
│ └── query.py # POST /api/v1/query
│
├── frontend/ # Next.js 16 前端
│ ├── package.json # next / react / react-dom
│ └── src/app/ # App Router（layout.tsx / page.tsx）
│
├── tests/ # 测试
│ ├── conftest.py # 共享 fixture
│ ├── test_*.py # 单元 / 端点契约测试
│ └── integration/ # 系统级端到端集成测试
│ └── test_system.py
│
├── utils/ # 工具
│ ├── logger.py # 日志（loguru）
│ └── helpers.py # 重试装饰器等
│
└── docs/ # 文档
├── deployment.md # Docker 部署详解
├── development-guide.md # 开发指南
└── PROGRESS.md # 重构进度总结
| 层级 | 技术 |
|---|---|
| 语言 | Python 3.11 |
| 后端框架 | FastAPI + Uvicorn |
| 工作流 | LangGraph |
| 配置 | Pydantic v2 |
| 向量数据库 | Qdrant |
| 关系数据库 | MySQL 8 |
| 缓存 | Redis 7 |
| LLM 接口 | OpenAI 兼容（支持 DeepSeek / 通义千问等） |
| 中文检索 | jieba + rank_bm25 |
| 前端 | Next.js 16 + React 19 + TypeScript（App Router） |
| 容器化 | Docker + Docker Compose |
| 测试 | pytest + pytest-asyncio + httpx TestClient |
MIT License