为什么docker中布置的mineru的对pdf解析后的结果比windows中客户端的mineru的解析结果差好多？

[qyb320]

为什么docker中布置的mineru的对pdf解析后的结果比windows中客户端的mineru的解析结果差好多？是不是用的模型是小模型，解析的效果就差好多？

[dosubot[bot]]

Hi @qyb320! I'm Dosu and I’m helping the MinerU team.

@qyb320 你好！Docker 和 Windows 客户端的 MinerU 使用的是完全相同的核心解析模块和模型，并不是因为 Docker 用了小模型 [1]。效果差异主要来自以下几个配置方面的原因：

1. 后端选择不同
这是最常见的原因。Docker 部署可能默认使用了 pipeline 后端，而效果更好的是 vlm-auto-engine 或 hybrid-auto-engine 后端。建议在命令中显式指定后端 [1]：

-b vlm-auto-engine   # 需要 8GB+ 显存
# 或
-b hybrid-auto-engine

2. GPU 环境变量未正确配置
Docker 中使用 VLM/hybrid 后端时，需要设置关键环境变量 [2]：

VLLM_USE_V1=1                        # RTX 30xx 及以上 GPU 需要
MINERU_API_MAX_CONCURRENT_REQUESTS=1  # 显存有限时建议设为 1

3. 中文字体缺失
Linux Docker 容器需要显式安装中文字体，否则会导致文本丢失。官方 Dockerfile 已包含安装 fonts-noto-cjk，但如果你是自行构建镜像需要确认这一点 [3]。

4. 模型缓存目录未挂载
如果 .cache 目录没有正确挂载，模型可能加载不完整 [2]：

docker run ... -v /your/path/.cache:/root/.cache ...

5. Docker 启动参数
使用 VLM 后端时，--shm-size 和 --ipc=host 对性能和效果至关重要 [1]：

docker run --gpus all --shm-size 32g --ipc=host ...

总结来说，不是模型大小的问题，而是 Docker 环境配置的问题。建议你检查一下使用的后端类型和上述配置项，调整后效果应该能跟 Windows 客户端一致。

To reply, just mention @dosu.

---

Share context across your team and agents. Try Dosu.

[myhloli]

具体描述下差异在什么地方，如何部署，又是如何使用的呢？

[qyb320]

