everything-claude-code

Hybrid-Retrieval-QA-System 🚀

混合检索问答系统：结合RAG语义理解与MySQL关键词检索的智能知识助手，专为教育领域优化

📋 目录

• 核心特性
• 系统架构
• 技术栈
• 快速开始
• API文档
• 性能指标
• 项目结构
• 开发指南
• 常见问题
• 许可证

✨ 核心特性

🔍 混合检索智能路由

• 简单查询 → MySQL BM25关键词检索（<100ms响应）
• 复杂查询 → RAG语义理解 + LLM生成（1-3s响应）
• 智能分类 → BERT模型自动判断问题复杂度
• 会话记忆 → 基于上下文的连贯对话支持

📄 企业级文档管理

• 全格式支持：PDF、Word、PPT、图片OCR、Markdown
• 批量处理：ZIP压缩包自动解压 & 处理
• 日志审计：完整的上传、操作、回滚记录
• 安全防护：文件名校验、路径遍历防护、事务回滚

🌐 生产级API设计

• RESTful API：标准HTTP接口
• WebSocket：实时流式问答支持
• 完整CRUD：知识库增删改查全操作
• 健康检查：系统状态监控端点

🛡️ 可靠性保障

• 错误回滚：误操作一键恢复
• 性能监控：QPS、响应时间、错误率实时监控
• 容错设计：服务降级、自动重试、超时控制
• 数据安全：敏感信息脱敏、API密钥保护

🏗️ 系统架构

graph TB
    %% 用户层
    User[👤 用户] --> Web[🌐 Web界面]
    User --> CLI[💻 CLI工具]
    User --> API[🔌 API调用]

    %% API网关层
    Web --> Router[🔄 路由网关]
    CLI --> Router
    API --> Router

    %% 查询分类层
    Router --> Classifier{🤖 BERT分类器}
    Classifier -->|简单/事实型| BM25[🔍 MySQL BM25检索]
    Classifier -->|复杂/推理型| RAG[🧠 RAG引擎]

    %% MySQL检索分支
    BM25 --> MySQL[(🗄️ MySQL知识库)]
    MySQL --> Cache1[⚡ Redis缓存]
    Cache1 --> Answer1[✅ 精准答案]

    %% RAG检索分支
    RAG --> Loader[📄 文档加载器]
    Loader --> Splitter[✂️ 文本分割器]
    Splitter --> Vectorizer[🔢 向量编码]
    Vectorizer --> Milvus[(📊 Milvus向量库)]
    Milvus --> Retriever[🎯 语义检索]
    Retriever --> LLM[🤖 大语言模型]
    LLM --> Answer2[💡 生成答案]

    %% 公共组件
    subgraph "🛡️ 支撑系统"
        Cache[(⚡ Redis缓存)]
        Logger[📝 日志系统]
        Monitor[📈 性能监控]
        Auth[🔐 认证授权]
    end

    %% 数据流
    Answer1 --> Response[📦 响应组装]
    Answer2 --> Response
    Response --> Cache
    Response --> Logger
    Response --> User

    %% 管理接口
    Admin[👨‍💼 管理员] --> Upload[⬆️ 文档上传]
    Upload --> Logger
    Upload --> Rollback[↩️ 回滚机制]

架构设计理念

1. 分离关注点：检索、生成、存储分层设计
2. 混合检索优势：MySQL快 + RAG准，兼顾速度与质量
3. 模块化扩展：各组件可独立替换、升级
4. 生产就绪：日志、监控、容错全链路覆盖

🛠️ 技术栈

组件	技术选择	版本	说明
后端框架	FastAPI	0.115+	高性能异步API框架，自动生成OpenAPI文档
向量数据库	Milvus	2.5+	支持大规模向量相似性检索
关系数据库	MySQL	8.0+	结构化知识存储与BM25检索
缓存系统	Redis	5.0+	会话缓存、结果缓存、热点数据加速
文档处理	LangChain + Unstructured	0.3+	多格式文档解析与文本提取
向量模型	BGE-M3	1.3+	中文语义理解，支持稠密+稀疏+ColBERT检索
LLM服务	阿里云DashScope	-	通义千问系列模型，性价比高
文本分割	中文递归分割器	自定义	针对中文文档优化的分割算法
查询分类	BERT-base-chinese	-	问题复杂度自动分类
前端界面	React + Vite	18+	现代化Web管理界面

🚀 快速开始

环境要求

• Python 3.10+
• MySQL 8.0+
• Redis 6.0+
• Milvus 2.5+（可选，用于RAG功能）

1. 安装依赖

# 克隆项目
git clone https://github.com/spongebobgit/Hybrid-Retrieval-QA-System.git
cd Hybrid-Retrieval-QA-System

# 安装Python依赖
pip install -r requirments.txt

# 或使用虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate   # Windows
pip install -r requirments.txt

2. 配置环境

# 复制配置文件模板
cp config.ini.example config.ini

# 编辑配置文件（填写你的实际配置）
# 需要配置：MySQL连接、Redis连接、阿里云API密钥等

3. 启动服务

# 开发模式（热重载）
uvicorn app:app --host 0.0.0.0 --port 8001 --reload

# 生产模式
uvicorn app:app --host 0.0.0.0 --port 8001 --workers 4

4. 访问系统

• Web界面：http://localhost:8001
• API文档：http://localhost:8001/docs
• 健康检查：http://localhost:8001/health

📚 API文档

核心端点

1. 问答接口

• 同步问答：POST /api/query

  curl -X POST "http://localhost:8001/api/query" \
    -H "Content-Type: application/json" \
    -d '{"query": "Python是什么编程语言？", "session_id": "optional"}'
  

• 流式问答：WebSocket /ws

  const ws = new WebSocket('ws://localhost:8001/ws');
  ws.send(JSON.stringify({query: "请详细解释机器学习", session_id: "123"}));
  

2. 文档管理

• 上传文档：POST /api/upload

  # 单文件上传
  curl -X POST "http://localhost:8001/api/upload" \
    -F "[email protected]" \
    -F "source=ai"
  
  # 多文件上传
  curl -X POST "http://localhost:8001/api/upload" \
    -F "[email protected]" \
    -F "[email protected]" \
    -F "source=java"
  
  # ZIP压缩包上传
  curl -X POST "http://localhost:8001/api/upload" \
    -F "[email protected]" \
    -F "is_zip=true" \
    -F "source=bigdata"
  

• 知识库统计：GET /api/knowledgebase/stats

  curl "http://localhost:8001/api/knowledgebase/stats"
  

3. 日志管理

• 查询日志：GET /api/upload/logs

  curl "http://localhost:8001/api/upload/logs?source=ai&limit=10&offset=0"
  

• 回滚操作：`POST /api/upload/rollback/{log_id}"

  curl -X POST "http://localhost:8001/api/upload/rollback/123"