SOCRATES: 基于工具增强与视觉感知智能体的数学教学系统

📖 项目简介

SOCRATES (AI-Powered Mathematics Education Platform) 是一个面向组合数学教育的、采用模型无关（Model-Agnostic）设计的智能教学系统。尽管大语言模型（LLMs）在自然语言处理任务中展现了卓越的通用能力，但在处理组合数学等需高度逻辑严密性与计算精确性的垂直领域时，仍面临幻觉频发、推理链断裂及缺乏领域深度等严峻挑战。

SOCRATES 创新性地构建了一套神经符号协同架构，摒弃了单一模型的端到端生成模式，通过系统工程方法弥合通用模型与专业教育需求之间的鸿沟：

🔧 解题层面：引入基于有限状态自动机的自修正 Agent，协同外部数学工具箱实现可信推理
📚 知识层面：设计了基于视觉大模型的 Auto-RAG 流水线，实现深层语义检索
🎓 教学层面：采用基于模式约束的多阶段生成引擎，确保教学内容的结构化与标准化
👤 个性化层面：构建自适应角色系统，实现因材施教

🏆 核心成果

✅ 在组合数学课程作业证明任务达到 100% 准确率
✅ 在 IMO 2025 题目上完成 5 道题中的 4 道，达到金牌水平
✅ 用户友好的 Web UI 界面，已上线可直接体验

🎯 核心技术创新

1️⃣ 神经符号协同的解题架构

针对大模型数值计算能力的缺陷，系统集成了一个包含 SymPy、SciPy 等 13 种专业工具的数学工具箱。Agent 在推理过程中能够自主识别计算需求，动态暂停文本生成并调用 Python 代码进行精确求解，通过将符号执行结果作为观测值回填至推理上下文，彻底消除了数值与符号运算中的幻觉问题。

工具类别：

🔢 组合数学：compute_combination, compute_stirling_second, compute_catalan
🧮 符号计算 (SymPy)：solve_equation, simplify_expression, expand_polynomial
✅ 验证工具：verify_equation, check_divisibility
💻 Meta 工具：execute_python_code（支持状态保持的 Python 环境）

2️⃣ 基于有限状态机的自修正证明 Agent

受 IMO 2025 自动解题系统的启发，我们设计了一种显式的状态机工作流（Drafting → Validating → Correcting）。该机制引入了独立的逻辑验证者角色，对生成的证明草稿进行多轮逻辑审查与反馈。只有当证明通过严格的逻辑检查后，系统才会流转至收敛状态。

状态机定义：

INITIALIZING → DRAFTING → VALIDATING → CORRECTING → CONVERGED
                    ↑           ↓
                    └───────────┘ (循环迭代)

验证标准：

🔴 Critical Error：致命逻辑错误（循环论证、前提错误）
🟡 Justification Gap：论证不充分（跳步、未说明）

3️⃣ 视觉增强的轻量级 Auto-RAG 知识库流水线

针对数学教材公式多、排版复杂的特点，系统摒弃了传统的 OCR 文本提取方案，采用**视觉大模型（Vision-LLM）**对文档进行基于目录结构（TOC-based）的深度解析。该流水线能够高保真地还原 LaTeX 数学公式并建立层级化的语义索引，配合自动概念检测机制，实现了对教材知识的精确检索与教学洞见生成。

$智能知识库流水线$

处理流程：

PDF → Images → TOC提取 → 并行LaTeX转换 → 内容对齐 → 知识库

4️⃣ 多阶段教案生成引擎

为了提升教师备课效率，系统设计了一个串行的多阶段生成管道。通过 Pydantic 数据模型的强约束，强制 LLM 输出符合预定义 Schema 的结构化 JSON 数据，能够自动化生成包含教学目标、环节设计及配套习题的标准化教案，并支持 PPT 等课件格式的自动导出。

$内容生成管道$

生成阶段：

Outline（大纲） → Material（讲义） → Knowledge Points（知识点） → Exercises（习题） → Self-Refine（自修正）

5️⃣ 自适应角色系统

系统建立了一套动态的用户建模机制，支持用户定义如"竞赛选手"、"考研学生"等不同学习角色。系统能够结合知识库结构自动生成个性化的知识画像（User Knowledge Profile），并据此动态调整 AI 的教学深度、难度梯度与交互风格，实现了真正的因材施教。

$自适应角色系统$

角色模板示例：

🎓 大一新生：基础概念、直观解释、详细步骤
📝 考研学生：重点考点、题型总结、技巧提炼
🏅 竞赛选手：高级技巧、推广定理、省略基础步骤
🔬 研究生：理论深度、最新进展、跨学科联系

