Skip to content

About

AI Intro course final project - RAG over local corpus with DeepSeek + BGE embeddings + ChromaDB

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

《人工智能导论》课程知识问答助手

基于 DeepSeek 官方 API + 本地 RAG 的课程专属智能问答系统 —— 答案有据可查,思考过程可见

Python License: MIT Last Commit Repo Size


为《人工智能导论》课程学生打造的可解释问答助手:围绕课程核心概念(KNN、神经网络、CNN、大模型、Prompt 工程、RAG 等)做精准答疑。答案基于课程讲义切片检索生成,减少大模型幻觉;DeepSeek-R1 的思考链(reasoning_content)可展开查看,让「AI 是怎么找到答案的」一目了然。知识库全部本地化(课程材料不出本机),LLM 走 DeepSeek 官方云端 API。

✨ 亮点

📚 检索增强,拒绝幻觉

课程材料 → 切片 → BGE 中文向量 → ChromaDB 检索 → 构造 prompt 喂给 LLM。低于相似度阈值(默认 0.25)的切片直接丢弃,不硬凑答案。

🧠 思考链可视化

展示 DeepSeek-R1 的完整推理过程(reasoning_content);无思考链时自动基于检索流程合成「思考过程」,教学场景下让推理路径可解释。

🔒 知识库不出本机

文档解析、向量嵌入、向量库全部本地运行;只有最终问题 + 命中切片发给 DeepSeek 云端 API,API Key 走 .env + chmod 600 保护。

🖥️ 开箱即用的 Web 界面

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
Loading

🚀 快速开始

前置条件

第一步:配置 API Key

cp .env.example .env
# 编辑 .env,把 DEEPSEEK_API_KEY 改成你的 key(sk-xxx 格式)
chmod 600 .env   # 关键!防止 key 泄露

⚠️ 绝对不要把 key 贴到任何聊天工具里,被刷额度很快。

macOS / Linux

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:7860

Windows(PowerShell / CMD)

python -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

⚙️ 配置要点(.env)

变量 默认值 说明
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 可用性与账户余额

🤖 AI 工具使用声明

  • 代码编写:Claude / GPT 辅助
  • 报告撰写:Claude / GPT 辅助起草
  • 模型:DeepSeek-R1(官方云端 API)
  • 视频剪辑:iMovie / CapCut

《人工智能导论》课程期末大作业 · MIT License
Built with DeepSeek API · BGE Embeddings · ChromaDB · Gradio

About

AI Intro course final project - RAG over local corpus with DeepSeek + BGE embeddings + ChromaDB

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages