feat(pdf): add mineru-first strategy for MinerU-priority fallback

[q2000s]

Enhancement: Add mineru-first strategy for MinerU-priority fallback

Motivation

PR #4725 引入了 mineru_api_mode (auto/sync/async) 来支持 MinerU 的三种协议形态，非常棒的功能。但在实际部署中发现一个需求缺口：

当前 auto 策略的行为是 本地 pdfplumber 优先 → MinerU 回退。但对于需要高精度解析的场景（复杂版面、表格、公式），用户可能希望 MinerU 优先 → 本地 pdfplumber 回退。

在本地测试中，MinerU 的解析质量明显优于 pdfplumber，尤其是：

• 表格结构识别
• 数学公式保留
• 多栏版面处理
• 图片位置关联

因此建议增加 mineru-first 策略。

Changes

1. openviking_cli/utils/config/parser_config.py

# Before:
strategy: str = "auto"  # "local" | "mineru" | "auto"

# After:
strategy: str = "auto"  # "local" | "mineru" | "auto" | "mineru-first"

# Before (validate method):
if self.strategy not in ("local", "mineru", "auto"):
    raise ValueError(
        f"Invalid strategy '{self.strategy}'. Must be 'local', 'mineru', or 'auto'"
    )

# After:
if self.strategy not in ("local", "mineru", "auto", "mineru-first"):
    raise ValueError(
        f"Invalid strategy '{self.strategy}'. Must be 'local', 'mineru', 'auto', or 'mineru-first'"
    )

2. openviking/parse/parsers/pdf.py

# Before:
        if self.config.strategy == "local":
            return await self._convert_local(pdf_path, resource_name=resource_name)

        elif self.config.strategy == "mineru":
            return await self._convert_mineru(pdf_path, resource_name=resource_name)

        elif self.config.strategy == "auto":
            # Try local first
            try:
                return await self._convert_local(pdf_path, resource_name=resource_name)
            except Exception as e:
                logger.warning(f"Local conversion failed: {e}")

                # Fallback to MinerU if configured
                if self.config.mineru_endpoint:
                    logger.info("Falling back to MinerU API")
                    return await self._convert_mineru(pdf_path, resource_name=resource_name)
                else:
                    raise ValueError(
                        f"Local conversion failed and no MinerU endpoint configured: {e}"
                    )

# After:
        if self.config.strategy == "local":
            return await self._convert_local(pdf_path, resource_name=resource_name)

        elif self.config.strategy == "mineru":
            return await self._convert_mineru(pdf_path, resource_name=resource_name)

        elif self.config.strategy == "mineru-first":
            # Try MinerU API first; fall back to local pdfplumber on failure
            try:
                return await self._convert_mineru(pdf_path, resource_name=resource_name)
            except Exception as e:
                logger.warning(f"MinerU API failed: {e}")
                logger.info("Falling back to local pdfplumber")
                return await self._convert_local(pdf_path, resource_name=resource_name)

        elif self.config.strategy == "auto":
            # Try local first
            try:
                return await self._convert_local(pdf_path, resource_name=resource_name)
            except Exception as e:
                logger.warning(f"Local conversion failed: {e}")

                # Fallback to MinerU if configured
                if self.config.mineru_endpoint:
                    logger.info("Falling back to MinerU API")
                    return await self._convert_mineru(pdf_path, resource_name=resource_name)
                else:
                    raise ValueError(
                        f"Local conversion failed and no MinerU endpoint configured: {e}"
                    )

3. openviking/service/core.py

# Before:
        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)
        ) and pdf_config.mineru_api_mode != "async"

        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

# After:
        pdf_config = self._config.pdf
        should_preflight_mineru = (
            pdf_config.strategy in ("mineru", "mineru-first")
            or (pdf_config.strategy == "auto" and pdf_config.mineru_endpoint is not None)
        ) and pdf_config.mineru_api_mode != "async"

        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 in ("mineru", "mineru-first"):
                    raise

Strategy Comparison

Strategy	优先级	回退行为	适用场景
local	本地 only	无	无 MinerU 部署
mineru	MinerU only	无	强制使用 MinerU
auto	本地 → MinerU	本地失败才用 MinerU	默认，兼容现有部署
mineru-first	MinerU → 本地	MinerU 失败才用本地	高精度需求， MinerU 优先

Configuration Example

{
  "pdf": {
    "strategy": "mineru-first",
    "mineru_endpoint": "http://127.0.0.1:8899",
    "mineru_api_mode": "auto",
    "mineru_token": "your-online-api-token"
  }
}

Test Results (Local)

已验证 mineru-first 策略在以下场景正常工作：

1. MinerU API 可用时：使用 MinerU 解析，返回高质量结果
2. MinerU API 不可用时：自动回退到本地 pdfplumber，不中断流程
3. 与 mineru_api_mode: auto 配合：自动检测协议形态（v1-sync/v2-tasks/online-batch）

Summary

This enhancement adds mineru-first as a new strategy option that mirrors the existing auto strategy but with reversed priority. It's a small, self-contained change that gives users more flexibility in balancing quality vs. availability.

[q2000s]

Now, this PR has been compatible with v0.5 of OV. Please take a look.