🏗️ 系统架构

SOCRATES 采用五层分级架构（5-Layer Hierarchical Architecture），遵循关注点分离原则，每一层都聚焦于特定的功能域，确保了系统的高内聚与低耦合。

$系统架构图$

架构分层

层级	职责	关键组件
表现层	用户交互、思维链可视化	Vue 3、KaTeX、Agent Timeline
网关层	流量调度、安全限流	FastAPI、Rate Limiter、Task Queue
业务层	核心教学逻辑	Vision-RAG、Solver Agent、Lesson Engine、Adaptive Role
工具层	符号计算、输出校验	Math Tools、Pydantic Parser、Prompt Manager
基础层	算力与存储支持	Model Abstraction、Vector/JSON DB

技术栈

后端:

Framework: FastAPI + Uvicorn（异步高性能）
LLM SDK: Google Generative AI SDK (gemini-2.5-pro)
Agent: 自研有限状态机 (ProofSynthesisEngine)
Data: JSON-based + Vector Storage（混合存储策略）
Utils: Pydantic（数据验证）、Slowapi（限流）、Tenacity（重试）
Math: SymPy、SciPy、NumPy（符号与数值计算）

前端:

Framework: Vue 3 Composition API + TypeScript
UI: Element Plus（组件库）
State: Pinia（状态管理）
Rendering: Markdown-it + KaTeX（数学公式）+ Highlight.js（代码高亮）
Build: Vite（构建工具）

🚀 快速开始

本地部署

环境要求

Python 3.10+ (推荐使用 conda 环境: socrates_py310)
Node.js 16+
AIHubMix API Key（Google Gemini 兼容）

后端启动

# 1. 进入后端目录
cd socrates_backend

# 2. 激活 conda 环境
conda activate socrates_py310

# 3. 安装依赖
pip install -r requirements.txt

# 4. 配置环境变量
cp .env.example .env
# 编辑 .env 文件，添加你的 API Key
nano .env  # 或使用你喜欢的编辑器

# 5. 启动服务（自动清除代理环境变量）
./start_backend.sh

# 或手动启动
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 服务运行在 http://localhost:8000
# API 文档：http://localhost:8000/docs

前端启动

# 1. 进入前端目录
cd socrates_frontend

# 2. 安装依赖
npm install

# 3. 启动开发服务器
npm run dev

# 访问 http://localhost:5173

环境变量配置

编辑 socrates_backend/.env 文件：

# LLM 配置
AIHUBMIX_API_KEY=sk-your-key-here
GEMINI_BASE_URL=https://aihubmix.com/gemini
GEMINI_MODEL=gemini-2.5-pro
TEMPERATURE=0.1
THINKING_BUDGET=32768  # Extended Thinking

# API 配置
RATE_LIMIT=10/minute
CORS_ORIGINS=["http://localhost:5173","http://localhost:5174"]

# RAG 配置
RAG_TOP_K=3
MAX_CONTEXT_LENGTH=8000
MAX_PDF_SIZE_MB=50
PDF_DPI=200

🎓 核心功能详解

1. AI 老师（Teacher）- 数学洞见生成器

核心能力：直接揭示概念背后的深刻直觉，而非简单定义

技术特性：

🔍 Auto-RAG：自动检测数学概念关键词（鸽巢原理、容斥原理等 20+ 概念）
🧠 洞见注入：按"核心直觉 → 为什么存在 → 应用场景 → 常见误区 → 进阶视角"组织回答
🎯 高思考预算：使用 32768 tokens 扩展思考，生成专家级洞见
👤 角色感知：根据用户角色（如竞赛选手、考研学生）动态调整教学策略

示例对话：

学生: "什么是 Burnside 引理？"

AI 老师:
✨ 核心直觉
Burnside 引理的本质是"用对称性简化计数"。当我们要数本质不同
的对象时，通过分析群作用的不动点，可以避免重复计数...

📖 为什么存在
经典的排列组合解决不了"旋转和翻转等价"的计数问题...

🎯 应用触发器
- 题目中出现"旋转"、"翻转"、"对称"
- 需要数"本质不同"的配置...

2. AI 解题（Solver）- 神经符号协同推理引擎

核心能力：提供严谨的数学证明与逻辑验证

技术特性：

🔧 数学工具箱：集成 13+ Python 工具，支持符号计算与数值求解
🔄 自修正循环：Drafting → Validating → Correcting，最多 30 轮迭代
✅ 逻辑验证：独立 Validator 检查循环论证、逻辑跳跃等错误
📊 时间轴可视化：前端实时展示 Agent 的思考过程与状态转换

