六级笔记问答 TheBy-star/cet6-rag-atlas

CET6-RAG Atlas

面向大学英语六级备考的垂直领域检索增强生成助手

面向大学英语六级备考的垂直领域 RAG 智能问答系统

English · 概述 · 架构 · 快速开始 · 踩坑记录

📖 Overview | 项目简介

CET6-RAG Atlas 是垂直领域的 RAG 助手，只做一件事：把学习者自己的六级笔记变成有依据、可引用的问答系统。

它不是又一个 ChatGPT 套壳。每个回答都来自检索到的个人笔记——词汇条目、长难句分析、翻译错题记录——每条结论都能追溯到来源片段。

CET6-RAG Atlas 是一个面向大学英语六级备考的垂直领域 RAG 问答系统。它把个人整理的高频词汇、阅读长难句分析和翻译错题本转化为可检索的本地知识库，让大模型在个人笔记的约束下回答问题，并给出可展开查看的引用来源。

Design principle / 设计原则

先检索，后生成。资料里没有依据时，系统应该明确说“资料不足”，而不是编造。

先检索，后生成。资料里没有依据时，系统应该明确说“资料不足”，而不是编造。

Why "Atlas"? | 为什么叫 Atlas

Atlas 不是地图的堆叠，而是对一片知识疆域的结构化索引。这个项目把个人笔记切分成可检索的知识单元，映射到向量空间，再按语义召回并组装成有依据的回答。

Atlas 不是地图的堆叠，而是对一片知识疆域的结构化索引。这个项目把个人笔记切分成可检索的知识单元，映射到向量空间，再按语义召回并组装成有依据的回答。

✨ Core Features | 核心特性

1. Citation-Grounded Generation | 引用溯源防幻觉

每个回答都基于 top-K 检索片段构成的有限上下文生成。提示词要求模型标注 [1]、[2]、[3]，界面会展示每条引用背后的源文件、章节和向量距离。

- English: 不引入模型自身的游离知识。检索到的上下文不够时，助手会明确说明。
- 中文： 回答只允许使用检索到的个人笔记；资料不足时明确说明，避免“看起来很对”的幻觉答案。
- Traceability / 可追溯： source + section + chunk_id + distance 全部保留，点击“查看检索来源”即可核对原文。

2. Structured Prompt & Structured Output | 结构化 Prompt 与输出

提示词按三段式契约组装：

[System Role] CET-6 tutor; answer only from retrieved context
1. 直接结论 / Direct conclusion
2. 地道表达或语法分析 / Idiomatic expression or grammar analysis
3. 易错点 / Common pitfalls
4. 引用编号 / Citations

这样输出可预测，学习者更容易理解，也比自由聊天式回答更容易评估。

3. 本地优先、轻量部署 | Local-First, Lightweight Deployment

- 本地知识： 笔记、切分结果和 ChromaDB 向量都保存在磁盘上。
- 检索兜底： ChromaDB 文件不可用或损坏时，应用自动切换到基于 NumPy 的本地索引（data/local_index），界面仍可正常使用。
- 轻量嵌入： BAAI/bge-small-zh-v1.5 通过 FastEmbed + ONNX Runtime 运行，不依赖 PyTorch，也不需要 GPU。
- 最小网络暴露面： 生成时只把检索到的上下文和问题发送给 DeepSeek API。
- 一条命令启动界面： streamlit run app.py，或双击 Windows 的 .bat 脚本。

中文： 笔记、切分结果和向量库全部保存在本地；BGE 使用 ONNX 推理，不装 PyTorch、不要求 GPU；只有生成回答时，检索到的片段和问题会发送给 DeepSeek。

4. 垂直领域设计 | Vertical-Domain by Design

| 资料 / Corpus | 用途 / Purpose | 元数据 |
| 高频词汇 / Vocabulary | 词义、搭配、例句 | doc_type=vocabulary |
| 阅读长难句 / Long Sentences | 主干、修饰成分、语法分析 | doc_type=long_sentences |
| 翻译错题本 / Translation Errors | 原文、试译、参考译文、错因 | doc_type=translation |

系统刻意做窄：它是 CET-6 学习助手，不是通用聊天机器人。窄是特性——检索、提示词和评估都因此变得可控。

5. 条目感知切分 | Entry-Aware Chunking

流水线不按字符数盲目切分，而是先用 --- 分隔符把笔记拆成自包含条目，再只对超出切分预算的条目递归切分。

- 把「原文 / 我的译文 / 参考译文 / 错因」保留为一个语义单元。
- 默认：chunk_size=400，chunk_overlap=80，按 BGE 的 512 token 输入窗口调优。
- 添加 source、doc_type、section、chunk_id 和 char_count 元数据，用于过滤和引用。