我是用docker compose来创建的，是用的pipeline后端的，显卡是GTX 4060 显存8G，如后端用vlm-auto-engine，在.env中应如何增加配置项？ 阿 标 ***@***.*** 原始邮件 发件人：dosubot[bot] ***@***.***> 发件时间：2026年4月29日 10:45 收件人：opendatalab/MinerU ***@***.***> 抄送：qyb320 ***@***.***>, Mention ***@***.***> 主题：Re: [opendatalab/MinerU] 为什么docker中布置的mineru的对pdf解析后的结果比windows中客户端的mineru的解析结果差好多？ (Discussion #4878) Hi @qyb320! I'm Dosu and I’m helping the MinerU team. @qyb320 你好！Docker 和 Windows 客户端的 MinerU 使用的是完全相同的核心解析模块和模型，并不是因为 Docker 用了小模型 [1]。效果差异主要来自以下几个配置方面的原因： 1. 后端选择不同 这是最常见的原因。Docker 部署可能默认使用了 pipeline 后端，而效果更好的是 vlm-auto-engine 或 hybrid-auto-engine 后端。建议在命令中显式指定后端 [1]： -b vlm-auto-engine   # 需要 8GB+ 显存 # 或 -b hybrid-auto-engine 2. GPU 环境变量未正确配置 Docker 中使用 VLM/hybrid 后端时，需要设置关键环境变量 [2]： VLLM_USE_V1=1                        # RTX 30xx 及以上 GPU 需要 MINERU_API_MAX_CONCURRENT_REQUESTS=1  # 显存有限时建议设为 1 3. 中文字体缺失 Linux Docker 容器需要显式安装中文字体，否则会导致文本丢失。官方 Dockerfile 已包含安装 fonts-noto-cjk，但如果你是自行构建镜像需要确认这一点 [3]。 4. 模型缓存目录未挂载 如果 .cache 目录没有正确挂载，模型可能加载不完整 [2]： docker run ... -v /your/path/.cache:/root/.cache ... 5. Docker 启动参数 使用 VLM 后端时，--shm-size 和 --ipc=host 对性能和效果至关重要 [1]： docker run --gpus all --shm-size 32g --ipc=host ... 总结来说，不是模型大小的问题，而是 Docker 环境配置的问题。建议你检查一下使用的后端类型和上述配置项，调整后效果应该能跟 Windows 客户端一致。 To reply, just mention @dosu. Share context across your team and agents. Try Dosu. — Reply to this email directly, view it on GitHub, or unsubscribe. Triage notifications on the go with GitHub Mobile for iOS or Android. You are receiving this because you were mentioned.

[dosubot[bot]]

@qyb320 你好！MinerU 的官方 compose.yaml 中，后端选择不是通过 .env 环境变量控制的，而是通过各服务的 command 参数控制 [1]。

不过有一个重要提醒：GTX 4060 的 8GB 显存对于 vlm-auto-engine 来说比较紧张，因为 vLLM 启动时会预分配大量显存 [2]。你需要降低显存使用率参数才有可能跑起来。

具体修改方法如下，以 mineru-api 服务为例，在 compose.yaml 中取消注释并调低 --gpu-memory-utilization [3]：

mineru-api:
  image: mineru:latest
  container_name: mineru-api
  restart: always
  profiles: ["api"]
  ports:
    - 8000:8000
  environment:
    MINERU_MODEL_SOURCE: local
    PYTORCH_CUDA_ALLOC_CONF: "expandable_segments:True"
  entrypoint: mineru-api
  command:
    --host 0.0.0.0
    --port 8000
    --gpu-memory-utilization 0.3   # 8GB显存建议设为0.3，默认0.5可能会OOM
  ulimits:
    memlock: -1
    stack: 67108864
  ipc: host
  deploy:
    resources:
      reservations:
        devices:
          - driver: nvidia
            device_ids: ["0"]
            capabilities: [gpu]

关键改动点：

1. --gpu-memory-utilization 0.3：从默认的 0.5 降到 0.3，减少 vLLM 的 KV cache 显存占用，避免 8GB 显存 OOM [4]
2. PYTORCH_CUDA_ALLOC_CONF: "expandable_segments:True"：减少 GPU 显存碎片 [5]

如果使用的是 mineru-gradio（Web UI）服务，同样在对应的 command 中加上 --gpu-memory-utilization 0.3 即可 [6]。

⚠️ 注意：由于 8GB 显存确实很紧张，如果启动 vlm-auto-engine 后仍然 OOM，可以尝试 hybrid-auto-engine 后端（效果也比纯 pipeline 好很多），或者进一步将 --gpu-memory-utilization 降低到 0.2。如果都不行，pipeline 后端虽然效果略差，但也可以通过确保字体安装正确等方式来提升效果。

To reply, just mention @dosu.

---

Share context across your team and agents. Try Dosu.

[qyb320]

我想在ragflow中调用mineru的vlm-auto-engine，在ragflow的.env文件中应如何设置mineru的相关参数？ 阿 标 ***@***.*** 原始邮件 发件人：dosubot[bot] ***@***.***> 发件时间：2026年4月29日 14:17 收件人：opendatalab/MinerU ***@***.***> 抄送：qyb320 ***@***.***>, Mention ***@***.***> 主题：Re: [opendatalab/MinerU] 为什么docker中布置的mineru的对pdf解析后的结果比windows中客户端的mineru的解析结果差好多？ (Discussion #4878) @qyb320 你好！MinerU 的官方 compose.yaml 中，后端选择不是通过 .env 环境变量控制的，而是通过各服务的 command 参数控制 [1]。 不过有一个重要提醒：GTX 4060 的 8GB 显存对于 vlm-auto-engine 来说比较紧张，因为 vLLM 启动时会预分配大量显存 [2]。你需要降低显存使用率参数才有可能跑起来。 具体修改方法如下，以 mineru-api 服务为例，在 compose.yaml 中取消注释并调低 --gpu-memory-utilization [3]： mineru-api:  image: mineru:latest  container_name: mineru-api  restart: always  profiles: ["api"]  ports:    - 8000:8000  environment:    MINERU_MODEL_SOURCE: local    PYTORCH_CUDA_ALLOC_CONF: "expandable_segments:True"  entrypoint: mineru-api  command:    --host 0.0.0.0    --port 8000    --gpu-memory-utilization 0.3   # 8GB显存建议设为0.3，默认0.5可能会OOM  ulimits:    memlock: -1    stack: 67108864  ipc: host  deploy:    resources:      reservations:        devices:          - driver: nvidia            device_ids: ["0"]            capabilities: [gpu] 关键改动点：

…

--gpu-memory-utilization 0.3：从默认的 0.5 降到 0.3，减少 vLLM 的 KV cache 显存占用，避免 8GB 显存 OOM [4] PYTORCH_CUDA_ALLOC_CONF: "expandable_segments:True"：减少 GPU 显存碎片 [5] 如果使用的是 mineru-gradio（Web UI）服务，同样在对应的 command 中加上 --gpu-memory-utilization 0.3 即可 [6]。 ⚠️ 注意：由于 8GB 显存确实很紧张，如果启动 vlm-auto-engine 后仍然 OOM，可以尝试 hybrid-auto-engine 后端（效果也比纯 pipeline 好很多），或者进一步将 --gpu-memory-utilization 降低到 0.2。如果都不行，pipeline 后端虽然效果略差，但也可以通过确保字体安装正确等方式来提升效果。 To reply, just mention @dosu. Share context across your team and agents. Try Dosu. — Reply to this email directly, view it on GitHub, or unsubscribe. Triage notifications on the go with GitHub Mobile for iOS or Android. You are receiving this because you were mentioned.

[dosubot[bot]]

@qyb320 RAGFlow 与 MinerU 的集成方式有两种：CLI 调用和 HTTP API 调用，后端选择的配置方式取决于你使用哪种集成方式。

方式一：通过 CLI 调用（RAGFlow 容器内安装 MinerU）

RAGFlow 的 .env 中主要配置这两个变量 [1]：

HF_ENDPOINT=https://hf-mirror.com
MINERU_EXECUTABLE=/ragflow/uv_tools/.venv/bin/mineru

但这种方式下，后端选择（-b vlm-auto-engine）是 RAGFlow 调用 mineru 命令时传入的参数，不是在 .env 中配置的，需要看 RAGFlow 侧的代码是否支持指定后端。

方式二：通过 HTTP API 调用（推荐）

这是 MinerU 维护者推荐的方式 [2]。你需要：

1. 独立部署 MinerU API 服务，使用 MinerU 自己的 compose.yaml 启动 mineru-api（参考之前的配置），API 默认端口是 8000
2. MinerU API 支持按请求指定后端——在调用 /file_parse 等接口时通过 backend 参数传入 vlm-auto-engine [3]
3. 在 RAGFlow 侧配置 MinerU 的 API 地址（具体变量名取决于你的 RAGFlow 版本）

⚠️ 需要注意的兼容性问题：MinerU 3.0+ 的输出目录结构发生了变化，如果 RAGFlow 是通过读取本地文件获取解析结果，可能会找不到文件。MinerU 维护者建议改为通过 API 返回值获取结果 [2]。

总结来说，RAGFlow 的 .env 文件本身没有直接配置 MinerU 后端类型的选项。如果要使用 vlm-auto-engine，建议独立部署 MinerU API 服务，然后让 RAGFlow 通过 HTTP 调用它。这样你可以在 MinerU 侧自由控制后端和显存参数。

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.

[qyb320]

ragflow远程调用mineru的指定后端当中没有vlm-auto-engine 阿 标 ***@***.*** 原始邮件 发件人：dosubot[bot] ***@***.***> 发件时间：2026年4月29日 20:14 收件人：opendatalab/MinerU ***@***.***> 抄送：qyb320 ***@***.***>, Mention ***@***.***> 主题：Re: [opendatalab/MinerU] 为什么docker中布置的mineru的对pdf解析后的结果比windows中客户端的mineru的解析结果差好多？ (Discussion #4878) @qyb320 RAGFlow 与 MinerU 的集成方式有两种：CLI 调用和 HTTP API 调用，后端选择的配置方式取决于你使用哪种集成方式。 方式一：通过 CLI 调用（RAGFlow 容器内安装 MinerU） RAGFlow 的 .env 中主要配置这两个变量 [1]： HF_ENDPOINT=https://hf-mirror.com MINERU_EXECUTABLE=/ragflow/uv_tools/.venv/bin/mineru 但这种方式下，后端选择（-b vlm-auto-engine）是 RAGFlow 调用 mineru 命令时传入的参数，不是在 .env 中配置的，需要看 RAGFlow 侧的代码是否支持指定后端。 方式二：通过 HTTP API 调用（推荐） 这是 MinerU 维护者推荐的方式 [2]。你需要： 独立部署 MinerU API 服务，使用 MinerU 自己的 compose.yaml 启动 mineru-api（参考之前的配置），API 默认端口是 8000 MinerU API 支持按请求指定后端——在调用 /file_parse 等接口时通过 backend 参数传入 vlm-auto-engine [3] 在 RAGFlow 侧配置 MinerU 的 API 地址（具体变量名取决于你的 RAGFlow 版本） ⚠️ 需要注意的兼容性问题：MinerU 3.0+ 的输出目录结构发生了变化，如果 RAGFlow 是通过读取本地文件获取解析结果，可能会找不到文件。MinerU 维护者建议改为通过 API 返回值获取结果 [2]。 总结来说，RAGFlow 的 .env 文件本身没有直接配置 MinerU 后端类型的选项。如果要使用 vlm-auto-engine，建议独立部署 MinerU API 服务，然后让 RAGFlow 通过 HTTP 调用它。这样你可以在 MinerU 侧自由控制后端和显存参数。 To reply, just mention @dosu. Docs are dead. Just use Dosu. — Reply to this email directly, view it on GitHub, or unsubscribe. Triage notifications on the go with GitHub Mobile for iOS or Android. You are receiving this because you were mentioned.

[dosubot[bot]]

@qyb320 这个问题确实存在——RAGFlow 侧没有提供 vlm-auto-engine 的后端选项，是 RAGFlow 的限制，不是 MinerU 的限制。

从 MinerU 的 API 来看，/file_parse 接口是支持通过 backend 参数指定 vlm-auto-engine 的 [1]。如果 RAGFlow 调用时没有传这个参数，MinerU 会默认使用 hybrid-auto-engine [2]。

不过好消息是，hybrid-auto-engine 本身效果已经比 pipeline 好很多，它结合了 pipeline 和 VLM 的能力，并且支持多语种。如果 RAGFlow 默认使用的是 hybrid-auto-engine，效果应该已经比你之前用 pipeline 好不少了。

目前 MinerU 的 API 服务端也没有提供启动参数或环境变量来修改默认后端 [3]，所以没法在 MinerU 侧强制所有请求都走 vlm-auto-engine。

如果你确实需要使用 vlm-auto-engine，有两个思路：

1. 先试试 hybrid-auto-engine（这是 MinerU API 的默认后端），看看效果是否已经满足需求
2. 如果必须用 vlm-auto-engine，需要在 RAGFlow 侧修改调用 MinerU API 时传入的 backend 参数——这属于 RAGFlow 侧的功能需求，建议向 RAGFlow 社区反馈

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.

[qyb320]

我在运行mineru-gradio时出现下面的错误信息，是什么原因？ Preparing request... Checking server status... Submitting task... Task submitted：task_id=e0000631-acec-437b-9d45-c793fb03c5ee Processing on server (659.3s) Failed: Task e0000631-acec-437b-9d45-c793fb03c5ee failed for GB 50011-2010 建筑抗震设计规范.pdf: {"task_id": "e0000631-acec-437b-9d45-c793fb03c5ee", "status": "failed", "backend": "hybrid-auto-engine", "file_names": ["GB 50011-2010 建筑抗震设计规范"], "created_at": "2026-04-29T13:04:26.088582+00:00", "started_at": "2026-04-29T13:04:26.088937+00:00", "completed_at": "2026-04-29T13:15:23.725199+00:00", "error": "EngineCore encountered an issue. See stack trace (above) for the root cause.", "status_url": "http://127.0.0.1:40455/tasks/e0000631-acec-437b-9d45-c793fb03c5ee", "result_url": "http://127.0.0.1:40455/tasks/e0000631-acec-437b-9d45-c793fb03c5ee/result", "queued_ahead": 0} 阿 标 ***@***.*** 原始邮件 发件人：dosubot[bot] ***@***.***> 发件时间：2026年4月29日 20:43 收件人：opendatalab/MinerU ***@***.***> 抄送：qyb320 ***@***.***>, Mention ***@***.***> 主题：Re: [opendatalab/MinerU] 为什么docker中布置的mineru的对pdf解析后的结果比windows中客户端的mineru的解析结果差好多？ (Discussion #4878) @qyb320 这个问题确实存在——RAGFlow 侧没有提供 vlm-auto-engine 的后端选项，是 RAGFlow 的限制，不是 MinerU 的限制。 从 MinerU 的 API 来看，/file_parse 接口是支持通过 backend 参数指定 vlm-auto-engine 的 [1]。如果 RAGFlow 调用时没有传这个参数，MinerU 会默认使用 hybrid-auto-engine [2]。 不过好消息是，hybrid-auto-engine 本身效果已经比 pipeline 好很多，它结合了 pipeline 和 VLM 的能力，并且支持多语种。如果 RAGFlow 默认使用的是 hybrid-auto-engine，效果应该已经比你之前用 pipeline 好不少了。 目前 MinerU 的 API 服务端也没有提供启动参数或环境变量来修改默认后端 [3]，所以没法在 MinerU 侧强制所有请求都走 vlm-auto-engine。 如果你确实需要使用 vlm-auto-engine，有两个思路： 先试试 hybrid-auto-engine（这是 MinerU API 的默认后端），看看效果是否已经满足需求 如果必须用 vlm-auto-engine，需要在 RAGFlow 侧修改调用 MinerU API 时传入的 backend 参数——这属于 RAGFlow 侧的功能需求，建议向 RAGFlow 社区反馈 To reply, just mention @dosu. Docs are dead. Just use Dosu. — Reply to this email directly, view it on GitHub, or unsubscribe. Triage notifications on the go with GitHub Mobile for iOS or Android. You are receiving this because you were mentioned.

[dosubot[bot]]

@qyb320 这个 "EngineCore encountered an issue" 错误是 vLLM 引擎因 GPU 显存不足（OOM）导致的 [1]。你的 GTX 4060 只有 8GB 显存，而 hybrid-auto-engine 后端使用 vLLM 时默认会预分配 50% 的显存用于 KV cache，对 8GB 显存来说太激进了。

任务跑了约 11 分钟后失败，说明处理过程中显存逐渐耗尽。

解决方法：启动 mineru-gradio 时降低 --gpu-memory-utilization 参数 [1]：

mineru-gradio --server-name 0.0.0.0 --server-port 7860 --gpu-memory-utilization 0.3

如果你是用 Docker Compose，在 compose.yaml 的 mineru-gradio 服务的 command 中加上这个参数。同时建议设置环境变量减少显存碎片：

environment:
  MINERU_MODEL_SOURCE: local
  PYTORCH_CUDA_ALLOC_CONF: "expandable_segments:True"

如果设为 0.3 仍然 OOM，可以尝试进一步降到 0.2。如果还是不行，说明 8GB 显存确实不够跑 hybrid-auto-engine，可以退回到 pipeline 后端（通过在 Gradio 界面中选择 pipeline）。

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.