Skip to content

JunjieYu28/Paper-RAG

BranchesTags

Repository files navigation

🎓 RAG智能助教系统 - 项目文档

1. 项目简介

核心功能

RAG智能助教系统是一个基于**多模态检索增强生成(Multimodal RAG)**的智能教学辅助平台，专为教育场景设计。系统集成了以下核心功能：

🤖 智能问答系统

  • 多模态理解: 支持文本+图像的复合问答，能够理解课件中的图表、公式和图像内容
  • 上下文检索: 基于ChromaDB向量数据库的精准语义检索
  • 混合检索: 结合密集向量检索(Dense)和稀疏检索(BM25)，提升检索准确率
  • 来源追溯: 自动标注答案来源文件和页码，确保信息可溯源性

📚 知识库管理

  • 多格式支持: PDF、PPTX、DOCX、TXT、MD、图片等多种格式
  • 智能索引: 自动提取文本和图像内容，构建多模态向量索引
  • 增量更新: 智能检测文件变更，仅更新变化部分，提升效率
  • 文件夹管理: 支持层级目录结构，便于课程资料组织

💬 对话管理

  • 历史记录: 完整的对话历史保存和管理
  • 多候选答案: 支持同一问题的多个回答版本，可切换查看
  • 文件夹分类: 支持对话文件夹管理，便于课程分类
  • 思考模式: 可视化AI推理过程，帮助理解回答逻辑

🖼️ 多模态交互

  • 图像理解: 自动提取并描述PDF/PPTX中的图像内容
  • 实时上传: 支持用户上传图片、文档进行即时问答
  • 视觉问答: 结合图像内容和文本知识的综合回答

解决的问题

  1. 教学效率提升: 自动回答学生常见问题，减轻教师重复工作
  2. 学习资源整合: 统一管理分散的课程资料，提供智能检索
  3. 个性化学习: 基于课程材料的精准问答，提供个性化学习支持
  4. 多媒体理解: 克服传统文本RAG对图像内容的理解局限

整体架构

系统采用前后端分离的模块化设计：

  • 前端层: Streamlit框架，提供响应式Web界面
  • 业务逻辑层: Python核心模块，处理RAG逻辑、知识库管理
  • 数据层: ChromaDB向量数据库 + 文件系统存储
  • AI服务层: 集成OpenAI/DashScope API，提供多模态理解能力

2. 项目结构

RAG-TA/
├── 📄 app.py                          # 【主入口】Streamlit应用启动点
├── 📄 splash_screen.py                # 【启动页】粒子特效动画页面
├── 📄 rag_app.py                      # 【主控制器】应用路由和模块调度
├── 📄 requirements.txt                # 【依赖配置】Python包依赖列表
├── 📄 README.md                       # 【项目说明】基础项目介绍
│
├── 📁 backend/                        # 【后端核心】业务逻辑模块
│   ├── 📄 __init__.py
│   ├── 📄 config.py                   # 【配置管理】API密钥、模型参数、系统配置
│   ├── 📄 rag_agent.py                # 【RAG核心】问答逻辑、多模态处理、流式输出
│   ├── 📄 vector_store.py             # 【向量存储】ChromaDB封装、混合检索、多模态向量
│   ├── 📄 kb_manager.py               # 【知识库管理】文件操作、索引构建、增量更新
│   ├── 📄 document_loader.py          # 【文档加载】多格式文档解析、图像提取
│   ├── 📄 text_splitter.py            # 【文本分割】智能分块、重叠处理
│   ├── 📄 image_processor.py          # 【图像处理】图像描述生成、缓存管理
│   ├── 📄 file_utils.py               # 【文件工具】通用文件操作、路径处理
│   ├── 📄 history_manager.py          # 【历史管理】对话记录、候选答案管理
│   └── 📄 process_data.py             # 【数据处理】批量处理脚本
│
├── 📁 modules/                        # 【前端模块】UI组件库
│   ├── 📄 __init__.py
│   ├── 📄 chat_ui.py                  # 【对话界面】聊天UI、消息渲染、交互逻辑
│   ├── 📄 knowledge_base_ui.py        # 【知识库UI】文件管理界面、索引操作
│   ├── 📄 planning_ui.py              # 【规划界面】学习规划功能
│   └── 📄 utils.py                    # 【工具函数】CSS样式、组件初始化
│
├── 📁 data/                           # 【知识库目录】用户课程资料存储
├── 📁 vector_db/                      # 【向量数据库】ChromaDB数据文件
├── 📁 image_cache/                    # 【图像缓存】提取的图像和描述
├── 📁 temp_uploads/                   # 【临时上传】用户上传文件临时存储
│
├── 📁 evaluate/                       # 【评估模块】系统评估和测试
│   ├── 📁 datasets/                   # 【评估数据集】评估数据集
│   ├── 📁 data_construct/             # 【数据构建】评估数据集构建
│   ├── 📁 retriever_eval/             # 【检索评估】检索系统性能评估
│   └── 📁 generator_eval/             # 【生成评估】回答质量评估
│
├── 📁 test_src/                       # 【测试代码】单元测试和集成测试
│   ├── 📄 test_*.py                   # 各种测试文件
│   └── 📁 data/                       # 测试数据
│
├── 📄 .gitignore                      # 【Git配置】忽略文件配置
└── 📄 LICENSE                         # 【许可证】项目许可证

