📚 FlipTutor — 以教促学·智能反向课堂

通过"教"来学习，让 AI 成为你的学习伙伴

FlipTutor 是一个基于费曼学习法的智能教学辅助平台。通过让学生向 AI 讲解知识点，系统会智能提问、评估理解程度，并提供个性化的复习建议。结合语义向量检索技术，实现智能的知识点关联和复习推荐。

✨ 核心特性

🎓 教学演练

• 自由讲解：像老师一样讲解任何知识点
• 智能追问：AI 基于讲解内容生成针对性问题
• 智能评分：多维度评估理解深度和准确性
• 个性化反馈：指出知识盲点并提供改进建议
• 复习计划：自动生成一周复习计划

🔍 语义检索

• 向量化存储：使用 Sentence-Transformers 进行文本嵌入
• 语义相似搜索：基于内容相似度而非关键词匹配
• 智能过滤：按用户、主题、时间筛选
• 关键词高亮：搜索结果智能高亮匹配内容
• 详情展开：直接查看历史讲解的完整记录

👤 用户系统

• 安全认证：JWT Token + HttpOnly Cookie 双模式
• 权限隔离：用户数据完全隔离
• 会话管理：自动续期和安全登出

🎨 现代化界面

• 深色主题：护眼的渐变配色方案
• 毛玻璃效果：Glassmorphism 设计风格
• 流畅动画：丰富的交互动画和过渡效果
• 响应式布局：完美适配桌面和移动设备

🛠️ 技术栈

前端

• 框架：Vue 3 (Composition API)
• 构建工具：Vite
• 样式：CSS Variables + 渐变设计
• 状态管理：Reactive Refs
• HTTP 客户端：Fetch API

后端

• 框架：FastAPI
• 认证：JWT (PyJWT)
• 数据库：SQLite + SQLAlchemy
• AI 模型：DeepSeek API
• 语义向量：Sentence-Transformers (BGE-small-zh-v1.5)
• 密码加密：bcrypt

数据存储

• 结构化数据：SQLite (用户、讲解记录、评分)
• 向量数据：NumPy + JSON (语义嵌入、元数据)

🚀 快速开始

环境要求

• Python 3.10+
• Node.js 16+
• pip / npm
• BGE 语义模型（~400MB，需提前下载）

⚠️ 重要准备：项目运行前必须先下载 BAAI/bge-small-zh-v1.5 模型到本地！

📋 安装流程概览

1. 克隆项目
2. 下载语义模型 ⬅️ 最重要！
3. 安装后端依赖
4. 配置环境变量
5. 安装前端依赖
6. 启动服务

1. 克隆项目

git clone <your-repo-url>
cd fliptutor_vue_semantic_auth

2. 后端配置

安装依赖

pip install -r requirements.txt

下载语义模型（必需）

本项目使用 BAAI/bge-small-zh-v1.5 语义模型，需要手动下载到本地。

方法一：使用 Hugging Face CLI

# 安装 huggingface-cli
pip install huggingface-hub

# 下载模型（需要科学上网）
huggingface-cli download BAAI/bge-small-zh-v1.5 --local-dir E:\Projects\models\bge-small-zh-v1.5

方法二：手动下载

1. 访问 Hugging Face 模型页面
2. 下载所有文件到本地目录，如：E:\Projects\models\bge-small-zh-v1.5
3. 确保目录中包含：config.json, pytorch_model.bin, tokenizer_config.json 等文件

方法三：国内镜像站（推荐国内用户）

# 使用 ModelScope（国内可访问，无需科学上网）
pip install modelscope
modelscope download --model BAAI/bge-small-zh-v1.5 --local_dir E:\Projects\models\bge-small-zh-v1.5

💡 提示：下载完成后，记住模型存放的路径，稍后需要配置到 .env 文件中。

环境变量配置

# 创建 .env 文件
cat > .env << EOF
# JWT 密钥（请修改为随机字符串）
JWT_SECRET=your-super-secret-key-change-me

# DeepSeek API Key
DEEPSEEK_API_KEY=your-deepseek-api-key

