OCR 集成指南

将 OCR 集成到应用程序的实用指南——处理多页 PDF、选择合适的模式和优化识别准确率。

概述

本指南介绍常见的 OCR 集成模式。完整的端点参考请查看 OCR API 参考。

选择合适的模式

使用场景	推荐模式	原因
搜索索引	`simple`	纯文本更易索引，成本更低
内容重新发布	`formatted`	保留表格、标题和结构
数据提取	`formatted`	结构化输出便于解析
快速复制粘贴	`simple`	最快最便宜的选择

处理多页 PDF

每一页作为独立对象在 pages 数组中返回。使用页面级别的 markdown 进行逐页处理：

for page in data["data"]["pages"]:
    print(f"第 {page['pageNumber']} 页：")
    print(page["markdown"])
    print("---")

要获取整个文档的完整 Markdown，使用顶层的 data.markdown 字段。

错误处理

始终先检查 success 再访问 data。使用指数退避处理可重试错误：

import time

def ocr_with_retry(client, payload, max_retries=3):
    for attempt in range(max_retries):
        response = client.post("/api/v1/ocr", json=payload)
        data = response.json()

        if data["success"]:
            return data

        error = data["error"]
        if not error["retryable"]:
            raise Exception(f"不可重试的错误: {error['code']}")

        wait = 2 ** attempt  # 1s, 2s, 4s
        print(f"{wait}s 后重试... ({error['code']})")
        time.sleep(wait)

    raise Exception("超过最大重试次数")

使用幂等键

在生产环境中，始终使用幂等键防止重复扣费：

import uuid

response = requests.post(
    "https://image-to-text.org/api/v1/ocr",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Idempotency-Key": f"ocr-{uuid.uuid4()}",
    },
    json={
        "image_url": "https://example.com/invoice.pdf",
        "mode": "formatted",
    },
)

处理大批量文件

处理多个文件时，请遵守限流规则：

间隔请求 — 每次请求间隔至少 5 秒
跟踪用量 — 对照计划限额监控每日使用量
检查余额 — 提交大批量任务前确认剩余积分
使用幂等键 — 防止意外重复处理

提高准确率的建议

分辨率很重要 — 低于 150 DPI 的图片可能降低准确率
光线充足 — 高对比度的文档效果最佳
文字平直 — 旋转的文字更难检测
背景干净 — 避免文字背后有复杂背景
标准字体 — 手写文字的准确率低于印刷文字