MinerU visual details enrichment test guide

This repository contains a Docker-based guide for testing an experimental MinerU branch that adds optional external VLM enrichment for visual details.

The branch is not an official MinerU release. It is intended for people who want to test the feature locally and provide feedback.

What this branch does

MinerU remains the primary document parser. It still handles:

• document layout;
• OCR and page structure;
• image crops;
• tables;
• visual sub_type;
• base image / chart content.

When enabled, the experimental feature calls an external OpenAI-compatible VLM endpoint only for referenced image / chart blocks that already have MinerU-generated content. The external VLM appends a didactic explanation inside the existing visual details block.

Expected Markdown shape:

![](images/xxx.jpg)
<details>
<summary>candlestick</summary>

<MinerU visual content>

### Didactic interpretation
<external VLM enrichment>
</details>

The external VLM can run locally or remotely. Ollama is one possible option if it exposes an OpenAI-compatible /v1 endpoint, but the workflow is provider-agnostic.

Requirements

• Linux machine with NVIDIA GPU.
• Docker with NVIDIA Container Toolkit.
• Enough disk space for the Docker image and MinerU models.
• An OpenAI-compatible VLM endpoint for the enrichment step, for example:
  • Ollama on the host machine;
  • a local OpenAI-compatible VLM server;
  • a remote OpenAI-compatible VLM service.

Clone the MinerU test branch

This guide assumes that the guide repository and the MinerU test repository are placed next to each other under the same parent folder, for example:

~/repos/
├── mineru-visual-details-test-guide/
└── mineru-visual-details/

From the parent folder, clone the MinerU test branch:

git clone -b feature/external-visual-details-enrichment \
  https://github.com/flowerpower/MinerU.git \
  mineru-visual-details

cd mineru-visual-details

Build the Docker image

The Docker build must run from inside the cloned MinerU repository because the Dockerfile installs MinerU from the local source code.

If your folders are arranged as shown above and you are currently inside mineru-visual-details, copy the Dockerfile from this guide repository with:

cp ../mineru-visual-details-test-guide/Dockerfile.visual-details-test .

After this copy, the file should exist here:

~/repos/mineru-visual-details/Dockerfile.visual-details-test

Build the image:

docker build -t mineru:visual-details-test -f Dockerfile.visual-details-test .

The Dockerfile installs MinerU from the local cloned source, not from PyPI.

Prepare input and output folders

Run these commands from inside the cloned MinerU repository:

mkdir -p input output
cp /path/to/your/test.pdf input/

Replace /path/to/your/test.pdf with the real path of the PDF you want to test. For example:

cp ~/Documents/my-document.pdf input/test.pdf

In the Docker command below, $PWD means "the current working directory". If you are inside ~/repos/mineru-visual-details, then:

$PWD/input

means:

~/repos/mineru-visual-details/input

and:

$PWD/output

means:

~/repos/mineru-visual-details/output

Those two folders are mounted inside the container as /workspace/input and /workspace/output.

Make sure the external VLM endpoint is running

Example with an OpenAI-compatible endpoint on the host:

http://host.docker.internal:11434/v1

On Linux, the Docker command below includes:

--add-host=host.docker.internal:host-gateway

so the container can reach services running on the host machine.

Run a test parse with external visual enrichment

Replace:

• test.pdf with your PDF filename;
• qwen3-vl:235b-instruct-cloud with your VLM model name;
• en with your preferred output language, or use auto.

docker run --rm -it \
  --gpus all \
  --shm-size 16g \
  --ipc=host \
  --add-host=host.docker.internal:host-gateway \
  -e CUDA_VISIBLE_DEVICES=0 \
  -e PYTORCH_ALLOC_CONF=expandable_segments:True \
  -v "$PWD/input:/workspace/input:ro" \
  -v "$PWD/output:/workspace/output" \
  mineru:visual-details-test \
  mineru \
    -p "/workspace/input/test.pdf" \
    -o /workspace/output/test_visual_details \
    -b vlm-auto-engine \
    --details-image-analysis true \
    --details-vlm-url http://host.docker.internal:11434/v1 \
    --details-vlm-model qwen3-vl:235b-instruct-cloud \
    --details-vlm-timeout 180 \
    --details-vlm-max-concurrency 2 \
    --details-vlm-language en \
  2>&1 | tee output/test_visual_details.log

Notes:

• Do not pass --image-analysis false; MinerU image/chart analysis should remain enabled.
• --details-image-analysis true enables only the external didactic enrichment step.
• --details-vlm-max-concurrency 2 is a reasonable starting point. Increase it only if your external VLM endpoint can handle more parallel requests.
• If you prefer absolute paths instead of $PWD, replace the volume mounts with your real folders, for example:

  -v "/home/your-user/repos/mineru-visual-details/input:/workspace/input:ro" \
  -v "/home/your-user/repos/mineru-visual-details/output:/workspace/output" \

• For very large documents, you may add:

-e MINERU_TASK_RESULT_TIMEOUT_SECONDS=14400

Check the result

Look for the generated Markdown under:

output/test_visual_details/<PDF name>/vlm/

The logs should include progress lines like:

Details image analysis started ...
Details image analysis progress ...
Details image analysis finished ...

Feedback

If you test the branch, useful feedback includes:

• operating system and GPU;
• Docker image build result;
• external VLM endpoint/model used;
• document size and page count;
• total processing time;
• whether the generated ### Didactic interpretation sections are useful for your RAG workflow.