Skip to content

Latest commit

 

History

History
433 lines (317 loc) · 8.32 KB

DEPLOYMENT_GUIDE.md

File metadata and controls

433 lines (317 loc) · 8.32 KB

XJTU-SlideNote 部署与运行指南

🚀 快速开始

前置要求

系统依赖

macOS:

# 安装 FFmpeg 和 Poppler
brew install ffmpeg poppler

Ubuntu/Debian:

sudo apt update
sudo apt install ffmpeg poppler-utils python3-dev

Windows:

  1. 下载 FFmpeg: https://ffmpeg.org/download.html
  2. 下载 Poppler: https://github.com/oschwartz10612/poppler-windows/releases
  3. 将两者添加到系统 PATH

Python 要求

  • Python 3.10 或更高版本

📦 后端部署

1. 创建虚拟环境

cd backend
python -m venv venv

# macOS/Linux 激活
source venv/bin/activate

# Windows 激活
venv\Scripts\activate

2. 安装依赖

pip install --upgrade pip
pip install -r requirements.txt

注意事项:

  • PaddleOCR 首次运行会自动下载模型文件（约100MB）
  • 如需 GPU 加速，安装 paddlepaddle-gpu 替代 paddlepaddle

3. 配置环境变量

# 复制环境变量模板
cp .env.example .env

# 编辑 .env 文件，配置 LLM API
nano .env  # 或使用你喜欢的编辑器

必需配置：

# LLM 配置
LLM_API_KEY=your-openai-api-key-here

# 可选：使用其他提供商
# LLM_PROVIDER=deepseek
# LLM_MODEL_NAME=deepseek-chat
# LLM_BASE_URL=https://api.deepseek.com

4. 启动后端服务

# 开发模式（带热重载）
uvicorn app.main:app --reload --port 8000

# 生产模式
uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 2

验证启动： 访问 http://localhost:8000/health 应返回：

{"status":"healthy","app":"XJTU-SlideNote"}

查看 API 文档：

🎨 前端部署（Electron 开发模式）

1. 安装依赖

cd frontend
pnpm install

# 如果没有 pnpm
npm install -g pnpm
pnpm install

2. 启动开发服务器

# Web 模式（浏览器）
pnpm run dev

# Electron 桌面模式
pnpm run dev:electron

🧪 完整演示流程

步骤 1: 创建学期和课程

API 调用示例:

# 1. 创建学期
curl -X POST http://localhost:8000/api/semesters \
  -H "Content-Type: application/json" \
  -d '{"name": "大三上", "order": 0}'

# 返回: {"id": 1, "name": "大三上", ...}

# 2. 创建课程
curl -X POST http://localhost:8000/api/courses \
  -H "Content-Type: application/json" \
  -d '{"semester_id": 1, "name": "操作系统", "order": 0}'

# 返回: {"id": 1, "name": "操作系统", ...}

# 3. 创建课时
curl -X POST http://localhost:8000/api/lessons \
  -H "Content-Type: application/json" \
  -d '{"course_id": 1, "name": "第1讲-操作系统概述", "order": 0}'

# 返回: {"id": 1, "name": "第1讲-操作系统概述", ...}

步骤 2: 上传视频并提取 PPT

方式一：使用本地视频文件

curl -X POST http://localhost:8000/api/extract/upload \
  -F "file=@/path/to/your/video.mp4" \
  -F "lesson_id=1" \
  -F "scene_threshold=0.3" \
  -F "dedup_threshold=10"

# 返回: {"task_id": "xxx-xxx-xxx", "status": "submitted"}

方式二：使用视频 URL

curl -X POST http://localhost:8000/api/extract \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://example.com/lecture.mp4",
    "lesson_id": 1,
    "scene_threshold": 0.3,
    "dedup_threshold": 10
  }'

步骤 3: 查询任务进度

# 使用上一步返回的 task_id
curl http://localhost:8000/api/tasks/{task_id}

# 任务状态：
# - pending: 等待执行
# - processing: 执行中
# - completed: 已完成
# - failed: 执行失败

步骤 4: 生成学习笔记

使用 SSE（Server-Sent Events）接收流式输出：

# 使用 curl 观察流式输出
curl -N -X POST http://localhost:8000/api/ai/notes \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": 1,
    "style": "beginner"
  }'

