Python 接入 OCR：把图片文字整理成可校验的 JSON 字段

标签建议：Python、OCR、API、文档处理

OCR 接口返回文字后，项目才刚走完一半。真正进入数据库之前，还要解决文本为空、字段缺失、类型错误和结果不可追踪的问题。本文给出一个 Python 标准库方案：先调用 OCR 文字识别 API 恢复文本，再按 JSON Schema 抽取业务字段。

1. 准备环境变量

不要把 AppKey 写进代码或提交到仓库：

export GUGUDATA_APPKEY='your-app-key'

2. 调用 OCR 接口

OCR 请求使用表单编码，图片 URL 放在 imageurl 字段中：

import json
import os
from urllib.parse import urlencode
from urllib.request import Request, urlopen


def recognize_image(image_url: str) -> list[str]:
    app_key = os.environ["GUGUDATA_APPKEY"]
    url = (
        "https://api.gugudata.com/imagerecognition/ocr"
        f"?{urlencode({'appkey': app_key})}"
    )
    body = urlencode({"imageurl": image_url}).encode("utf-8")
    request = Request(
        url,
        data=body,
        headers={"Content-Type": "application/x-www-form-urlencoded"},
        method="POST",
    )

    with urlopen(request, timeout=30) as response:
        payload = json.load(response)

    status = payload.get("DataStatus", {})
    if int(status.get("StatusCode", 0)) != 100:
        raise RuntimeError(status.get("StatusDescription", "OCR failed"))

    lines = payload.get("Data", {}).get("ResultText", [])
    if not lines:
        raise ValueError("OCR returned no text lines")
    return lines

这里有一个容易忽略的点：HTTP 200 不等于识别成功。还要检查 DataStatus.StatusCode，并验证 ResultText 不是空数组。

3. 规范化文本

OCR 返回的是文本行数组。进入字段抽取前，可以做最小化规范化，但不要随意删除标点或合并所有空格，否则可能破坏金额、编号和表格语义。

def normalize_lines(lines: list[str]) -> str:
    normalized = [line.strip() for line in lines if line.strip()]
    return "\n".join(normalized)

4. 用 Schema 约束字段

例如从采购截图中提取项目名称、项目编号和预算金额：

{
  "type": "object",
  "properties": {
    "projectName": {"type": "string"},
    "projectCode": {"type": "string"},
    "budgetAmount": {"type": "number"}
  },
  "required": ["projectName", "projectCode"]
}

规范化文本可以继续提交给 文档字段抽取 API。这样 OCR 负责“读字”，Schema 负责“交付结构”，两层失败也能分别记录。

5. 把失败分开处理

生产代码至少要区分：

• 网络超时或非 2xx：有限次数重试，并采用退避策略；
• 业务状态不为 100：记录状态描述，进入失败队列；
• 文本为空或字段缺失：进入人工复核；
• 金额、日期等类型不合法：阻止写入正式表。

如果输入是 PDF，不要先截图再逐页 OCR。可以直接使用 PDF 转文本 API 恢复连续文本，再复用相同的 Schema 抽取和校验步骤。

关键不是把三个接口简单串起来，而是让每一步都有明确输入、输出、状态和可重放证据。