tencentcloud-ocr-extractdocagent（腾讯云 ocr 提取 docagent）

腾讯云实时文档抽取Agent (ExtractDocAgent)

用途

调用腾讯云OCR实时文档抽取Agent接口，支持从图片/PDF中按用户自定义的字段名称进行结构化信息抽取。模型参数更小，速度更快，适用于对实时性要求高（30秒以内）且输入输出Token在2000以内的场景。

核心能力：

• 自定义字段抽取：支持用户自定义需要抽取的字段名称
• KV对抽取：支持键值对形式的信息抽取（KeyType=0）
• 表格字段抽取：支持表格形式的信息抽取（KeyType=1）
• 字段提示词：支持为每个字段提供描述/提示词，提升抽取准确性
• PDF支持：支持PDF文件的单页文档抽取
• 多格式输入：支持PNG、JPG、JPEG、BMP、PDF格式

官方文档：https://cloud.tencent.com/document/api/866/126442

使用时机

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

• 需要从文档图片/PDF中抽取指定字段的结构化信息
• 需要从合同、发票、报告等文档中提取特定内容
• 需要按自定义字段名进行文档信息提取
• 涉及文档结构化抽取的任何场景
• 需要同时抽取KV对和表格形式的信息

环境要求

• Python 3.6+
• 依赖：tencentcloud-sdk-python（通过 pip install tencentcloud-sdk-python 安装）
• 环境变量：

- TENCENTCLOUD_SECRET_ID：腾讯云API密钥ID - TENCENTCLOUD_SECRET_KEY：腾讯云API密钥Key

使用方式

运行 scripts/main.py 脚本完成文档结构化信息抽取。

请求参数

ItemNames 结构：

输出格式

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

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

{
  "抽取结果": [
    {
      "组序号": 1,
      "字段列表": [
        {
          "字段名(自动识别)": "合同编号",
          "字段名(配置)": "合同编号",
          "字段值": "HT-2024-001"
        }
      ]
    }
  ],
  "旋转角度": 0.0,
  "RequestId": "xxx"
}

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

{
  "Angle": 0.0,
  "StructuralList": [
    {
      "Groups": [
        {
          "Lines": [
            {
              "Key": {
                "AutoName": "合同编号",
                "ConfigName": "合同编号"
              },
              "Value": {
                "AutoContent": "HT-2024-001",
                "Coord": { ... },
                "PageIndex": "0"
              }
            }
          ]
        }
      ]
    }
  ],
  "ErrorCode": "",
  "ErrorMessage": "",
  "RequestId": "xxx"
}

响应数据结构说明

GroupInfo 结构：

LineInfo 结构：

ItemInfo 结构：

Key 结构：

Value 结构：

错误码说明

重要业务逻辑

1. ImageBase64和ImageUrl必须提供其一，都提供时只使用ImageUrl
2. 图片/PDF编码后不超过10M，分辨率建议600*800以上，像素需介于20-10000px
3. 支持格式：PNG、JPG、JPEG、BMP、PDF
4. ItemNames不能为空，KeyName不能为空
5. KeyType仅支持0(KV对)和1(表格字段)两种类型
6. KV类型和表格类型分别有数量上限
7. KeyName和KeyPrompt有长度限制
8. PdfPageNumber>=1，仅支持PDF单页识别
9. 计费策略：固定价格，不限抽取字段数；自适应价格下抽取字段>10个记两次费用，≤10个记一次费用
10. 默认接口请求频率限制：20次/秒
11. 建议图片存储于腾讯云COS以获得更高的下载速度和稳定性
12. 响应中ErrorCode非空时表示业务处理失败，需检查ErrorMessage获取错误详情

调用示例

# 通过URL抽取文档中的KV字段
python scripts/main.py --image-url "https://example.com/contract.jpg" \
  --item-names '[{"KeyName":"合同编号","KeyType":0,"KeyPrompt":"文档中的合同编号"}]'

# 同时抽取KV字段和表格字段
python scripts/main.py --image-url "https://example.com/invoice.jpg" \
  --item-names '[{"KeyName":"发票号码","KeyType":0},{"KeyName":"明细","KeyType":1,"KeyPrompt":"明细条目表格"}]'

# 通过文件路径(自动Base64编码)抽取
python scripts/main.py --image-base64 ./document.png \
  --item-names '[{"KeyName":"姓名","KeyType":0},{"KeyName":"金额","KeyType":0}]'

# 识别PDF中的文档(指定页码)
python scripts/main.py --image-base64 ./document.pdf --pdf-page-number 2 \
  --item-names '[{"KeyName":"总金额","KeyType":0}]'

# 输出原始JSON响应
python scripts/main.py --image-url "https://example.com/doc.jpg" \
  --item-names '[{"KeyName":"标题","KeyType":0}]' --raw

# 指定地域
python scripts/main.py --image-url "https://example.com/doc.jpg" \
  --item-names '[{"KeyName":"签署日期","KeyType":0}]' --region ap-beijing```