或在前端使用 EventSource:

const eventSource = new EventSource('/api/ai/notes', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ file_id: 1, style: 'beginner' })
});

eventSource.onmessage = (event) => {
  console.log('接收到:', event.data);
};

步骤 5: 生成练习题

curl -N -X POST http://localhost:8000/api/ai/exercises \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": 1,
    "include_notes": true,
    "config": {
      "choice_count": 5,
      "short_answer_count": 3,
      "difficulty": "medium"
    }
  }'

📁 存储结构

处理完成后，文件将按以下结构组织：

storage/
├── slidenote.db                 # SQLite 数据库
├── users/
│   └── 1/                       # 用户 ID (默认单用户)
│       └── 大三上/              # 学期
│           └── 操作系统/        # 课程
│               └── 第1讲-操作系统概述/  # 课时
│                   ├── slides.pdf      # 提取的 PPT
│                   ├── notes_beginner.md  # 生成的笔记
│                   └── exercises_medium.md # 生成的练习题
└── tasks/                       # 任务状态文件
    ├── {task-id-1}.json
    └── {task-id-2}.json

🛠 故障排查

问题 1: FFmpeg 未找到

错误信息: FFmpeg not found

解决方案:

# 验证 FFmpeg 是否安装
ffmpeg -version

# 如未安装，按前置要求安装

问题 2: PaddleOCR 初始化失败

错误信息: paddleocr not installed

解决方案:

pip install paddleocr paddlepaddle
# 或 GPU 版本
pip install paddleocr paddlepaddle-gpu

问题 3: LLM API 调用失败

错误信息: LLM Generation Failed: ...

检查项:

  1. 确认 .env 中 LLM_API_KEY 已正确配置
  2. 验证 API 密钥有效性
  3. 检查网络连接
  4. 查看 API 额度是否充足

问题 4: 视频处理超时

可能原因: 视频过大或阈值设置不当

解决方案:

# 调高场景检测阈值（提取更少帧）
scene_threshold: 0.4  # 默认 0.3

# 调整去重阈值
dedup_threshold: 15   # 默认 10

问题 5: 数据库错误

错误信息: table not found 或 no such column

解决方案:

# 删除旧数据库重新初始化
rm storage/slidenote.db

# 重启后端，数据库会自动重建

⚙️ 性能调优

视频处理优化

调整场景检测阈值:

# .env 文件
FFMPEG_SCENE_THRESHOLD=0.4  # 越大越宽松，提取帧越少

调整去重敏感度:

IMAGE_DEDUP_THRESHOLD=15    # 越大去重越激进

OCR 优化

启用 GPU 加速（如有 NVIDIA GPU）:

OCR_USE_GPU=true

调整 OCR 语言:

OCR_LANG=ch   # 中文
# OCR_LANG=en   # 英文

LLM 优化

调整生成参数:

LLM_MAX_TOKENS=8192      # 增大输出长度
LLM_TEMPERATURE=0.5      # 降低随机性，更稳定

📊 监控和日志

查看实时日志

# 后端日志
cd backend
tail -f logs/app.log  # 如果配置了日志文件

# 或直接查看控制台输出

任务状态监控

# 查看所有任务
curl http://localhost:8000/api/tasks?limit=20

# 查看特定状态的任务
curl http://localhost:8000/api/tasks?status=processing&limit=10

🔧 开发环境配置

代码格式化

# 安装开发依赖
pip install black ruff

# 格式化代码
black backend/app
ruff check backend/app

运行测试

cd backend
pytest

📝 API 快速参考

核心端点

功能 方法 端点
创建学期 POST /api/semesters
创建课程 POST /api/courses
创建课时 POST /api/lessons
上传视频 POST /api/extract/upload
查询任务 GET /api/tasks/{task_id}
生成笔记 POST /api/ai/notes (SSE)
生成练习题 POST /api/ai/exercises (SSE)
获取文件 GET /api/files/{file_id}

完整 API 文档见：http://localhost:8000/docs

🆘 获取帮助

如遇到问题：

  1. 检查系统依赖是否正确安装（FFmpeg, Poppler）
  2. 查看 .env 配置是否正确
  3. 查看控制台日志输出
  4. 参考故障排查章节

祝使用愉快！ 🎉