MathCraft 是一个包含 Python 后端与 React 前端的数学智能体项目。后端提供知识库管理、文档解析、索引检索、模型配置和出题服务;前端提供题目生成、题目预览、组卷和参数配置等交互界面。
项目包含一个统一的 MathCraft 后端:同一进程提供知识库、模型配置、文档入库、检索和题目生成 API;frontend 是配套的 React 应用。前后端按独立进程启动,详细目录职责见 backend/README.md 和 frontend/README.md。
MathCraft 从 DeepTutor 的 a31d8262 提交裁剪而来,缩减为单租户快照,不跟踪上游,运行时数据全部落在 $MATH_Q_HOME/data。内部 math_q_agent 包作为兼容层保留,新的启动命令和公共模块名统一为 MathCraft。
MathCraft/ # 仓库根:工程配置、跨端契约与文档
├── README.md # 项目说明、启动方式和文档入口
├── AGENTS.md # 协作约定:文档同步、密钥红线、中文约定式提交
├── LICENSE # Apache-2.0 许可全文
├── THIRD_PARTY_NOTICES.md # 第三方来源说明与许可证正文
├── STUBS.md # 单租户替身模块清单
├── GLOSSARY.md # 学习空间、个人中心、设置与知识库领域术语
├── pyproject.toml # 包元数据、依赖与 extras
├── openapi.json # 导出的 OpenAPI 契约快照
├── .env.example # 环境变量样例
├── .gitignore # 忽略虚拟环境、运行时数据、缓存与 .env
├── backend/ # Python 后端,详细结构见 backend/README.md
│ ├── MathCraft/ # 对外 Python 模块与启动入口
│ ├── math_q_agent/ # DeepTutor 兼容实现包
│ │ ├── api/routers/profile.py # 单租户教师资料与头像接口
│ │ └── services/profile/ # 资料校验与独立持久化
│ └── README.md # 后端目录结构与职责说明
├── docs/ # API 文档、设计资料与项目流程文档
│ ├── api.md # HTTP API 参考
│ ├── design/ # 新功能与模块设计文档
│ │ ├── 个人中心与模型配置页面设计.md # 已确认的页面方案与能力边界
│ │ ├── 个人中心与应用设置功能规格.md # 本地功能规格、用户故事与验收标准
│ │ └── 个人中心与应用设置实施记录.md # 验收结果、审查及验证边界
│ ├── adr/ # 架构决策记录
│ └── 智能体出题工作流程.docx # 出题流程说明
├── frontend/ # React 前端,详细结构见 frontend/README.md
│ ├── src/components/settings/ # 模型、引擎、解析及知识库入口
│ ├── src/components/profile/ # 教师资料表单与头像上传
│ └── README.md # 前端目录结构与开发命令
└── tools/ # 仓库维护脚本
.venv/、data/、.pytest_cache/ 等本地生成物已在 .gitignore 中忽略,不属于仓库内容。
- Python 3.11 – 3.14(
pyproject.toml:requires-python = ">=3.11,<3.15")。 - uv 可选;本仓库现有的
.venv里没有 pip(uv 创建的虚拟环境默认如此)。 - 首次索引前需要配置模型,见下文「首次使用」。
方式 A:uv(推荐,本仓库开发环境即此方式)
uv venv .venv
uv pip install --python .venv/Scripts/python.exe -e .方式 B:标准库 venv(自带 pip)
python -m venv .venv
.venv\Scripts\python.exe -m pip install -e .macOS / Linux 把解释器路径换成 .venv/bin/python 即可。
已有
.venv却提示No module named pip,说明这个环境里没装 pip:改用uv pip install,或执行.venv\Scripts\python.exe -m ensurepip补装 pip。
基础安装已经包含默认的 llamaindex RAG 引擎和内置 text_only 文档解析引擎,启动默认服务不需要安装下面的 extras。其他解析器、RAG 引擎和测试依赖按需安装(下例用 uv;用 pip 时把 uv pip install --python .venv/Scripts/python.exe 换成 .venv\Scripts\python.exe -m pip install):
uv pip install --python .venv/Scripts/python.exe -e ".[parse]" # 可选:全部额外文档解析引擎
uv pip install --python .venv/Scripts/python.exe -e ".[graphrag]" # 可选:GraphRAG(需 Python < 3.14)
uv pip install --python .venv/Scripts/python.exe -e ".[engines]" # 可选:全部额外 RAG 引擎与重排依赖
uv pip install --python .venv/Scripts/python.exe -e ".[dev]" # 可选:测试依赖其中,text_only 不依赖额外解析器或模型,负责普通 PDF、Office 和文本类文件的基础文本提取;llamaindex 使用本地索引和向量检索,运行前仍需通过 /api/settings 配置可用的嵌入模型。扫描型 PDF 没有文字层时会强制使用 MinerU 云端 OCR,必须通过 /api/settings 或 MINERU_MODE=cloud 配置 MinerU,并提供 API Token;系统不会为扫描 PDF 启动本地 OCR、LiteParse 或 Docling 回退。其他格式或明确选择的解析器仍按对应依赖和外部服务配置运行。
.venv\Scripts\python.exe -m MathCraft --port 8000应用导入不会加载 .env 或写入运行时设置。ASGI 启动时加载 .env、初始化设置和日志,再开始接收请求;初始化失败会直接终止启动。命令行入口会先读取 .env 和已保存的启动配置。端口优先级为 --port > shell / .env 中的 BACKEND_PORT > system.json > 内置默认值。以上命令显式绑定 8000,与下文验证地址和 Vite 默认代理端口一致;省略 --port 且没有环境变量或已保存配置时,后端使用 8001。
Python 启动模块和公共 API 模块名统一为 MathCraft。知识库、模型配置和出题接口都由这个进程提供,内部 math_q_agent 代码已直接装配进统一应用。
知识库统一使用 DeepTutor 正式知识库模块,默认 RAG provider 为 llamaindex。出题服务只调用正式知识库的文件列表和 RAG 查询,不再提供独立的 Chroma/Ollama 入库链路。
| 参数 | 默认值 | 说明 |
|---|---|---|
--host |
127.0.0.1 |
绑定地址;只对本机提供服务 |
--port |
启动配置(.env.example 为 8000) |
绑定端口;没有环境变量或保存配置时使用内置值 8001 |
--reload |
关闭 | 当前入口虽然接受此参数,但传给 Uvicorn 的是应用对象,无法启用热重载;开发时使用下方 Uvicorn 命令 |
也可以直接通过 Uvicorn 启动(便于接入进程管理器):
.venv\Scripts\python.exe -m uvicorn MathCraft.api.main:app --host 127.0.0.1 --port 8000开发时可在上述 Uvicorn 命令末尾添加 --reload --reload-dir backend;日志级别使用 Uvicorn 的 --log-level info。这些参数中,--log-level 不属于 python -m MathCraft 的命令行参数。
统一后端和前端开发服务器都从仓库根目录的 .env 读取进程级环境变量:
| 服务 | .env 行为 |
配置位置 |
|---|---|---|
MathCraft(上述示例为 8000) |
启动时读取仓库根 .env;shell 中已有的同名变量优先 |
首次没有 model_catalog.json 时由 LLM_*、TASK_*、EMBEDDING_* 初始化;通过 /api/settings 保存的 catalog 优先;MinerU 支持用 MINERU_* 做部署级覆盖 |
| Vite(5173) | 通过 envDir: '..' 读取同一份 .env |
FRONTEND_* 控制开发服务器,VITE_API_BASE_URL 控制生产前端 API 地址 |
.env.example 仅包含变量名和空凭据占位,.env 已被 .gitignore 忽略。模型配置的来源优先级是:
model_catalog.json > shell 环境变量 > .env > 内置默认值
模型环境变量只负责首次生成或补齐尚不存在的 model_catalog.json;通过 /api/settings 保存后,后续重启不会被 .env 覆盖。MinerU 的 MINERU_* 是解析器的部署级覆盖,仍会在运行时覆盖 document_parsing.json 对应字段。
扫描型 PDF 建议配置:
MINERU_MODE=cloud
MINERU_API_BASE_URL=https://mineru.net
MINERU_API_TOKEN=MINERU_API_TOKEN 必须填入本机或部署环境的真实 Token,不能写入 .env.example、代码、测试或提交记录。缺少 Token 时,扫描 PDF 会明确报“没有配置 MinerU 云端 OCR”,不会启动本地 OCR、LiteParse 或 Docling 回退。
| 变量 | 说明 |
|---|---|
MATH_Q_HOME |
数据根,默认当前工作目录(在仓库根启动时即仓库根);可在 shell 或 .env 中设置,须在 ASGI 启动前确定;运行时数据落在 <MATH_Q_HOME>/data |
MATH_Q_MODE |
运行模式,本服务只使用 server |
CORS_ORIGIN |
兼容应用 math_q_agent.api.main:app 读取的额外浏览器来源,逗号分隔;统一应用 MathCraft.api.main:app 当前固定允许所有来源,此变量不会收紧其 CORS 策略 |
BACKEND_HOST / BACKEND_PORT |
知识库与模型配置服务绑定地址和端口 |
LLM_BINDING / LLM_MODEL / LLM_API_KEY / LLM_BASE_URL |
首次启动时初始化主模型 Provider、模型、密钥和地址 |
TASK_BINDING / TASK_MODEL / TASK_API_KEY / TASK_BASE_URL |
首次启动时初始化后台任务模型 |
TASK_MODE |
任务模型模式:inherit、profiles 或 reference,默认 profiles |
EMBEDDING_BINDING / EMBEDDING_MODEL / EMBEDDING_API_KEY / EMBEDDING_BASE_URL |
首次启动时初始化嵌入模型 |
EMBEDDING_DIMENSION |
首次启动时初始化嵌入维度 |
FRONTEND_HOST / FRONTEND_PORT |
Vite 开发服务器绑定地址和端口 |
VITE_API_BASE_URL |
前端生产构建使用的绝对 API 地址;本地开发留空,使用 Vite /api 代理 |
curl.exe http://127.0.0.1:8000/healthz
# {"status":"ok","service":"MathCraft"}
curl.exe http://127.0.0.1:8000/api/auth/status
# {"auth_enabled":false,"single_user":true,"user":{...}}| 入口 | 作用 |
|---|---|
GET /healthz |
存活探针,与引擎/凭证配置无关 |
GET /docs |
Swagger 交互式文档 |
GET /openapi.json |
OpenAPI 契约(仓库根的 openapi.json 是同一份快照) |
GET /api/settings |
模型目录、提供方、解析等设置 |
GET /api/knowledge-bases |
知识库列表 |
示例:创建一个知识库并上传文档。
curl.exe -X POST http://127.0.0.1:8000/api/knowledge-bases -F name=demo -F files=@notes.pdf
curl.exe http://127.0.0.1:8000/api/knowledge-bases- 可先在
.env填写LLM_*、TASK_*、EMBEDDING_*,也可以启动后调用/api/settings编辑 Provider、模型、API 格式和嵌入维度。 - 调用
/api/settings/test-provider测试 Provider,再通过/api/settings/draft与/api/settings/apply保存;保存会写入运行时model_catalog.json,覆盖首次.env初始化值。 - 选择
text_only、Docling 或 MinerU 作为全局文档解析引擎;普通知识库流程默认使用 LlamaIndex。 - 通过知识库 API 创建知识库、上传文档并读取后台索引状态;出题服务选择正式知识库和其中的 raw 文档,
/api/generate、/api/chat仅负责编排。
backend/ 下的 api/、services/、schemas/、main.py 提供出题编排能力,并已与 DeepTutor 正式知识库和模型配置 API 合并到同一 FastAPI 进程;frontend/ 是配套前端(React 19 + Vite + Tailwind v4,构建产物可部署到 GitHub Pages)。
启动顺序是:启动统一后端,再启动前端开发服务器。
# 1) 通过正式知识库 API 上传文档并启动索引
# 具体请求见 docs/api.md;模型和嵌入配置统一通过 /api/settings 管理
# 2) 前端开发服务(另开终端,/api 代理到 BACKEND_PORT)
cd frontend
npm install
npm run dev题库管理上方的「知识库连接」支持真实建库、文件上传与引擎配置;下方既有题库协作、文档上传和模拟进度仍为演示,使用 bankMock 和定时器,不会触发真实索引。正式接口见 docs/api.md。Vite 默认代理到 127.0.0.1:8000,不会读取后端保存的 system.json;如果后端改用其他端口,请同时在根目录 .env 设置 BACKEND_PORT 并重启前端开发服务器。
前端生产构建 npm run build 产出 frontend/dist;.github/workflows/deploy.yml 提供手动触发的 GitHub Pages 部署,仓库在 Settings → Pages 启用后即可使用。检索与出题的命令行测试脚本位于 backend/scripts/(脚本已把 backend/ 加入 import 路径)。模型密钥由 /api/settings 管理,严禁写入代码、文档或提交记录。
服务持久化的全部内容位于 $MATH_Q_HOME/data:
data/
├── knowledge_bases/
│ ├── kb_config.json # 全部知识库的注册表
│ └── <kb>/
│ ├── raw/ # 上传的原始文件
│ ├── metadata.json
│ ├── .progress.json # 可恢复的索引进度
│ ├── version-N/ # 索引产物 + meta.json
│ └── visual_assets/
├── parse_cache/<hash>/<parser>/ # 解析结果缓存
└── user/settings/*.json # 模型目录、解析、引擎等设置
MATH_Q_HOME 默认使用进程启动时的当前工作目录;在仓库根目录启动时才对应仓库根目录。真实部署时应指向独立挂载的卷,并保证该目录可写、不进版本库。
当前工厂注册 9 个 RAG provider,配置时使用下表中的精确标识符:
| 引擎 | 默认安装 | 说明 |
|---|---|---|
llamaindex |
是 | 默认引擎,全文 + 向量 + 可选 BM25 |
pageindex |
是(pageindex 包) |
PageIndex Cloud 云端服务,需配置专用 API Key |
pageindex-oss |
是(pageindex 包) |
PageIndex OSS 本地索引,使用当前激活的 LLM,支持 PDF |
graphrag |
否 | pip install -e ".[graphrag]",需 Python < 3.14 |
lightrag |
否 | pip install -e ".[rag-lightrag]" |
lightrag-server |
否 | 连接外部 LightRAG 服务 |
ima |
否 | 连接外部 IMA 部署 |
kiwix |
否 | 连接外部 Kiwix 服务 |
weknora |
否 | 连接外部 WeKnora 部署 |
可选引擎惰性导入:缺少依赖时在引擎列表与预检中报告 unavailable,其配置端点仍可正常使用,服务启动不受影响。交叉编码器重排是 .[rag-rerank] extra。
文档解析接入 7 个引擎(text_only、pymupdf4llm、markitdown、liteparse、docling、mineru、tika),除 text_only 外均为可选。扫描型 PDF 的 OCR 主路径固定使用 MinerU 云端,要求在设置中配置 mode=cloud 和 API Token;MinerU 本地 CLI、LiteParse 和 Docling 不作为扫描 PDF 的隐式 OCR 回退。
没有认证。所有请求都以本地管理员身份处理,/api/auth/status 返回 single_user: true,CORS 默认放行。请绑定回环地址,或把它放在自建网关之后。
uv pip install --python .venv/Scripts/python.exe -e ".[dev]"
.venv\Scripts\python.exe -m pytest -qpyproject.toml 的 testpaths 已指向 backend/tests,直接运行即可。套件通过 TestClient 驱动真实 ASGI 应用,数据根指向一次性的 backend/tests/.data-home;它会启动一个假的 OpenAI 兼容 /embeddings 端点,因此默认 LlamaIndex 流水线无需任何外部凭证即可完成索引与检索。端到端用例会建库、上传文档、等待索引完成并断言召回片段。
以下是环境或范围事实,不是待修复的缺陷。
- 依赖网络的连接器路径未验证。 GitHub 源、网页源,以及远程 Kiwix / IMA / WeKnora / LightRAG-server 连接器均已实现,失败路径有测试覆盖(拒绝连接时必须快速返回可读错误,且不能注册出“看起来能用”的知识库);正常路径需要外网或外部服务,裁剪环境不具备。
- 只有默认引擎做过端到端索引。 测试用 LlamaIndex 对着假嵌入端点建索引。每个引擎都能解析到各自的流水线类,安装对应 extra 后会从
configured: false变为true,但真实的 GraphRAG / LightRAG / PageIndex 索引没有在这里构建过。 - 隔离文档解析需要真实临时目录。 PDF 解析通过 worker 子进程完成;在禁止子进程管道的沙箱中,解析器会报失败而不是静默降级。PDF 入库请在普通环境运行服务。
- 按设计没有认证。 请绑定回环地址或用网关前置。
- 应用模块导入仅装配路由;运行时设置初始化、环境变量导出和日志配置在 ASGI lifespan 启动阶段完成。导出 OpenAPI 不会创建运行时设置或日志。
- 配置默认路径通过当前路径服务解析,导入后、启动前设置
MATH_Q_HOME仍然有效;显式路径注入继续受支持,已创建的服务实例仍绑定原目录。运行期间请通过设置 API 修改配置,切换数据根请重启进程。 - 设置接口只有在模型目录内容实际改变时才重置 LLM/嵌入客户端;重复保存相同配置不会重置。
- 模型环境变量负责首次初始化目录;已保存的有效目录(包括明确保存的空目录)优先,不会被环境变量再次覆盖。
| 文档 | 内容 |
|---|---|
| docs/api.md | HTTP API 参考:端点、参数、curl 示例、WebSocket 契约 |
| docs/design/PRD-智能出题智能体.md | 智能出题产品需求、范围和验收标准 |
| docs/design/个人中心与模型配置页面设计.md | 五项教师资料、三种模型用途与连接管理、知识库引擎、文档解析及学习空间延期 |
| docs/design/个人中心与应用设置功能规格.md | 本地规范:46 条用户故事、实现决策与 18 项行为验收 |
| docs/design/个人中心与应用设置实施记录.md | 实际交付、18 项验收映射、双轴审查及本地验证边界 |
| docs/design/知识库模块说明.md | 知识库模块架构、生命周期、数据布局和接口分组 |
| docs/design/扫描PDF云端OCR策略.md | 扫描 PDF 的检测、MinerU 云端 OCR 契约和验收标准 |
| docs/design/模型配置来源与普通知识库流程.md | 模型目录优先级、Task 模式与普通知识库后端流程 |
| docs/adr/0001-正式知识库作为唯一知识库入口.md | 正式知识库唯一入口的架构决策 |
| GLOSSARY.md | 学习空间、个人中心、应用设置、知识库、RAG 和出题编排术语 |
| openapi.json | 机器可读的 OpenAPI 契约快照 |
| STUBS.md | 每个被替换为单租户替身的模块及其原行为 |
| THIRD_PARTY_NOTICES.md | 第三方来源与许可证正文 |
| AGENTS.md | 本仓库的协作约定(文档同步、密钥红线、提交规范) |
改动接口后请同步契约与文档:
.venv\Scripts\python.exe -c "import json, MathCraft.api.main as m; open('openapi.json','w',encoding='utf-8').write(json.dumps(m.app.openapi(), indent=2, ensure_ascii=False))"
.venv\Scripts\python.exe tools\gen_api_docs.py第一条命令从统一应用导出 OpenAPI 契约到根目录 openapi.json;第二条命令读取该快照并生成 docs/api.md。这两步用于开发维护,不是启动服务的必要步骤。端点表由契约生成,生成脚本中的检索说明和 WebSocket 示例仍需随行为变化人工维护。
左侧导航底部「设置」默认打开主语言模型,包含模型与服务、知识库引擎及文档解析。主语言模型、辅助任务模型(可跟随主模型)与嵌入模型使用模型草稿:保存草稿不影响正式配置;应用更改只应用已保存草稿;引擎和解析各自保存。连接检查仅说明实际检查到的能力。
个人中心只维护头像、昵称、只读教师身份、任教学段及年级。使用独立的 /api/user-profile 接口持久化;头像选择后先预览,点击「保存资料」后先保存资料、再上传头像;两步分别反馈结果,失败保留可重试选择。支持经校验的 PNG、JPEG、WebP,最大 5 MiB。资料与模型目录互相独立。
题库管理上方提供真实知识库与「配置引擎」入口,建库选择只作用于本次知识库。原有题库协作、组卷和学习空间仍保留明确的演示/未开放状态,不向学生真实发布。安装下载任务只观察当前后端进程;取消不回滚已完成内容。
规格:个人中心与应用设置功能规格。实际验收:实施记录。接口:API 文档。
本项目以 Apache-2.0 发布,全文见 LICENSE,pyproject.toml 中同步声明 license = {text = "Apache-2.0"}。LICENSE 中的版权行为上游项目(Copyright 2025 Data Intelligence Lab, The University of Hong Kong),裁剪时原样保留。
代码取自 DeepTutor(该项目同样为 Apache-2.0);第三方来源与对应的 MIT 等许可证正文见 THIRD_PARTY_NOTICES.md。