我用 Qwen3.8-Max 搭了一个 AI 作业辅导助手，拍照讲题 + 错题本诊断一次搞定

一、背景

二、最终效果

三、搭建过程

[3.1 技术选型](#3.1 技术选型)

[3.2 核心 Prompt / Agent 编排](#3.2 核心 Prompt / Agent 编排)

[3.3 踩坑记录](#3.3 踩坑记录)

四、效果对比

五、总结：

六、复现指南

[6.1 环境配置](#6.1 环境配置)

[6.2 安装依赖](#6.2 安装依赖)

[6.3 配置 API Key](#6.3 配置 API Key)

[6.4 启动服务](#6.4 启动服务)

[6.5 注意事项](#6.5 注意事项)

一、背景

家里有个初二娃，每天晚饭后辅导作业跟打仗似的。搜题 App 一拍就出答案，孩子抄完就跑；轮到我讲，明明一步能算完的东西，我绕三圈都讲不清，讲到第三遍自己都开始怀疑人生。我真正想要的是一个能讲"为什么"、还能顺手出几道同类题确认孩子真懂了的帮手。最近试了 Qwen3.8-Max，发现它既能看懂图片，又能一口气读很多内容，于是周末用 Vibe Coding 一把梭，把这个 Demo 搭了出来。

二、最终效果

AI作业辅助助手demo演示

打开 Demo 链接，你会看到两个模式：

单题辅导：拍张题目照片或输入文字，选年级学科，点"开始辅导"。文字题大概 3-5 秒，图片题大概 30 秒到 2 分钟，它会返回：
- 题目复述（图片会先被识别成文字）；
- 分步骤讲解，每步都讲"为什么"；
- 3 道同类练习题 + 答案解析。
上传题目图片

输入题目文字
错题本诊断（隐藏大招）：把娃一周的错题拍一堆图或贴文字进去，Qwen3.8-Max 用长上下文一次性"通读"，跨题归纳薄弱知识点，再给出针对性练习和家长建议。

我实测的一组数据：

|-------------|----------------------|-------------|
| 场景 | 返回结果 | 耗时 |
| 文字题 3+5=? | 5 步启发式讲解 + 3 道同类题 | 10-15 秒 |
| 图片题（含中文题干） | 正确识别题干 + 4 步讲解 | 59 秒 |
| 错题本诊断（多张图） | 薄弱知识点 + 针对性练习 + 家长建议 | 30 秒 - 2 分钟 |

三、搭建过程

3.1 技术选型

没上重型框架，一切以"能跑、能复现"为原则：

大模型：Qwen3.8-Max（通用API调用，本体支持多模态输入 + 长上下文）。
后端：FastAPI，轻量，几分钟起服务。
前端：原生 HTML + Tailwind CSS，零构建，浏览器直接打开。
模型接入：OpenAI 兼容接口。我买的是阿里云百炼的 Lite Token Plan，SDK 直接走标准地址会报 InvalidApiKey，必须走套餐专属 Base URL。
图片处理：Pillow 压缩（最长边 1280、JPEG 质量 85、RGBA 转 RGB）。
异步任务：内存 _tasks 字典 + threading，用于绕开某些公网网关 30 秒超时。自己部署在服务器上不存在这样的问题。

3.2 核心 Prompt / Agent 编排

整个辅导的"灵魂"在两段 System Prompt 里：一段让模型当"会讲题的老师"，一段让它当"会看错题本的班主任"。

单题辅导 System Prompt：

复制代码

你是一位耐心、专业的作业辅导老师，擅长用"启发式"而非"直接给答案"的方式帮助学生真正理解题目。
你的辅导必须做到：
1. 语言贴合指定年级学生的认知水平，避免超出该学段的术语；
2. 解题过程分步骤，每步都解释"为什么这么做"，而不是只给算式或结论；
3. 不跳步、不堆术语，必要时用生活化的比喻帮助理解；
4. 最后生成 3 道同类型练习题，帮助学生巩固，并附答案与简要解析。

你必须且只能以严格的 JSON 格式返回，不要输出任何额外文字、解释或代码块标记。JSON 结构如下：
{
  "question": "题目的准确复述（若输入是图片，请先识别并写出完整题干）",
  "steps": [
    {"step": 1, "title": "步骤标题", "detail": "该步骤的详细讲解，包含原因说明"}
  ],
  "practice": [
    {"question": "练习题题干", "answer": "练习题答案与简要解析"}
  ]
}

后端收到模型输出后，先用 parse_json() 正则兜底提取 JSON，再用 Pydantic 校验成 AnalyzeResponse。如果模型没乖乖只吐 JSON，就把原始文本塞进 raw 字段返回，保证页面不白屏。

错题本诊断 System Prompt：

复制代码

你是一位资深的学情分析师兼班主任，擅长从学生的一份错题本或试卷中找出系统性薄弱点。
用户会上传多张错题图片或若干文字题目（可能包含多道不同知识点、甚至跨学科）。这是发挥长上下文优势的场景：请一次性通读所有题目。

请完成：
1. 逐一识别每道错题的学科、知识点、错误类型（概念不清 / 计算失误 / 审题错误 / 方法不当）；
2. 跨题归纳 2-4 个最突出的薄弱知识点，并解释为什么它们会反复出错（要具体，不要泛泛而谈）；
3. 针对每个薄弱点生成 2 道巩固练习题（附答案与简要解析）；
4. 给出一条简洁、可操作的给家长的辅导建议。

你必须且只能以严格的 JSON 格式返回，不要输出任何额外文字。JSON 结构：
{
  "problems": [{"index": 1, "subject": "学科", "knowledge": "知识点", "error_type": "错误类型", "brief": "题目简述"}],
  "weak_points": [{"point": "薄弱知识点", "reason": "为什么反复出错"}],
  "practice": [{"question": "练习题题干", "answer": "答案与解析"}],
  "advice": "给家长的辅导建议"
}

3.3 踩坑记录

这部分最真实，也是我最想写的。

坑 1：图片不能直接传裸 base64。一开始我把图片 base64 直接塞进消息，模型根本不认。后来改成完整 data:image/png;base64,... 格式才正常。就一个小格式，折腾了小半天。

坑 2：模型偶尔会 JSON 套个代码块。我都明确要求"只返回 JSON"了，它还是有一定概率包一层 ```````json````，前后再加两句"这是答案"。最后用正则先把代码块内容扒出来再解析，实在不行就把原文丢给前端兜底展示。

坑 3（最痛）：Token Plan 必须用专属 Base URL。我买的是 Lite Token Plan，给的是"套餐专属 API Key"。一开始拿 dashscope SDK 走标准地址，死活报 InvalidApiKey，Key 明明是对的。查了半天才发现套餐给了专用 Base URL，必须配合 OpenAI 兼容模式走这个地址：

复制代码

https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1

改完一行配置，瞬间通了。

四、效果对比

|----------|-----------------------|--------------------------------------|
| 指标 | 之前 | 现在 |
| 耗时（单题文字） | 家长讲解 15-20 分钟 | 10-15 秒出分步讲解 |
| 耗时（单题图片） | 拍照搜题 10 秒，但只给答案 | 30-120 秒，给完整讲解 + 3 道同类题 |
| 错题本诊断 | 家长手动翻找 30 分钟以上，抓不住薄弱点 | 30-120 秒出薄弱点 + 针对性练习 |
| Token 消耗 | 人工 0 | 未精确统计；单次调用约数千 token 量级，与题目长度、图片大小正相关 |
| 可接受率 | 看家长水平，波动大 | 输出稳定，但仍需家长/学生复核；未做标准化准确率评测 |

五、总结：

优点：Qwen3.8-Max 在"题目理解、分步讲解、结构化输出"上是稳的，关键是它能一次跑完"识别→讲解→练习"这条线，不用人中间搭手。

最超出我预期的是长上下文在错题本诊断上的价值：把整周错题一次喂进去，它不是逐题答，而是能归纳出"你娃为什么老在移项符号上栽跟头"这种系统性问题，再按病根出题。这种"纵览全局"的能力，换个只能单题聊的小模型是真干不了。对一个家长来说，这比单题讲解更像是"请了个真懂孩子的家教"。

不足：主要是 Token Plan 的接入方式需要一点点额外配置，官方关于"套餐专属 Key 怎么对接"的示例偏少，我当时踩了一会儿。但一旦跑通，模型本身（识图、讲解、长上下文诊断）一点短板都没有。

六、复现指南

想在自己电脑上跑的同学，步骤很轻：

6.1 环境配置

Python 3.10+
Windows / macOS / Linux 均可

6.2 安装依赖

复制代码

python -m venv .venv
.venv\Scripts\activate
pip install -r backend\requirements.txt

6.3 配置 API Key

复制 backend/.env.example 为 backend/.env，填入：

复制代码

DASHSCOPE_API_KEY=sk-sp-你的Key
DASHSCOPE_BASE_URL=https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
QWEN_MODEL=qwen3.8-max
QWEN_VL_MODEL=qwen3.8-max
PORT=8000

重点：Token Plan 用户一定要填 DASHSCOPE_BASE_URL，按量付费用户可改成 https://dashscope.aliyuncs.com/compatible-mode/v1\。

6.4 启动服务

推荐用：

复制代码

python backend/main.py

也可以：

复制代码

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

浏览器打开 http://localhost:8000\ 即可。

6.5 注意事项

图片题和多图诊断已改为异步轮询，页面会显示"已用时 X 秒"，等待 30-120 秒属正常。且这个时间会随着上传图片的数量递增。
模型接入 Base URL时，如果用默认 dashscope SDK 地址会报 InvalidApiKey（Lite Token Plan 专属 Key）。正确做法是.env 必须配 DASHSCOPE_BASE_URL=https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1，走 OpenAI 兼容模式
多模态模型名，如果误配 qwen-vl-max 会调不到本体多模态能力，正确做法是QWEN_MODEL 和 QWEN_VL_MODEL 都用 qwen3.8-max（本体即支持图片输入 + 100万 Token 长上下文）。

完整代码获取：项目源码

如果你也是被辅导作业折磨过的家长，或者正在琢磨大模型能落地到什么真实场景，欢迎打开 Demo 试两道题------拍张孩子最近的错题丢进诊断模式，多模态模型名"纵览全局"是什么感觉了。