模块职责说明

🎯 核心模块

  • app.py: 应用入口，配置Streamlit页面设置和全局主题
  • rag_app.py: 主控制器，负责页面路由和模块协调
  • backend/rag_agent.py: RAG系统的核心大脑，处理问答逻辑

📊 数据处理模块

  • backend/vector_store.py: 向量数据库抽象层，支持文本和多模态向量
  • backend/kb_manager.py: 知识库管理器，处理文件CRUD和索引操作
  • backend/document_loader.py: 多格式文档解析器，支持PDF/PPTX等
  • backend/text_splitter.py: 智能文本分割器，优化检索效果

🎨 前端界面模块

  • modules/chat_ui.py: 对话界面的完整实现，包含流式输出和思考模式
  • modules/knowledge_base_ui.py: 知识库管理界面，支持文件操作和索引管理
  • splash_screen.py: 炫酷的粒子特效启动页面

⚙️ 支持模块

  • backend/config.py: 集中配置管理，包含API密钥和模型参数
  • backend/image_processor.py: 图像处理和描述生成，支持多模态理解
  • backend/history_manager.py: 对话历史管理，支持多候选答案和文件夹分类

3. 架构图

graph TB
    subgraph "前端层 Frontend (Streamlit)"
        A[启动页 splash_screen.py] --> B[主控制器 rag_app.py]
        B --> C[对话界面 chat_ui.py]
        B --> D[知识库界面 knowledge_base_ui.py]
        B --> E[规划界面 planning_ui.py]
    end
    
    subgraph "业务逻辑层 Backend"
        F[RAG智能体 rag_agent.py] --> G[向量存储 vector_store.py]
        F --> H[知识库管理 kb_manager.py]
        H --> I[文档加载器 document_loader.py]
        H --> J[文本分割器 text_splitter.py]
        H --> K[图像处理器 image_processor.py]
        F --> L[历史管理器 history_manager.py]
    end
    
    subgraph "数据存储层 Data Layer"
        M[ChromaDB 向量数据库]
        N[文件系统 data/]
        O[图像缓存 image_cache/]
        P[临时上传 temp_uploads/]
    end
    
    subgraph "外部服务 External Services"
        Q[OpenAI/DashScope API]
        R[多模态模型 qwen-vl-max]
        S[文本嵌入模型 text-embedding-v4]
    end
    
    %% 前端到后端的连接
    C --> F
    D --> H
    E --> F
    
    %% 后端内部数据流
    F --> G
    G --> M
    H --> N
    H --> O
    I --> J
    J --> G
    K --> G
    L --> P
    
    %% API调用
    F --> Q
    F --> R
    F --> S
    K --> Q
    
    %% 数据流向
    style F fill:#e1f5fe
    style G fill:#f3e5f5
    style H fill:#e8f5e8
    style M fill:#fff3e0
    style Q fill:#fce4ec
