# StudyRAG 课程资料智能问答助手 **Repository Path**: zwr1105/study-rag ## Basic Information - **Project Name**: StudyRAG 课程资料智能问答助手 - **Description**: 基于 LangChain + DeepSeek 的课程资料智能问答助手，支持向量与混合检索、引用追溯、文档增删改、范围筛选及资料不足拒答。 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-10-30 - **Last Updated**: 2026-10-30 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # StudyRAG：基于 LangChain 的课程资料智能问答助手 **开源仓库：[https://gitee.com/zwr1105/study-rag](https://gitee.com/zwr1105/study-rag)** **作者：Alina（zwr1105）** **项目类型：智能应用开发课程作业｜许可证：MIT｜运行环境：Python 3.11** ## 一、项目简介 StudyRAG 是一款面向课程学习与资料查阅的智能问答应用。用户将课程笔记、学习材料或项目文档导入知识库后，可以用自然语言提问。系统先检索相关原文，再通过 LangChain 调用 DeepSeek 在线大模型生成回答，并展示参考来源。 项目采用检索增强生成（RAG），不训练或微调大模型。问答范围限于已入库且被选中的资料，不自动搜索互联网。相比普通聊天，项目强调资料管理、语义检索、回答依据和资料不足时的拒答。 ## 二、主要功能 | 功能 | 实现说明 | |---|---| | 资料导入 | 支持 UTF-8 TXT、Markdown 和含文本的 PDF；保留文件名、页码及文本块标识 | | 文档管理 | 追加资料、内容哈希去重、查看列表、单独或批量删除、单文档更新及版本计数 | | 语义检索 | 本地 Embedding 编码，归一化向量通过余弦相似度检索 | | 混合检索 | 支持 BM25L、Dense、Hybrid，Hybrid 使用 RRF 融合排名 | | 候选重排 | 可选 Cross-Encoder 对初步召回结果重新排序 | | 检索范围 | 可查询全部资料或指定多份文档，在召回前过滤正文与向量 | | 依据追溯 | 展示原文片段及引用编号，校验模型提供的摘录是否存在 | | 资料不足拒答 | 结合可调相关性门槛、结构化充分性判断和引用校验，避免无依据草稿直接展示 | | 过程反馈 | 分别显示解析、模型加载、编码、检索、生成、校验等阶段及可操作错误提示 | | 持久化 | SQLite 保存文本、元数据、向量与索引配置，事务及版本检查保护更新一致性 | ## 三、技术栈与 LangChain 的使用 | 技术 | 在项目中的作用 | |---|---| | LangChain Core | `Document` 文档对象、`Embeddings` 接口、提示词和 Runnable 编排 | | LangChain Text Splitters | 按字符与中文分隔符切分文档，保留来源元数据 | | LangChain DeepSeek | 通过 `ChatDeepSeek` 调用在线大模型 | | LCEL | 使用 `Prompt → ChatModel → OutputParser` 组织生成流程 | | Sentence Transformers | 本地 Embedding 和可选 Cross-Encoder 重排序 | | NumPy / rank-bm25 | 精确余弦检索与 BM25L 关键词检索 | | SQLite | 文本及向量持久化、事务提交和并发版本检查 | | Streamlit | 文件上传、资料管理、问题输入、结果与阶段进度展示 | | Pytest / Ruff | 自动测试、静态检查和格式检查 | 默认 Embedding 为 `BAAI/bge-small-zh-v1.5`，重排模型为 `BAAI/bge-reranker-base`。首次使用需要下载权重，也可配置为本地模型目录。在线生成模型名称通过环境变量配置。 ## 四、系统架构与工作流程 ```text 资料入库： 文件上传 → 解析与来源记录 → 文本切分 → 内容去重 ↓ 本地 Embedding 编码 ↓ SQLite 保存文本、元数据和向量 用户问答： 问题 + 文档范围 → 范围内关键词 / 向量召回 → RRF 混合排名 ↓ 可选 Cross-Encoder 重排 ↓ 相关性筛选与上下文预算控制 ↓ LangChain 调用 DeepSeek 判断并生成回答 ↓ 原文摘录与引用校验 → 展示答案或资料不足提示 ``` 向量检索使用 NumPy 精确计算，查询复杂度为 O(Nd)。这一实现便于理解和验证，适合本项目的小规模资料库；当前没有使用 FAISS 或独立向量数据库。 ## 五、安装与运行 ### 1. 获取项目并安装 Windows PowerShell 示例： ```powershell git clone https://gitee.com/zwr1105/study-rag.git cd study-rag py -3.11 -m venv .venv .\.venv\Scripts\python.exe -m pip install --upgrade pip .\.venv\Scripts\python.exe -m pip install -e ".[local,dev]" Copy-Item .env.example .env ``` 已有 `.env` 时保留自己的配置，不要覆盖真实密钥。`requirements-tested.txt` 记录基础环境验证过的依赖版本；可选模型依赖见 `pyproject.toml`。 ### 2. 配置模型 在本地 `.env` 中填写： ```dotenv DEEPSEEK_API_KEY=在本地填写自己的密钥 DEEPSEEK_BASE_URL=https://api.deepseek.com DEEPSEEK_MODEL=deepseek-flash EMBEDDING_MODEL=BAAI/bge-small-zh-v1.5 RERANKER_MODEL=BAAI/bge-reranker-base LOCAL_FILES_ONLY=false ABSTAIN_MIN_COSINE=0.35 DATA_DIR=data ``` 模型名称以账户可用模型为准，可参考 [DeepSeek 官方说明](https://api-docs.deepseek.com/)。`ABSTAIN_MIN_COSINE` 是未经当前语料校准的启发式门槛，不是答案正确概率；设置为 `off` 可关闭数值过滤，模型判断和原文校验仍保留。 ### 3. 启动页面 ```powershell .\.venv\Scripts\python.exe -m streamlit run app.py ``` 打开终端给出的本地地址，通常为 `http://localhost:8501`。首次启动如询问邮箱，留空回车即可。停止应用按 `Ctrl+C`。 ## 六、使用步骤与演示问题 1. 勾选“使用项目示例资料”，或上传自己的资料；只用自己的文件时取消示例选项。 2. 勾选“建库时生成本地语义向量”，点击“追加资料 / 首次建库”。观察解析、模型加载、编码及保存状态。 3. 确认“向量索引：已建立”，选择 `dense` 或 `hybrid`。 4. 选择查询全部资料或指定文档。 5. 先勾选“仅检索”检查召回原文，再取消该项调用 DeepSeek。 6. 核对回答中的引用与原文；资料不足时应显示拒答及原因。 | 演示问题 | 基于示例资料的预期表现 | |---|---| | RAG 会修改模型权重吗？ | 检索 RAG 笔记，依据原文回答 | | 为什么不直接把两种检索分数相加？ | 检索 RRF 与分数尺度相关内容 | | 更新资料失败会破坏旧知识库吗？ | 检索事务相关说明 | | 这门课的老师叫什么名字？ | 示例没有姓名，应说明资料不足 | | 期末考试是哪一天？ | 示例没有日期，应说明资料不足 | 上表是演示预期，真实模型可能误判，需要结合原文核验。若暂时无法下载模型，可关闭语义向量生成，使用 `bm25` 和“仅检索”先验证资料流程；之后点击“生成 / 重建全部语义向量”升级。 资料管理区支持删除与更新。移除上传框中的文件不会删除知识库内容；相同内容即使改名也会跳过，同名不同内容可以并存。版本号为当前内容的更新计数，不保存历史版本。 ## 七、项目结构 ```text app.py Streamlit 页面 study_rag/ config.py 配置读取 documents.py 解析、切分与来源信息 embeddings.py 本地模型适配 store.py 文档增删改、向量与事务 retrieval.py 范围过滤、BM25、Dense、RRF、重排 generation.py LangChain 编排、依据校验与拒答 operations.py 入库和查询工作流 progress.py 进度事件与分批编码 progress_ui.py 状态面板与任务记录 errors.py 错误分类与恢复建议 examples/ 可公开的示例资料 evaluation/ 检索与拒答评测 tests/ 自动测试 docs/ 设计和操作说明 .env.example 无真实密钥的配置模板 pyproject.toml 依赖与项目配置 LICENSE MIT 许可证 ``` ## 八、测试与评测 ```powershell .\.venv\Scripts\python.exe -m pytest -q .\.venv\Scripts\python.exe -m ruff check . .\.venv\Scripts\python.exe -m ruff format --check . .\.venv\Scripts\python.exe -m evaluation.run --mode bm25 .\.venv\Scripts\python.exe -m evaluation.run --mode dense .\.venv\Scripts\python.exe -m evaluation.run --mode hybrid .\.venv\Scripts\python.exe -m evaluation.run --mode hybrid --rerank ``` 截至 2026-10-30，完整自动测试 **125 项通过**，静态检查与格式检查通过。测试覆盖文档管理、事务一致性、范围过滤、引用与拒答、阶段进度及页面交互；真实模型用可控测试对象替代，测试通过不代表真实回答一定正确。 BM25 的 8 条示例检索题在 K=3 时，文档级 Recall@3、MRR@3、Hit@3 均为 1.0。该结果仅用于小样本流程验证，不能推导真实业务效果或声称混合检索必然更优。 真实 DeepSeek 拒答评测需要显式启用在线调用，会消耗 API 用量： ```powershell .\.venv\Scripts\python.exe -m evaluation.abstention --mode dense --allow-online ``` 报告写入 `reports/`。拒答评测分别统计无答案拒答率和有答案误拒答率，网络错误单列；本项目尚未给出真实在线模型质量对比结论。详细验证范围见 [验证记录](docs/verification.md)。 ## 九、限制与后续改进 - 当前为本地单用户应用，没有登录、租户隔离或公网部署能力；检索范围选择不等同权限控制。 - 单文件限 10 MB，PDF 限 200 页，单文件提取文本限 50 万字符；每次最多 20 文件、共 30 MB，知识库最多 5000 块。扫描 PDF 需先 OCR。 - 文本和向量保存在本地 `data/knowledge.db`，在线生成会将问题与选中片段发送给 DeepSeek。仓库不包含真实密钥和用户资料库。 - 摘录存在不代表它充分支持回答，相关性门槛与提示词也不能完全消除幻觉；需要更多真实标注问题和人工核验。 - 向量计算为增量处理，SQLite 提交仍采用完整快照；更大规模可引入增量 SQL、后台建库与近似向量索引。 - 模型加载和在线请求没有可精确估算的完成百分比，仅显示阶段状态；任务记录只保存在当前会话。 ## 十、开源许可与参考 应用代码采用 [MIT License](LICENSE)。第三方依赖及模型权重遵循各自许可证；使用商业在线 API 不代表该服务随应用一同开源。 - [LangChain DeepSeek 集成说明](https://docs.langchain.com/oss/python/integrations/chat/deepseek) - [DeepSeek API 文档](https://api-docs.deepseek.com/) - [Sentence Transformers 文档](https://www.sbert.net/) 开源仓库：[https://gitee.com/zwr1105/study-rag](https://gitee.com/zwr1105/study-rag)