解析pdf时，如何配置MinerU使用OCR解析？

[JasonGofen]

你好，我在用MinerU解析PDF时，发现PDF中的图片中的文字没有解析出来。我用的是HTTP API的方式调用的MinerU。
请教两个问题：
1.如何在使用HTTP API的方式调用的MinerU解析文档时，强制开启OCR解析？
2.我们购买了商业的OCR，如果配置MinerU在解析文档时，调用商业OCR API？
目前的入参是这样：

[JasonGofen]

parse_method:ocr 貌似没有起效。

[dosubot[bot]]

你用的参数 parse_method=ocr 理论上是正确的，前提是 backend 必须是 pipeline 或 hybrid*（比如 hybrid-auto-engine），并且 lang_list 语言参数建议设置为实际文档语言（如 ch）以提升识别率。代码和文档都明确，HTTP API 不需要单独的 enable_ocr 参数，parse_method=ocr 就会强制全页 OCR 识别【参考1】【参考2】。

如果你已经这样设置但图片文字还是没被识别，常见原因有：PDF 结构特殊（如扫描件、加密、字体编码异常）、系统缺少字体、OCR 语言模型不匹配、图片质量太低等。建议升级 MinerU 至 2.5.x 以上版本，OCR 效果有明显提升【参考3】。还可以尝试调整 OCR 相关参数（如 det_db_box_thresh、det_db_unclip_ratio 等）来优化边缘和密集区域的检测【参考4】。

目前 MinerU 没有官方支持直接集成商业 OCR API 的方式，内部只用自带的 OCR（如 PaddleOCR）。如果你一定要用商业 OCR，建议先用外部工具对 PDF 做 OCR 预处理，再用 MinerU 解析结构化内容【参考5】。

如需进一步排查，可以开启 debug 日志，或提供中间输出文件（如 middle.json），我可以帮你分析。

---

参考：

• HTTP API 参数说明与用法
• parse_method=ocr 强制开启 OCR 讨论
• OCR 识别效果与版本建议
• OCR 参数微调建议
• 商业 OCR 集成说明

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[JasonGofen]

版本及相关参数信息：
MinerU version：2.7.1 Release
backend：hybrid-auto-engine
parse_method：ocr
lang_list：ch
其他补充：
如果把pdf中的图片拿出来，单独扔给minerU是可以解析出来文字的。只是放到pdf中不能解析。所以，其实minerU是可以正常解析该图片，只是还不知道到底哪里出现了问题，导致pdf中的同图片继续不出文字。

[dosubot[bot]]

你遇到的问题，核心原因通常在于 PDF 渲染或图片提取阶段出错，导致 OCR 没有拿到正确的图片内容。你当前的参数配置（hybrid-auto-engine + parse_method=ocr + lang_list=ch）是正确的，理论上应该能对 PDF 中的图片做 OCR，但实际流程中有几个常见“坑”：

1. PDF 渲染为图片失败或超时：MinerU 会用 pdfium 把每页 PDF 渲染成图片，受 MINERU_PDF_LOAD_IMAGES_TIMEOUT（默认 300 秒）控制。如果某页渲染超时或导入异常，会直接跳过该页，不报错，后续 OCR 也就没有内容可识别[源码细节]。

2. PDF 结构异常或图片嵌入方式特殊：比如扫描件、加密、字体包缺失、图片分辨率/编码特殊等，都会导致渲染或图片提取失败[常见原因]。

3. OCR 阈值过滤：OCR 检测时对区域有最小宽度、置信度等过滤，过小或置信度低的结果会被丢弃，导致部分图片文字未输出[OCR 过滤逻辑]。

4. 图片单独识别正常，PDF 里失败：说明 OCR 本身没问题，问题多半出在 PDF 渲染或图片提取阶段。PDF 渲染为图片时可能丢失了图片的原始信息（如分辨率、方向、编码），或者该页被跳过。

排查建议：

