[Question]: how to config mineru parsing

[ZTurboX]

Self Checks

• I have searched for existing issues search for existing issues, including closed ones.
• I confirm that I am using English to submit this report (Language Policy).
• Non-english title submitions will be closed directly ( 非英文标题的提交将会被直接关闭 ) (Language Policy).
• Please do not modify this template :) and fill in all the required fields.

Describe your problem

I have deployed mineru with mineru-vllm-server abd mineru-api command .
how to config mineru parsing

[dosubot]

To configure MinerU parsing in RAGFlow after deploying mineru-vllm-server and mineru-api, set the following environment variables in your .env file:

USE_MINERU=true
MINERU_EXECUTABLE=/path/to/mineru
MINERU_BACKEND="vlm-http-client"
MINERU_SERVER_URL="http://your-vllm-server-ip:30000"
# Optional:
MINERU_OUTPUT_DIR=/tmp/mineru_output
MINERU_DELETE_OUTPUT=1

The recommended backend for remote GPU parsing is vlm-http-client, which lets RAGFlow run on CPU and offload parsing to your remote MinerU vLLM server via HTTP. Make sure to restart your backend services after updating these settings so the changes take effect. When USE_MINERU=true is set, RAGFlow will attempt to auto-install and configure MinerU at startup; check backend logs for installation/config messages if you run into issues (source, source, source).

In the RAGFlow Web UI, go to your dataset’s configuration page, select the built-in ingestion pipeline, and choose MinerU as the PDF parser. You’ll see UI options for parse method (auto, txt, ocr), formula recognition, and table recognition—these control how MinerU parses your documents (source).

Best practices:

• Keep MAX_CONCURRENT_CHUNK_BUILDERS=1 to avoid concurrency errors, since MinerU doesn’t have built-in parallel request handling.
• Avoid spaces in filenames to prevent parsing failures.
• MinerU parsing output is more fragmented than DeepDoc; use the HierarchicalMerger component in RAGFlow to merge blocks if needed.
• If you change the parser, delete and re-upload PDFs for the new parser to take effect.

If you run into missing file errors with vlm-http-client, check if RAGFlow is looking for output in /vlm/ but MinerU writes to /auto/; you may need to patch the parser logic (source).

For more details, see the MinerU integration FAQ and official MinerU environment variable docs.

To reply, just mention @dosu.

---

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

   

[dosubot]

With your setup, the recommended way to integrate MinerU parsing in RAGFlow is to use the vlm-http-client backend, which connects directly to your mineru-vllm-server over HTTP and does not require the mineru-api service for PDF parsing. In your RAGFlow .env, set:

USE_MINERU=true
MINERU_EXECUTABLE=/path/to/mineru
MINERU_BACKEND=vlm-http-client
MINERU_SERVER_URL=http://<your-vllm-server-ip>:<port>
# Optional:
MINERU_OUTPUT_DIR=/tmp/mineru_output
MINERU_DELETE_OUTPUT=1

Restart your backend after updating these. In the RAGFlow UI, select MinerU as the parser for your dataset. For remote parsing, only vlm-http-client is recommended—using the API mode (MINERU_APISERVER/mineru-api) can cause blocking and is not async-friendly details.

If you see missing file errors, check if RAGFlow expects output in /vlm/ but MinerU writes to /auto/; you may need to patch the parser logic details. Avoid spaces in filenames and keep MAX_CONCURRENT_CHUNK_BUILDERS=1 to prevent concurrency issues.

Let me know if you hit any errors or need help with a specific part of the setup.

To reply, just mention @dosu.

---

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

   

[ZTurboX]

@dosu I use mineru-vllm-server --host 0.0.0.0 --port xxx and mineru-api --host 0.0.0.0 --port xxx;
And config ragflow .env as follows

USE_MINERU=true
MINERU_APISERVER=http://xxxx:xxxx
MINERU_BACKEND=vlm-http-client
MINERU_SERVER_URL=http://xxxx:xxxx
MINERU_OUTPUT_DIR=/home/ragflow/mineru/output
MINERU_DELETE_OUTPUT=1

when use docker start ragflow , it report “[mineru] not found, bootstrapping with uv“;rather than use mineru remote host

[ZTurboX]

@dosu I use mineru-vllm-server --host 0.0.0.0 --port xxx and mineru-api --host 0.0.0.0 --port xxx;
And config ragflow .env as follows

USE_MINERU=true
MINERU_APISERVER=http://xxxx:xxxx/
MINERU_BACKEND=vlm-http-client
MINERU_SERVER_URL=http://xxxx:xxxx/
MINERU_OUTPUT_DIR=/home/ragflow/mineru/output
MINERU_DELETE_OUTPUT=1

when use docker start ragflow , it report “[mineru] not found, bootstrapping with uv“;rather than use mineru remote host

[dosubot]

Your issue is caused by RAGFlow trying to install MinerU locally because of how older versions handle the USE_MINERU variable—even when you set MINERU_APISERVER for remote parsing. This is a known bug in versions before v0.22.0: the Docker entrypoint always attempts a local install if USE_MINERU=true, ignoring the remote API config, which triggers the “[mineru] not found, bootstrapping with uv” message (details).

If you’re running RAGFlow v0.22.0 or later (after PR #11977), you should remove USE_MINERU and MINERU_EXECUTABLE from your .env. Just set MINERU_APISERVER (and optionally MINERU_BACKEND, MINERU_OUTPUT_DIR, etc.), then restart your container. Local MinerU install is no longer needed or supported—RAGFlow will act as a remote client and use your MinerU API server directly (docs).

If you’re on an older version, either upgrade to the latest release or patch your entrypoint.sh: add a check at the start of ensure_mineru() to skip local install if MINERU_APISERVER is set (example patch). This will stop the unwanted local bootstrapping.

Also, make sure your environment variables are actually loaded by the container, and check if the RAGFlow UI (Model providers page) or config files are overriding your .env settings.

Let me know your RAGFlow version if you’re unsure which fix applies.

To reply, just mention @dosu.

---

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

   

[ZTurboX]

when remove USE_MINERU and MINERU_EXECUTABLE,after started, In the RAGFlow Web UI, dataset’s configuration page,has mineru-from-env-1,mineru-from-env-2,mineru-from-env-3,mineru-from-env-4,which one to select

[yongtenglei]

Hi, @ZTurboX

You should be able to add new MinerU models through this interface, and you can delete any models from env, that is safe.

Cheers.