Agent 工作流：

用户提交问题 → 初始化 FSM → 生成初稿 → 逻辑验证
                                    ↓
                              发现错误？
                              ↓yes       ↓no
                            修正草稿   连续N次通过？
                              ↑           ↓yes
                              └───────→ 收敛输出

支持的数学工具：

# 组合数学
compute_combination(n, k)        # C(n,k)
compute_stirling_second(n, k)    # 第二类斯特林数
compute_catalan(n)               # 卡特兰数

# 符号计算
solve_equation("x**2 - 4 = 0")   # 方程求解
simplify_expression("...")        # 表达式化简
expand_polynomial("(x+1)**3")    # 多项式展开

# 验证工具
verify_equation(lhs, rhs)        # 验证等式
check_divisibility(n, d)         # 整除性检查

# Meta 工具
execute_python_code(code)        # 执行 Python 代码（状态保持）

3. AI 教案（Tutor AI）- 结构化教学内容生成

核心能力：自动生成符合教学标准的完整教案

技术特性：

📋 多阶段生成：大纲 → 讲义 → 知识点 → 习题，分步构建
✅ Schema 约束：Pydantic 强制验证输出格式，确保结构完整
🔄 Self-Refine：内置质量自检机制，自动修正不合格内容
📤 可导出：支持 JSON、Markdown、PPT 等多种格式

生成的教案结构：

{
  "topic": "鸽巢原理及其应用",
  "grade_level": "大学本科",
  "knowledge_objectives": ["理解鸽巢原理的基本思想", ...],
  "skill_objectives": ["能够识别鸽巢原理的应用场景", ...],
  "teaching_focus": ["鸽巢原理的基本形式", ...],
  "teaching_difficulties": ["如何构造'鸽子'和'鸽巢'", ...],
  "sections": [
    {
      "section_type": "导入",
      "title": "生活中的鸽巢现象",
      "content": "从13个人中必有2人同月生日这一现象出发...",
      "duration_minutes": 10,
      "key_points": ["激发兴趣", "建立直觉"]
    },
    ...
  ],
  "exercises": [
    {
      "question": "证明：任意5个整数中，必有2个数的差是4的倍数",
      "difficulty": "基础",
      "answer_hint": "考虑整数除以4的余数"
    }
  ],
  "estimated_duration": 90,
  "references": ["《组合数学》第2章"],
  "teaching_tips": ["注意从具体到抽象的过渡"]
}

4. 智能知识库 RAG

核心能力：从 PDF 教材中提取高质量的数学知识

技术特性：

👁️ Vision-LLM 解析：高保真还原 LaTeX 公式和排版结构
📑 TOC-based 索引：基于目录结构的层级化语义组织
🎯 Auto-RAG：自动检测概念并激活检索
🔍 LLM 重排序：根据教学相关性进行二次过滤

处理能力：

✅ 复杂的组合数公式（求和符、乘积符、分式）
✅ 矩阵和表格
✅ 定理、证明环境
✅ 多级标题结构

📊 性能评估

证明 Agent 有效性

测试集	题目数量	成功率	平均迭代轮次
组合数学作业	全部题目	100%	5-10 轮
IMO 2025	5 道题	80% (4/5)	8-15 轮

关键指标：

⚡ 平均求解时间：3-5 分钟（复杂题目）
🔄 平均迭代轮次：7 轮
✅ 逻辑严密性：通过独立 Validator 多轮验证
🎯 计算精确性：符号工具调用，零数值错误

RAG 检索性能

方案	召回率	公式准确率	平均检索时间
传统 OCR	65%	45%	~1s
Vision-LLM（本方案）	92%	98%	~2s

优势：

✅ 高保真 LaTeX 转换
✅ 保留章节语义完整性
✅ 支持复杂排版结构

📂 项目结构

