腾讯云试题批改Agent (SubmitQuestionMarkAgentJob / DescribeQuestionMarkAgentJob)
用途
调用腾讯云OCR试题批改Agent接口，面向K12教育场景的试题批改产品，支持整卷/单题端到端处理（试卷切题+题目批改+手写坐标回显），聚焦试题批改（含手写答案）和试题解析（不含手写答案）。精准输出题目、正误判定、答案对比、错误分析及知识点等结构化评估结果。低年级算式批改效果优于线上数学作业批改。
核心能力：
- 异步双接口模式：Submit 提交任务获取 JobId → Describe 轮询查询结果（DONE/FAIL 时完成）
- 整卷批改：自动切题后逐题批改，返回每道题目的批改信息
- 单题批改：跳过切题环节，直接对单题进行批改，支持传入参考答案
- 深度思考：可选开启深度思考模式，进行更深层次推理分析（速度更慢）
- 知识点输出：可配置输出题目关联的知识点信息
- 正确答案输出：可配置输出题目的正确答案
- 手写答案坐标：可配置输出手写答案在原图中的坐标位置
- 多格式输入：支持 PNG、JPG、JPEG、BMP、GIF、WEBP、HEIC、TIFF、HEIF 及 PDF 格式
官方文档：
使用时机
当用户提出以下需求时触发此技能：
- 需要对试卷图片/PDF进行自动批改
- 需要识别手写答案并判断正误
- 需要对K12试题进行批改分析
- 需要获取试题的知识点信息
- 需要获取试题的正确答案
- 需要对单道题目进行批改（含参考答案）
- 涉及试卷切题、试题解析的任何场景
环境要求
- Python 3.6+
- 依赖：
tencentcloud-sdk-python（通过 pip install tencentcloud-sdk-python 安装）
- 环境变量：
TENCENTCLOUD_SECRET_ID：腾讯云API密钥IDTENCENTCLOUD_SECRET_KEY：腾讯云API密钥Key
使用方式
运行 scripts/main.py 脚本完成试题批改。该接口为异步接口，脚本会自动提交任务并轮询查询结果。
请求参数
提交任务 (SubmitQuestionMarkAgentJob) 参数
| 参数 | 类型 | 必填 | 说明 |
|---|
| ImageBase64 | str | 否(二选一) | 图片/PDF的Base64值，编码后不超过10M，分辨率建议600*800以上，支持PNG/JPG/JPEG/BMP/PDF格式 |
| ImageUrl | str | 否(二选一) | 图片/PDF的URL地址，下载时间不超过3秒。都提供时只使用ImageUrl。建议存储于腾讯云 |
| PdfPageNumber | int | 否 | PDF页码，仅支持单页识别，默认1 |
| BoolSingleQuestion | bool | 否 | 是否单题批改（跳过切题），默认false |
| EnableDeepThink | bool | 否 | 是否开启深度思考（更深层推理，速度更慢），默认false |
| QuestionConfigMap | str | 否 | 题目信息输出配置（JSON字符串），可选key：KnowledgePoints(输出知识点)/TrueAnswer(输出正确答案)/ReturnAnswerPosition(输出手写答案坐标) |
| ReferenceAnswer | str | 否 | 单题批改时的参考答案，仅单题时有效，多题时不生效 |
查询任务 (DescribeQuestionMarkAgentJob) 参数
| 参数 | 类型 | 必填 | 说明 |
|---|
| JobId | str | 是 | 任务唯一ID，由Submit接口返回，长度不超过32字符 |
| UserAgent | str | 否 | 请求来源标识(可选)，用于追踪调用来源，统一固定为Skills |
输出格式
识别成功后返回 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 响应
| 参数 | 类型 | 说明 |
|---|
| JobId | str | 任务唯一ID，用于查询结果 |
| QuestionInfo | list of QuestionInfo | 切题题目边框坐标列表（BoolSingleQuestion=true时为空） |
| QuestionCount | str | 切题数量，作为计费题目数总量 |
| RequestId | str | 唯一请求ID |
DescribeQuestionMarkAgentJob 响应
| 参数 | 类型 | 说明 |
|---|
| JobStatus | str | 任务状态：WAIT(等待中)/RUN(执行中)/FAIL(失败)/DONE(成功) |
| ErrorCode | str | 任务执行错误码（非FAIL时为空） |
| ErrorMessage | str | 任务执行错误信息（非FAIL时为空） |
| Angle | float | 图片旋转角度（角度制），水平方向为0，顺时针为正 |
| MarkInfos | list of MarkInfo | 试题批改信息 |
| RequestId | str | 唯一请求ID |
MarkInfo 结构（嵌套递归）：
| 字段 | 类型 | 说明 |
|---|
| MarkItemTitle | str | 题目的题干信息 |
| AnswerInfos | list of AnswerInfo | 批改答案列表（按从左到右、从上到下排列） |
| MarkInfos | list of MarkInfo | 嵌套子题信息（无子题则为空） |
AnswerInfo 结构：
| 字段 | 类型 | 说明 |
|---|
| HandwriteInfo | str | 手写答案内容（如选择题的手写选项、填空题的手写内容） |
| IsCorrect | bool | 答案是否正确 |
| AnswerAnalysis | str | 答案分析结果 |
| HandwriteInfoPositions | list of int | 答案区域4角点坐标（长度8数组：左上/右上/右下/左下），需配置ReturnAnswerPosition。可能返回null |
| RightAnswer | str | 正确答案内容，需配置 QuestionConfigMap 的 TrueAnswer 为 true |
| KnowledgePoints | list of str | 知识点内容，需配置 QuestionConfigMap 的 KnowledgePoints 为 true。可能返回null |
QuestionInfo 结构：
| 字段 | 类型 | 说明 |
|---|
| Angle | float | 旋转角度 |
| Height | int | 预处理后图片高度 |
| Width | int | 预处理后图片宽度 |
| ResultList | list of ResultList | 文档元素（可能返回null） |
| OrgHeight | int | 输入图片高度 |
| OrgWidth | int | 输入图片宽度 |
| ImageBase64 | str | 预处理后的图片base64编码 |
错误码说明
| 错误码 | 含义 |
|---|
| FailedOperation.DownLoadError | 文件下载失败 |
| FailedOperation.ImageDecodeFailed | 图片解码失败 |
| FailedOperation.ImageSizeTooLarge | 图片尺寸过大，请确保编码后不超过10M |
| FailedOperation.OcrFailed | OCR识别失败 |
| FailedOperation.PDFParseFailed | PDF解析失败 |
| FailedOperation.UnKnowError | 未知错误 |
| FailedOperation.UnKnowFileTypeError | 未知的文件类型 |
| FailedOperation.UnOpenError | 服务未开通，请先在腾讯云控制台开通试题批改Agent服务 |
| InvalidParameterValue.InvalidParameterValueLimit | 参数值错误 |
| LimitExceeded.TooLargeFileError | 文件内容太大 |
| ResourceUnavailable.InArrears | 账号已欠费 |
| ResourceUnavailable.ResourcePackageRunOut | 账号资源包耗尽 |
| ResourcesSoldOut.ChargeStatusException | 计费状态异常 |
重要业务逻辑
- 异步双接口模式：Submit 提交任务 → Describe 轮询，JobStatus 为 DONE/FAIL 时完成
- Submit 计费，Describe 不计费
- ImageBase64 和 ImageUrl 必须提供其一，都提供时只使用 ImageUrl
- 支持格式：PNG/JPG/JPEG/BMP/GIF/WEBP/HEIC/TIFF/HEIF 及 PDF
- PdfPageNumber 必须为正整数，仅支持单页识别
- BoolSingleQuestion=true 时跳过切题，直接单题批改
- QuestionConfigMap 示例：
{"KnowledgePoints":true,"TrueAnswer":true,"ReturnAnswerPosition":false}
- ReferenceAnswer 仅单题时有效，多题时不生效
- JobId 长度不超过32字符
- 默认接口请求并发限制：10题/分钟
- 建议图片存储于腾讯云COS以获得更高的下载速度和稳定性
- 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```
