# Gemini 3 Pro 数学试卷解析集成指南

## 概述

本项目已集成 Google Gemini 3 Pro 模型，专门优化数学试卷的解析能力。Gemini 3 Pro 在数学公式识别、几何图形理解和复杂推导方面表现优异。

## 主要特性

### 🎯 数学专项优化

当使用 Gemini 模型解析数学试卷时，系统会自动启用以下优化：

1. **高精度公式识别**
   - 自动将所有数学表达式转换为 LaTeX 格式
   - 支持复杂公式：分数、根式、极限、求和、积分、矩阵等
   - 准确识别数学符号：不等式、集合、逻辑符号等

2. **几何图形理解**
   - 详细描述图形类型（三角形、圆、函数图像等）
   - 标注关键点、线段、角度
   - 记录坐标系信息

3. **解题步骤提取**
   - 识别推导过程
   - 提取关键公式和定理
   - 记录中间计算结果

4. **知识点精准标注**
   - 代数、几何、三角
   - 微积分、概率统计
   - 向量与矩阵

## 配置方法

### 1. 环境变量配置

编辑 `backend/.env` 文件（如果没有则复制 `.env.example`）：

```bash
# OpenRouter API Key
OPENROUTER_API_KEY=your-api-key-here

# 选择模型
AI_MODEL=google/gemini-3-pro-preview  # 使用 Gemini
# AI_MODEL=anthropic/claude-sonnet-4.5  # 或使用 Claude（默认）

# 启用 AI 解析器
USE_CLAUDE_PARSER=true
```

### 2. 获取 API Key

