readme

README.md

@@ -0,0 +1,103 @@
+# GenAI PDF Paper Tutor
+
+一个基于 Gradio 的论文阅读小工具：
+
+- 上传 PDF 论文
+- 生成中文讲解（角色风格化）
+- 支持讲解 TTS（手动点击）
+- 进入 Exam 页面后生成 MCQ（选择题）
+- 支持多角色（从 `characters/` 目录自动读取）
+
+## 功能流程
+
+1. 在讲解页选择角色
+2. 上传 PDF，点击 `Generate`
+3. 查看讲解内容（可点击 `Play Lecture Audio`）
+4. 点击 `Exam` 进入考试页
+5. 在考试页重新选择角色
+6. 点击底部 `Generate` 生成 MCQ
+7. 开始答题（答错会显示解析，并可播放解析语音）
+
+## 运行环境
+
+- Python 3.10+
+- 已安装依赖（见 `requirements.txt`）
+
+安装依赖：
+
+```bash
+pip install -r requirements.txt
+```
+
+运行：
+
+```bash
+python app.py
+```
+
+## API 配置（DashScope / OpenAI-compatible）
+
+项目会从 `.env` 读取 API 配置（已兼容 `API_UR` 和 `API_URL`）：
+
+```env
+API_UR="https://dashscope.aliyuncs.com/compatible-mode/v1"
+API_KEY="你的Key"
+```
+
+说明：
+
+- 讲解/MCQ 使用 OpenAI-compatible `/chat/completions`
+- TTS 优先尝试 `/audio/speech`，失败后回退 DashScope TTS 接口
+
+## 角色目录结构（自动发现）
+
+下拉/角色按钮会自动读取 `characters/` 下的所有子目录。
+
+示例：
+
+```text
+characters/
+  snape/
+    meta.json
+    avatar.jpg
+    lecture_prompt.txt
+    mcq_prompt.txt
+    mcq_retry_prompt.txt
+```
+
+`meta.json` 常用字段：
+
+- `id`
+- `display_name`
+- `tagline`
+- `byline`
+- `chat_label`
+- `chat_mode`
+- `avatar`
+- `lecture_prompt_file`
+- `mcq_prompt_file`
+- `mcq_retry_prompt_file`
+
+如果某个角色目录没有 `meta.json`，系统也会显示该目录（用目录名作为角色名，并使用默认 prompt）。
+
+## 常见问题
+
+### 1. 生成很慢
+
+这是正常现象（PDF 渲染 + VL 推理耗时较高）。可尝试：
+
+- 减少页数：`QWEN_VL_MAX_PAGES=1` 或 `2`
+- 降低渲染尺度：`QWEN_VL_RENDER_SCALE=1.0`
+
+### 2. PDF 无法提取文本
+
+请确认已安装 `pypdf`：
+
+```bash
+pip install pypdf
+```
+
+### 3. MCQ 生成失败 / JSON 错误
+
+模型可能返回不完整 JSON，代码里已做重试与解析兜底；如果仍失败可重试一次或更换角色 prompt。
+