# 跨域设置
ALLOWED_ORIGINS=http://localhost:5173,http://127.0.0.1:5173

# Cookie 模式（1=开启，0=Bearer Token）
AUTH_USE_COOKIE=0

# ⚠️ 语义模型路径（必需！请修改为你的实际路径）
BGE_MODEL_PATH=E:\Projects\models\bge-small-zh-v1.5

# 向量存储路径
SEMANTIC_STORE_PATH=./semantic_store
EOF

⚠️ 重要：

• 请务必修改 BGE_MODEL_PATH 为你实际的模型存储路径！
• Windows 用户：路径中的反斜杠 \ 可直接使用，或使用双反斜杠 \\
• Linux/Mac 用户：使用正斜杠 /，如 /home/user/models/bge-small-zh-v1.5

启动后端

uvicorn backend.app:app --reload --host 0.0.0.0 --port 8000

3. 前端配置

安装依赖

cd frontend-vue
npm install

环境变量配置

# 创建 .env 文件
echo "VITE_API_BASE=http://127.0.0.1:8000" > .env

启动前端

npm run dev

浏览器访问：http://localhost:5174

---

✅ 首次运行检查清单

在启动项目前，请确认：

• 已下载 BGE 语义模型到本地
• 已在 .env 中正确配置 BGE_MODEL_PATH
• 已配置 DEEPSEEK_API_KEY
• 已配置 JWT_SECRET（改为随机字符串）
• 后端依赖已安装（pip install -r requirements.txt）
• 前端依赖已安装（npm install）

如果以上都已完成，就可以正常启动了！🚀

---

📖 使用指南

1️⃣ 注册/登录

• 首次访问需要注册账号
• 用户名：4-20位字母/数字/下划线
• 密码：至少6位，建议包含大小写和数字

2️⃣ 教学演练

1. 选择主题：输入要学习的知识点（如：TCP三次握手）
2. 讲解内容：像老师一样详细讲解这个主题
3. 提交讲解：AI 会生成3-5个针对性问题
4. 回答追问：认真回答每个问题
5. 查看评估：获得详细的评分和改进建议

3️⃣ 历史记录

• 查看所有历史讲解记录
• 点击展开查看详细内容
• 查看 AI 的评分和反馈
• 复习一周复习计划

4️⃣ 相似复习

• 输入想复习的内容或问题
• 系统基于语义相似度推荐相关讲解
• 可按主题筛选
• 点击查看完整记录详情

📁 项目结构

fliptutor_vue_semantic_auth/
├── backend/                    # 后端代码
│   ├── app.py                 # FastAPI 主应用
│   ├── db.py                  # 数据库模型
│   ├── models.py              # Pydantic 数据模型
│   ├── prompts.py             # AI 提示词模板
│   └── services/              # 业务逻辑
│       ├── auth.py            # 认证服务
│       ├── deepseek.py        # AI 模型调用
│       ├── embedder.py        # 文本嵌入
│       ├── scoring.py         # 评分算法
│       └── semantic_store.py  # 语义向量存储
├── frontend-vue/              # 前端代码
│   ├── src/
│   │   ├── App.vue           # 主应用组件
│   │   ├── main.js           # 入口文件
│   │   ├── api.js            # API 封装
│   │   ├── styles.css        # 全局样式
│   │   └── components/       # Vue 组件
│   │       ├── AuthPanel.vue       # 登录注册
│   │       ├── LectureForm.vue     # 讲解表单
│   │       ├── QuestionsForm.vue   # 问答表单
│   │       ├── Records.vue         # 历史记录
│   │       └── SimilarSearch.vue   # 相似搜索
│   ├── index.html
│   ├── package.json
│   └── vite.config.js
├── semantic_store/            # 向量数据库
│   ├── embeddings.npy        # 向量嵌入
│   ├── texts.json            # 文本内容
│   └── metadata.json         # 元数据
├── fliptutor.db              # SQLite 数据库
├── requirements.txt          # Python 依赖
└── README.md

🔌 API 接口

认证接口