🏗 系统架构 | System Architecture mermaid
flowchart LR
subgraph IDX["① Offline Indexing / 离线建库"] direction LR
T["📚 Personal NotesTXT"] --> K["✂️ Entry-aware Chunking400 / 80"]
K --> E["🧠 BGE Embeddingbge-small-zh-v1.5"]
E --> DB[("🗂️ ChromaDBLocal Persistent Store")]
end

subgraph RAG["② Online RAG / 在线问答"] direction LR
U["👤 User Query用户提问"] --> Q["🧠 BGE Query Embedding问题向量化"]
Q --> R["🔍 Top-K RetrievalChromaDB 检索"]
R --> P["🧩 Prompt AssemblyContext + Query + Guardrails"]
P --> L["🤖 DeepSeek APIdeepseek-chat"]
L --> F["🖥️ Streamlit UIAnswer + Citations"]
end

DB -.-> R
F --> C["📌 Source / Section / Distance引用溯源"]

在线链路 / Online path：text 用户提问 → BGE 向量化 → ChromaDB Top-K 检索 → 组装 Prompt（资料 + 问题 + 约束） → DeepSeek 生成 → Streamlit 展示回答与引用

离线链路： text 个人笔记 txt → 按条目切分 → chunks.jsonl → BGE Embedding → ChromaDB 持久化

高分辨率 SVG 版本见 docs/architecture.svg。

🧰 技术栈

| 层 | 技术 | 选型理由 |
| 语言 | Python 3.12 | Windows 上 AI 生态稳定 |
| 前端 | Streamlit 1.66 | 快速搭聊天界面，样板代码少 |
| 编排 | LangChain Core + Text Splitters | 文档抽象与递归切分 |
| 向量化 | BAAI/bge-small-zh-v1.5（512 维） | 体积小，中文检索强 |
| 向量化运行时 | FastEmbed + ONNX Runtime | 不依赖 PyTorch，对 CPU 友好 |
| 向量库 | ChromaDB 1.5 | 本地持久化，Python API 简单 |
| 大模型 | DeepSeek deepseek-chat | 中文生成强，API 兼容 OpenAI |
| HTTP 客户端 | requests | 直接控制 Chat Completions 请求 |

设计目标： 在普通 Windows 笔记本上跑通全流程，不需要 GPU，也不需要笨重的深度学习栈。

📸 效果展示

CET6-RAG Atlas demo

示例：

| 项 | 值 |
| 提问 | 六级翻译中促进经济怎么翻最地道？ |
| Top-1 来源 | translation/翻译错题本.txt → 促进经济（高频搭配） |
| 距离 | 0.6607 |
| 回答 | boost economic growth / give a boost to the economy |
| 引用 | [1]、[2]、[3]，附可展开的来源卡片 |

🚀 快速开始

环境要求

- Windows 10 / 11（macOS / Linux 用等价命令同样可以）
- Python 3.12
- 一个余额充足的 DeepSeek API key
- 不需要 GPU

1. 克隆并创建虚拟环境 bash
git clone https://github.com/<your-name>/cet6-rag-atlas.git
cd cet6-rag-atlas

py -3.12 -m venv .venv

激活环境： powershell

Windows PowerShell

.\.venv\Scripts\Activate.ps1

If script execution is blocked, use the interpreter directly:

.\.venv\Scripts\python.exe <command>

2. 用镜像安装依赖 powershell .\.venv\Scripts\python.exe -m pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt

如果 pip 新版依赖解析器在 Windows 上卡住，改用旧版解析器： powershell .\.venv\Scripts\python.exe -m pip install --use-deprecated=legacy-resolver -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt

注意： 不要在安装脚本里顺手升级 pip；部分 Windows 环境下 pip install -U pip 会长时间卡住。

3. 配置 API Key powershell Copy-Item .env.example .env

编辑 .env： text
DEEPSEEK_API_KEY=sk-your-key-here

.env 已被 Git 忽略，绝不能提交。

4. 构建知识库 powershell .\.venv\Scripts\python.exe step1_chunk.py .\.venv\Scripts\python.exe step2_build_index.py

首次运行会下载 BGE 模型（约 95 MB）。中国大陆用户请先设置：

$env:HF_ENDPOINT = "https://hf-mirror.com"

5. 启动 Streamlit

.\.venv\Scripts\python.exe -m streamlit run app.py

打开：

http://localhost:8501

如果 ChromaDB 打不开数据库文件，应用会自动回退到 data/local_index/ 里的 NumPy 索引。需要时运行 python local_index.py 重建。

如果 ChromaDB 数据库文件损坏，页面会自动切换到 data/local_index/ 的 NumPy 索引；需要手动重建时运行 python local_index.py。

6. 可选：命令行模式

.\.venv\Scripts\python.exe step3_ask.py

然后提问：

六级翻译中促进经济怎么翻最地道？

输入 exit 退出。

Windows 一键脚本

| 脚本 | 用途 |
| 一键运行.bat | 从 data/raw 构建分块 |
| 一键运行_第二步.bat | 向量化分块并构建 ChromaDB |
| 一键运行_第三步.bat | 命令行 RAG 问答 |
| 一键运行_第四步.bat | 启动 Streamlit 界面 |

📂 数据格式

把笔记放到：

仓库自带 6 条翻译错题示例，放在 data/raw/translation/ 下，clone 后即可直接跑通演示。正式使用时请替换成你自己的笔记。如果笔记含隐私信息，提交前先把 data/raw/ 加进 .gitignore。

仓库自带 6 条翻译错题示例，保证 clone 后可以立即跑通。正式使用时请替换为自己的笔记；如果笔记包含隐私，提交前把 data/raw/ 加入 .gitignore。

data/raw/
├─ vocabulary/ # 高频词汇 ├─ long_sentences/ # 阅读长难句 └─ translation/ # 翻译错题

每条记录以 ## 开头，条目之间用单独一行 --- 分隔：

促进经济【中文原文】这些措施将有力促进经济发展。
【我的译文】These measures will strongly promote economic development. 【参考译文】These measures will give a strong boost to economic growth. 【错因】“促进经济”更地道的搭配是 boost economic growth。

减少污染【中文原文】政府正在采取措施减少空气污染。
【参考译文】The government is taking measures to reduce air pollution. 【错因】pollution 是泛指，不需要加 the。

整理建议：

- 一条记录 = 一个独立知识点。
- 尽量把每条控制在 400 个汉字以内。
- 用主题做标题，别写「错题 1」/「句子 2」。
- 长难句条目保留中文语法分析，这对中文查询的召回提升很明显。
- 不要把问题和答案拆到不同文件里。

🧠 核心实现

1. 切分策略

| 参数 | 取值 | 理由 |
| 条目分隔符 | --- | 保留独立的问答 / 单词 / 句子单元 |
| chunk_size | 400 字符 | 适配 BGE 的 512 token 窗口，留出头部余量 |
| chunk_overlap | 80 字符 | 保留边界上下文 |
| 切分器 | RecursiveCharacterTextSplitter | 优先按段落 → 句子 → 字符切分 |

每个输出分块都带这些字段：

{
"source": "translation/翻译错题本.txt", "doc_type": "translation", "section": "促进经济", "chunk_id": "chk_xxx", "char_count": 319 }

2. 检索配置

| 设置项 | 值 |
| Top-K | 3 |
| 距离度量 | ChromaDB 默认值（归一化向量上的 L2） |
| 嵌入维度 | 512 |
| Collection | cet6_notes |
| 存储位置 | data/chroma_db/ |

3. Prompt 约束

SYSTEM:
You are a CET-6 tutor. Answer only from the retrieved context.
If the context is insufficient, say so explicitly. Do not invent facts.
Cite sources as [1], [2], [3].

USER:
[Retrieved Context]
[1] source / section
...

[Question]
...

Produce:
1. Direct conclusion
2. Idiomatic expression or grammar analysis
3. Common pitfalls
4. Citations

4. 为什么用 FastEmbed

sentence-transformers 会引入 PyTorch，Windows 下体积可能超过 2 GB，安装阻力很大。FastEmbed 通过 ONNX Runtime 跑同一个 BGE 模型，安装包轻量，对单用户本地 RAG 应用来说够用。

中文： sentence-transformers 会引入 PyTorch，Windows 下安装体积大、失败率高；FastEmbed 使用 ONNX Runtime 加载同一个 BGE 模型，体积小、CPU 可跑，非常适合个人本地项目。

🧑💻 开发者踩坑记录

1. ChromaDB on Windows: path escaping / 路径转义问题

现象：

chromadb.errors.InternalError:
error returned from database: (code: 14) unable to open database file

原因：

在 Windows 下，如果传给 PersistentClient 的路径末尾没有分隔符，ChromaDB 可能把最后一级目录当成数据库文件名，导致 SQLite 文件落到父目录，进而报 unable to open database file。

错误写法：

client = chromadb.PersistentClient(path=str(DB_DIR))

