ljwx-study/GEMINI_INTEGRATION.md

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

概述

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

主要特性

🎯 数学专项优化

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

1. 高精度公式识别

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

2. 几何图形理解

   • 详细描述图形类型（三角形、圆、函数图像等）
   • 标注关键点、线段、角度
   • 记录坐标系信息

3. 解题步骤提取

   • 识别推导过程
   • 提取关键公式和定理
   • 记录中间计算结果

4. 知识点精准标注

   • 代数、几何、三角
   • 微积分、概率统计
   • 向量与矩阵

配置方法

1. 环境变量配置

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

# 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
2. 注册并获取 API Key
3. 将 Key 设置到环境变量

使用方法

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

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

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

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

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 的解析效果：

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 数学专项模式会返回更详细的数学信息：

{
  "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

示例：对比测试

# 运行对比测试
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 代码

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 获取可用模型列表

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