• 确认系统已安装 fonts-noto-core 和 fonts-noto-cjk 字体包，避免字体缺失影响渲染。
• 尝试设置更长的 MINERU_PDF_LOAD_IMAGES_TIMEOUT 环境变量，防止大页/复杂页超时被跳过。
• 用 API 请求时加上 return_middle_json=True，分析 middle.json 里对应图片 block 是否存在、img_path 是否为空，定位是渲染、提取还是 OCR 阶段丢失。
• 尝试用第三方工具（如 Adobe、pdfimages）将 PDF 统一页面尺寸、去除水印、转为标准 PDF，再用 MinerU 解析。
• 如有复杂排版、长图、特殊嵌入方式，建议先用外部工具提取图片做 OCR，再用 MinerU 做结构化解析[详细分析]。

关于商业 OCR：
MinerU 暂不支持直接集成外部商业 OCR API。要用商业 OCR，需先用外部工具对 PDF 做 OCR 预处理，再用 MinerU 解析结构化内容[官方说明]。

如需进一步定位，建议上传 PDF 样本和 middle.json，便于社区协助分析。

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[JasonGofen]

大数据部会议纪要-20251231-V2.docx
大数据部会议纪要-20251231-V2.pdf
middle.json
以上是，我们所使用的待解析的文件，pdf是通过docx另存为得到的。middle.json是解析上面的pdf得到的。pdf中解析不出的图片分别是，word/pdf 中第二页的两张。
我们初步看过minerU的代码，好像是pdf解析过程中对深色背景图片的解析支持不太够。但单独把pdf中的图片扔个minerU是可以解析的。
image1_middle.json
该 image1_middle.json 为word/pdf 中第二页的第1张黑色背景的图片，是单独把该图片扔给MinerU得到的。
请社区大佬们，帮忙看看是怎么个事儿。

[dosubot[bot]]

你遇到的现象，结合 MinerU 的实现和社区经验，主要原因是 PDF 渲染和图片提取阶段对深色/黑色背景图片没有专门的增强或适配逻辑，OCR 依赖图片本身的对比度和模型鲁棒性。如果单独提取图片后 OCR 能正常识别，但 PDF 解析时失败，常见原因包括：

• PDF 渲染为图片时，图片分辨率、色彩、对比度等信息可能被改变，导致深色背景下文字与背景反差不足，OCR 检测框被过滤（如置信度低于 0.5 或宽度小于 3 像素）参考。
• MinerU 的图片裁剪和 OCR 前处理会把区域粘贴到白色背景，但不会主动做对比度增强或二值化，深色背景下的文字容易被漏检参考。
• middle.json 结构中 discarded_blocks 字段可能包含被误判丢弃的图片块，建议重点排查该字段，确认目标图片是否被分类为 discarded参考。
• 复杂 PDF（如特殊嵌入、分辨率、排版）渲染时可能丢失图片信息，导致 OCR 阶段拿不到有效图片。

建议排查和优化：

1. 检查 middle.json 里第二页相关 image block 是否存在、img_path 是否为空，或是否被归入 discarded_blocks。
2. 尝试用外部工具（如 pdfimages、Adobe）提取 PDF 中的图片，手动增强对比度（如调整亮度/对比度、二值化），再用 MinerU 解析。
3. 如需自动化，可在生成 PDF 前对 Word 中的深色图片做对比度增强处理。
4. 若必须用商业 OCR，可先用外部工具对 PDF 做 OCR 预处理，再用 MinerU 做结构化解析，MinerU 暂不支持直接集成商业 OCR API参考。
5. 可尝试升级 MinerU 至最新版，确保系统已安装 fonts-noto-core 和 fonts-noto-cjk 字体包，避免字体缺失影响渲染。

本质上，MinerU 对深色背景图片没有专门的 OCR 增强逻辑，识别效果取决于图片本身的对比度和 OCR 模型能力。遇到类似场景，建议优先做图片预处理或用外部 OCR 工具辅助参考。

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}