Loading

数据流向说明

  1. 用户交互流程:

    • 用户通过Streamlit界面输入问题或上传文件
    • 前端将请求发送到RAG Agent处理
    • Agent根据问题类型选择处理策略

  2. 多模态处理流程:

    • 文档加载器解析PDF/PPTX，提取文本和图像
    • 图像处理器生成图像描述，缓存到本地
    • 文本分割器将内容切分为适合检索的块

  3. 向量检索流程:

    • 向量存储同时支持文本和多模态embedding
    • 混合检索结合密集向量和BM25稀疏检索
    • 返回相关度最高的文档片段

  4. AI生成流程:

    • Agent整合检索到的上下文和用户问题
    • 调用多模态模型生成回答
    • 支持流式输出和思考过程可视化

4. 安装说明

环境要求

  • Python: 3.8+ (推荐 3.12)
  • 操作系统: Windows/macOS/Linux
  • 内存: 推荐 8GB+ (处理大型文档时)

依赖安装

核心依赖

# Streamlit Web框架
pip install streamlit

# OpenAI兼容API客户端
pip install openai>=1.0.0

# 向量数据库
pip install chromadb>=0.4.0

# LangChain生态
pip install langchain>=0.1.0
pip install langchain-openai>=0.0.5

文档处理依赖

# PDF处理
pip install pypdf2>=3.0.0
pip install pymupdf>=1.23.0

# PPTX处理
pip install python-pptx>=0.6.21

# DOCX处理
pip install docx2txt>=0.8

# 图像处理
pip install pillow>=9.0.0
pip install pytesseract>=0.3.10

向量检索依赖

# 句向量模型
pip install sentence-transformers>=2.2.0

# BM25检索
pip install rank-bm25>=0.2.2

# 中文分词
pip install jieba>=0.42.1

多模态依赖

# 阿里云DashScope SDK
pip install dashscope>=1.14.0

# 文本工具
pip install tiktoken>=0.5.0

数据处理依赖

# 数值计算
pip install numpy>=1.22.4
pip install pandas>=1.5.3

# 进度条
pip install tqdm>=4.65.0

# 剪贴板操作
pip install pyperclip>=1.8.2

一键安装

# 安装所有依赖
pip install -r requirements.txt

# 或者使用conda环境
conda create -n RAG python=3.12
conda activate RAG
pip install -r requirements.txt

配置说明

API密钥配置

在 backend/config.py 中配置：

# OpenAI兼容API配置
OPENAI_API_KEY = "your-api-key"
OPENAI_API_BASE = "https://dashscope.aliyuncs.com/compatible-mode/v1"
MODEL_NAME = "qwen3-max"

# 多模态模型配置
MULTIMODAL_MODEL = "qwen-vl-max-latest"
MULTIMODAL_GENERATION_MODEL = "qwen3-vl-plus"

目录结构创建

# 创建必要目录
mkdir -p data
mkdir -p vector_db  
mkdir -p image_cache
mkdir -p temp_uploads

5. 快速开始 (Quick Start)

步骤1: 环境准备

# 1. 克隆项目
git clone https://github.com/xuankunyang/RAG-TA.git
cd RAG-TA

# 2. 创建虚拟环境
conda create -n RAG python=3.12
conda activate RAG

# 3. 安装依赖
pip install -r requirements.txt

步骤2: 配置API密钥

编辑 backend/config.py，填入您的API密钥：

# 替换为您的实际API密钥
OPENAI_API_KEY = "sk-your-actual-api-key"

步骤3: 准备知识库

# 1. 创建数据目录（如果不存在）
mkdir -p data

# 2. 将课程材料放入data目录
# 支持的格式：
#   - PDF文档 (.pdf)
#   - PowerPoint演示文稿 (.pptx) 
#   - Word文档 (.docx)
#   - 文本文件 (.txt, .md)
#   - 图片文件 (.png, .jpg, .jpeg, .gif)

