README.md

metadata

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）

安装依赖：

pip install -r requirements.txt

运行：

python app.py

API 配置（DashScope / OpenAI-compatible）

项目会从 .env 读取 API 配置（已兼容 API_UR 和 API_URL）：

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），然后推送代码：

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 配置调用

# 讲解/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/ 下的所有子目录。

示例：

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：

pip install pypdf

3. MCQ 生成失败 / JSON 错误

模型可能返回不完整 JSON，代码里已做重试与解析兜底；如果仍失败可重试一次或更换角色 prompt。