TencentCloud QuestionMark OCR

腾讯云试题批改Agent (SubmitQuestionMarkAgentJob / DescribeQuestionMarkAgentJob)

用途

调用腾讯云OCR试题批改Agent接口，面向K12教育场景的试题批改产品，支持整卷/单题端到端处理（试卷切题+题目批改+手写坐标回显），聚焦试题批改（含手写答案）和试题解析（不含手写答案）。精准输出题目、正误判定、答案对比、错误分析及知识点等结构化评估结果。低年级算式批改效果优于线上数学作业批改。

核心能力：

• 异步双接口模式：Submit 提交任务获取 JobId → Describe 轮询查询结果（DONE/FAIL 时完成）
• 整卷批改：自动切题后逐题批改，返回每道题目的批改信息
• 单题批改：跳过切题环节，直接对单题进行批改，支持传入参考答案
• 深度思考：可选开启深度思考模式，进行更深层次推理分析（速度更慢）
• 知识点输出：可配置输出题目关联的知识点信息
• 正确答案输出：可配置输出题目的正确答案
• 手写答案坐标：可配置输出手写答案在原图中的坐标位置
• 多格式输入：支持 PNG、JPG、JPEG、BMP、GIF、WEBP、HEIC、TIFF、HEIF 及 PDF 格式

官方文档：

• 提交任务：https://cloud.tencent.com/document/api/866/128273
• 查询任务：https://cloud.tencent.com/document/api/866/128274

使用时机

当用户提出以下需求时触发此技能：

• 需要对试卷图片/PDF进行自动批改
• 需要识别手写答案并判断正误
• 需要对K12试题进行批改分析
• 需要获取试题的知识点信息
• 需要获取试题的正确答案
• 需要对单道题目进行批改（含参考答案）
• 涉及试卷切题、试题解析的任何场景

环境要求

• Python 3.6+
• 依赖：tencentcloud-sdk-python（通过 pip install tencentcloud-sdk-python 安装）
• 环境变量：
  • TENCENTCLOUD_SECRET_ID：腾讯云API密钥ID
  • TENCENTCLOUD_SECRET_KEY：腾讯云API密钥Key

使用方式

运行 scripts/main.py 脚本完成试题批改。该接口为异步接口，脚本会自动提交任务并轮询查询结果。

请求参数

提交任务 (SubmitQuestionMarkAgentJob) 参数

查询任务 (DescribeQuestionMarkAgentJob) 参数

输出格式

识别成功后返回 JSON 格式结果：

格式化输出模式（默认）：

{
  "任务ID": "1410885500986064896",
  "任务状态": "DONE",
  "切题数量": "2",
  "旋转角度": 0.0,
  "批改结果": [
    {
      "题号": 1,
      "题干": "1. 小琪在做作业时发现有一道题的一部分被墨水遮住了...",
      "子题": [
        {
          "题号": "1-1",
          "题干": "(1)小琪猜测,墨水遮住的内容是"2a",请你根据小琪的猜测完成计算;",
          "答案列表": [
            {
              "手写答案": "\\frac{2}{a-1}...",
              "是否正确": false,
              "答案分析": "首先将除法转化为乘法，对分子分母因式分解后约分...",
              "正确答案": "...",
              "知识点": ["分式运算", "因式分解"],
              "答案坐标": [113, 648, 558, 648, 558, 698, 113, 698]
            }
          ]
        }
      ]
    }
  ],
  "RequestId": "xxx"
}

原始输出模式（--raw）：

{
  "JobId": "1410885500986064896",
  "JobStatus": "DONE",
  "ErrorCode": "",
  "ErrorMessage": "",
  "Angle": 0.0,
  "MarkInfos": [
    {
      "MarkItemTitle": "1. 小琪在做作业时...",
      "AnswerInfos": [],
      "MarkInfos": [
        {
          "MarkItemTitle": "(1)小琪猜测...",
          "AnswerInfos": [
            {
              "HandwriteInfo": "\\frac{2}{a-1}...",
              "IsCorrect": false,
              "AnswerAnalysis": "首先将除法转化为乘法...",
              "RightAnswer": "",
              "KnowledgePoints": [],
              "HandwriteInfoPositions": [113, 648, 558, 648, 558, 698, 113, 698]
            }
          ],
          "MarkInfos": []
        }
      ]
    }
  ],
  "RequestId": "xxx"
}

响应数据结构说明

SubmitQuestionMarkAgentJob 响应

DescribeQuestionMarkAgentJob 响应

MarkInfo 结构（嵌套递归）：

AnswerInfo 结构：

QuestionInfo 结构：

错误码说明

重要业务逻辑

1. 异步双接口模式：Submit 提交任务 → Describe 轮询，JobStatus 为 DONE/FAIL 时完成
2. Submit 计费，Describe 不计费
3. ImageBase64 和 ImageUrl 必须提供其一，都提供时只使用 ImageUrl
4. 支持格式：PNG/JPG/JPEG/BMP/GIF/WEBP/HEIC/TIFF/HEIF 及 PDF
5. PdfPageNumber 必须为正整数，仅支持单页识别
6. BoolSingleQuestion=true 时跳过切题，直接单题批改
7. QuestionConfigMap 示例：{"KnowledgePoints":true,"TrueAnswer":true,"ReturnAnswerPosition":false}
8. ReferenceAnswer 仅单题时有效，多题时不生效
9. JobId 长度不超过32字符
10. 默认接口请求并发限制：10题/分钟
11. 建议图片存储于腾讯云COS以获得更高的下载速度和稳定性
12. MarkInfo 为递归嵌套结构，可能存在多层子题

调用示例

# 通过URL进行整卷批改（输出知识点和正确答案）
python scripts/main.py --image-url "https://example.com/exam_paper.jpg" \
  --question-config '{"KnowledgePoints":true,"TrueAnswer":true}'

# 通过URL进行单题批改（带参考答案）
python scripts/main.py --image-url "https://example.com/single_question.jpg" \
  --single-question --reference-answer "x=2"

# 开启深度思考模式
python scripts/main.py --image-url "https://example.com/exam.jpg" --enable-deep-think

# 通过文件路径进行批改（自动Base64编码）
python scripts/main.py --image-base64 ./exam_paper.png

# 批改PDF试卷（指定页码）
python scripts/main.py --image-base64 ./exam.pdf --pdf-page-number 2

# 输出原始JSON响应
python scripts/main.py --image-url "https://example.com/exam.jpg" --raw

# 指定地域和自定义轮询参数
python scripts/main.py --image-url "https://example.com/exam.jpg" \
  --region ap-beijing --poll-interval 3 --poll-timeout 300```