为《人工智能导论》课程学生打造的可解释问答助手:围绕课程核心概念(KNN、神经网络、CNN、大模型、Prompt 工程、RAG 等)做精准答疑。答案基于课程讲义切片检索生成,减少大模型幻觉;DeepSeek-R1 的思考链(reasoning_content)可展开查看,让「AI 是怎么找到答案的」一目了然。知识库全部本地化(课程材料不出本机),LLM 走 DeepSeek 官方云端 API。
|
课程材料 → 切片 → BGE 中文向量 → ChromaDB 检索 → 构造 prompt 喂给 LLM。低于相似度阈值(默认 0.25)的切片直接丢弃,不硬凑答案。 |
展示 DeepSeek-R1 的完整推理过程( |
|
文档解析、向量嵌入、向量库全部本地运行;只有最终问题 + 命中切片发给 DeepSeek 云端 API,API Key 走 |
Gradio 双栏布局:左侧对话(含示例问题),右侧实时展示命中的参考资料(来源、章节、相似度),附耗时与 token 用量统计。 |
flowchart TD
subgraph 离线建库
A["docs/ 课程材料<br>PDF / DOCX / MD / TXT"] --> B["src/ingest.py<br>加载 + 清洗 + 切分"]
B --> C["corpus/chunks.json<br>切片语料"]
C --> D["src/embed_index.py<br>BGE-small-zh 向量化"]
D --> E[("vectorstore/<br>ChromaDB 本地向量库")]
end
subgraph 在线问答
Q["用户提问<br>Gradio Web 界面"] --> R["src/retriever.py<br>cosine 检索 top_k=4"]
E --> R
R -->|≥ 阈值 0.25| P["src/prompt.py<br>构造 system + user prompt"]
P --> L["DeepSeek 官方 API<br>deepseek-reasoner (R1)"]
L --> O["答案 + 思考链<br>+ 引用来源展示"]
end
- Python 3.10+(推荐 3.11)
- DeepSeek API Key:到 https://platform.deepseek.com/api_keys 申请(注册送免费额度)
cp .env.example .env
# 编辑 .env,把 DEEPSEEK_API_KEY 改成你的 key(sk-xxx 格式)
chmod 600 .env # 关键!防止 key 泄露
⚠️ 绝对不要把 key 贴到任何聊天工具里,被刷额度很快。
python3.11 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python -m src.ingest # 文档切片 → corpus/
python -m src.embed_index # 向量化 → vectorstore/
python -m src.app # 浏览器打开 http://localhost:7860python -m venv .venv
.\.venv\Scripts\Activate.ps1 # CMD 用 .venv\Scripts\activate.bat
# 若报「禁止运行脚本」:Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
pip install -r requirements.txt
python -m src.ingest
python -m src.embed_index
python -m src.app| 变量 | 默认值 | 说明 |
|---|---|---|
DEEPSEEK_MODEL |
deepseek-reasoner |
R1 带思考链(演示推荐);deepseek-chat(V3)更快但无思考链 |
EMBEDDING_MODEL |
BAAI/bge-small-zh-v1.5 |
本地中文向量模型,约 93MB |
TOP_K / SCORE_THRESHOLD |
4 / 0.25 |
检索条数与 cosine 相似度阈值 |
CHUNK_SIZE / CHUNK_OVERLAP |
400 / 80 |
切片字符数与重叠 |
HF_ENDPOINT |
https://huggingface.co |
国内出网慢时改 https://hf-mirror.com |
GRADIO_PORT |
7860 |
Web 界面端口 |
换一批课程材料后重跑 python -m src.ingest && python -m src.embed_index 即可重建知识库。批量回归测试用 python -m src.run_tests(读取 tests/test_questions.json,结果写入 outputs/)。
ai-intro-rag-assistant/
├── README.md # 本文件
├── requirements.txt # Python 依赖
├── .env.example # 环境变量模板(复制为 .env,勿提交)
├── 演示视频脚本.md # 视频录制脚本(5-10 分钟逐段讲解稿)
├── 论文大纲.md # 课程报告论文骨架
├── docs/ # 原始课程材料(MD 讲义,9 章)
├── corpus/ # 处理后的知识库切片(chunks.json,60 片)
├── vectorstore/ # ChromaDB 持久化目录(运行时生成,不入库)
├── outputs/ # 测试结果与报告产物
├── src/
│ ├── config.py # 配置加载(.env 集中管理)
│ ├── ingest.py # 文档加载(PDF/DOCX/MD/TXT)+ 切分
│ ├── embed_index.py # BGE 向量化 + 入 ChromaDB
│ ├── retriever.py # cosine 检索 + 阈值过滤
│ ├── rag.py # RAG 主流程 + 思考链处理
│ ├── prompt.py # Prompt 模板
│ ├── run_tests.py # 批量测试脚本
│ └── app.py # Gradio Web 界面
└── tests/
└── test_questions.json # 12 条测试用例(含期望关键词)
| 组件 | 选型 | 作用 |
|---|---|---|
| 大模型 | DeepSeek-Reasoner(云端 API,兼容 OpenAI 协议) | 推理 + 思考链 |
| Embedding | BAAI/bge-small-zh-v1.5(本地 sentence-transformers) | 中文语义向量化 |
| 向量库 | ChromaDB(本地持久化) | 文档检索 |
| 前端 | Gradio | Web 交互界面 |
| 文档加载 | pypdf + python-docx + markdown + bs4 | 解析课程材料 |
| 报错 | 原因 | 解决 |
|---|---|---|
Authentication FAILED / 401 |
API key 错或没填 | 检查 .env 里 DEEPSEEK_API_KEY,注意无多余空格 |
未配置 DEEPSEEK_API_KEY |
启动时 key 为空 | 填好 .env;用 python -m src.config 验证 API_KEY set = True |
source : 无法将"source"项识别为 cmdlet |
PowerShell 里用了 bash 语法 | PowerShell 用 .\.venv\Scripts\Activate.ps1;CMD 用 .venv\Scripts\activate.bat |
无法加载文件…禁止运行脚本 |
PowerShell 默认禁 .ps1 | Set-ExecutionPolicy RemoteSigned -Scope CurrentUser |
Could not open requirements file |
目录不对或 venv 未激活 | cd 到项目根目录后重新激活 venv |
ModuleNotFoundError: No module named 'openai' |
依赖没装 | pip install -r requirements.txt |
| 向量库为空 / 检索 0 命中 | 没建索引 | 先跑 python -m src.ingest 和 python -m src.embed_index |
- 成员 A:需求分析 + RAG 核心代码 + 模型部署
- 成员 B:界面设计 + 文档整理 + 测试评估 + 视频录制
- 单轮问答为主,不保留多轮对话上下文给 LLM(历史仅展示在前端)
- 检索为纯向量召回(无 BM25/重排),切片策略为字符级 + 段落优先,复杂跨页推理能力有限
- 答案质量依赖 DeepSeek 云端 API 可用性与账户余额
- 代码编写:Claude / GPT 辅助
- 报告撰写:Claude / GPT 辅助起草
- 模型:DeepSeek-R1(官方云端 API)
- 视频剪辑:iMovie / CapCut
Built with DeepSeek API · BGE Embeddings · ChromaDB · Gradio