# course_helper

**Repository Path**: wangofcong/course_helper

## Basic Information

- **Project Name**: course_helper
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-28
- **Last Updated**: 2026-07-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🎓 近屿智能课程咨询助手

> **课程问答助手 + 专业领域顾问** — 基于 RAG 技术的智能课程咨询系统

[![Python](https://img.shields.io/badge/Python-3.9%2B-blue)](https://python.org)
[![Vue 3](https://img.shields.io/badge/UI-Vue_3-4FC08D)](https://vuejs.org)
[![FastAPI](https://img.shields.io/badge/API-FastAPI-green)](https://fastapi.tiangolo.com)
[![ChromaDB](https://img.shields.io/badge/VectorDB-ChromaDB-yellow)](https://chromadb.com)
[![MySQL](https://img.shields.io/badge/DB-MySQL-4479A1)](https://mysql.com)
[![LLM](https://img.shields.io/badge/LLM-OpenAI_Compatible-4A6CF7)](https://platform.deepseek.com)

---

## 📋 目录

- [项目简介](#-项目简介)
- [系统架构](#-系统架构)
- [功能特性](#-功能特性)
- [技术栈](#-技术栈)
- [快速开始](#-快速开始)
- [项目结构](#-项目结构)
- [API 接口](#-api-接口)
- [Docker 部署](#-docker-部署)
- [相关文档](#-相关文档)

---

## 💡 项目简介

"近屿智能课程咨询助手"是一款基于 **RAG（检索增强生成）** 技术的智能课程咨询系统：

**核心能力：**

- 📖 **基于课程文档**回答用户关于课程内容的疑问
- 📄 **上传文档后自动解析**，实时扩充知识库向量
- 🌐 **联网搜索**（SearXNG 自部署），实时获取互联网信息
- 🎯 **意图识别**，区分课程咨询、闲聊、系统报告等场景
- 💬 **多轮对话**，维护上下文理解
- 🔐 **用户认证**，注册/登录，文件级访问控制
- 📊 **系统报告**（root 用户）—— 查询用户/文件/会话/向量库全局统计

---

## 🏗 系统架构

```
┌─────────────────────────────────────────┐
│          用户浏览器访问                   │
│      http://localhost:80 (Nginx)        │
└──────────────────┬──────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────┐
│     Nginx 反向代理 (端口 80，唯一入口)     │
│  ┌──────────────────────────────────────┐│
│  │  /assets/*  →  Vue 静态文件（直接返回）││
│  │  /          →  index.html（SPA 路由） ││
│  │  /api/*     →  反向代理到 FastAPI     ││
│  └──────────────────────────────────────┘│
└──────────────────┬──────────────────────┘
                   │ 内部网络 (Docker)
                   ▼
┌─────────────────────────────────────────┐
│     FastAPI 后端 (内部端口 8000)          │
│  /api/chat  /api/stream  /api/auth      │
│  /api/session  /api/file  /api/know     │
└──────┬────────────────┬─────────────────┘
       │                │
       ▼                ▼
┌──────────────┐  ┌──────────────────┐
│  业务逻辑层   │  │  ChromaDB        │
│  RAG 引擎     │  │  (向量数据库)     │
│  LLM 客户端   │  │  课程文档向量索引  │
│  意图识别     │  └──────────────────┘
│  会话管理     │
│  用户管理     │  ┌──────────────────┐
└──────┬───────┘  │  SearXNG         │
       │          │  (元搜索引擎)      │
       ▼          └──────────────────┘
┌──────────────────────┐
│   LLM API            │
│   (对话 + Embedding) │
└──────────────────────┘

┌──────────────────────┐
│   MySQL 数据库        │
│   users / sessions   │
│   messages           │
└──────────────────────┘
```

---

## ✨ 功能特性

### ✅ 已实现

| 模块 | 功能 | 说明 |
|------|------|------|
| **用户认证** | 注册/登录 | 手机号用户名 + 密码复杂性验证；root 用户首次启动自动创建 |
| **对话交互** | RAG 问答 | 意图识别 → 向量检索 + 联网搜索 → LLM 生成 → 来源标注 |
| **对话交互** | 流式输出 | SSE 逐字显示，低延迟体验 |
| **对话交互** | 多轮对话 | 上下文窗口管理，历史截断 |
| **会话管理** | 新建/切换/删除 | 对话历史持久化到 MySQL，首轮自动生成标题 |
| **文件上传** | 多格式支持 | PDF/DOCX/TXT/PPTX/HTML/IPYNB |
| **文件上传** | 自动解析入库 | 3 层解析降级（Unstructured → 库解析 → 纯文本），分块向量化 |
| **文件访问控制** | 权限隔离 | root 上传的文件对所有用户可见，普通用户上传仅自己可见 |
| **知识库管理** | 向量存储 | ChromaDB 持久化，1024 维向量（LLM Embedding） |
| **系统报告** | root 查询 | 用户统计、文件信息、会话/消息统计、ChromaDB 状态 |
| **信息脱敏** | 隐私保护 | 系统报告中手机号中间 4 位自动 `****` 替换 |
| **联网搜索** | 实时信息获取 | SearXNG 自部署元搜索 + Trafilatura 正文提取，并行于本地知识库检索 |

### 🚧 规划中

- [ ] Rerank 重排序优化
- [ ] 管理员后台页面
- [ ] 会话搜索与全文检索
- [ ] 知识库手动管理界面

---

## 🛠 技术栈

### 前端

| 技术 | 用途 |
|------|------|
| [Vue 3](https://vuejs.org) | 前端框架 (Composition API) |
| [Vite](https://vitejs.dev) | 构建工具 (快速 HMR) |
| [Axios](https://axios-http.com) | HTTP 客户端 |

### 后端

| 技术 | 用途 |
|------|------|
| [FastAPI](https://fastapi.tiangolo.com) | 异步 Web 框架，RESTful API |
| [Uvicorn](https://www.uvicorn.org) | ASGI 服务器 |
| [httpx](https://www.python-httpx.org) | 异步 HTTP 客户端 |
| [Gradio](https://gradio.app) | 备选轻量 UI（旧版，已停用） |

### AI 服务

| 技术 | 用途 |
|------|------|
| LLM API（OpenAI 兼容接口） | 支持 DeepSeek / OpenAI / 通义千问 / 硅基流动 等任意厂商 |
| Embedding API（OpenAI 兼容接口） | 文本向量化（默认 1024 维，可在 .env 中配置） |
| 规则+LLM 意图识别 | 规则匹配（置信度>0.9 短路径）→ LLM 分类降级；泛词"文档/文件"由 LLM 判断而非规则硬匹配 |

### 数据存储

| 技术 | 用途 |
|------|------|
| [MySQL](https://mysql.com) | 用户、会话、消息持久化 |
| [ChromaDB](https://chromadb.com) | 向量数据库 |

### 文件处理

| 技术 | 用途 |
|------|------|
| [Unstructured](https://unstructured.io) | 多格式文档解析 |
| [PyPDF2](https://pypi.org/project/PyPDF2/) | PDF 解析备选 |
| [LangChain Text Splitters](https://python.langchain.com) | 文本分块（500字/块，50字重叠） |
| [python-docx / python-pptx](https://python-pptx.readthedocs.io) | DOCX/PPTX 解析备选 |
| [BeautifulSoup](https://www.crummy.com/software/BeautifulSoup/) | HTML 解析备选 |
| [Trafilatura](https://trafilatura.readthedocs.io) | 网页正文提取（纯本地，零外部依赖） |

### 搜索引擎

| 技术 | 用途 |
|------|------|
| [SearXNG](https://docs.searxng.org) | 自部署元搜索引擎，聚合 Bing/百度/搜狗/DuckDuckGo |

---

## 🚀 快速开始

### 前置条件

- Python ≥ 3.9
- Node.js ≥ 18
- MySQL 8.0+
- LLM API Key（如 DeepSeek / OpenAI / 通义千问 等，[DeepSeek 申请](https://platform.deepseek.com)）

### 1. 克隆项目

```bash
git clone <仓库地址>
cd course_helper
```

### 2. 一键启动（推荐）

**Linux / macOS / Git Bash:**
```bash
./start.sh
```

**Windows PowerShell:**
```powershell
.\start.ps1
```

启动脚本会自动完成：
1. ✅ 创建 `data/uploads`、`data/chroma_db`、`data/sessions` 目录
2. ✅ 检测 `.env` 文件，不存在则从 `.env.example` 复制
3. ✅ 创建 Python 虚拟环境并安装依赖
4. ✅ 安装前端 npm 依赖
5. ✅ 检查 MySQL 连接并自动创建数据库
6. ✅ 启动 FastAPI（8000） + Vue 开发服务器（5173）

### 3. 手动启动（分步）

```bash
# 1. 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 2. 安装依赖
pip install -r requirements.txt
cd frontend && npm install && cd ..

# 3. 配置环境变量
cp .env.example .env
# 编辑 .env 填入真实密钥

# 4. 创建数据库（如果尚未创建）
mysql -u root -p -e "CREATE DATABASE course_helper DEFAULT CHARSET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# 5. 终端 1 — FastAPI 后端
uvicorn api.main:app --reload --host 0.0.0.0 --port 8000

# 6. 终端 2 — Vue 前端
cd frontend && npm run dev

# 7. Docker 部署（替代上述步骤 5-6）
# docker compose up --build
```

### 4. 访问服务

| 环境 | 地址 | 说明 |
|------|------|------|
| **本地开发 — Vue 前端** | http://localhost:5173 | Vite 开发服务器（热更新） |
| **本地开发 — FastAPI** | http://localhost:8000 | 后端 API（含 Swagger 文档） |
| **Docker 生产部署** | http://localhost:80 | Nginx 统一入口（仅限前端路由） |
| **Docker API 文档** | 不暴露 | 生产环境 Swagger 仅本地调试时直接访问 FastAPI |

---

## 📁 项目结构

```
course_helper/
│
├── start.sh / start.ps1       # 一键启动脚本
├── .env.example               # 环境配置模板
├── docker-compose.yml         # Docker 编排（含 Nginx + MySQL）
├── Dockerfile                 # FastAPI 应用镜像构建
├── Dockerfile.nginx           # Nginx 多阶段构建（Vue 构建 + 反向代理）
├── searxng/
│   └── settings.yml           # SearXNG 元搜索引擎配置
├── deploy/
│   └── nginx.conf             # Nginx 生产配置文件
├── .dockerignore              # Docker 构建排除
│
├── app.py                     #（旧版 Gradio UI，已停用）
├── requirements.txt           # Python 依赖
│
├── api/                       # FastAPI 路由层
│   ├── main.py                # 入口 + CORS + 启动事件
│   ├── auth.py                # 认证接口
│   ├── chat.py                # 聊天接口（含 SSE 流式）
│   ├── session.py             # 会话管理接口
│   ├── file.py                # 文件管理接口
│   └── knowledge.py           # 知识库入库接口
│
├── core/                      # 核心业务逻辑
│   ├── config.py              # 全局配置（.env → Settings）
│   ├── database.py            # MySQL 连接
│   ├── user_manager.py        # 用户管理（注册/登录/查询）
│   ├── session_manager.py     # 会话管理（MySQL 持久化）
│   ├── rag_engine.py          # RAG 检索引擎（检索+生成+流式）
│   ├── llm_client.py          # LLM API 客户端（同步+流式，OpenAI 兼容接口）
│   └── intent_recognizer.py   # 意图识别（规则+LLM 降级）
│
├── services/                  # 服务层
│   ├── file_processor.py      # 文件解析（3层降级）
│   ├── embedding_service.py   # 向量化服务
│   ├── web_search.py          # 联网搜索（SearXNG + Trafilatura）
│   └── knowledge_base.py      # 知识库管理
│
├── db/                        # 数据库层
│   ├── chroma_client.py       # ChromaDB 客户端封装
│   └── vector_store.py        # 向量存储操作（CRUD + 统计）
│
├── frontend/                  # Vue 3 前端
│   ├── package.json
│   ├── vite.config.js         # Vite 配置（代理 /api → 8000）
│   ├── src/
│   │   ├── App.vue            # 根组件
│   │   ├── main.js            # 入口
│   │   ├── style.css          # 全局样式
│   │   ├── api/
│   │   │   └── client.js      # API 客户端（axios + fetch SSE）
│   │   ├── components/
│   │   │   ├── ChatArea.vue   # 主聊天区域
│   │   │   ├── SideBar.vue    # 侧栏会话列表
│   │   │   ├── ChatMessage.vue# 单条消息组件
│   │   │   ├── LoginModal.vue # 登录弹窗
│   │   │   └── RegisterModal.vue # 注册弹窗
│   │   └── store/
│   │       └── index.js       # 响应式状态管理
│   └── index.html
│
├── sql/
│   └── init.sql               # MySQL 初始化脚本
│
├── docs/                      # 项目文档
│   ├── architecture.md        # 系统架构
│   ├── development.md         # 开发指南
│   └── function-map.md        # 功能全景图
│
├── tests/                     # 测试
│   ├── test_rag.py
│   └── test_api.py
│
└── data/                      # 运行时数据（被 gitignore，首次运行自动创建）
    ├── uploads/               # 上传的文件
    ├── chroma_db/             # ChromaDB 持久化目录
    └── sessions/              # 旧版 JSON 会话（迁移后只读）
```

---

## 📡 API 接口

### 认证

| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/api/auth/register` | 用户注册 |
| `POST` | `/api/auth/login` | 用户登录 |

### 聊天

| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/api/chat` | 发送消息（同步返回） |
| `POST` | `/api/chat/stream` | 发送消息（SSE 流式返回） |

### 会话

| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/api/session/create` | 创建新会话 |
| `POST` | `/api/session/delete` | 删除会话 |
| `GET` | `/api/session/list` | 获取会话列表 |
| `GET` | `/api/session/{session_id}` | 获取会话详情 |

### 文件与知识库

| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/api/file/upload` | 上传文件 (multipart) |
| `POST` | `/api/knowledge/ingest` | 文档入库（解析 → 分块 → 向量化） |
| `GET` | `/api/knowledge/status` | 知识库状态 |
| `POST` | `/api/knowledge/clear` | 清空知识库 |

---

## 🐳 Docker 部署

### 一键部署

```bash
./start.sh --docker
# 或
docker compose up --build
```

### Docker Compose 服务

```yaml
services:
  mysql:            # MySQL 8.0，自动创建数据库
  nginx:            # Nginx 反向代理（唯一入口，端口 80）
  app:              # FastAPI 后端（内部 8000，不对外暴露）
  searxng:          # SearXNG 元搜索引擎（自部署，零费用）
```

- **Nginx** 是生产环境唯一入口，提供：
  - Vue SPA 静态文件托管（带浏览器缓存优化）
  - `/api/*` 反向代理到 FastAPI（SSE 流式支持）
  - 安全头、Gzip 压缩、SPA 路由回退
- **FastAPI** 仅在 Docker 内部网络通信，端口不暴露到宿主机
- **SearXNG** 提供联网搜索能力，通过 Docker 内部网络被 app 调用（`http://searxng:8080`）
- MySQL 数据持久化在 Docker 卷 `mysql_data`
- 应用数据 `./data` 挂载到容器 `/app/data`
- Vue 前端通过 `Dockerfile.nginx` 多阶段构建，不依赖宿主机 Node 环境
- 访问 `http://localhost:80` 即可打开 Vue SPA

**注意：**
- 本地开发建议用 `./start.sh` 本地模式，Docker 模式用于生产
- Docker 中 MySQL 端口映射为 3307 避免与本地冲突
- 如需调试 API（如 Swagger），可临时取消 `app` 服务的端口注释：`# ports: - "8000:8000"`

---

## 📚 相关文档

| 文档 | 说明 |
|------|------|
| **[系统架构文档](docs/architecture.md)** | 详细架构图、技术栈、模块设计、API 接口、数据流 |
| **[开发指南](docs/development.md)** | 环境搭建、模块开发、代码规范、部署方案 |
| **[功能全景图](docs/function-map.md)** | 产品功能架构完整视图 |
| **[CLAUDE.md](CLAUDE.md)** | 项目 AI 开发助手配置 |

---

## 🤝 贡献指南

1. Fork 本仓库
2. 创建特性分支：`git checkout -b feat/your-feature`
3. 提交更改：`git commit -m 'feat: add some feature'`
4. 推送分支：`git push origin feat/your-feature`
5. 提交 Pull Request

---

## 📄 许可证

本项目基于 MIT 许可证开源。

---

*文档版本：v1.0.0 · 最后更新：2026年6月*