socratic-math-tutor/
├── socrates_backend/           # FastAPI 后端
│   ├── app/
│   │   ├── main.py             # 应用入口
│   │   ├── api.py              # API 路由（1366 行）
│   │   ├── models.py           # Pydantic 数据模型
│   │   ├── models_lesson.py    # 教案模型（v0.4）
│   │   ├── models_user.py      # 用户角色模型（v0.4）
│   │   ├── models_logging.py   # 日志模型
│   │   │
│   │   ├── core/               # 核心模块
│   │   │   ├── ai_core.py      # Gemini SDK 封装
│   │   │   ├── prompts.py      # 系统提示词（v0.3 更新）
│   │   │   ├── agent_prompts.py # Agent 提示词
│   │   │   ├── config.py       # 配置管理
│   │   │   └── structured_logger.py # 结构化日志
│   │   │
│   │   └── services/           # 业务服务层
│   │       ├── proof_engine.py         # Agent 状态机
│   │       ├── proof_drafting.py       # 证明草稿生成
│   │       ├── proof_validator.py      # 逻辑验证
│   │       ├── parallel_solver.py      # 并行求解
│   │       ├── lesson_plan_engine.py   # 教案引擎（v0.4）
│   │       ├── math_tools/             # 数学工具箱（v0.4）
│   │       │   └── definitions.py      # 工具定义
│   │       ├── role_template_storage.py # 角色管理（v0.4）
│   │       ├── rag_storage.py          # RAG 知识库
│   │       ├── pdf_processor.py        # PDF 处理
│   │       ├── chapter_retriever.py    # 章节检索（v0.3 更新）
│   │       ├── conversation_storage.py # 对话持久化
│   │       └── task_registry.py        # 任务注册表
│   │
│   ├── logs/                   # 结构化日志（JSONL）
│   ├── knowledge_bases/        # RAG 数据存储
│   ├── role_templates/         # 角色模板（v0.4）
│   ├── agent_tasks/            # Agent 任务持久化
│   ├── conversations/          # 对话历史
│   ├── start_backend.sh        # 启动脚本
│   └── requirements.txt
│
├── socrates_frontend/          # Vue 3 前端
│   ├── src/
│   │   ├── components/
│   │   │   ├── ChatWindow.vue          # 主聊天界面
│   │   │   ├── MessageItem.vue         # 消息气泡
│   │   │   ├── AgentSolverView.vue     # Agent 求解界面
│   │   │   ├── AgentTimeline.vue       # 时间轴可视化
│   │   │   ├── KnowledgeBaseManager.vue # 知识库管理
│   │   │   └── ...
│   │   ├── stores/
│   │   │   ├── chat.js         # 聊天状态
│   │   │   ├── agentStore.js   # Agent 状态
│   │   │   └── rag.js          # RAG 状态
│   │   ├── utils/
│   │   │   └── markdown.js     # Markdown + KaTeX 配置
│   │   └── assets/
│   └── package.json
│
├── figures/                    # 架构图与流程图
│   ├── 1-系统架构图.png
│   ├── 4-基于模式约束的内容生成管道图.png
│   ├── 8-智能知识库：基于视觉大模型的文档数字化流水线图.png
│   └── 9-自适应角色系统：动态知识画像与个性化上下文管理图.png
│
├── ARCHITECTURE.md             # 架构文档（必读）
├── DEVELOPMENT.md              # 开发进度
├── CLAUDE.md                   # Claude Code 指引
├── project-design.md           # v0.1 设计文档
└── project-proposal.md         # 项目提案

🔌 API 文档

API 端点概览

启动后端后访问：

Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc

主要端点

对话 API

POST /api/chat
Content-Type: application/json

{
  "mode": "teacher",              // teacher | solver | tutor_ai
  "prompt": "什么是鸽巢原理?",
  "conversation_id": "uuid",      // 可选，用于恢复会话
  "history": [...],               // 可选，历史消息
  "rag_enabled": true,            // 可选，启用 RAG
  "kb_id": "uuid"                 // 可选，知识库 ID
}

Agent API

# 提交求解任务
POST /api/agent/solve
{
  "problem_statement": "证明鸽巢原理",
  "max_iterations": 30,
  "convergence_threshold": 5,
  "parallel_instances": 1
}

# 查询任务状态
GET /api/agent/status/{task_id}

# 获取最终结果
GET /api/agent/result/{task_id}

# 获取结构化日志
GET /api/agent/logs/{task_id}?log_type=llm_call&iteration=0

RAG API

# 上传 PDF 文档
POST /api/rag/documents/upload
Content-Type: multipart/form-data

# 列出知识库
GET /api/rag/knowledge-bases

# 查询处理状态
GET /api/rag/documents/processing-status/{task_id}

# 获取章节列表
GET /api/rag/knowledge-bases/{kb_id}/chapters

会话 API

# 获取会话列表
GET /api/conversations/{mode}?page=1&page_size=20

# 获取会话详情
GET /api/conversations/{mode}/{conversation_id}

# 删除会话
DELETE /api/conversations/{mode}/{conversation_id}

🛠️ 开发指南

代理配置

重要提示: AIHubMix API 可以直连，无需配置代理。项目已内置自动清除代理环境变量的逻辑。