# 示例目录结构：
data/
├── 课程1/
│   ├── 第一章.pdf
│   ├── 第二章.pptx
│   └── 习题.docx
├── 课程2/
│   ├── 讲义.pdf
│   └── 补充材料/
│       └── 图表.png
└── 笔记.md

步骤4: 构建向量索引

# 方法1: 通过Web界面构建（推荐）
# 启动应用后，在"知识库管理"页面点击"重建索引"

# 方法2: 使用Python脚本
python -c "
from backend.kb_manager import KBManager
kb = KBManager()
result = kb.rebuild_vector_store(enable_multimodal=True)
print(result)
"

步骤5: 启动系统

# 启动Streamlit应用
streamlit run app.py

# 或者使用Python方式
python -m streamlit run app.py

步骤6: 开始使用

🎯 基础问答

  1. 访问 http://localhost:8501
  2. 点击"🚀 Enter"进入主界面
  3. 在"💬 对话"页面输入问题
  4. 系统自动检索相关材料并生成回答

📚 知识库管理

  1. 切换到"📚 知识库管理"页面
  2. 查看已索引的文件列表
  3. 可以上传新文件或重建索引
  4. 支持文件夹管理和文件预览

🖼️ 多模态功能

  1. 在对话设置中开启"🖼️ 多模态模式"
  2. 上传包含图像的PDF/PPTX文件
  3. 系统自动提取并理解图像内容
  4. 可以直接上传图片进行问答

🧠 高级功能

  • 思考模式: 在设置中开启"🧠 思考模式"查看AI推理过程
  • 文件引用: 使用@文件名引用特定文件作为上下文
  • 对话管理: 创建文件夹分类管理不同课程的对话
  • 历史记录: 查看和恢复历史对话

常见问题解决

Q1: 首次启动时索引构建很慢？

A: 这是正常现象，系统需要：

  • 解析所有文档
  • 提取图像内容
  • 生成向量embedding
  • 构建BM25索引

优化建议:

# 在config.py中调整并发数
MAX_WORKERS = 8  # 增加并发处理线程

# 关闭图像描述缓存以节省时间（如果已有缓存）
ENABLE_DESCRIPTION_CACHE = False

Q2: 多模态功能无法使用？

A: 检查以下配置：

# 确保config.py中启用多模态
USE_MULTIMODAL_RAG = True

# 检查DashScope安装
pip install dashscope

# 验证API密钥权限

Q3: 检索效果不理想？

A: 尝试以下优化：

# 调整检索参数
TOP_K = 5  # 增加检索数量
CHUNK_SIZE = 600  # 减小块大小
CHUNK_OVERLAP = 150  # 增加重叠

# 启用混合检索
USE_HYBRID_RETRIEVAL = True
DENSE_WEIGHT = 0.6
SPARSE_WEIGHT = 0.4

Q4: 内存不足错误？

A: 处理大型文档时的解决方案：

# 减小块大小
CHUNK_SIZE = 400

# 限制并发处理
MAX_WORKERS = 2

# 分批处理文档
# 一次只处理少量文件

性能优化建议

🚀 索引优化

  • 使用SSD存储向量数据库
  • 定期清理缓存文件
  • 合理设置块大小（600-800字符）

💾 内存优化

  • 启用增量更新而非全量重建
  • 调整并发线程数
  • 监控内存使用情况

🔍 检索优化

  • 启用混合检索提升准确率
  • 使用文件夹限定检索范围
  • 调整dense/sparse权重比例

🎉 完成！

恭喜！您已经成功部署了RAG智能助教系统。现在可以：

  1. 📖 上传课程材料构建知识库
  2. 💬 智能问答获得专业解答
  3. 🖼️ 多模态交互理解图像内容
  4. 📊 管理对话组织学习记录

如需更多功能或遇到问题，请参考项目的详细文档或联系开发团队。

About

No description, website, or topics provided.

Resources

Readme

License

Apache-2.0 license

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages