企业官网建设流程全解析

Umi-OCR v2.1.4 及更早版本调用 /api/doc/download 时为什么要用拼写错误的 ingore_blank 参数？

【免费下载链接】Umi-OCROCR software, free and offline. 开源、免费的离线OCR软件。支持截屏/批量导入图片，PDF文档识别，排除水印/页眉页脚，扫描/生成二维码。内置多国语言库。项目地址: https://gitcode.com/GitHub_Trending/um/Umi-OCR

如果你在按 Umi-OCR 的 HTTP 接口手册走文档识别流程，会在第 3 步卡住：调用/api/doc/download生成目标文件（如 txt、双层可搜索 PDF）时，请求体里控制"是否忽略空页"的布尔参数到底该写成ignore_blank还是ingore_blank？两个拼写在仓库文档里同时出现过，看起来像是笔误，但它们对应不同版本的服务端行为。这篇文章说明这个拼写差异的来龙去脉、如何按你所装的 Umi-OCR 版本选择正确的键名，以及如何通过响应判断调用是否成功。

前提：Umi-OCR 已启动并允许 HTTP 服务（默认开启）。按 HTTP接口手册 的说明，全局设置页必须勾选允许 HTTP 服务才能使用 HTTP 接口；示例代码默认访问http://127.0.0.1:1224。另外，api_doc.md 标注v2.1.4及以上的版本才具有文档识别功能，所以这个接口最早只会在 v2.1.4 及之后的版本上出现。

ignore_blank 参数在流程中的作用

文档识别流程共 5 步：查询参数 → 上传文件 → 轮询任务状态 → 生成目标文件并获取下载链接 → 下载并清理。/api/doc/download是第 3 步，方法为POST，json 参数中除任务id、file_types外还有：

• ignore_blank：布尔值。是否忽略空页（没有文字的页数）。
  • true（默认）：如 txt、csv 等文件中，会跳过空页。
  • false：不跳过空页，文件中空页的内容记为空字符串。

也就是说，这个参数控制最终文件里空页是"不出现"还是"以空字符串占位"。如果键名写错而该值又不等于默认值true，你的设置就不会按预期生效——这正是必须分清拼写的原因。

拼写差异的来源：文档与实际代码

三个文档位置共同说明了这件事，且互相一致：

1. api_doc.md 的"第3步：获取结果下载链接"一节列出的是正确拼写ignore_blank，并附有注释：

   注： Umi-OCRv2.1.4及以前的版本，ignore_blank参数存在问题，请使用最新版本。

2. 官方示例代码 api_doc_demo.py 中实际发送的键是错误拼写ingore_blank，并带有注释（原文）：

   # ↓ `ingore_blank` is a typo. If you are using Umi-OCR version 2.1.4 or earlier, please use this incorrect spelling. # ↓ If you are using the latest code-built version of Umi-OCR, please use the corrected spelling `ignore_blank`. "ingore_blank": False, # Do not ignore blank pages

   即：使用 v2.1.4 或更早版本时要用这个错误拼写；使用最新代码构建的版本时改用修正后的拼写ignore_blank。

3. CHANGE_LOG.md 的 v2.1.5（2025.3.26）更新条目写明：

   修复：HTTP接口/api/doc/download参数ignore_blank的错误。

当前仓库源码 doc_server.py 中/api/doc/download路由读取的正是修正后的键名：ignore_blank = user_data.get("ignore_blank", True)。所以可以确定：v2.1.5 修复后，服务端只认ignore_blank；v2.1.4 及更早版本存在参数问题，示例代码因此为它们保留了ingore_blank这一键名。

按版本编写请求

判断路径很简单：你的 Umi-OCR 是 v2.1.4 或更早，还是 v2.1.5 及更新版本。以 Python 为例，第 1 步（/api/doc/upload上传并拿到任务id）和第 2 步（轮询/api/doc/result直到is_done==true && state=="success"）与版本无关，可直接参考 api_doc_demo.py 中的完整实现。第 3 步请求只改一处键名：

import json import requests base_url = "http://127.0.0.1:1224" url = "{}/api/doc/download".format(base_url) headers = {"Content-Type": "application/json"} download_options = { "id": id, # 第1步上传接口返回的任务ID "file_types": ["txt"], # 只填一个值时返回单个文件的下载链接 # v2.1.4 及更早版本：使用错误拼写 ingore_blank "ingore_blank": False, # 不忽略空页，文件中空页的内容记为空字符串 } # 若使用 v2.1.5 及更新版本（含最新代码构建版本）： # 将上一行替换为 "ignore_blank": False data_str = json.dumps(download_options) response = requests.post(url, data=data_str, headers=headers) res_data = json.loads(response.text)

如果不需要区分空页（接受默认行为"跳过空页"），则干脆不传该参数，两种版本都走默认值true，键名问题自然不存在。

file_types可选值有："pdfLayered"（双层可搜索PDF，默认）、"pdfOneLayer"（单层纯文本PDF）、"txt"、"txtPlain"、"jsonl"、"csv"；只填写一个值时返回单个文件的下载链接，填写多个值时返回一个 zip 压缩包的下载链接。

验证调用是否成功

响应为 json 字典，键值含义见 api_doc.md：

• code：100为成功生成目标文件，其余为无法生成目标文件。
• data：成功时为下载链接，失败时为失败原因。
• name：只有成功时才存在，下载链接对应的文件名。

按code == 100判断成功后，用 GET 请求（或浏览器直接打开）data中的链接下载文件——注意链接中类似 id 的部分不是任务ID，不能通过任务ID拼接出下载链接。最后建议调用/api/doc/clear/<id>（GET）清理任务：清理会删除该任务存放在服务器上的所有临时文件（包括上传的文件）；若不手动清理，任务会在 24 小时后自动清理。

限制与官方建议

• api_doc.md 给出的官方建议是"请使用最新版本"。如果你可以升级，升级到 v2.1.5 及以上后直接使用ignore_blank即可，不必再关心错误拼写。
• HTTP接口手册 声明该文档仅适用于 Umi-OCR 最新版本，旧版本应查看 GitHub 备份分支中对应版本的文档；本文涉及的拼写区分以api_doc_demo.py注释、api_doc.md注和 CHANGE_LOG 的修复记录为准。
• v2.1.4 及更早版本"参数存在问题"的具体表现，上述文档未给出更多细节，本文不猜测失败时的具体报错；可执行的做法就是按版本选择键名，并以code == 100的响应验证结果。

【免费下载链接】Umi-OCROCR software, free and offline. 开源、免费的离线OCR软件。支持截屏/批量导入图片，PDF文档识别，排除水印/页眉页脚，扫描/生成二维码。内置多国语言库。项目地址: https://gitcode.com/GitHub_Trending/um/Umi-OCR