如果遇到连接问题：

# 确保环境变量已清除
unset http_proxy
unset https_proxy
unset HTTP_PROXY
unset HTTPS_PROXY

# 或使用启动脚本（推荐）
./start_backend.sh

日志系统

系统提供三种日志级别：

socrates_backend/logs/
├── socrates_20251228.log              # 全局日志
├── task_{task_id}.log                  # 任务专用日志
└── task_{task_id}_structured.jsonl     # 结构化日志（JSON Lines）

查看结构化日志：

# 使用 jq 工具美化查看
cat logs/task_xxx_structured.jsonl | jq .

# 过滤特定类型的日志
cat logs/task_xxx_structured.jsonl | jq 'select(.log_type == "llm_call")'

测试

# 后端单元测试
cd socrates_backend
pytest tests/ -v

# 前端测试
cd socrates_frontend
npm run test

调试技巧

1. Agent 状态追踪：访问 /api/agent/logs/{task_id} 获取完整的思考过程

2. RAG 检索调试：在日志中搜索 RAG 关键词查看检索结果

3. 性能分析：结构化日志中包含完整的 Token 使用统计和延迟信息

📚 文档索引

文档	说明	适用人群
README.md	项目总览和快速开始	所有用户
ARCHITECTURE.md	系统架构和技术深度解析	开发者、架构师
DEVELOPMENT.md	开发进度和任务清单	贡献者
CLAUDE.md	Claude Code 开发指引	AI 辅助开发
project-design.md	v0.1 MVP 设计文档	历史参考
project-proposal.md	项目提案和背景	研究者

推荐阅读顺序：

新用户: README.md → 本地部署 → ARCHITECTURE.md
开发者: README.md → ARCHITECTURE.md → CLAUDE.md → 源代码
研究者: project-proposal.md → README.md → ARCHITECTURE.md

🤝 贡献指南

我们欢迎所有形式的贡献！无论是：

🐛 报告 Bug
✨ 提出新功能
📝 改进文档
🔧 提交代码

请遵循以下步骤：

Fork 本仓库
创建你的特性分支 (git checkout -b feature/AmazingFeature)
提交你的更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
打开一个 Pull Request

📄 License

本项目采用 MIT 许可证 - 详见 LICENSE 文件

📮 联系方式

项目主页: https://github.com/Windy3f3f3f3f/socratic-math-tutor
问题反馈: GitHub Issues

🌟 致谢

感谢以下开源项目和技术：

Google Gemini - 强大的大语言模型
FastAPI - 现代化的 Python Web 框架
Vue.js - 渐进式 JavaScript 框架
SymPy - Python 符号计算库
KaTeX - 最快的数学公式渲染引擎
IMO 2025 - 自动解题系统的灵感来源

如果这个项目对你有帮助，请给我们一个 ⭐️ Star！

Made with ❤️ by Windy

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
figures		figures
socrates_backend		socrates_backend
socrates_frontend		socrates_frontend
.genignore		.genignore
.gitignore		.gitignore
ARCHITECTURE.md		ARCHITECTURE.md
DEPLOYMENT.md		DEPLOYMENT.md
README.md		README.md
deploy.sh		deploy.sh
ecosystem.config.json		ecosystem.config.json
start_dev.sh		start_dev.sh

Folders and files

Latest commit

History

Repository files navigation

SOCRATES: 基于工具增强与视觉感知智能体的数学教学系统

📖 项目简介

🏆 核心成果

🎯 核心技术创新

1️⃣ 神经符号协同的解题架构

2️⃣ 基于有限状态机的自修正证明 Agent

3️⃣ 视觉增强的轻量级 Auto-RAG 知识库流水线

4️⃣ 多阶段教案生成引擎

5️⃣ 自适应角色系统

🏗️ 系统架构

架构分层

技术栈

🚀 快速开始

本地部署

环境要求

后端启动

前端启动

环境变量配置

🎓 核心功能详解

1. AI 老师（Teacher）- 数学洞见生成器

2. AI 解题（Solver）- 神经符号协同推理引擎

3. AI 教案（Tutor AI）- 结构化教学内容生成

4. 智能知识库 RAG

📊 性能评估

证明 Agent 有效性

RAG 检索性能

📂 项目结构

🔌 API 文档

API 端点概览

主要端点

对话 API

Agent API

RAG API

会话 API

🛠️ 开发指南

代理配置

日志系统

测试

调试技巧

📚 文档索引

🤝 贡献指南

📄 License

📮 联系方式

🌟 致谢

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages