RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.
Go agent-harnessagent-native-databaseagentic-aiagentic-retrievalagentic-searchaiai-agentscontext-enginecontext-engineeringcontext-managementharness-engineeringknowledge-compilationragretrieval-augmented-generationretrieval-harnesssearch-harness
fix(mineru): align backend names with current MinerU API (#19055)
天海蒼灆792a17cf2091
diff --git a/deepdoc/parser/mineru_parser.py b/deepdoc/parser/mineru_parser.pyindex 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_urlif 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, reasontry: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, reasondiff --git a/docs/faq.mdx b/docs/faq.mdxindex 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 paAll 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 WARNINGThird-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.pyindex 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_positiassert 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 reasondiff --git a/web/src/locales/en.ts b/web/src/locales/en.tsindex 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.tsindex b322fbaed1..1f9283c625 100644--- a/web/src/locales/zh.ts+++ b/web/src/locales/zh.ts@@ -1851,7 +1851,8 @@ NER:使用 spaCy NER 和基于规则的关键词提取来抽取 Entities 和 Rmineru: {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.tsindex 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;