1. 访问 [OpenRouter](https://openrouter.ai/keys)
2. 注册并获取 API Key
3. 将 Key 设置到环境变量

## 使用方法

### 方式一：通过环境变量全局启用

设置 `AI_MODEL=google/gemini-3-pro-preview` 后，所有试卷解析都会使用 Gemini 模型。

```bash
# 在 .env 文件中设置
AI_MODEL=google/gemini-3-pro-preview
```

### 方式二：在代码中指定模型

```python
from claude_exam_parser import ClaudeExamParser

# 使用 Gemini 模型
parser = ClaudeExamParser(model="google/gemini-3-pro-preview")
result = parser.parse_exam_file("math_exam.pdf", subject="数学", grade="高一")

if result["success"]:
    parsed_data = result["result"]
    print(f"识别到 {parsed_data['total_questions']} 道题目")
    print(f"学科: {parsed_data['subject']}")
```

### 方式三：使用测试脚本对比

我们提供了专门的测试脚本来对比 Claude 和 Gemini 的解析效果：

```bash
cd backend

# 对比两个模型的解析效果
python test_gemini_math.py math_exam.pdf 数学 高一

# 只测试单个文件
python test_gemini_math.py physics_test.pdf 物理
```

测试脚本会：
- 同时使用 Claude 和 Gemini 解析同一份试卷
- 对比解析速度、题目数量、公式识别数量
- 生成详细的对比报告
- 保存解析结果到 `test_results/` 目录

## 支持的模型

| 模型 | 适用场景 | 特点 |
|------|---------|------|
| `google/gemini-3-pro-preview` | 数学、物理试卷 | 数学能力强，公式识别准确 |
| `anthropic/claude-sonnet-4.5` | 通用试卷 | 通用能力强，上下文理解好 |
| `openai/gpt-4o` | 通用试卷 | 速度快，综合能力强 |
| `openai/gpt-4-turbo` | 通用试卷 | 性价比高 |

## 解析结果格式

Gemini 数学专项模式会返回更详细的数学信息：

```json
{
  "subject": "数学",
  "grade": "高一",
  "exam_type": "期中考试",
  "total_questions": 20,
  "total_score": 150,
  "questions": [
    {
      "number": 1,
      "type": "choice",
      "question": "已知函数 $f(x) = x^2 - 3x + 2$，求 $f(0)$ 的值",
      "options": [
        "A. $0$",
        "B. $1$",
        "C. $2$",
        "D. $3$"
      ],
      "answer": "C",
      "difficulty": 2,
      "score": 5,
      "knowledge_points": ["二次函数", "函数求值"],
      "formulas": [
        "$f(x) = x^2 - 3x + 2$",
        "$f(0) = 0^2 - 3 \\times 0 + 2 = 2$"
      ],
      "has_image": false,
      "page": 1
    }
  ],
  "stats": {
    "choice_count": 10,
    "fill_blank_count": 5,
    "calculation_count": 3,
    "essay_count": 2,
    "difficulty_distribution": {
      "1": 2,
      "2": 5,
      "3": 8,
      "4": 4,
      "5": 1
    }
  }
}
```

## 性能对比

基于我们的测试（数学试卷）：

| 指标 | Claude Sonnet 4.5 | Gemini 3 Pro |
|------|-------------------|--------------|
| 公式识别准确率 | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| 几何图形理解 | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| 解题步骤提取 | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| 通用理解能力 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| 速度 | 快 | 中等 |

**推荐：**
- **数学/物理试卷**：使用 Gemini 3 Pro
- **其他学科试卷**：使用 Claude Sonnet 4.5

## 示例：对比测试

```bash
# 运行对比测试
cd backend
python test_gemini_math.py sample_math_exam.pdf 数学 高一
```

输出示例：
```
================================================================================
对比报告
================================================================================

对比结果:
[
  {
    "模型": "anthropic/claude-sonnet-4.5",
    "耗时(秒)": "12.45",
    "题目数": 20,
    "公式数": 35,
    "含公式题目": "18/20",
    "选择题": 10,
    "填空题": 5,
    "计算题": 3,
    "解答题": 2
  },
  {
    "模型": "google/gemini-3-pro-preview",
    "耗时(秒)": "15.23",
    "题目数": 20,
    "公式数": 42,
    "含公式题目": "20/20",
    "选择题": 10,
    "填空题": 5,
    "计算题": 3,
    "解答题": 2
  }
]

💾 详细结果已保存到: test_results/
```

## API 调用示例

### Python 代码

```python
from claude_exam_parser import ClaudeExamParser

# 初始化解析器（Gemini 模型）
parser = ClaudeExamParser(
    api_key="your-openrouter-api-key",  # 可选，会从环境变量读取
    model="google/gemini-3-pro-preview"
)

# 解析数学试卷
result = parser.parse_exam_file(
    file_path="math_exam.pdf",
    subject="数学",
    grade="高一"
)

if result["success"]:
    # 获取解析数据
    data = result["result"]

    # 打印基本信息
    print(f"学科: {data['subject']}")
    print(f"题目总数: {data['total_questions']}")

    # 遍历题目
    for question in data["questions"]:
        print(f"\n题目 {question['number']}: {question['type']}")
        print(f"  题干: {question['question']}")
        print(f"  难度: {question['difficulty']}")
        print(f"  知识点: {', '.join(question['knowledge_points'])}")

        # 显示公式
        if question.get("formulas"):
            print(f"  公式:")
            for formula in question["formulas"]:
                print(f"    {formula}")
else:
    print(f"解析失败: {result['error']}")
```

## 故障排除

### 1. API Key 错误

```
ValueError: 需要提供 OpenRouter API Key
```

**解决方法：**
- 检查 `.env` 文件中是否设置了 `OPENROUTER_API_KEY`
- 确保 API Key 有效且未过期

### 2. 模型不支持

```
HTTP 400: Model not found
```

**解决方法：**
- 检查模型名称是否正确
- 确认 OpenRouter 账户有权限访问该模型
- 查看 [OpenRouter Models](https://openrouter.ai/models) 获取可用模型列表

### 3. 解析超时

```
Timeout: API 请求超时
```

**解决方法：**
- 试卷页数过多可能导致超时
- 可以拆分试卷或增加超时时间（修改 `claude_exam_parser.py` 中的 `timeout` 参数）

## 费用说明

使用 OpenRouter 的费用取决于模型和使用量：

- **Gemini 3 Pro**: 约 $0.001 - $0.01 / 1K tokens
- **Claude Sonnet 4.5**: 约 $0.003 - $0.015 / 1K tokens

一份标准数学试卷（10-20题）大约消耗 5K-15K tokens，成本约 $0.01 - $0.20。

查看最新价格：https://openrouter.ai/models

## 最佳实践

1. **数学试卷优先使用 Gemini**
   - 公式识别更准确
   - 几何图形理解更好

2. **批量处理时考虑成本**
   - 可以先用免费额度测试
   - 大规模使用前评估费用

3. **保存解析结果**
   - 避免重复解析同一份试卷
   - 使用缓存机制

4. **对比验证**
   - 重要试卷建议用两个模型对比验证
   - 使用测试脚本生成对比报告

## 下一步

- [ ] 添加更多数学专项测试用例
- [ ] 优化 Gemini 的 prompt 以提高准确率
- [ ] 支持物理、化学等其他理科试卷的专项优化
- [ ] 添加结果缓存机制
- [ ] 开发批量处理工具

## 技术支持

如有问题或建议，请：
1. 查看本文档
2. 查看 `backend/CLAUDE_PARSER_README.md`
3. 运行测试脚本验证配置
4. 提交 Issue 或 PR

---

**更新时间**: 2025-11-22
**版本**: 1.0.0