问题排查

1. 确认已经完整解压，运行的是 .bat 或 .command 启动器，而不是 index.html。
2. Windows 使用完整的 Windows 10/11 x64 包；macOS 确认已安装 Python 3.10+，首次准备环境时保持联网。
3. 查看启动窗口显示的具体错误。若浏览器没自动打开但服务已就绪，可按启动提示中的本地地址访问。
4. 若提示端口占用，先确认是否已有 MathBank 运行；正常打开已有服务即可。不要任意关闭未知进程。

如何判断：工作台出现「题库就绪」。仍失败时，把启动错误和操作系统版本按下方模板记录下来。这个阶段还没有调用 AI，不需要先换模型。

1. 核对 Key 是否填写在它所属的平台字段，避免复制前后空格或残缺内容。
2. 自定义服务核对 Base URL、模型 ID 与 Key 是否属于同一家服务商。
3. 进入服务商后台确认模型权限与额度。不要把聊天会员订阅直接视为 API 额度。
4. 保存后用三题样例或一张截图重新验证。

仍失败：记录完整错误码和错误文本，遮挡 Key 后反馈。不要上传 .env。

逐字核对模型 ID、大小写和组织前缀。例如 DeepSeek 官方的 deepseek-flash 与硅基流动的 deepseek-ai/DeepSeek-V4-Flash 不是同一入口配置。

识图时确认你改的是「默认公式识图模型」，且服务商当前接口支持图片。在硅基流动中，优先查看项目列出的 Qwen-VL 识图选项。

如何判断：用一张清晰单题图得到有效识别结果。详细候选见模型选择。

1. 记录具体错误：发生在上传、提取、拆题还是生成解析阶段。
2. 用一张清晰截图或三题样例重试一次，排除单次文件太大的影响。
3. 确认当前电脑能访问所选服务商；浏览器能打开平台首页，不代表 API 请求一定可达。
4. 两类任务都连接失败时，优先检查共用的网络、代理与服务地址。保留现有设置，避免盲目切换或重启可用代理。

仍失败：收集完整错误信息和已做的检查，按下方模板反馈。仅凭“Key 已配置”不能确认连接正常。

先做：检查原图清晰度、裁切范围和倾斜情况；Word 则先看特殊公式转换提示。PDF 可以对同一小段尝试不同提取策略。

判断改善：对照原题逐个检查上下标、分式、正负号、区间和表格。如果原始识别文本仍错，再尝试另一个「默认公式识图模型」。

先做：检查提取文本是否完整，缩短单次内容；把一道跨页题涉及的页面一起选中。

判断改善：题量和小问与原卷一致。文本已完整但拆题仍异常时，更换「试卷智能拆解模型」，用同一段内容对照。

当前 PDF 批量导入的配图插入仍有问题。含配图的试卷，优先使用原始 Word 文件。

只有 PDF 时，导入后请逐题核对，在题目编辑器中补充缺失图片。换模型不能解决这一已知限制。

优先检查文件内容、长度与特殊公式。将资料另存为标准 .docx，挑选少量完整题目测试，查看转换报告。不要先修改已经验证可用的所有 API 设置。

PDF 编译与 TikZ 预览依赖本地 LaTeX；Word 可编辑公式导出涉及 Pandoc。先查看对应依赖与编译错误，AI 可用不代表导出环境已准备齐全。

先用一道简单题目导出验证。若只有某题失败，检查该题公式或绘图源码。更多环境说明可查项目 README。这个阶段不应优先更换识图或拆题模型。

常见含义：可能是内容格式、模型参数、图片输入不兼容等问题；MathBank 的部分 AI 接口也会把服务商或网络异常包装成 400。

先做什么：先复制完整错误正文，查看是否还包含另一个错误码、模型名或连接异常。核对对应任务的模型与文件；不能仅凭 400 断定是 Key 错误。

常见含义：若正文写着“某平台接口错误 HTTP 401”，通常是该平台不接受当前 API Key。MathBank 普通网页的本地访问凭证问题通常返回 403。

先做什么：核对报错平台、Key 是否完整有效及是否填在对应字段；不要把本地页面的 Token 问题与服务商 API Key 混为一谈。

常见含义：服务商可能限制账号、模型、实名或地区权限。若正文是 Invalid or missing local token，则是本地页面访问凭证问题。

先做什么：按正文区分来源：服务商问题查账号与权限；本地凭证问题先保留未保存编辑，再从启动器打开的地址刷新。不要因此更换模型平台的 Key。

常见含义：可能是接口地址或模型 ID 不正确，也可能是题目、文件或临时任务已不存在。

先做什么：区分报错对象：模型问题查完整 ID 与 Base URL；文件或任务问题查是否已删除、过期，再按需重新选择文件或发起任务。

常见含义：本地题库可能发现保存前的查重结果已变化，或请求中的服务实例与当前运行服务不一致。

先做什么：按界面提示重新核对重复题；服务重启后先保留未保存编辑，再重新打开页面。不要直接重复写入或删除数据来消除提示。

常见含义：超过了上传接口或中转服务允许的大小。选中少量 PDF 页面，不会改变原文件的上传大小。

先做什么：先核对文件大小限制，必要时把原文件另存为更小的文件；图片可适度压缩并保持公式清晰。单纯换模型通常无效。

常见含义：缺少必填字段、字段类型或取值不符合接口要求；旧页面与更新后的程序不一致时也可能出现。

先做什么：记录错误正文中的字段名称，检查输入。若刚更新软件，先保存或暂存编辑，再刷新页面重新尝试。

常见含义：可能触发服务商的频率、令牌或账号配额限制，也可能是本地任务队列已满。

先做什么：先等待现有任务结束，减少同时提交的任务；查看平台的额度和限制说明。不要连续快速重试，也不要仅凭 429 判断余额不足。

常见含义：可能是本地处理异常，也可能是模型服务商的 HTTP 错误或连接超时被 MathBank 包装成 500。它不直接等于软件缺陷、API Key 错误或平台故障。

先做什么：同时保存页面完整提示、发生时间与对应日志片段。若正文指出平台错误，核对内层状态码；超时先缩小样例。日志不一定保留完整上游错误或 traceback。

常见含义：常见于反向代理或中转站，表示转发链路中的上游响应异常。

先做什么：记录平台、模型和报错时间，稍后用小样例重试。持续出现时联系该服务商，并附上已遮挡敏感信息的错误正文。

常见含义：服务可能尚未启动就绪、维护中或负载过高。MathBank 的健康检查未就绪时也会返回 503。

先做什么：本地启动时先等待就绪，持续不就绪再查启动日志；外部平台报错时先查看平台状态。不要反复提交同一批任务。

常见含义：代理或中转站等待模型响应超过了它允许的时间。它与 Key 是否正确不是同一个问题。

先做什么：缩短单次内容或 PDF 页数，用完整小样例测试；持续超时则查服务商链路与超时限制。没有 HTTP 码的 Read timed out 也应先按超时方向排查。

200 只代表这次通信成功返回。流式解题可能在返回内容中报告错误；PDF / Word 后台任务查询也可能返回 200，但任务状态是 error。请以页面任务结果与具体错误为准，不能仅凭 200 判断业务成功。

这些信息描述连接中断、读取超时或加密连接失败，并不能直接证明 Key 错了。保留完整错误链，先用小样例检查当前电脑到所选服务的连接；AI 与 OCR 同时失败时，优先检查共用网络、代理和接口地址。

不要只截取最后一行，也不要盲目关闭或切换正在使用的代理。获取日志后，按下面的反馈模板说明已经尝试的步骤。

server.log 主要保存后端服务的输出。如果还停在查找 Python、安装依赖等阶段，可能尚未生成新的服务日志，此时请复制或截图启动窗口中的完整错误。

若存在 .system_generated/probe.log，也一起保留。它记录服务就绪探测失败的原因，不是每次都有；成功启动后会被删除。旧的 server.log 不一定对应本次失败，要核对时间。

从源码直接运行 uvicorn 时，日志通常在启动命令所在终端，不会自动写入这里的 server.log。请复制终端中的对应错误。

如果方便，可打开浏览器开发者工具：Chrome / Edge 使用 F12 或菜单中的“开发者工具”，查看 Console（控制台）里的红色错误；macOS Chrome 可按 Command + Option + J。先保留报错截图，刷新前保存或暂存编辑。

需要检查请求时，可在 Network（网络）里找到失败请求，记录地址、状态码和 Response（响应）中的错误文字。只复制必要信息；请求头和完整请求体可能含 Token、Key 或原题，不要整包公开发送。