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

📅 2026-05-25 18:42:19阅读时间: 11分钟

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

一、Docker 部署 Umi-OCR

1. 部署前提

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

bash 复制代码 
lscpu | grep avx

如果命令输出中包含 avx 和 avx2，则可以继续部署。

2. 构建 Docker 镜像

首先，下载官方提供的 Dockerfile 并构建镜像。

bash 复制代码 
# 1. 下载 Dockerfile
wget https://raw.githubusercontent.com/hiroi-sora/Umi-OCR_runtime_linux/main/Dockerfile

# 2. 构建镜像
docker build -t umi-ocr-paddle .

如果遇到网络问题，可以在构建时设置代理：

bash 复制代码 
docker build -t umi-ocr-paddle . \
  --build-arg HTTP_PROXY=http://X.X.X.X:7897 \
  --build-arg HTTPS_PROXY=http://X.X.X.X:7897

3. 运行容器

Umi-OCR 支持两种运行模式：无头模式（Headless）和 GUI 模式。

无头模式
适合在没有显示器的云服务器或不支持 X 显示协议的系统上运行，主要用于提供 HTTP API 服务。

bash 复制代码 
docker run -d --name umi-ocr \
  -e HEADLESS=true \
  -p 1224:1224 \
  umi-ocr-paddle
  • -e HEADLESS=true：启用无头模式。
  • -p 1224:1224：将容器内的 1224 端口映射到主机的 1224 端口（可根据需要修改主机端口）。

GUI 模式
适合在有显示器的 Xorg 桌面环境下使用，可以使用截屏、文件拖拽导入等图形界面功能。

bash 复制代码 
# 在主机上开放 X 服务权限
xhost +

# 运行容器
docker run -d --name umi-ocr \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  -e DISPLAY=$DISPLAY \
  -v /home:/home \
  -p 1224:1224 \
  umi-ocr-paddle
  • -v /tmp/.X11-unix:/tmp/.X11-unix 和 -e DISPLAY=$DISPLAY：允许容器连接宿主机的显示服务。
  • -v /home:/home：将主机 home 目录挂载到容器内相同路径，以便使用文件拖拽功能。

二、HTTP API 接口调用

Umi-OCR 在运行后会提供 HTTP 服务，默认端口为 1224。您可以通过 RESTful API 进行调用。

1. 图片 OCR 识别接口

接口地址：http://<服务器IP>:1224/api/ocr

请求方法：POST

请求参数（JSON格式）：

参数名 类型 是否必填 描述
base64 string 是 待识别图像的 Base64 编码字符串，无需 data:image/png;base64, 等前缀。
options object 否 配置选项字典。具体可用参数可通过查询接口获取。

请求示例：

json 复制代码 
{
  "base64": "iVBORw0KGgoAAAAN……",
  "options": {
    "ocr.language": "models/config_chinese.txt",
    "ocr.cls": true,
    "ocr.limit_side_len": 4320,
    "tbpu.parser": "multi_none",
    "data.format": "text"
  }
}

响应格式：

json 复制代码 
{
  "code": 100,
  "data": ["识别出的文本行1", "识别出的文本行2"],
  "time": 0.85,
  "timestamp": 1716634200.123
}
  • code: 100 表示成功，101 表示图片中无文本，其他值为失败。
  • data: 识别结果，格式取决于 options 中的 data.format 设置。
  • time: 识别耗时（秒）。
  • timestamp: 任务开始时间戳。

2. 参数查询接口

在调用识别接口前，可以先查询当前可用的配置参数。

接口地址：http://<服务器IP>:1224/api/ocr/get_options

请求方法：GET

响应：返回一个 JSON 对象，包含所有可配置的 options 参数及其可选值。

3. 二维码识别与生成接口

Umi-OCR 同样支持二维码的识别与生成。

二维码识别接口

  • 地址：http://<服务器IP>:1224/api/qrcode
  • 方法：POST
  • 参数：与图片 OCR 接口类似，需传入图片的 base64 字符串。
  • 响应：返回识别出的二维码内容。

二维码生成接口

  • 地址：http://<服务器IP>:1224/api/qrcode (与识别相同，通过参数区分)
  • 方法：POST
  • 参数：需传入 text（要编码的文本）和可选的 options（如码类型、尺寸等）。
  • 响应：返回生成的二维码图片的 Base64 字符串。

三、使用示例（Python）

以下是一个调用图片 OCR 接口的 Python 示例：

python 复制代码 
import json
import requests
import base64

# 1. 查询可用参数
response = requests.get("http://127.0.0.1:1224/api/ocr/get_options")
print("可用参数：", json.dumps(response.json(), indent=4, ensure_ascii=False))

# 2. 准备图片并编码为 Base64
with open("test.png", "rb") as image_file:
    img_base64 = base64.b64encode(image_file.read()).decode('utf-8')

# 3. 调用 OCR 接口
url = "http://127.0.0.1:1224/api/ocr"
payload = {
    "base64": img_base64,
    "options": {
        "data.format": "text"
    }
}
headers = {'Content-Type': 'application/json'}
response = requests.post(url, data=json.dumps(payload), headers=headers)
result = response.json()
print("识别结果：", result)

总结

通过 Docker 部署 Umi-OCR，您可以快速搭建一个离线、高效的 OCR 服务。无头模式非常适合集成到自动化流程或后端服务中，而 GUI 模式则便于在桌面环境进行交互式操作。其提供的 HTTP API 接口规范且功能全面，便于开发者进行二次开发和集成。

返回文章列表