跳到主要内容

OCR 文档识别 ​

Agents-Flex OCR 为图片、PDF 等文档解析场景提供统一接口。目前支持百度智能云 PaddleOCR-VL、Gitee AI 模力方舟、MinerU 和 SoMark。公共模型位于 agents-flex-core,每个供应商使用独立 Maven 模块。

适合解决什么问题 ​

OCR 模块适合把扫描件、合同、报告、表格等非结构化文件转换为文本、Markdown 或结构化结果资源。公共接口屏蔽了供应商在提交协议、任务状态和结果字段上的差异,业务代码可以用相同方式提交和查询任务。

框架负责统一调用模型,但不负责文件长期存储、结果 URL 转存、业务审核和供应商费用控制。这些能力应由应用层补充。

模块结构 ​

text
agents-flex-core
└── com.agentsflex.core.model.ocr
    ├── OcrModel
    ├── OcrRequest
    ├── OcrResponse
    ├── OcrDocument
    ├── OcrPage
    ├── OcrBlock
    ├── OcrBoundingBox
    ├── OcrResource
    └── OcrTaskStatus

agents-flex-ocr
├── agents-flex-ocr-baidu
├── agents-flex-ocr-gitee
├── agents-flex-ocr-mineru
└── agents-flex-ocr-somark

统一调用模型 ​

所有供应商都实现 OcrModel,包含三个主要入口:

java
// 只提交任务,立即返回任务编号和当前状态
OcrResponse submitted = model.recognize(request);

// 使用供应商任务编号查询一次,不循环、不休眠
OcrResponse latest = model.getResult(submitted.getTaskId());

// 提交并在当前线程轮询至终态或超时
OcrResponse result = model.recognizeAndWait(request, 10 * 60_000L, 3_000L);

recognizeAndWait() 适合命令行工具、测试和少量短任务。Web 服务或大量长任务应保存任务编号,通过 异步任务模块 在后台查询,避免长期占用请求线程。

如何选择调用方式 ​

场景推荐方式原因
本地工具、集成测试recognizeAndWait()代码简单,可以接受阻塞线程
少量任务,应用自行调度recognize() + getResult()可以自己控制查询时间
Web 服务、长任务、需要跨重启恢复Async Task持久化状态、自动查询、重试和多 Worker 协调

recognizeAndWait() 超时只代表本地停止等待。只要响应仍有 taskId,就可以继续查询同一个远端任务。

输入类型 ​

OcrRequest 支持远程 URL 和本地文件,一次请求只能选择一种:

java
OcrRequest urlRequest = OcrRequest.ofUrl("https://example.com/report.pdf");
OcrRequest fileRequest = OcrRequest.ofFile(new File("report.pdf"));

还可以覆盖模型或透传供应商参数:

java
OcrRequest request = OcrRequest.ofFile(new File("report.pdf"));
request.setModel("provider-model-name");
request.putOption("language", "ch");

供应商对文件格式、大小、页数和远程 URL 的限制不同。框架只统一对象模型,不会绕过供应商限制。

统一响应 ​

字段说明
taskId供应商任务编号,可用于继续查询
status统一任务状态
text纯文本识别结果,供应商提供时可用
markdownMarkdown 识别结果,供应商提供时可用
document标准化的页面、内容块、页面尺寸及空间坐标
resourcesMarkdown、JSON、ZIP 等结果资源
errorCode / errorMessage标准化错误信息
metadata(元数据)尚未标准化的供应商原始字段

常见状态:

状态含义
SUBMITTED已接受,等待执行或等待首次查询
RUNNING供应商正在处理
SUCCEEDED已成功,可读取文本或资源
FAILED供应商明确失败
CANCELED供应商任务已取消
TIMED_OUT本地等待超时,云端任务不一定失败
UNKNOWN无法映射的供应商状态

当状态为 TIMED_OUT 时,响应会保留 taskId,可以继续调用 getResult()。

结构化文档与空间坐标 ​

供应商返回版面 JSON 时,适配器会将其映射到 OcrDocument,同时继续在响应 metadata 中保留原始返回:

java
OcrDocument document = response.getDocument();
if (document != null) {
    for (OcrPage page : document.getPages()) {
        OcrPageSize size = page.getSize();
        for (OcrBlock block : page.getBlocks()) {
            OcrBoundingBox bbox = block.getBoundingBox();
            System.out.println(block.getType() + ": " + block.getContent());
        }
    }
}

OcrPageSize 同时声明页面宽高和 OcrCoordinateUnit;OcrPage.coordinateOrigin 声明原点位置, OcrBoundingBox 固定使用 x1, y1, x2, y2。坐标必须结合所属页面的尺寸、单位、原点和可选旋转角度解释。

内容块使用公共的 OcrBlockType。无法识别的供应商类型会映射为 OTHER,并通过 providerType 保留原始类型名称。页面和块继承 Metadata,尚未进入公共协议的供应商字段可以继续保留, 因此标准化不会替代或丢失原始结果。

供应商对比 ​

供应商Maven 模块本地文件远程 URLpage.sizeblocksbbox
百度智能云agents-flex-ocr-baiduBase64 上传支持支持支持支持
Gitee AIagents-flex-ocr-giteemultipart 上传支持,适配器先下载再上传不支持由返回的 segments 合成不支持
MinerUagents-flex-ocr-mineru预签名 URL 上传支持支持支持支持
SoMarkagents-flex-ocr-somarkmultipart 上传支持,由供应商下载支持支持支持

以上能力已使用各供应商的真实服务响应验证。百度从 parse_result_url 指向的解析 JSON 中读取页面尺寸、 版面块和多边形坐标;MinerU 从结果 ZIP 的 layout.json 中读取页面尺寸、段落块和边界框;SoMark 直接从 结构化页面结果中读取。Gitee 当前真实响应只包含按顺序排列的 segments,没有页边界、页面尺寸或空间 坐标。

选择供应商时,除了模型效果,还应评估文件大小和页数限制、输入方式、结果链接有效期、并发额度及数据合规要求。

结果处理建议 ​

  1. 先检查 status 和 isError(),不要只判断 taskId。
  2. 成功后同时检查 text、markdown 和 resources,不同供应商输出位置不同。
  3. 尽快把临时结果 URL 转存到自己的对象存储。
  4. 保存框架任务 ID、供应商任务 ID 和必要的元数据,便于审计和故障恢复。
  5. 对关键文档增加内容完整性校验或人工审核,不要把 OCR 结果默认视为绝对准确。

内置模型的 getResult() 会统一解析不同的结果位置,并把最终内容写入响应;等待入口通过轮询该方法获得 相同结果:

java
OcrResponse response = model.recognizeAndWait(request);
String markdown = response.getMarkdown();

getResult() 支持内联 Markdown、Markdown 下载资源、ZIP 中的 Markdown,并以纯文本作为最后降级结果。 通过 BaseOcrModel.setDocumentImagePublisher() 可以把结果图片上传到对象存储,并将 Markdown 图片引用替换为 Publisher 返回的 URL。图片可以来自 ZIP、Base64 Data URI 或 HTTP/HTTPS 地址;配置 Publisher 后,远程图片 也会被下载并转存。未配置 Publisher 时保留供应商返回的远程 URL。

下一步 ​