Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
feat(pdf): refactor MinerU parsing to the official file_parse API (#3953)
Zonas Zhou6e77291265be
diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.mdindex f27398883..ad10a71d6 100644--- a/docs/en/guides/01-configuration.md+++ b/docs/en/guides/01-configuration.md@@ -882,6 +882,34 @@ Use `github_domains`, `gitlab_domains`, or `azure_devops_domains` when the hostneeds those platform-specific URL semantics. Add other Git hosts to`code_hosting_domains`.++PDF parsing configuration. Three strategies are supported: `local` (local pdfplumber), `mineru` (remote MinerU API), and `auto` (try local first, fall back to MinerU).++```json+{+ "pdf": {+ "strategy": "auto",+ "mineru_endpoint": "http://127.0.0.1:8000",+ "mineru_timeout": 300.0,+ "mineru_bodys": {+ "backend": "hybrid-auto-engine",+ "lang_list": ["ch"],+ "parse_method": "auto"+ }+ }+}+```++| Parameter | Type | Description |+|-----------|------|-------------|+| `strategy` | str | Parsing strategy: `local` / `mineru` / `auto` (default `auto`) |+| `mineru_endpoint` | str | MinerU API **base URL** (e.g. `http://127.0.0.1:8000`) |+| `mineru_timeout` | float | Request timeout in seconds (default `300.0`) |+| `mineru_bodys` | dict | MinerU API multipart form fields |++**MinerU protocol**: a synchronous `POST {mineru_endpoint}/file_parse` request with the PDF as the multipart `files` field; form parameters are passed through from `mineru_bodys`.+### rerankReranking model for search result refinement. Supports VikingDB (Volcengine), Cohere, and OpenAI-compatible APIs.diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.mdindex dd4116536..a3ada0f23 100644--- a/docs/zh/guides/01-configuration.md+++ b/docs/zh/guides/01-configuration.md@@ -850,6 +850,34 @@ ollama pull guoxuter/ov_intent_analysis_sft:v7_q8需要 GitHub、GitLab 或 Azure DevOps 专属 URL 语义时,应配置到对应的平台字段;其他 Git 主机统一添加到 `code_hosting_domains`。++PDF 解析配置。支持三种策略:`local`(本地 pdfplumber)、`mineru`(远程 MinerU API)、`auto`(先本地、失败回退 MinerU)。++```json+{+ "pdf": {+ "strategy": "auto",+ "mineru_endpoint": "http://127.0.0.1:8000",+ "mineru_timeout": 300.0,+ "mineru_bodys": {+ "backend": "hybrid-auto-engine",+ "lang_list": ["ch"],+ "parse_method": "auto"+ }+ }+}+```++| 参数 | 类型 | 说明 |+|------|------|------|+| `strategy` | str | 解析策略:`local` / `mineru` / `auto`(默认 `auto`) |+| `mineru_endpoint` | str | MinerU API **base URL**(如 `http://127.0.0.1:8000`) |+| `mineru_timeout` | float | 请求超时秒数(默认 `300.0`) |+| `mineru_bodys` | dict | MinerU API multipart form 参数 |++**MinerU 协议**:同步调用 `POST {mineru_endpoint}/file_parse`,multipart 文件字段为 `files`,form 参数由 `mineru_bodys` 透传。+### rerank用于搜索结果精排的 Rerank 模型。支持 VikingDB (火山引擎)、Cohere 和 OpenAI 兼容接口。diff --git a/examples/ov.conf.example b/examples/ov.conf.exampleindex d54a08e1d..52a3d6a2c 100644--- a/examples/ov.conf.example+++ b/examples/ov.conf.example@@ -228,9 +228,13 @@"max_section_size": 4000,"section_size_flexibility": 0.3,"max_section_chars": 6000,- "mineru_endpoint": "https://mineru.example.com/api/v1",- "mineru_api_key": "{your-mineru-api-key}",+ "mineru_endpoint": "http://127.0.0.1:8000","mineru_timeout": 300.0,+ "mineru_bodys": {+ "backend": "hybrid-auto-engine",+ "lang_list": ["ch"],+ "parse_method": "auto"+ },},"code": {"github_raw_domain": "raw.githubusercontent.com",diff --git a/openviking/parse/parsers/pdf.py b/openviking/parse/parsers/pdf.pyindex 4d7acca20..f299a0680 100644--- a/openviking/parse/parsers/pdf.py+++ b/openviking/parse/parsers/pdf.py@@ -13,6 +13,7 @@ to the MarkdownParser after conversion."""import asyncio+import base64import hashlibimport ioimport re@@ -29,6 +30,7 @@ from openviking.parse.base import (lazy_import,)from openviking.parse.parsers.base_parser import BaseParser+from openviking.utils.time_utils import parse_iso_datetimefrom openviking_cli.utils import get_loggerfrom openviking_cli.utils.config.parser_config import PDFConfig@@ -57,8 +59,7 @@ class PDFParser(BaseParser):>>> # Remote API parsing>>> config = PDFConfig(... strategy="mineru",- ... mineru_endpoint="https://api.example.com/convert",- ... mineru_api_key="key"+ ... mineru_endpoint="http://127.0.0.1:8000"... )>>> parser = PDFParser(config)>>> result = await parser.parse("document.pdf")@@ -682,27 +683,38 @@ class PDFParser(BaseParser):async def _convert_mineru(self,pdf_path: Path,+ storage=None,resource_name: Optional[str] = None,) -> tuple[str, Dict[str, Any]]:"""- Convert PDF to Markdown using MinerU API.+ Convert PDF to Markdown using the MinerU /file_parse API.Args:pdf_path: Path to PDF file- resource_name: Optional resource name (unused in MinerU conversion)+ storage: Media storage used to persist extracted images; defaults to+ the configured storage if None+ resource_name: Resource name under which extracted images are saved;+ defaults to the PDF stemReturns:- Tuple of (markdown_content, metadata)+ Tuple of (markdown_content, metadata) where metadata includes+ strategy, endpoint, api_version, backend, task_id, processing_time+ (seconds) and images_savedRaises:- ImportError: If httpx not installed- Exception: If API call fails+ ValueError: If MinerU endpoint is not configured, or the task does+ not complete+ Exception: If the API call fails"""httpx = lazy_import("httpx")if not self.config.mineru_endpoint:raise ValueError("MinerU endpoint not configured")+ # mineru_endpoint is a base URL; append /file_parse unless it already ends with it+ base = self.config.mineru_endpoint.rstrip("/")+ url = base if base.endswith("/file_parse") else f"{base}/file_parse"+meta = {"strategy": "mineru","endpoint": self.config.mineru_endpoint,@@ -713,44 +725,86 @@ class PDFParser(BaseParser):async with httpx.AsyncClient(timeout=self.config.mineru_timeout) as client:# Prepare file uploadwith open(pdf_path, "rb") as f:- files = {"file": (pdf_path.name, f, "application/pdf")}+ files = {"files": (pdf_path.name, f, "application/pdf")}- # Prepare headers- headers = {}- if self.config.mineru_api_key:- headers["Authorization"] = f"Bearer {self.config.mineru_api_key}"+ # Prepare Form fields+ data: Dict[str, Any] = dict(self.config.mineru_bodys or {})- # Prepare request params- params = self.config.mineru_params or {}+ # MinerU must return extracted images for the markdown refs.+ data["return_images"] = True# Make API request- logger.info(f"Calling MinerU API: {self.config.mineru_endpoint}")+ logger.info(f"Calling MinerU API: {url}")response = await client.post(- self.config.mineru_endpoint,+ url,files=files,- headers=headers,- params=params,+ data=data,)response.raise_for_status()- # Parse response- result = response.json()- markdown_content = result.get("markdown", "")+ # Parse response+ result = response.json()+ if result.get("status") != "completed":+ raise ValueError(f"MinerU task not completed: {result.get('status')}")++ results = result.get("results") or {}+ file_result = results.get(pdf_path.name) or next(iter(results.values()), {})+ markdown_content = file_result.get("md_content") or ""++ # Extract metadata from response+ meta["api_version"] = result.get("version")+ meta["backend"] = result.get("backend")+ meta["task_id"] = result.get("task_id")+ started_at, completed_at = result.get("started_at"), result.get("completed_at")+ if started_at and completed_at:+ meta["processing_time"] = (+ parse_iso_datetime(completed_at) - parse_iso_datetime(started_at)+ ).total_seconds()++ if not markdown_content:+ logger.warning(f"MinerU returned empty content for {pdf_path}")+ return markdown_content, meta- # Extract metadata from response- meta["api_version"] = result.get("version")- meta["processing_time"] = result.get("processing_time")- meta["total_pages"] = result.get("total_pages")+ if storage is None:+ from openviking_cli.utils.storage import get_storage- if not markdown_content:- logger.warning(f"MinerU returned empty content for {pdf_path}")+ storage = get_storage()- logger.info(- f"MinerU conversion: {meta.get('total_pages', '?')} pages → "- f"{len(markdown_content)} chars"+ if resource_name is None:+ resource_name = pdf_path.stem++ # MinerU embeds images as base64 data-URLs, referenced from markdown+ # as `images/<filename>`; save them into the media store and rewrite+ # the references to the stored relative paths.+ repl: Dict[str, str] = {}+ media_dir = storage.media_dir+ for img_name, data_url in (file_result.get("images") or {}).items():+ try:+ # data URL form: "data:image/jpeg;base64,<b64>"+ image_bytes = base64.b64decode(data_url.split(",", 1)[-1])+ img_path = Path(img_name)+ image_path = storage.save_image(+ resource_name,+ image_bytes,+ filename=img_path.stem,+ extension=img_path.suffix or ".png",+ )+ repl[f"images/{img_name}"] = image_path.relative_to(media_dir).as_posix()+ except Exception as img_err:+ logger.warning(f"Failed to save MinerU image {img_name}: {img_err}")++ if repl:+ # Single pass over the markdown replaces every known reference;+ # unknown ``images/...`` text is left untouched.+ ref_pattern = re.compile(+ "|".join(re.escape(ref) for ref in sorted(repl, key=len, reverse=True)))+ markdown_content = ref_pattern.sub(lambda m: repl[m.group(0)], markdown_content)+ meta["images_saved"] = len(repl)- return markdown_content, meta+ logger.info(f"MinerU conversion: {len(markdown_content)} chars")++ return markdown_content, metaexcept Exception as e:logger.error(f"MinerU API call failed: {e}")diff --git a/openviking/service/core.py b/openviking/service/core.pyindex 3cfdc9f8d..3b8a9994b 100644--- a/openviking/service/core.py+++ b/openviking/service/core.py@@ -19,6 +19,7 @@ from openviking.server.identity import RequestContext, Rolefrom openviking.service.agent_evolution_service import AgentEvolutionServicefrom openviking.service.debug_service import DebugServicefrom openviking.service.fs_service import FSService+from openviking.service.mineru_preflight import wait_for_mineru_readyfrom openviking.service.pack_service import PackServicefrom openviking.service.relation_service import RelationServicefrom openviking.service.resource_memory_link_service import ResourceMemoryLinkService@@ -497,6 +498,25 @@ class OpenVikingService:self._queue_manager.start()logger.info("QueueManager workers started")+ # Preflight the MinerU endpoint when it will be used, so endpoint+ # misconfiguration or a stopped service surfaces now instead of on the+ # first PDF import. Required for strategy="mineru"; advisory for "auto".+ pdf_config = self._config.pdf+ should_preflight_mineru = pdf_config.strategy == "mineru" or (+ pdf_config.strategy == "auto" and pdf_config.mineru_endpoint is not None+ )++ if should_preflight_mineru and pdf_config.mineru_endpoint:+ try:+ await wait_for_mineru_ready(pdf_config.mineru_endpoint)+ logger.info("MinerU preflight passed: %s", pdf_config.mineru_endpoint)+ except RuntimeError as exc:+ if pdf_config.strategy == "mineru":+ raise+ logger.warning(+ "MinerU preflight failed (fallback will retry on first parse): %s", exc+ )+self._initialized = Truelogger.info("OpenVikingService initialized")diff --git a/openviking/service/mineru_preflight.py b/openviking/service/mineru_preflight.pynew file mode 100644index 000000000..1b12693e8--- /dev/null+++ b/openviking/service/mineru_preflight.py@@ -0,0 +1,68 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0+"""+Startup preflight for the MinerU API.++Polls the MinerU ``/health`` endpoint so that endpoint misconfiguration, a+stopped service, or a protocol incompatibility is surfaced at service+initialization instead of on the first PDF import.+"""++import asyncio+import time++import httpx++HEALTH_TIMEOUT = 5.0 # Total polling timeout in seconds.+HEALTH_POLL_INTERVAL = 0.2 # Delay between polls in seconds.+HEALTH_REQUEST_TIMEOUT = 0.5 # Per-request timeout in seconds.+++async def wait_for_mineru_ready(endpoint: str, timeout: float = HEALTH_TIMEOUT) -> None:+ """+ Poll the MinerU ``/health`` endpoint until it reports ready.++ A healthy response is HTTP 200 with a JSON object carrying a non-empty+ ``protocol_version`` and ``status == "healthy"``.++ Args:+ endpoint: MinerU base URL (e.g. ``http://127.0.0.1:8000``).+ timeout: Total time to poll before giving up, in seconds.++ Raises:+ RuntimeError: If the endpoint does not report ready within ``timeout``+ seconds. The message includes the health URL and the last error.+ """+ health_url = f"{endpoint.rstrip('/')}/health"+ deadline = time.monotonic() + timeout+ last_error = "no response"++ async with httpx.AsyncClient(timeout=HEALTH_REQUEST_TIMEOUT) as client:+ while time.monotonic() < deadline:+ try:+ response = await client.get(health_url)+ payload = response.json()+ except (httpx.HTTPError, ValueError) as exc:+ last_error = str(exc) or exc.__class__.__name__+ else:+ if isinstance(payload, dict):+ protocol = payload.get("protocol_version")+ status = payload.get("status")+ else:+ protocol = status = None++ if response.status_code == 200 and protocol and status == "healthy":+ return++ last_error = (+ f"unexpected response: HTTP {response.status_code}, "+ f"protocol_version={protocol!r}, status={status!r}"+ )++ await asyncio.sleep(HEALTH_POLL_INTERVAL)++ raise RuntimeError(+ f"MinerU startup preflight failed for {health_url} after {timeout}s. "+ f"Last error: {last_error}. "+ "Start a compatible mineru-api service or correct pdf.mineru_endpoint."+ )diff --git a/openviking_cli/utils/config/parser_config.py b/openviking_cli/utils/config/parser_config.pyindex 83fd271c2..1ac59cef6 100644--- a/openviking_cli/utils/config/parser_config.py+++ b/openviking_cli/utils/config/parser_config.py@@ -148,18 +148,16 @@ class PDFConfig(ParserConfig):Attributes:strategy: Parsing strategy ("local" | "mineru" | "auto")mineru_endpoint: MinerU API endpoint URL- mineru_api_key: MinerU API authentication keymineru_timeout: MinerU request timeout in seconds- mineru_params: Additional MinerU API parameters+ mineru_bodys: Additional MinerU API multipart form fields"""strategy: str = "auto" # "local" | "mineru" | "auto"# MinerU API configurationmineru_endpoint: Optional[str] = None # API endpoint URL- mineru_api_key: Optional[str] = None # API authentication keymineru_timeout: float = 300.0 # Request timeout in seconds (5 minutes)- mineru_params: Optional[dict] = None # Additional API parameters+ mineru_bodys: Optional[dict] = None # Additional API multipart form fields# Heading detection configurationheading_detection: str = "auto" # "bookmarks" | "font" | "auto" | "none"diff --git a/tests/unit/test_mineru_preflight.py b/tests/unit/test_mineru_preflight.pynew file mode 100644index 000000000..0e7d08152--- /dev/null+++ b/tests/unit/test_mineru_preflight.py@@ -0,0 +1,117 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0+"""Unit tests for the MinerU startup preflight (wait_for_mineru_ready)."""++import httpx+import pytest++from openviking.service.mineru_preflight import wait_for_mineru_ready++ENDPOINT = "http://127.0.0.1:8000"+HEALTH_URL = "http://127.0.0.1:8000/health"+++class _FakeResponse:+ def __init__(self, status_code=200, payload=None, json_error=None):+ self.status_code = status_code+ self._payload = payload+ self._json_error = json_error++ def json(self):+ if self._json_error is not None:+ raise self._json_error+ return self._payload+++def _make_fake_client(get_handler):+ class _FakeClient:+ def __init__(self, **kwargs):+ self.kwargs = kwargs++ async def __aenter__(self):+ return self++ async def __aexit__(self, *exc):+ return False++ async def get(self, url):+ return get_handler(url)++ return _FakeClient+++def patch_httpx(monkeypatch):+ def _apply(get_handler):+ monkeypatch.setattr(httpx, "AsyncClient", _make_fake_client(get_handler))++ return _apply+++async def test_ready_immediately(patch_httpx):+ patch_httpx(lambda url: _FakeResponse(payload={"protocol_version": 2, "status": "healthy"}))++ # Should return without raising.+ await wait_for_mineru_ready(ENDPOINT)+++async def test_ready_after_unhealthy(patch_httpx):+ calls = {"count": 0}++ def handler(url):+ calls["count"] += 1+ if calls["count"] == 1:+ return _FakeResponse(status_code=503, payload={"status": "starting"})+ return _FakeResponse(payload={"protocol_version": 2, "status": "healthy"})++ patch_httpx(handler)++ await wait_for_mineru_ready(ENDPOINT)+ assert calls["count"] == 2+++async def test_timeout_raises(patch_httpx):+ patch_httpx(+ lambda url: _FakeResponse(payload={"protocol_version": 2, "status": "unhealthy"})+ )++ with pytest.raises(RuntimeError) as exc_info:+ await wait_for_mineru_ready(ENDPOINT, timeout=0.05)++ message = str(exc_info.value)+ assert HEALTH_URL in message+ assert ENDPOINT in message+ assert "status='unhealthy'" in message+++async def test_network_error_raises(patch_httpx):+ def handler(url):+ raise httpx.ConnectError("connection refused")++ patch_httpx(handler)++ with pytest.raises(RuntimeError) as exc_info:+ await wait_for_mineru_ready(ENDPOINT, timeout=0.05)++ message = str(exc_info.value)+ assert HEALTH_URL in message+ assert "connection refused" in message+++async def test_empty_error_message_falls_back_to_class_name(patch_httpx):+ def handler(url):+ raise httpx.ConnectTimeout("")++ patch_httpx(handler)++ with pytest.raises(RuntimeError) as exc_info:+ await wait_for_mineru_ready(ENDPOINT, timeout=0.05)++ message = str(exc_info.value)+ assert HEALTH_URL in message+ assert "ConnectTimeout" in message