Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

fix(mineru): align backend names with current MinerU API (#19055)

天海蒼灆792a17cf2091
diff --git a/deepdoc/parser/mineru_parser.py b/deepdoc/parser/mineru_parser.py
index cf40876820..17c54447ba 100644
--- a/deepdoc/parser/mineru_parser.py
+++ b/deepdoc/parser/mineru_parser.py
@@ -91,15 +91,13 @@ LANGUAGE_TO_MINERU_MAP = {
class MinerUBackend(StrEnum):
- """MinerU processing backend options."""
+ """MinerU processing backend options (current public API names)."""
- PIPELINE = "pipeline" # Traditional multimodel pipeline (default)
- VLM_TRANSFORMERS = "vlm-transformers" # Vision-language model using HuggingFace Transformers
- VLM_MLX_ENGINE = "vlm-mlx-engine" # Faster, requires Apple Silicon and macOS 13.5+
- VLM_VLLM_ENGINE = "vlm-vllm-engine" # Local vLLM engine, requires local GPU
- VLM_VLLM_ASYNC_ENGINE = "vlm-vllm-async-engine" # Asynchronous vLLM engine, new in MinerU API
- VLM_LMDEPLOY_ENGINE = "vlm-lmdeploy-engine" # LMDeploy engine
- VLM_HTTP_CLIENT = "vlm-http-client" # HTTP client for remote vLLM server (CPU only)
+ PIPELINE = "pipeline"
+ VLM_ENGINE = "vlm-engine"
+ HYBRID_ENGINE = "hybrid-engine"
+ VLM_HTTP_CLIENT = "vlm-http-client"
+ HYBRID_HTTP_CLIENT = "hybrid-http-client"
class MinerULanguage(StrEnum):
@@ -239,7 +237,7 @@ class MinerUParser(RAGFlowPdfParser):
def check_installation(self, backend: str = "pipeline", server_url: Optional[str] = None) -> tuple[bool, str]:
reason = ""
- valid_backends = ["pipeline", "vlm-http-client", "vlm-transformers", "vlm-vllm-engine", "vlm-mlx-engine", "vlm-vllm-async-engine", "vlm-lmdeploy-engine"]
+ valid_backends = [b.value for b in MinerUBackend]
if backend not in valid_backends:
reason = f"[MinerU] Invalid backend '{backend}'. Valid backends are: {valid_backends}"
self.logger.warning(reason)
@@ -262,17 +260,17 @@ class MinerUParser(RAGFlowPdfParser):
self.logger.warning(reason)
return False, reason
- if backend == "vlm-http-client":
+ if backend in (MinerUBackend.VLM_HTTP_CLIENT, MinerUBackend.HYBRID_HTTP_CLIENT):
resolved_server = server_url or self.mineru_server_url
if not resolved_server:
- reason = "[MinerU] MINERU_SERVER_URL required for vlm-http-client backend."
+ reason = f"[MinerU] MINERU_SERVER_URL required for {backend} backend."
self.logger.warning(reason)
return False, reason
try:
server_ok = self._is_http_endpoint_valid(resolved_server)
- self.logger.info(f"[MinerU] vlm-http-client server check reachable={server_ok} url={resolved_server}")
+ self.logger.info(f"[MinerU] {backend} server check reachable={server_ok} url={resolved_server}")
except Exception as exc:
- self.logger.warning(f"[MinerU] vlm-http-client server probe failed: {resolved_server}: {exc}")
+ self.logger.warning(f"[MinerU] {backend} server probe failed: {resolved_server}: {exc}")
return True, reason
diff --git a/docs/faq.mdx b/docs/faq.mdx
index 0562bb3e34..9d865efd6c 100644
--- a/docs/faq.mdx
+++ b/docs/faq.mdx
@@ -653,20 +653,18 @@ To improve response speed:
### How to use MinerU to parse PDF documents?
-From v0.22.0 onwards, RAGFlow includes MinerU (≥ 2.6.3) as an optional PDF parser of multiple backends. Please note that RAGFlow acts only as a *remote client* for MinerU, calling the MinerU API to parse PDFs and reading the returned files. To use this feature:
+From v0.22.0 onwards, RAGFlow includes MinerU (≥ 3.3.0) as an optional PDF parser of multiple backends. Please note that RAGFlow acts only as a *remote client* for MinerU, calling the MinerU API to parse PDFs and reading the returned files. To use this feature:
-1. Prepare a reachable MinerU API service (FastAPI server).
+1. Prepare a reachable MinerU API service (FastAPI server, MinerU ≥ 3.3.0).
2. In the **.env** file or from the **Model providers** page in the UI, configure RAGFlow as a remote client to MinerU:
- `MINERU_APISERVER`: The MinerU API endpoint (e.g., `http://mineru-host:8886`).
- - `MINERU_BACKEND`: The MinerU backend:
+ - `MINERU_BACKEND`: The MinerU backend (matches current MinerU API / CLI `-b` values):
- `"pipeline"` (default)
+ - `"vlm-engine"`
+ - `"hybrid-engine"`
- `"vlm-http-client"`
- - `"vlm-transformers"`
- - `"vlm-vllm-engine"`
- - `"vlm-mlx-engine"`
- - `"vlm-vllm-async-engine"`
- - `"vlm-lmdeploy-engine"`.
- - `MINERU_SERVER_URL`: (optional) The downstream vLLM HTTP server (e.g., `http://vllm-host:30000`). Applicable when `MINERU_BACKEND` is set to `"vlm-http-client"`.
+ - `"hybrid-http-client"`.
+ - `MINERU_SERVER_URL`: Required when `MINERU_BACKEND` is `"vlm-http-client"` or `"hybrid-http-client"`; unused for other backends. The downstream OpenAI-compatible HTTP server (e.g., `http://vllm-host:30000`).
- `MINERU_OUTPUT_DIR`: (optional) The local directory for holding the outputs of the MinerU API service (zip/JSON) before ingestion.
- `MINERU_DELETE_OUTPUT`: Whether to delete temporary output when a temporary directory is used:
- `1`: Delete.
@@ -679,6 +677,10 @@ From v0.22.0 onwards, RAGFlow includes MinerU (≥ 2.6.3) as an optional PDF pa
All MinerU environment variables are optional. When set, these values are used to auto-provision a MinerU OCR model for the tenant on first use. To avoid auto-provisioning, skip the environment variable settings and only configure MinerU from the **Model providers** page in the UI.
:::
+:::caution WARNING
+**Upgrade note:** Older backend names (`vlm-transformers`, `vlm-vllm-engine`, `vlm-mlx-engine`, `vlm-vllm-async-engine`, `vlm-lmdeploy-engine`) are no longer accepted. After upgrading, re-select a current backend in **Model providers** (or update `MINERU_BACKEND`) and ensure your MinerU API service is ≥ 3.3.0.
+:::
+
:::caution WARNING
Third-party visual models are marked **Experimental**, because we have not fully tested these models for the aforementioned data extraction tasks.
:::
@@ -691,14 +693,14 @@ The table below summarizes the most frequently used MinerU environment variables
| Environment variable | Description | Default | Example |
| ---------------------- | ---------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------- |
| `MINERU_APISERVER` | URL of the MinerU API service | _unset_ | `MINERU_APISERVER=http://your-mineru-server:8886` |
-| `MINERU_BACKEND` | MinerU parsing backend | `pipeline` | `MINERU_BACKEND=pipeline\|vlm-transformers\|vlm-vllm-engine\|vlm-mlx-engine\|vlm-vllm-async-engine\|vlm-http-client` |
-| `MINERU_SERVER_URL` | URL of remote vLLM server (for `vlm-http-client`) | _unset_ | `MINERU_SERVER_URL=http://your-vllm-server-ip:30000` |
+| `MINERU_BACKEND` | MinerU parsing backend | `pipeline` | `MINERU_BACKEND=pipeline\|vlm-engine\|hybrid-engine\|vlm-http-client\|hybrid-http-client` |
+| `MINERU_SERVER_URL` | Required for `vlm-http-client` / `hybrid-http-client`; unused otherwise | _unset_ | `MINERU_SERVER_URL=http://your-vllm-server-ip:30000` |
| `MINERU_OUTPUT_DIR` | Directory for MinerU output files | System-defined temporary directory | `MINERU_OUTPUT_DIR=/home/ragflow/mineru/output` |
| `MINERU_DELETE_OUTPUT` | Whether to delete MinerU output directory when a temp dir is used | `1` (delete temp output) | `MINERU_DELETE_OUTPUT=0` |
1. Set `MINERU_APISERVER` to point RAGFlow to your MinerU API server.
2. Set `MINERU_BACKEND` to specify a parsing backend.
-3. If using the `"vlm-http-client"` backend, set `MINERU_SERVER_URL` to your vLLM server's URL. MinerU API expects `backend=vlm-http-client` and `server_url=http://<server>:30000` in the request body.
+3. If using `"vlm-http-client"` or `"hybrid-http-client"`, set `MINERU_SERVER_URL` to your OpenAI-compatible server's URL. MinerU API expects `backend=<http-client-backend>` and `server_url=http://<server>:30000` in the request body.
4. Set `MINERU_OUTPUT_DIR` to specify where RAGFlow stores MinerU API output; otherwise, a system temp directory is used.
5. Set `MINERU_DELETE_OUTPUT` to `0` to keep MinerU's temp output (useful for debugging).
@@ -710,19 +712,19 @@ For information about other environment variables natively supported by MinerU,
### How to use MinerU with a vLLM server for document parsing?
-RAGFlow supports MinerU's `vlm-http-client` backend, enabling you to delegate document parsing tasks to a remote vLLM server while calling MinerU via HTTP. To configure:
+RAGFlow supports MinerU's `vlm-http-client` and `hybrid-http-client` backends, enabling you to delegate document parsing tasks to a remote OpenAI-compatible server (for example vLLM) while calling MinerU via HTTP. To configure:
1. Ensure a MinerU API service is reachable (for example `http://mineru-host:8886`).
-2. Set up or point to a vLLM HTTP server (for example `http://vllm-host:30000`).
+2. Set up or point to an OpenAI-compatible HTTP server (for example `http://vllm-host:30000`).
3. Configure the following in your **docker/.env** file (or your shell if running from source):
- `MINERU_APISERVER=http://mineru-host:8886`
- - `MINERU_BACKEND="vlm-http-client"`
+ - `MINERU_BACKEND="vlm-http-client"` (or `"hybrid-http-client"`)
- `MINERU_SERVER_URL="http://vllm-host:30000"`
- MinerU API calls expect `backend=vlm-http-client` and `server_url=http://<server>:30000` in the request body.
+ MinerU API calls expect `backend=vlm-http-client` (or `hybrid-http-client`) and `server_url=http://<server>:30000` in the request body.
4. Configure `MINERU_OUTPUT_DIR` / `MINERU_DELETE_OUTPUT` as desired to manage the returned zip/JSON before ingestion.
:::tip NOTE
-When using the `vlm-http-client` backend, the RAGFlow server requires no GPU, only network connectivity. This enables cost-effective distributed deployment with multiple RAGFlow instances sharing one remote vLLM server.
+When using an `*-http-client` backend, the RAGFlow server requires no GPU, only network connectivity. This enables cost-effective distributed deployment with multiple RAGFlow instances sharing one remote inference server.
:::
### How to use an external Docling Serve server for document parsing?
diff --git a/test/unit_test/deepdoc/parser/test_mineru_parser.py b/test/unit_test/deepdoc/parser/test_mineru_parser.py
index fc974a87b6..cc5125033c 100644
--- a/test/unit_test/deepdoc/parser/test_mineru_parser.py
+++ b/test/unit_test/deepdoc/parser/test_mineru_parser.py
@@ -928,3 +928,29 @@ def test_read_output_keeps_original_tag_when_middle_json_has_single_table_positi
assert module.MinerUParser.extract_positions(line_tag) == [
([0], 20.0, 170.0, 40.0, 340.0),
]
+
+
+def test_mineru_backend_matches_public_api(monkeypatch):
+ module = _load_mineru_parser(monkeypatch)
+ assert {b.value for b in module.MinerUBackend} == {
+ "pipeline",
+ "vlm-engine",
+ "hybrid-engine",
+ "vlm-http-client",
+ "hybrid-http-client",
+ }
+
+
+def test_check_installation_requires_server_url_for_hybrid_http_client(monkeypatch):
+ module = _load_mineru_parser(monkeypatch)
+ parser = module.MinerUParser(mineru_api="http://mineru.local")
+ monkeypatch.setattr(
+ module.MinerUParser,
+ "_is_http_endpoint_valid",
+ staticmethod(lambda url, timeout=5: True),
+ )
+
+ ok, reason = parser.check_installation("hybrid-http-client", server_url=None)
+
+ assert ok is False
+ assert "MINERU_SERVER_URL" in reason
diff --git a/web/src/locales/en.ts b/web/src/locales/en.ts
index e16c2a5890..a0f2a54893 100644
--- a/web/src/locales/en.ts
+++ b/web/src/locales/en.ts
@@ -2234,7 +2234,7 @@ Example: Virtual Hosted Style`,
modelNameRequired: 'Model name is required',
apiServerRequired: 'MinerU API Server Configuration is required',
serverUrlBackendLimit:
- 'MinerU Server URL Address is only available for the HTTP client backend',
+ 'MinerU server URL is only available for vlm-http-client and hybrid-http-client backends',
apiserver: 'MinerU API Server Configuration',
outputDir: 'MinerU Output Directory Path',
backend: 'MinerU Processing Backend Type',
diff --git a/web/src/locales/zh.ts b/web/src/locales/zh.ts
index b322fbaed1..1f9283c625 100644
--- a/web/src/locales/zh.ts
+++ b/web/src/locales/zh.ts
@@ -1851,7 +1851,8 @@ NER:使用 spaCy NER 和基于规则的关键词提取来抽取 Entities 和 R
mineru: {
modelNameRequired: '模型名称为必填项',
apiServerRequired: 'MinerU API服务器配置为必填项',
- serverUrlBackendLimit: '仅在 backend 为 vlm-http-client 时可填写',
+ serverUrlBackendLimit:
+ '仅在 backend 为 vlm-http-client 或 hybrid-http-client 时可填写',
apiserver: 'MinerU API 服务器配置',
outputDir: 'MinerU 输出目录路径',
backend: 'MinerU 处理后端类型',
diff --git a/web/src/pages/user-setting/setting-model/provider-schema/field-config/provider-config-map.ts b/web/src/pages/user-setting/setting-model/provider-schema/field-config/provider-config-map.ts
index a09cd4c3cd..5d5ea9bd03 100644
--- a/web/src/pages/user-setting/setting-model/provider-schema/field-config/provider-config-map.ts
+++ b/web/src/pages/user-setting/setting-model/provider-schema/field-config/provider-config-map.ts
@@ -19,6 +19,19 @@ import { LLMFactory } from '@/constants/llm';
import type { ProviderConfig } from '../types';
import { parseApiKeyAsObject } from './utils';
+const buildMineruApiKey = (values: Record<string, any>) => {
+ const cfg: Record<string, any> = { ...values };
+ delete cfg.instance_name;
+ cfg.mineru_delete_output = values.mineru_delete_output ? '1' : '0';
+ if (
+ values.mineru_backend !== 'vlm-http-client' &&
+ values.mineru_backend !== 'hybrid-http-client'
+ ) {
+ delete cfg.mineru_server_url;
+ }
+ return cfg;
+};
+
/**
* Factory configuration mapping table
* key: LLMFactory value
@@ -659,12 +672,10 @@ export const ProviderConfigMap: Record<string, ProviderConfig> = {
placeholder: 'mineruSelectBackend',
options: [
{ label: 'pipeline', value: 'pipeline' },
- { label: 'vlm-transformers', value: 'vlm-transformers' },
- { label: 'vlm-vllm-engine', value: 'vlm-vllm-engine' },
+ { label: 'vlm-engine', value: 'vlm-engine' },
+ { label: 'hybrid-engine', value: 'hybrid-engine' },
{ label: 'vlm-http-client', value: 'vlm-http-client' },
- { label: 'vlm-mlx-engine', value: 'vlm-mlx-engine' },
- { label: 'vlm-vllm-async-engine', value: 'vlm-vllm-async-engine' },
- { label: 'vlm-lmdeploy-engine', value: 'vlm-lmdeploy-engine' },
+ { label: 'hybrid-http-client', value: 'hybrid-http-client' },
],
validation: { message: 'mineruBackendMessage' },
},
@@ -675,7 +686,8 @@ export const ProviderConfigMap: Record<string, ProviderConfig> = {
required: false,
placeholder: 'mineruServerUrlPlaceholder',
shouldRender: (values: any) =>
- values?.mineru_backend === 'vlm-http-client',
+ values?.mineru_backend === 'vlm-http-client' ||
+ values?.mineru_backend === 'hybrid-http-client',
validation: { message: 'mineruServerUrlMessage' },
},
{
@@ -686,34 +698,18 @@ export const ProviderConfigMap: Record<string, ProviderConfig> = {
defaultValue: true,
},
],
- verifyTransform: (values) => {
- const cfg: Record<string, any> = { ...values };
- delete cfg.instance_name;
- cfg.mineru_delete_output = values.mineru_delete_output ? '1' : '0';
- if (values.mineru_backend !== 'vlm-http-client') {
- delete cfg.mineru_server_url;
- }
- return {
- apiKey: cfg,
- baseUrl: values.mineru_apiserver,
- modelInfo: [],
- };
- },
- submitTransform: (values) => {
- const cfg: Record<string, any> = { ...values };
- delete cfg.instance_name;
- cfg.mineru_delete_output = values.mineru_delete_output ? '1' : '0';
- if (values.mineru_backend !== 'vlm-http-client') {
- delete cfg.mineru_server_url;
- }
- return {
- instance_name: values.instance_name,
- llm_factory: LLMFactory.MinerU,
- api_key: cfg,
- base_url: '',
- model_info: [],
- };
- },
+ verifyTransform: (values) => ({
+ apiKey: buildMineruApiKey(values),
+ baseUrl: values.mineru_apiserver,
+ modelInfo: [],
+ }),
+ submitTransform: (values) => ({
+ instance_name: values.instance_name,
+ llm_factory: LLMFactory.MinerU,
+ api_key: buildMineruApiKey(values),
+ base_url: '',
+ model_info: [],
+ }),
echoTransform: (instance) => {
const obj = parseApiKeyAsObject(instance.api_key) ?? {};
const rawDelete = obj.mineru_delete_output;