正确写法：

import os

client = chromadb.PersistentClient(path=str(DB_DIR) + os.sep)

补充修复：

不要每次运行都删掉整个数据库目录再重建。Windows 下未释放的文件句柄会阻止删除目录。保留目录，只重建 collection：

client = chromadb.PersistentClient(path=str(DB_DIR) + os.sep)

try:
client.delete_collection(COLLECTION_NAME)
except Exception:
pass

collection = client.create_collection(COLLECTION_NAME)

中文： 不要每次运行都 shutil.rmtree(chroma_db)。Windows 文件句柄未释放时，删目录会失败；保留目录、只重建 collection 更稳。

2. pip 解析器卡住

现象： 安装卡在 Requirement already satisfied: pip 之后，有时持续几分钟，CPU 占用很高。

修复：

python -m pip install --use-deprecated=legacy-resolver -r requirements.txt

另外，自动化脚本里不要执行 pip install -U pip。

3. 镜像地址拼写错误

少写一个 /，就会把：

https://pypi.tuna.tsinghua.edu.cn/simple

变成：

https://pypi.tuna.tsinghua.edu.cn-simple
第二个是不同主机名，会报 getaddrinfo failed 失败。

4. HuggingFace model download is slow | 模型下载慢

$env:HF_ENDPOINT = "https://hf-mirror.com"

模型会缓存到 models/ 下，所以这只是一次性开销。

5. Streamlit first-run prompt | Streamlit 首次运行提示

项目自带 .streamlit/config.toml，其中 headless = true，用来跳过首次运行的邮箱提示。Windows 启动脚本会在服务器启动后主动打开浏览器。

📁 Project Structure | 目录结构

cet6-rag-atlas/
├─ app.py # Streamlit UI
├─ step1_chunk.py # TXT → chunks.jsonl
├─ step2_build_index.py # BGE → ChromaDB
├─ step3_ask.py # CLI RAG pipeline
├─ local_index.py # NumPy fallback index
├─ requirements.txt
├─ .env.example
├─ .streamlit/
│ └─ config.toml
├─ data/
│ ├─ raw/ # your notes (vocabulary / long sentences / translation)
│ ├─ chunks/chunks.jsonl # generated
│ ├─ chroma_db/ # generated vector store
│ └─ local_index/ # generated fallback index
├─ models/ # BGE cache (generated)
├─ docs/
│ ├─ architecture.svg
│ └─ demo-answer.png
├─ 一键运行*.bat # Windows launchers ├─ LICENSE └─ README.md

🗺 Roadmap | 路线图

- [x] Entry-aware chunking with metadata
- [x] BGE + ChromaDB local vector store
- [x] DeepSeek grounded generation with citations
- [x] Streamlit chat UI with expandable sources
- [ ] Hybrid retrieval (BM25 + dense vectors)
- [ ] Cross-encoder reranking (bge-reranker)
- [ ] Retrieval evaluation set (Recall@K, citation hit rate)
- [ ] Incremental indexing for edited notes
- [ ] Conversation memory with context compression
- [ ] Dockerized deployment

⚠️ Limitations | 当前限制

- 自带的示例索引只有 6 条翻译错题分块。在补上长难句语料之前，问长难句会正确返回「上下文不足」。
- 检索只用稠密向量，还没有 BM25 或重排器。
- 面向单用户本地使用，没有鉴权，也没有多租户隔离。
- 生成质量取决于个人笔记的覆盖面和结构。

中文： 当前示例库只有 6 条翻译错题；长难句问题会提示资料不足。项目定位是个人本地学习工具，不是多用户生产系统。

🤝 Contributing | 参与贡献

欢迎提 issue 和 pull request。如果你要新增语料或检索功能，请一并附上：

1. 最小可复现示例。
2. 改动前后的预期检索结果。
3. 任何新增依赖，并简要说明理由。

改动较大时，请先开 issue 讨论设计。

📄 License | 许可证

代码以 MIT License 发布。

个人笔记、API key、生成的向量库和模型缓存不属于开源代码，不要提交。

🙏 Acknowledgements | 致谢

- LangChain 提供文档抽象和文本切分器
- ChromaDB：本地向量存储
- BAAI：提供 bge-small-zh-v1.5
- FastEmbed：轻量 ONNX 嵌入
- DeepSeek：生成 API
- Streamlit：UI 层

Built for focused CET-6 preparation — retrieve your own notes, cite your own evidence.

为专注的六级备考而建：检索自己的笔记，引用自己的依据。

如果这个项目帮到了你，欢迎给个 ⭐。