内容
<div align="center">
<img src="https://img.icons8.com/3d-fluency/94/calculator.png" width="80" alt="智能数学求解器 Logo" />
# 🧮 智能数学求解器
**基于 LangGraph 多智能体架构，MCP 工具链和 React 高级 UI 的数学学习辅助工具 — 为学生打造，Gemini & Groq 驱动。**
[](https://advanced-math-ai.vercel.app)
[](https://false45-math-api.hf.space/docs)
[](LICENSE)
[](https://python.org)
[](https://react.dev)
[](https://fastapi.tiangolo.com)
[](Dockerfile)
[](tests/)
</div>
<br />
<div align="center">
<strong>
<a href="#-功能">功能</a> ·
<a href="#-架构">架构</a> ·
<a href="#-技术栈">技术栈</a> ·
<a href="#-截图">截图</a> ·
<a href="#-快速开始">快速开始</a> ·
<a href="#-路线图">路线图</a> ·
<a href="#-贡献">贡献</a>
</strong>
</div>
<br />
---
## ✨ 功能
| | 功能 | 描述 |
| :---: | :--- | :--- |
| 🧠 | **智能数学聊天** | 实时 AI 辅导，逐步推理。完美渲染复杂方程（LaTeX，KaTeX）。由 LangGraph 多智能体流水线驱动，包含规划、求解、验证、格式化阶段。 |
| 📸 | **多模态输入** | 上传 PDF 或使用相机扫描手写数学问题。Google Gemini Vision 提取并立即求解。 |
| 📚 | **NCERT 问答引擎** | 为 9-10 年级学生提供的互动多选题，由 **Qdrant Vector DB** 和 **RAG**（检索增强生成）驱动。 |
| 📐 | **符号数学引擎** | 专用 SymPy 计算引擎 — 微分、积分、求根和动态绘制 2D 函数图。 |
| 📈 | **进度仪表盘** | 跟踪连胜、准确率和弱项，**Firebase Auth** + **Recharts** 直线图。 |
| 🔗 | **MCP 工具服务器** | 6 个沙盒 Model Context Protocol 服务器（SymPy、计算器、绘图器、Python 执行器、图像求解器、PDF 阅读器）为 AI 提供真正的计算能力，而不是幻觉数学。 |
| 🎨 | **高级 UI/UX** | 暗色优先的 React 单页应用，具备玻璃拟态、微动画和移动响应式设计（Vite）。 |
---
## 🏗 架构
系统使用 **LangGraph** 进行有状态的多智能体编排，**Google ADK 代理** 作为专用推理节点，**MCP 服务器** 作为沙盒工具后端。
```mermaid
graph TD
%% ─── 前端 ───────────────────────────────────────────────
Client["🖥️ React 单页应用<br/>(Vite + TypeScript)"]
%% ─── API 网关 ────────────────────────────────────────────
subgraph API["⚡ API 层"]
FastAPI["FastAPI 网关"]
Auth["Firebase Auth<br/>中间件"]
end
%% ─── LangGraph 编排器 ─────────────────────────────────
subgraph 编排["🔄 LangGraph 状态机"]
Planner["📋 规划节点"]
RAG["📖 RAG 节点"]
Memory["🧠 内存节点"]
Solver["🔧 求解节点"]
Verifier["✅ 验证节点"]
Formatter["🎨 格式化节点"]
end
%% ─── 数据存储 ────────────────────────────────────────────
subgraph 存储["💾 存储"]
Firestore[("Firestore")]
Qdrant[("Qdrant<br/>向量数据库")]
end
%% ─── MCP 工具服务器 ───────────────────────────────────────
subgraph MCP["🔌 MCP 工具服务器"]
SymPy["SymPy MCP"]
Calc["计算器 MCP"]
GraphPlot["绘图器 MCP"]
PyExec["Python 沙盒 MCP"]
ImgSolver["图像求解器 MCP"]
PDFReader["PDF 阅读器 MCP"]
end
%% ─── 连接 ────────────────────────────────────────────
Client -- "SSE 流" --> FastAPI
FastAPI --> Auth
FastAPI --> Planner
Planner --> RAG
Planner --> Memory
RAG --> Solver
Memory --> Solver
Solver --> Verifier
Verifier -- "❌ 重试" --> Solver
Verifier -- "✅ 通过" --> Formatter
Formatter --> Client
Memory -.-> Firestore
RAG -.-> Qdrant
Solver --> SymPy
Solver --> Calc
Solver --> GraphPlot
Solver --> PyExec
Solver --> ImgSolver
Solver --> PDFReader
```
> **工作原理：** 用户的问题进入 LangGraph 状态机。**规划器** 分类问题，**RAG** 和 **内存** 节点并行获取相关上下文，**求解器** 使用 MCP 工具进行实际计算，**验证器** 检查正确性（错误时重试最多 3 次），**格式化器** 添加 LaTeX 样式后流式返回给客户端。
---
## 💻 技术栈
### 前端
- **KaTeX** — LaTeX 数学渲染
- **Recharts** — 交互式数据可视化
- **Lucide React** — 现代图标库
- **React Markdown** — 丰富文本格式化
### 后端
- **LangGraph** — 多智能体状态机编排
- **Google ADK** — 专用推理代理开发工具包
- **Gemini 2.5 Flash** — 主要大语言模型（多模态）
- **Groq (Llama 3.3 70B)** — 快速推理备用
- **SymPy** — 符号数学引擎
- **Qdrant** — NCERT RAG 向量数据库
- **Firebase Admin** — Firestore + Auth
### 运维
- **CI/CD** — GitHub Actions 自动测试
- **后端托管** — Hugging Face Spaces（Docker）
- **前端托管** — Vercel
- **容器化** — Docker + Docker Compose
---
## 📸 截图
<div align="center">
<table>
<tr>
<td align="center"><b>💬 AI 聊天（数学求解）</b><br/><img src="screenshots/chat_solving.png" width="400" alt="AI 聊天求解" /></td>
<td align="center"><b>📚 NCERT 问答引擎</b><br/><img src="screenshots/ncert_quiz.png" width="400" alt="NCERT 问答引擎" /></td>
</tr>
<tr>
<td align="center"><b>📐 交互式绘图（SymPy）</b><br/><img src="screenshots/graphing.png" width="400" alt="交互式绘图" /></td>
<td align="center"><b>📊 学习仪表盘</b><br/><img src="screenshots/dashboard.png" width="400" alt="学习仪表盘" /></td>
</tr>
</table>
</div>
---
## 🚀 快速开始
### 要求
- **Python 3.9+** 和 pip
- **Node.js 18+** 和 npm
- **Docker** （可选）
### 选项 1 — Docker Compose（推荐）
```bash
# 克隆仓库
git clone https://github.com/Sarika-stack23/agentic-math-solver.git
cd agentic-math-solver
# 配置环境
cp .env.example .env
# 使用您的 API 密钥编辑 .env
# 启动所有服务
docker compose up --build
```
| 服务 | URL |
| :--- | :--- |
| 后端 API | `http://localhost:8080` |
| API 文档（Swagger） | `http://localhost:8080/docs` |
| 前端 | `http://localhost:5173` |
### 选项 2 — 本地开发
#### 后端
```bash
cd backend
python3 -m venv venv
source venv/bin/activate # macOS/Linux
# venv\Scripts\activate # Windows
pip install -r requirements.txt
# 配置环境
cp ../.env.example ../.env
# 使用您的 API 密钥编辑 .env
uvicorn src.main:app --reload --port 8080
```
#### 前端
```bash
cd frontend
npm install
# 创建前端 .env
echo "VITE_API_URL=http://localhost:8080" > .env
npm run dev
```
### 环境变量
| 变量 | 必需 | 描述 |
| :--- | :---: | :--- |
| `GEMINI_API_KEY` | ✅ | [Google AI Studio](https://aistudio.google.com/apikey) — 免费层可用 |
| `GROQ_API_KEY` | ✅ | [Groq Console](https://console.groq.com/keys) — 免费层可用 |
| `USE_GEMINI` | — | 设置为 `true` 以使用 Gemini 作为主要模型（默认：`true`） |
| `USE_FIREBASE` | — | 设置为 `true` 以启用 Firebase Auth + Firestore |
| `FIREBASE_CREDENTIALS_PATH` | — | Firebase Admin SDK JSON 文件路径 |
---
## 📁 目录结构
```text
agentic-math-solver/
├── backend/
│ ├── src/
│ │ ├── agents/ # ADK 代理定义（规划器、求解器、验证器等）
│ │ ├── api/ # FastAPI 路由（聊天、进度、测验、视觉）
│ │ ├── graph/ # LangGraph 状态机编排
│ │ ├── math/ # 符号数学引擎（SymPy）
│ │ ├── services/ # Qdrant、Firebase 和外部服务连接器
│ │ ├── config.py # 集中式配置
│ │ └── main.py # FastAPI 应用程序入口
│ ├── knowledge-base/ # NCERT Markdown 文件用于 RAG 检索
│ ├── Dockerfile # 后端容器镜像
│ └── requirements.txt # Python 依赖项
│
├── frontend/
│ ├── src/
│ │ ├── components/ # React 组件（聊天、测验、绘图、仪表盘）
│ │ ├── context/ # Firebase Auth 状态管理
│ │ ├── App.tsx # 主应用程序壳
│ │ └── index.css # Glassmorphism UI 样式
│ ├── vercel.json # Vercel SPA 路由配置
│ └── package.json # Node 依赖项
│
├── mcp-servers/ # 模型上下文协议工具服务器
│ ├── calculator-mcp/ # 基本算术运算
│ ├── graph-plotter-mcp/ # 2D 函数图生成
│ ├── image-solver-mcp/ # Gemini Vision 图像处理
│ ├── pdf-reader-mcp/ # PDF 文本提取
│ ├── python-executor-mcp/ # 沙盒 Python 代码执行
│ └── sympy-mcp/ # 符号数学计算
│
├── tests/ # 19 个测试套件（pytest）
├── docs/ # 架构文档
├── screenshots/ # UI 截图（暗色和亮色模式）
├── .github/workflows/ # CI/CD 流水线
├── docker-compose.yml # 多服务编排
├── render.yaml # Render.com 部署配置
├── .env.example # 环境变量模板
├── CONTRIBUTING.md # 贡献指南
├── CHANGELOG.md # 版本历史
└── LICENSE # MIT 许可证
```
---
## 🗺 路線圖
- [x] 多智能体 LangGraph 编排流水线
- [x] MCP 工具服务器集成（6 个服务器）
- [x] 多模态输入（相机 + PDF）
- [x] NCERT RAG 问答引擎，带 Qdrant
- [x] Firebase Auth + 进度跟踪仪表盘
- [x] 高级暗色优先 UI，带玻璃拟态
- [x] Docker 容器化 + CI/CD 流水线
- [x] 部署到 Vercel（前端）+ Hugging Face（后端）
- [ ] 数学问题的语音输入（Web Speech API）
- [ ] 多语言支持（印地语、西班牙语、法语）
- [ ] 协作学习房间（WebSocket）
- [ ] 导出解决方案为 PDF
- [ ] 测验调度的间隔重复算法
- [ ] 家长/教师仪表盘，带学生分析
---
## 🤝 贡献
欢迎贡献！请阅读 [贡献指南](CONTRIBUTING.md) 获取有关：
- 配置开发环境
- 代码风格指南
- 拉取请求流程
- 错误报告和功能请求
---
## 📄 许可证
该项目在 **MIT 许可证** 下获得许可 — 请参阅 [LICENSE](LICENSE) 文件获取详细信息。
---
<div align="center">
**[⬆ 返回顶部](#-智能数学求解器)**
<br />
由 ❤️ 为学习数学的学生打造。
<br />
<a href="https://advanced-math-ai.vercel.app">
<img src="https://img.shields.io/badge/试用在线演示-000?style=for-the-badge&logo=vercel&logoColor=white" alt="试用在线演示" />
</a>
</div>
