MathBank使用指南
v3.1.0GitHub下载软件
MATHBANK HANDBOOK / 05

常见问题

常见使用疑问与故障现象,都可以从这里找答案。

本页目录

这里既有常见使用说明,也有按现象整理的故障排查。遇到错误时,先做一项检查,再用同一个小样例判断有没有改善;保留具体错误信息,比反复重试更有帮助。

默认处理等待时限:普通 AI 请求默认等待 15 分钟,文档识图、拆卷及来源核验默认 30 分钟;本地 PDF 每遍编译、Word 转换和原 Word 渲染各允许 5 分钟。任务查询和查重等待为 60 秒,上传与分享任务提交为 10 分钟。请求超时表示客户端未及时收到完整结果,不代表远端一定未处理;重连会优先查询原任务(等待更长时仍可能受中转服务商自身的超时限制影响)。

打不开,或一直没有就绪

V3.0.3 启动器提示换端口,草稿和选题篮会跟过去吗?

启动器优先打开本目录已运行且就绪的题库;若原端口被其他程序占用,会先提示新地址,得到确认后才切换并记住端口。无法确认已有题库归属或仍在启动时,不会另开第二份服务。

草稿、选题篮与未保存卷面按浏览器地址保存。换端口不会自动带走这些内容;先在原地址保留并保存编辑,再按启动窗口提示操作。不要为释放端口而强制关闭不明进程。查看版本边界 →

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

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

移动程序文件夹后打不开,应该怎么办?

先把文件夹放回原位置,重新打开 MathBank,并通过网页右上角的电源按钮正常关闭服务。确认后台已经停止后,再移动整个程序文件夹,不要只移动启动器、数据库或部分子目录。

如果放回原位置仍无法启动,请查看启动窗口和 .system_generated/server.log;移动前未关闭服务只是常见原因之一,不能据此判断所有启动失败。

启动、导入或导出时提示目录不可写、无写入权限

系统在启动、导入或导出前会预先检查所需存储位置,并直接提示具体用途、目录及失败原因:

  1. 按提示检查位置。空间不足时清理对应磁盘;文件被占用时等待释放,持续发生再检查同步或安全软件的占用记录。
  2. 权限受限或路径过长时换位置。先保存编辑,通过 MathBank 电源按钮正常关闭服务;确认停止后,把整个程序文件夹移到当前账户可写、路径较短的位置,再从新位置运行启动器。不要只移动启动器。
  3. 保留并核对数据。移动时保留数据库、static/uploads/ 和 data_backup/ 等原有内容;重新启动后打开一道旧题,检查题文和配图。查看需要保留的文件 →

如果启动阶段就失败,保留启动窗口中的完整错误;若分享任务已经提示导入完成,随后同步导出报错,请先核实题库结果,避免再次导入造成重复题目。

API、权限与网络错误

Base URL 应该填什么?一定要加 /v1 吗?

填写服务商提供的 API 接口地址,不要填服务商网页首页。是否需要以 /v1 结尾,以该服务商当前接口说明为准;不要看到一个案例需要 /v1,就给所有地址重复添加。

MathBank 已内置平台通常不需要在中转站字段里再填一次。自定义服务还要同时核对 Base URL、模型 ID 和 Key 是否属于同一家服务商。

提示密钥无效、权限不足或额度不足
  1. 核对 Key 是否填写在它所属的平台字段,避免复制前后空格或残缺内容。
  2. 自定义服务核对 Base URL、模型 ID 与 Key 是否属于同一家服务商。
  3. 进入服务商后台确认模型权限与余额。使用 API 前需要先充值并确认余额到账,创建 Key 不等于已有可用额度;也不要把聊天会员订阅直接视为 API 额度。查看充值步骤 →
  4. 保存后用三题样例或一张截图重新验证。

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

已经填了 API Key,为什么识图仍提示没有配置?

检查「默认公式识图模型」实际选择的平台和模型,再确认同一个平台的 Key 已保存。只填写另一家平台的 Key,不会自动提供给当前任务;拆题、解题、识图和绘图也可以分别选择不同平台。

配置匹配后仍失败,再查看服务商返回的错误、模型是否支持图片以及账号权限。正常识别后,结果应进入题干编辑区;“Key 已填写”本身不能证明接口已调用成功。

提示找不到模型,或模型不支持图片

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

识图时确认你改的是「默认公式识图模型」,且服务商当前接口支持图片。在硅基流动中,可对照项目列出的千问或新 Flash 识图选项;旧下载版没有新型号时,先核对版本与手动添加说明。

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

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

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

导入结果不完整或不准确

能一次导入几百页 PDF 吗?

不建议。程序允许的选页上限不等于推荐批次;页数、公式密度、配图数量、原卷解析长度和模型上下文都会影响稳定性。首次仍建议从少量完整题目开始,成功后再逐步增加。

长试卷可以按小节或十页以内的小批次处理,并把跨页题涉及的页面放在同一批。若超时、漏题或返回截断,优先缩小批次,而不是连续提交整卷。

文字识别出来了,但公式明显不对

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

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

多道题被合成一道、漏题,或跨页题被拆断

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

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

PDF 导入后,配图缺失、错位或被裁掉
  1. 先确认使用当前版本,并选择「智能图文提取(推荐)」;「文字优先」和「全页识图」的配图仍需手动补充。
  2. 展开「提取说明与原文对照」,查看未归位配图与原页,核对图片选项、多图题和跨页范围。
  3. 解析完成后,先对照原卷检查图片归属、选项顺序与裁剪范围;漏图可用「手动截图」补充,已有错图可直接点击重新截图替换。

旧的已完成结果不会自动重算;先保留需要的编辑,再用新版重新解析少量相关页。

查看 PDF 图文导入步骤 →
出现原文对照记录,还需要逐题确认吗?

来源说明可按需展开,不再要求逐题勾选确认,也不会单独阻止导入。这不是把疑点自动判为正确;有疑问的公式或图片仍应对照原卷。

当前「自动核对疑点」默认开启,可能额外调用识图模型并增加等待;明确差异会尝试修正后再复核。不需要时可以关闭,正常导入仍可继续。若导入按钮不可用,检查题目是否选中、题干与分类是否完整,以及是否有查重提示或任务尚未完成。查看原文对照与核验说明 →

导入中断或刷新页面后,还能继续吗?

重新打开导入中心后,先检查 Word 恢复面板与任务状态;有「继续未完成解析」时再按提示继续。需要重新提供文件时,选择原来的同一份文件。先看已保存的结果和恢复提示,再决定是否继续,不要直接重复整卷提交。

PDF 校对结果仅留在当前页面会话中,刷新或重启后不能恢复。完成核对后请及时点击「导入此题」或「导入选中题目」入库,长文档建议分批处理。查看恢复边界 →

Word 原卷已有答案,怎样避免 AI 重新生成?

不要勾选「自动生成 AI 解答与详细解析」。系统会优先保留并匹配原 Word 中已有的答案、题号与选项边界。

答案集中放在卷末、版式复杂或题号不明确时仍可能匹配不准。入库前逐题核对题目与答案对应关系;需要 AI 补解时,可在导入后单独生成。

TeX / Markdown 试卷拆分失败怎么办?

先用少量完整题目测试,并核对自定义宏、表格和配图文件名。Markdown 导入仍在完善,拆分结果可能有误;入库前检查题干、公式、配图和答案。

自定义 LaTeX 模板反复拆分失败时,可以先编译成 PDF,再尝试 PDF 导入。查看 TeX / Markdown 导入说明 →

Word 样例能成功,自己的文件却失败

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

界面与功能疑问

组卷题目太多,怎样直接跳到指定页码?

V3.1.0 已提供此功能。在组卷页面的「全库试题」「筛选结果」或「已选试题」有多页时,滚动到列表底部,输入页码,按回车或点击「跳转」。跳转后只将题目列表滚回顶部,保留当前筛选和试卷预览位置。

怎样添加多条关键词和排除条件?

V3.1.0 已提供此功能。在「本地题库」「草稿箱」或「智能组卷」点击「筛选」,在「关键词条件」中添加多条规则。比如让题干包含“导数”,再让来源排除“旧卷”。可以指定解析、教师评析、标签或全部文本。题目需满足所有包含项,命中任一排除项就会被剔除。

快捷搜索、教材和知识点等条件可以一同使用。收起筛选面板后,可通过摘要逐条移除条件。这三个页面的筛选都在工具栏左下方浮出,可按 Esc 或点击面板外部关闭。手动列表和 AI 选题共用条件,已经加入试卷的题目会保留。手机切到卷面预览后,可以继续打开「试卷信息」。

导入分享包时提示“导入前自动备份失败”,原有题目缺图怎么办?

这条提示说明任务停在备份现有题库的阶段,尚未写入分享包中的新题目。除了目录权限、存储空间及数据库异常外,旧版本在发现原有题目引用的图片文件丢失时也会停止备份。

V3.0.2 已支持在分享导入前自动记录旧题缺图、显示警告并继续导入;手动备份也可显式追加 --allow-missing-images。它只容忍图片文件已经不存在,权限、空间及数据库校验失败仍会停止。请勿为绕过报错而删除数据库中的图片引用;含缺图记录的备份需使用 V3.0.2 或更高版本恢复,且恢复不会自动生成缺失图片。查看适用范围与备份说明 →

录题弹窗上下显示不全,保存或关闭按钮被遮住怎么办?

先保留正在编辑的内容,再把浏览器窗口最大化,并检查页面缩放(可先恢复到 100%,仍遮挡时适当缩小)。正常情况下,录题弹窗应适应窗口高度,超出的内容在弹窗内部滚动,顶部的保存与关闭按钮保持可见。

如果仍然上下被裁掉,请记录浏览器版本和内核版本,并换用较新内核的浏览器(部分国产浏览器虽然显示“最新版”,仍可能沿用 Chromium 99 等旧内核)。V3.0.1 及更高版本已内置旧内核视口高度兼容修复,使用更早版本时可先按上述方法临时调整,再备份升级。

软件里也能搜索常见问题吗?

可以。MathBank 工作区内提供「QA · 常见问题」,可以按分类浏览,也可以搜索安装、API、导入、编辑、导出和备份问题。

内置 QA 适合快速查答案;需要完整上手路径、下载入口或更长的排查步骤时,可以继续使用本帮助网站。

教材分类和考查知识点有什么区别?切换教材会丢失分类吗?

教材分类记录题目在某版教材中的位置;知识点另记主要考查和辅助考查内容,可用于题库与组卷筛选。AI 分类会给出建议,仍需结合题目直接考查目标核对。

系统支持人教 A、人教 B、苏教、沪教、北师大和湘教六套教材,各版分类独立保存,切回可恢复已有位置。在设置中载入预设后,点击保存配置才正式切换。查看分类与知识点说明 →

收到老师分享的题库 ZIP,怎样导入?会覆盖已有题目吗?

在「系统设置 → 题库分享 → 导入分享包」中选择要接收的 ZIP,核对文件后点击「批量导入」。分享包携带所选题目、解析、分类、知识点和所需配图;不用重新做 AI 识别。

导入按新增处理,不覆盖现有题目,也不自动跳过重复包;重复导入会再次新增。导入完成后检查新增题目;断连后先核实是否已经入库,再考虑重试。查看分享包与完整备份的区别 →

能把题目截图转成可编辑的 LaTeX 吗?

可以。先配置支持图片输入的识图模型和对应 API,再在题目编辑器中上传或粘贴清晰截图。识别结果会进入题干编辑区,可以继续修改 LaTeX 和 Markdown 内容。

系统会分别处理题干图、选项图和表格图,但文字、公式、裁图和图像归属仍需人工核对后再保存。

插入的图片四周为什么会显示边框?

这是编辑和预览界面的操作提示,用来说明这里插入的是一张可以调整的图片。点击图片后,可以修改它的位置、尺寸等排版设置。

边框只用于网页中的识别与操作,正式导出的 Word 或 PDF 试卷不会带上这圈边框。

图片大小为什么不能自由调整?

MathBank 目前提供自动、小、中、大几个尺寸档位,不支持任意拖动宽高。题目还要进入 A4 和 PDF 排版;尺寸过于自由,容易挤压正文、破坏分页,甚至导致 PDF 编译失败。固定档位可以让网页预览和最终导出更稳定。

点击编辑器中的图片或文件徽标即可调整:正文图修改该图在当前位置的对齐与尺寸,题末图组调整整组位置与尺寸(题干右侧是窄栏,选为中、大图时会自动转到下方居右)。修改后正常保存题目。

如果需要更细致地调整某张图片,可以先导出 Word,再在 Word 中微调图片的大小和位置。调整后建议重新检查分页、题干与配图的对应关系。

怎样删除图片,或把题末图片移到正文中?

在题干编辑框中找到相应的 Markdown 图片引用,例如 ![插图](图片路径)。删除这段引用可从题干移除图片;剪切后粘贴到目标文字位置,可以改变图片锚点。

这里调整的是正文引用,不是直接删除磁盘文件,也不等于任意拖动或文字环绕。不要自行删除 static/uploads/ 中的文件;修改后检查预览并正常保存。

为什么题目中显示“插图待补”?

这表示系统判断当前位置应该有插图,但图片或绘图还没有成功插入。若该题需要 AI 生成 TikZ 图,先检查「高级 TikZ 绘图模型」、对应平台的 API Key、模型 ID 和接口地址是否配置正确,并用一幅简单图测试连接。

按作者使用经验,TikZ 绘图优先推荐 GPT 或 Gemini 等国外模型,通常比国内模型更适合生成和修改复杂绘图源码。可参考TikZ 模型建议和中转站配置说明。

如果缺少的是原 PDF 中已有的配图,而不是需要 AI 生成的新图,请按PDF 配图说明检查提取策略和未归位图片。

会增加初中数学、物理、化学等其他学科吗?

MathBank 主要围绕作者自己的高中数学使用场景开发,同时开源给有需要的老师使用。为了保持界面和操作流程简洁,作者暂不计划把自己不使用的学段、学科功能持续加入主程序。

题库管理、编辑、导入和导出的主体框架已经具备。有开发能力的用户可以基于开源代码,按自己的教材体系、分类方式和工作流程进行修改与扩展。

导入时没有解析,之后还能让 AI 补充吗?

可以。先把题目导入题库,再打开题目使用「AI 智能生成解答」;导入结果题卡也提供生成解析入口,无需重新导入整份试卷。

AI 生成内容仍需人工核对。识别到的原答案应优先保留,不要为了补解答而覆盖已经正确的原答案。

题库正常,但导出或绘图失败

学生卷出现答案图片、导出缺图,或重载后 0 分变成 5 分

V3.0.3 改进了 Word / PDF 图片导出:仅属于答案的图片不再补入 Word 题干,答案版保留答案图片;PDF 改进原位图片与答案 TikZ 的处理。重新载入已保存试卷时,明确设置的 0 分也会保留。

遇到上述现象,先保留原题和已保存试卷,对照源文检查图片引用、导出选项与分值,并记录版本;不要删除原图或反复重新导入题目。查看 V3.0.3 更新说明 →

PDF 编译、TikZ 预览或 Word 公式导出失败

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

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

解答题留白不够,可以直接输入高度吗?

可以。在组卷预览中调整全卷或单题的留白,支持直接输入 0–30 cm,也可按按钮微调。切换高考 19 题预设后会恢复紧凑布局,请重新检查需要的留白。

排版调整后打开实际导出的 PDF 核对分页;图片在正文中的位置、题末图组和留白会共同影响一页能放下的内容。

网页 A4 预览正常,为什么导出的 PDF 仍有错位或缺字?

网页 A4 是模拟排版,正式 PDF 使用 LaTeX 重新编译,字体、换行和分页可能不同。请点击组卷页面的「PDF 预览」,检查实际 PDF 中的数学符号、题干与配图及跨页位置;网页看起来正常不能替代这一步。

能容纳在一页内的普通带图题会保持题干与配图同页(长题仍允许跨页,长表格或显式分页等特殊排版沿用原规则)。导出时会自动将正文中的 △、∠ 适配为数学字体,同时保留已有数学环境和题库原文。

反馈时请同时提供网页表现、实际 PDF 和完整错误提示;需要进一步排查时,可使用「LaTeX 打包」取得源码。也不要把缺题一概视为预览问题。

PDF 缺字或编译失败时,怎样根据提示定位?

当编译器发现字体缺字时,系统会停止交付该 PDF,直接提示缺失的字符、码点和字体,并在编译日志有可靠行号时标出卷面题号、题库 ID 及题干或解析位置(无法唯一定位时会提示待核对):

  1. 先看「为什么会这样」和「建议如何修复」,再核对提示附近的原题;例如三角形可写成 $\triangle ABC$,角可写成 $\angle ACB$。保留完整数学定界符,不要盲目删除看不懂的字符或猜换相似符号。
  2. 需要反馈时展开编译器技术信息,保留完整错误和对应题目位置;图片问题同时核对配图文件是否可用。
  3. 修改后再次点击「PDF 预览」,检查实际生成的页面,而不只检查网页 A4。

未配置 API 也能查看本地诊断。缺字说明直接来自本地编译日志,不请求 AI;其他编译错误可由已配置的「试卷智能拆解模型」补充修复建议(调用失败时仍保留本地结果,AI 建议不会自动修改原题)。

本地新版提示:为什么会指出中文进入公式?AI 建议可靠吗?