• POST /auth/register - 用户注册
• POST /auth/login - 用户登录
• POST /auth/logout - 用户登出

教学接口

• POST /lecture/start - 开始讲解（生成追问）
• POST /lecture/answer - 提交答案（获取评分）

数据接口

• GET /records/{user_id} - 获取历史记录列表
• GET /record/{rid} - 获取单条记录详情
• GET /topics/{user_id} - 获取主题列表
• GET /review/similar - 语义相似搜索

详细 API 文档请访问：http://localhost:8000/docs

🎯 核心算法

1. 语义向量检索

# 使用 BGE-small-zh-v1.5 模型
# 1. 文本编码为 512 维向量
# 2. 归一化向量
# 3. 余弦相似度计算
# 4. Top-K 检索

2. 智能评分

# 混合评分机制
final_score = 0.7 * ai_score + 0.3 * heuristic_score

# ai_score: AI 模型评估（0-10）
# heuristic_score: 启发式规则
#   - 覆盖度（缺失知识点）
#   - 准确性（错误数量）
#   - 清晰度（表达质量）

3. 用户数据隔离

• 语义搜索自动过滤用户 ID
• 数据库查询强制鉴权
• JWT Token 验证用户身份

🔒 安全特性

• ✅ 密码 bcrypt 加密存储
• ✅ JWT Token 认证
• ✅ 可选 HttpOnly Cookie 模式
• ✅ CORS 跨域保护
• ✅ SQL 注入防护（SQLAlchemy ORM）
• ✅ 用户数据完全隔离

🎨 界面特色

• 🌈 紫青渐变配色方案
• 💎 毛玻璃卡片设计
• ✨ 流畅的动画效果
• 📱 响应式移动端适配
• 🎯 直观的信息层级
• 🔍 智能的交互反馈

🐛 常见问题

Q: 启动后端报错找不到模型？

A:

1. 确认已下载模型：检查 E:\Projects\models\bge-small-zh-v1.5 目录是否存在且包含模型文件
2. 检查环境变量：确认 .env 文件中的 BGE_MODEL_PATH 路径正确
3. 路径格式：Windows 路径需要使用 \ 或 \\，如 E:\Projects\models\bge-small-zh-v1.5 或 E:\\Projects\\models\\bge-small-zh-v1.5
4. 文件完整性：确保模型目录包含所有必需文件（config.json, pytorch_model.bin, tokenizer.json 等）

Q: 如何下载语义模型？

A: 推荐使用以下方法之一：

• Hugging Face CLI（需要科学上网）：huggingface-cli download BAAI/bge-small-zh-v1.5
• ModelScope 镜像（国内推荐）：modelscope download --model BAAI/bge-small-zh-v1.5
• 手动下载：从 Hugging Face 或 ModelScope 网站下载所有模型文件

Q: 搜索结果为空？

A:

1. 确保已创建至少一条讲解记录
2. 检查是否选择了正确的主题筛选
3. 尝试更换搜索关键词

Q: 相似度显示异常？

A: 如果是从旧版本升级，请删除 semantic_store/ 目录，系统会自动重新生成向量数据。

Q: 如何重置数据库？

A:

rm fliptutor.db
rm -rf semantic_store/
# 重启后端，会自动创建新数据库

🔄 更新日志

v2.0.0 (2025-10-20)

• ✨ 全新现代化 UI 设计
• 🔍 优化语义搜索，支持元数据过滤
• 📄 添加搜索结果详情展开功能
• 🐛 修复相似度显示问题
• 🎨 添加响应式动画效果
• 📝 明确说明语义模型需手动下载配置

v1.0.0 (2025-10-18)

• 🎉 初始版本发布
• 👤 用户认证系统
• 📚 教学演练功能
• 🔍 语义向量检索
• 📊 智能评分反馈

📄 开源协议

MIT License

👨‍💻 贡献指南

欢迎提交 Issue 和 Pull Request！

🙏 致谢

• DeepSeek - AI 模型支持
• Sentence-Transformers - 语义向量模型
• Vue.js - 前端框架
• FastAPI - 后端框架

---

Happy Learning! 📚✨