README.md

---
title: Character Based AI Paper tutor
emoji: 😈
colorFrom: indigo
colorTo: blue
sdk: gradio
sdk_version: "6.6.0"
python_version: "3.10"
app_file: app.py
pinned: false
---

# 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 接口

## 使用同 Organization 的 HF Audio Space 做 TTS

你的 `audio` 项目已经暴露 API：`/tts_chunk(text, voice, language)`。

### 1. 部署 `/Users/lexi/workplace/audio` 到 HF Space

先在 Hugging Face 里创建组织下的 Space（例如 `your-org/audio`），然后推送代码：

```bash
cd /Users/lexi/workplace/audio
git remote add hf https://huggingface.co/spaces/your-org/audio
git push hf main
```

如果该 Space 是私有仓库，请在 HF 里创建一个可访问该组织 Space 的 token（read 权限即可调用）。

### 2. 在 `/Users/lexi/workplace/genai/.env` 配置调用

```env
# 讲解/MCQ 仍走 DashScope/OpenAI-compatible
API_UR="https://dashscope.aliyuncs.com/compatible-mode/v1"
API_KEY="你的Key"
USE_MOCK_MODELS=0
USE_MOCK_TTS=0

# TTS 走 HF Space（优先）
HF_TTS_SPACE_ID="your-org/audio"
# 如果是私有 Space，填 token；公开 Space 可不填
HF_TOKEN="hf_xxx"
HF_TTS_API_NAME="/tts_chunk"
HF_TTS_VOICE="male"      # male 或 female
HF_TTS_LANGUAGE="Chinese"
# 1=HF失败时回退到原有TTS；0=只用HF，失败就报错
HF_TTS_ALLOW_FALLBACK=1
```

可选：

- 如果你更希望用完整 URL，可以改为 `HF_TTS_SPACE_URL="https://your-org-audio.hf.space"`。
- 如果不想回退到原 TTS 接口，设置 `HF_TTS_ALLOW_FALLBACK=0`。
- 如果只想 mock 文本/题目，但 TTS 用真实接口：`USE_MOCK_MODELS=1` 且 `USE_MOCK_TTS=0`。

## 角色目录结构（自动发现）

下拉/角色按钮会自动读取 `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。