Umi-OCR Docker 部署与 API 接口调用指南

Umi-OCR 是一款免费、开源、可批量的离线 OCR 软件，支持截屏识别、批量导入图片、PDF 文档识别、排除水印/页眉页脚、扫描/生成二维码等功能。其 Docker 部署方案使得在 Linux 服务器或桌面环境下运行和集成变得非常便捷。本文带你完成从环境检查到 API 对接的全流程。

一、Umi-OCR 简介

Umi-OCR 的核心优势在于：

完全离线：识别过程不依赖网络，数据不出本地，隐私安全有保障；
免费开源：基于 PaddleOCR 引擎，支持中英文及多语言识别；
批量高效：支持文件夹批量识别、忽略区域（排除水印）、图片对比、表格识别等；
接口友好：提供 HTTP API，可轻松集成到自己的业务系统中。

二、部署前提

在开始部署前，请确保你的主机 CPU 支持 AVX 指令集，这是运行 Umi-OCR Linux 版本的必要条件：

lscpu | grep avx

如果命令输出中包含 avx 和 avx2，则可以继续部署。若输出为空，说明 CPU 不支持 AVX，需要更换宿主机或使用支持 AVX 的 CPU 型号。

三、Docker 部署步骤

1. 拉取镜像

docker pull umi-ocr/umi-ocr:latest

2. 启动容器

docker run -d \
  --name umi-ocr \
  -p 9000:9000 \
  -v $(pwd)/data:/root/OCRmyPDF \
  --restart=always \
  umi-ocr/umi-ocr:latest

-p 9000:9000：将容器的 9000 端口映射到宿主机，用于访问 Web 界面与 API；
-v $(pwd)/data:/root/OCRmyPDF：持久化输出文件目录；
--restart=always：容器异常退出后自动重启。

3. 验证服务

curl http://localhost:9000/health
# 输出 {"status":"ok"} 即表示服务正常

浏览器访问 http://localhost:9000 可以看到 Web 操作界面，支持直接上传图片进行识别。

四、API 接口调用

Umi-OCR 提供了基于 HTTP 的 JSON API，方便其他系统集成。以下以最常见的单张图片识别为例：

curl -X POST http://localhost:9000/api/ocr \
  -H "Content-Type: application/json" \
  -d '{
    "base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB...",
    "options": {
      "lang": "ch",
      "use_doc_orientation_classify": false,
      "use_doc_unwarping": false
    }
  }'

响应结果示例：

{
  "code": 200,
  "data": {
    "texts": [
      {
        "text": "记录生活点滴，分享技术心得",
        "box": [[12, 34], [412, 34], [412, 78], [12, 78]]
      }
    ],
    "full_text": "记录生活点滴，分享技术心得"
  },
  "msg": "success"
}

常用参数说明

参数	类型	说明
`base64`	string	图片的 Base64 编码（不含 data 前缀）
`lang`	string	识别语言：ch / en / japan / korean 等
`use_doc_unwarping`	bool	是否启用文档矫正（拍摄倾斜场景）
`text_type`	string	普通文本 / 表格 / 数学公式等

五、批量识别与 PDF 处理

Umi-OCR 还支持批量识别：将多张图片的 Base64 放入数组，一次请求即可全部处理：

curl -X POST http://localhost:9000/api/batch-ocr \
  -H "Content-Type: application/json" \
  -d '{
    "images": ["base64_1", "base64_2", "base64_3"],
    "options": {"lang": "ch"}
  }'

对于 PDF 文档，可以直接将 PDF 文件传入，识别引擎会自动逐页处理并返回每页的文本结果，非常适合发票、合同、扫描件的批量归档场景。

六、常见问题

问题	排查建议
容器启动即退出	检查 CPU 是否支持 AVX，查看日志 `docker logs umi-ocr`
识别速度慢	确认是否使用了 GPU 镜像；CPU 模式下可调低图片分辨率
端口冲突	更换宿主端口映射，如 `-p 9100:9000`
中文识别不准	确保 `lang` 设置为 `ch`，并升级模型文件

七、总结

Umi-OCR 的 Docker 部署方式让 OCR 能力变得即插即用：一条 docker run 命令即可获得一个完全离线的识别服务，再通过 HTTP API 就能接入任意业务系统。对于有文档数字化、票据识别、内容审核需求的团队来说，是非常实用的自建方案。