[Bug]: Why are the parsed images obscured when I use MinerU as a parser?

快速结论：这是 RAGFlow 在 MinerU 及其他解析器中内置的图像裁剪逻辑特性，并非 Bug。当图像跨多个页面片段时，会对首尾图像叠加 50% 半透明黑色蒙层以标示上下文边界。优先检查图像是否仅跨越单个页面片段（此时蒙层总是被应用），或修改代码条件移除该效果。

问题场景

在 RAGFlow 0.24.0 版本中使用 MinerU 解析器（Parser）处理 PDF 文档时，解析后输出的图像被部分遮挡/变暗，出现半透明黑色蒙层。该现象也存在于 pdf_parser、docling_parser、paddleocr_parser 等其他解析器中。

报错原文

No explicit error message. The issue is visual: parsed images appear with a semi-transparent black overlay (50% opacity), obscuring content.

原因分析

这是 RAGFlow 的预设裁剪逻辑。当 MinerU 解析器将跨多个页面片段的图像进行裁剪拼接时，会对序列中的第一张（ii == 0）和最后一张（ii + 1 == len(imgs)）图像应用半透明黑色蒙层（putalpha(128)），用来在视觉上提示上下文边界。如果图像只跨越一个页面片段（len(imgs) == 1），则 ii == 0 恒成立，蒙层总是被叠加——因此单片段图像始终看起来被遮挡。这是设计意图，但可能不符合用户预期。

环境排查

RAGFlow 版本：0.24.0（当前已知受影响版本）
解析器类型：MinerU parser（同时排查其他解析器如 pdf_parser、docling_parser、paddleocr_parser）
检查图像在 PDF 中是否跨多页或多区域（判断 imgs 列表长度）

解决步骤

确认是否为预期行为：检查图像是否确实跨页面片段。如果是，则该效果是 RAGFlow 当前设计的上下文提示功能。

（可优先尝试）修改代码移除蒙层逻辑：编辑 deepdoc/parser/mineru_parser.py（以及对应的 pdf_parser.py、docling_parser.py、paddleocr_parser.py），找到如下代码段：

for ii, img in enumerate(imgs):
    if ii == 0 or ii + 1 == len(imgs):
        img = img.convert("RGBA")
        overlay = Image.new("RGBA", img.size, (0, 0, 0, 0))
        overlay.putalpha(128)
        img = Image.alpha_composite(img, overlay).convert("RGB")
    pic.paste(img, (0, int(height)))
    height += img.size[1] + GAP

删除或注释掉 if ii == 0 or ii + 1 == len(imgs): ... 部分，以去除蒙层效果。

重新解析：保存修改后，重新触发文档解析流程，查看图像是否恢复清晰。

验证方法

重新解析后，检查输出图像是否不再出现半透明黑色蒙层，内容完整清晰可见。如果图像跨越多个页面片段，首尾图像应不再变暗。

参考来源

infiniflow/ragflow #14197

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。

[Bug]: Why are the parsed images obscured when I use MinerU as a parser?