截至 2026-11-18,以下为本地源码调整,尚未进入 GitHub 主分支或 V3.1.0 正式下载包。新版先用普通话说明哪里需要检查;复杂源码和编译信息可按需展开。AI 建议单独列出并附引用依据,不会替换本地诊断,也不自动修改原题;有引用不代表推断一定正确。

例如 外部$和\angle BOD$ 把“和”放进了公式,数学字体可能无法显示它;核对题意后可改为 外部和$\angle BOD$。类似地,列举两个对象可写成 $OE$、$OF$。系统只在片段有充分依据时给具体修改示例,其余情况提示检查范围,不猜缺失内容。

按提示修改后再次点击「PDF 预览」。编译器通常先报告一个错误,修复后可能出现下一处问题;不能把一条建议当作整份试卷已修好的保证。

没有安装 LaTeX,也能取得试卷源码吗?

可以使用组卷页面的「LaTeX 打包」取得源码包。没有本地 LaTeX 时,源码仍可保存和导出;只有安装环境并编译成功后,才能在本机同时生成 PDF。

TikZ 预览和 PDF 编译需要 LaTeX。安装环境后仍失败时,结合源码包和编译日志检查题干、模板与图片。

看见错误码,先读完整提示

HTTP 错误码只说明大致类别。同一个 500,可能来自本地题库,也可能来自模型服务商或中转站。先记录你正在做哪一步、完整错误文本与时间,再查看下面的对应说明。

i
不要只截一个数字

部分 AI 错误会被 MathBank 包装为 400 或 500,正文中可能保留服务商的 HTTP 错误码或网络异常。排查时要一起看外层状态码与里面的具体提示。

HTTP 400 · 请求未被接受,也可能包装了上游错误

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

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

HTTP 401 · 身份凭证未通过

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

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

HTTP 403 · 当前请求没有访问权限

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

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

HTTP 404 · 目标不存在

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

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

HTTP 409 · 当前操作与已有状态冲突

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

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

HTTP 413 · 文件或请求体过大

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

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

HTTP 422 · 请求字段未通过校验

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

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

HTTP 429 · 请求频率、并发或配额受限

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

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

HTTP 500 · 服务内部发生异常

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

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

HTTP 502 · 网关没有获得有效的上游响应

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

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

HTTP 503 · 服务暂时不可用

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

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

HTTP 504 · 网关等待上游超时

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

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

HTTP 200,但页面仍提示任务失败

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

没有错误码,只有 Connection aborted / Read timed out / SSL 错误

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

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

获取日志:先复制,再重试

出现错误后,先记录发生时间、复制页面错误提示;导入中心的进度日志也请先截图,刷新或清空后可能不再保留。

!
先复制日志,再重启软件

正常启动器在每次启动新服务时会覆盖 .system_generated/server.log。请先把出错时的日志复制一份到桌面,再重启或继续测试。

日志未必包含完整错误链或服务商响应,请同时保留页面错误文字和相关日志片段。

Windows:从软件文件夹中取日志

  1. 找到你双击 启动题库系统.bat 的那个文件夹。
  2. 打开其中的 .system_generated 文件夹,找到 server.log。也可在文件资源管理器地址栏进入这个子目录。
  3. 把文件复制到桌面,用记事本打开,查找报错时间附近的内容。
  4. 若有 Traceback,保留从它开始直到最后异常原因的整段;不要只复制最后一句。

macOS:先显示隐藏文件

  1. 在 Finder 打开包含 启动题库系统.command 的软件文件夹。
  2. 按 Command + Shift + . 显示隐藏文件,进入 .system_generated。
  3. 先复制 server.log,再用文本编辑器打开,保留报错时间附近的完整错误段。
找不到 server.log,或启动阶段就失败了?

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 或原题,不要整包公开发送。

发送前检查:遮挡 API Key、访问 Token、学生信息、私人路径和未公开题目。不要发送 .env、数据库或整个题库文件夹。日志中可能包含题目内容或服务响应,优先提供与错误相关的一段。

加入 MathBank QQ 交流群

使用中遇到问题,或想交流模型选择与题库整理方法,可以在 QQ 的“找群”中搜索群号加入。

i
MathBank 用户交流群

群号:1107557945

提问时可使用下方反馈模板,附上版本、系统、出错步骤和已脱敏的错误片段。

仍然没解决?复制这份反馈模板

填写后可在 QQ 群或 GitHub Issues 中反馈。优先附上能复现问题的小样例;发送前按上方说明检查敏感信息。

前往 GitHub Issues 反馈 ↗

搜索使用指南

输入问题或关键词,查找对应的操作步骤。

图片预览