multi-ocr-py 0.1.0__py3-none-any.whl

multi_ocr/__init__.py

@@ -0,0 +1,25 @@
+"""Multi-OCR: 多引擎 OCR 工具包。
+
+同时支持 CLI 工具和 SDK 依赖包两种使用方式。
+
+CLI 使用:
+    multi-ocr <path> [--model MODEL] [--pages PAGES]
+
+SDK 使用:
+    from multi_ocr import get_engine, ocr_file, OCREngine
+
+    engine = get_engine("siliconflow", "deepseek-ai/DeepSeek-OCR", api_key="...")
+    result = ocr_file(Path("mydoc.pdf"), engine)
+"""
+
+from multi_ocr.engines import get_engine
+from multi_ocr.engines.base import OCREngine
+from multi_ocr.single import ocr_file
+from multi_ocr.batch import ocr_directory
+
+__all__ = [
+    "get_engine",
+    "OCREngine",
+    "ocr_file",
+    "ocr_directory",
+]

multi_ocr/batch.py

@@ -0,0 +1,139 @@
+"""批量处理模块：对目录下的图片或 PDF 进行批量 OCR。
+
+目录下只能有一种类型的文件（全图片或全 PDF），混合目录直接报错。
+"""
+
+import sys
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from pathlib import Path
+
+from tqdm import tqdm
+
+from multi_ocr.engines.base import OCREngine
+from multi_ocr.single import ocr_file
+
+# 支持的图片格式
+_IMAGE_EXTENSIONS = {".png", ".jpg", ".jpeg"}
+
+
+def _collect_files(input_dir: Path) -> tuple[list[Path], list[Path]]:
+    """扫描目录，收集图片和 PDF 文件，均按文件名排序。
+
+    Args:
+        input_dir: 输入目录路径。
+
+    Returns:
+        (图片文件路径列表, PDF 文件路径列表)，均已按文件名排序。
+    """
+    images: list[Path] = []
+    pdfs: list[Path] = []
+
+    for entry in sorted(input_dir.iterdir(), key=lambda p: p.name):
+        if not entry.is_file():
+            continue
+        if entry.suffix.lower() in _IMAGE_EXTENSIONS:
+            images.append(entry)
+        elif entry.suffix.lower() == ".pdf":
+            pdfs.append(entry)
+
+    return images, pdfs
+
+
+def _batch_images(
+    input_dir: Path, images: list[Path], engine: OCREngine, concurrency: int = 1
+) -> None:
+    """图片批量处理：逐张识别，合并结果写入 input_dir.md。
+
+    Args:
+        input_dir: 输入目录路径。
+        images: 已排序的图片文件路径列表。
+        engine: OCR 引擎实例。
+        concurrency: 并发数，默认 1（串行）。
+    """
+    if concurrency > 1:
+        results: list[str | None] = [None] * len(images)
+        with ThreadPoolExecutor(max_workers=concurrency) as executor:
+            future_to_idx = {
+                executor.submit(engine.parse_image, img_path): idx
+                for idx, img_path in enumerate(images)
+            }
+            for future in tqdm(
+                as_completed(future_to_idx),
+                total=len(images),
+                desc=f"处理 {input_dir.name} 目录",
+                file=sys.stderr,
+            ):
+                idx = future_to_idx[future]
+                results[idx] = future.result()
+        merged = "\n\n".join(r for r in results if r is not None)
+    else:
+        results = []
+        for img_path in tqdm(
+            images, desc=f"处理 {input_dir.name} 目录", file=sys.stderr
+        ):
+            text = engine.parse_image(img_path)
+            results.append(text)
+        merged = "\n\n".join(results)
+
+    output_path = input_dir.with_suffix(".md")
+    output_path.write_text(merged, encoding="utf-8")
+    print(f"已保存: {output_path}")
+
+
+def _batch_pdfs(pdfs: list[Path], engine: OCREngine, concurrency: int = 1) -> None:
+    """PDF 批量处理：逐文件调用 ocr_file()，各自输出 .md 文件。
+
+    每个 PDF 内部使用页面级并发（concurrency 传递给 ocr_file()）。
+
+    Args:
+        pdfs: 已排序的 PDF 文件路径列表。
+        engine: OCR 引擎实例。
+        concurrency: 页面级并发数，默认 1（串行逐页）。
+    """
+    for pdf_path in pdfs:
+        ocr_file(
+            input_path=pdf_path, engine=engine, pages=None, concurrency=concurrency
+        )
+
+
+def ocr_directory(input_dir: Path, engine: OCREngine, concurrency: int = 1) -> None:
+    """批量处理目录下的图片或 PDF 文件。
+
+    目录下只能有一种类型的文件（全图片或全 PDF），混合目录直接报错。
+
+    根据目录内容与引擎类型自动选择处理分支：
+    - 仅有图片 + 原生 PDF 引擎 → 图片合并为 PDF 再解析（更高效）
+    - 仅有图片 + 其他引擎 → 图片批量流程（合并输出）
+    - 仅有 PDF → PDF 批量流程（各自输出）
+
+    Args:
+        input_dir: 输入目录路径。
+        engine: OCR 引擎实例。
+        concurrency: 并发数，默认 1（串行）。
+
+    Raises:
+        FileNotFoundError: 目录不存在。
+        ValueError: 目录中没有可处理的文件，或包含混合文件类型。
+    """
+    if not input_dir.exists():
+        raise FileNotFoundError(f"目录不存在: {input_dir}")
+    if not input_dir.is_dir():
+        raise NotADirectoryError(f"不是目录: {input_dir}")
+
+    images, pdfs = _collect_files(input_dir)
+
+    # 严格检查：不允许混合文件类型
+    if images and pdfs:
+        raise ValueError(
+            f"目录中包含混合文件类型（图片和 PDF），请确保目录下只有一种类型的文件。\n"
+            f"  图片: {len(images)} 个 (.png/.jpg/.jpeg)\n"
+            f"  PDF:  {len(pdfs)} 个 (.pdf)"
+        )
+
+    if not images and not pdfs:
+        raise ValueError(f"目录中没有可处理的图片或 PDF 文件: {input_dir}")
+
+    if images:
+        _batch_images(input_dir, images, engine, concurrency)
+    else:
+        _batch_pdfs(pdfs, engine, concurrency)

multi_ocr/cli.py

@@ -0,0 +1,206 @@
+"""Multi-OCR: 将 PDF 和图片转换为 markdown 文档。
+
+支持多种 OCR 引擎:
+- SiliconFlow（DeepSeek-OCR / PaddleOCR-VL-1.5）
+- DashScope（Qwen-VL-OCR）
+- LiteParse（本地 PDF 解析）
+- Ollama（本地 DeepSeek-OCR）
+
+用法:
+    python main.py <path> [--model MODEL] [--pages PAGES] [--api-key KEY] [--ollama-url URL]
+
+    <path> 可以是文件或目录：
+    - 文件：单文件模式，自动判断图片/PDF
+    - 目录：批量模式，目录下只能有一种类型的文件（全图片或全 PDF）
+"""
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from multi_ocr.engines import get_engine
+from multi_ocr.single import ocr_file
+from multi_ocr.batch import ocr_directory
+
+DEFAULT_MODEL = "silicon-deepseek-ocr"
+
+# --model 缩写 → (provider, model_name, description)
+MODEL_MAP: dict[str, tuple[str, str, str]] = {
+    "silicon-deepseek-ocr": (
+        "siliconflow",
+        "deepseek-ai/DeepSeek-OCR",
+        "SiliconFlow + DeepSeek-OCR",
+    ),
+    "silicon-paddle-ocr": (
+        "siliconflow",
+        "PaddlePaddle/PaddleOCR-VL-1.5",
+        "SiliconFlow + PaddleOCR-VL-1.5",
+    ),
+    "dashscope-qwen-vl-ocr": ("dashscope", "qwen-vl-ocr", "DashScope + Qwen-VL-OCR"),
+    "liteparse": ("liteparse", "", "LiteParse (本地 PDF 解析)"),
+    "ollama-deepseek-ocr": (
+        "ollama",
+        "deepseek-ocr:latest",
+        "Ollama + DeepSeek-OCR",
+    ),
+}
+
+# provider -> 环境变量名
+_PROVIDER_ENV: dict[str, str] = {
+    "siliconflow": "SILICONFLOW_API_KEY",
+    "dashscope": "DASHSCOPE_API_KEY",
+    # ollama / liteparse 为本地引擎，不需要 API Key
+}
+
+
+def _get_api_key(provider: str, cli_key: str | None) -> str | None:
+    """获取 API Key：命令行 > provider 专用环境变量。
+    Ollama / LiteParse 无需 API Key，返回空字符串。
+    """
+    if cli_key:
+        return cli_key
+    if provider in ("liteparse", "ollama"):
+        return ""  # 本地引擎，无需 API Key
+    env_var = _PROVIDER_ENV[provider]
+    return os.environ.get(env_var)
+
+
+def _build_model_help() -> str:
+    """动态生成 --model 参数的帮助文本。"""
+    lines = [f"模型缩写（默认: {DEFAULT_MODEL}）\n可用模型:"]
+    for alias, (_prov, _model, desc) in MODEL_MAP.items():
+        lines.append(f"  {alias:<25} → {desc}")
+    return "\n".join(lines)
+
+
+def _build_api_key_help() -> str:
+    """动态生成 --api-key 参数的帮助文本。"""
+    lines = ["API Key（根据 --model 自动读取对应环境变量）:"]
+    for provider, env_var in _PROVIDER_ENV.items():
+        lines.append(f"  {provider} 模型 → {env_var}")
+    return "\n".join(lines)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="将 PDF 或图片转换为文字。默认使用 SiliconFlow + DeepSeek-OCR。",
+        formatter_class=argparse.RawTextHelpFormatter,
+    )
+    parser.add_argument(
+        "input",
+        type=Path,
+        help="输入文件路径（PDF 或图片）或目录路径（批量处理）",
+    )
+    parser.add_argument(
+        "--model",
+        default=DEFAULT_MODEL,
+        help=_build_model_help(),
+    )
+    parser.add_argument(
+        "--pages",
+        default=None,
+        help="页码范围，如 1-3,5（仅对单文件 PDF 有效）",
+    )
+    parser.add_argument(
+        "--api-key",
+        default=None,
+        help=_build_api_key_help(),
+    )
+    parser.add_argument(
+        "--ollama-url",
+        default=None,
+        help="Ollama 服务地址（默认读取 OLLAMA_BASE_URL 环境变量，都没有则用 http://127.0.0.1:11434）",
+    )
+    parser.add_argument(
+        "-j",
+        "--concurrency",
+        type=int,
+        default=1,
+        help="并发数量（默认: 1，即串行处理）",
+    )
+    args = parser.parse_args()
+
+    input_path: Path = args.input
+
+    # 校验路径存在
+    if not input_path.exists():
+        print(f"错误: 路径不存在: {input_path}", file=sys.stderr)
+        sys.exit(1)
+
+    # 判断模式：目录 → 批量，文件 → 单文件
+    batch_mode = input_path.is_dir()
+
+    # --pages 约束
+    pages: str | None = args.pages
+    if batch_mode and pages:
+        print("⚠️  --pages 在批量模式下忽略", file=sys.stderr)
+        pages = None
+
+    # 解析 --model 缩写 → provider + model_name
+    entry = MODEL_MAP.get(args.model)
+    if entry is None:
+        valid = ", ".join(MODEL_MAP.keys())
+        print(
+            f"无效的 --model 值 '{args.model}'，可用: {valid}",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    provider, model_name, _desc = entry
+
+    # API Key：命令行 > 环境变量（Ollama / LiteParse 跳过）
+    api_key = _get_api_key(provider, args.api_key)
+    if not api_key and provider not in ("liteparse", "ollama"):
+        env_var = _PROVIDER_ENV.get(provider, "")
+        print(
+            f"请设置 {env_var} 环境变量或使用 --api-key 参数。",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    # 获取 Ollama base_url（仅 ollama 引擎使用）
+    ollama_url = args.ollama_url or os.environ.get("OLLAMA_BASE_URL")
+
+    # 并发数
+    concurrency: int = args.concurrency
+    if concurrency < 1:
+        print("错误: --concurrency 必须 >= 1", file=sys.stderr)
+        sys.exit(1)
+
+    # 获取引擎
+    try:
+        engine = get_engine(
+            provider=provider,
+            model=model_name,
+            api_key=api_key,
+            base_url=ollama_url if provider == "ollama" else None,
+        )
+    except ValueError as e:
+        print(f"引擎初始化失败: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    # 执行 OCR
+    try:
+        if batch_mode:
+            ocr_directory(
+                input_dir=input_path,
+                engine=engine,
+                concurrency=concurrency,
+            )
+        else:
+            ocr_file(
+                input_path=input_path,
+                engine=engine,
+                pages=pages,
+                concurrency=concurrency,
+            )
+    except (FileNotFoundError, NotADirectoryError, ValueError) as e:
+        print(f"错误: {e}", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(f"未预期的错误: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

multi_ocr/engines/__init__.py

@@ -0,0 +1,49 @@
+from multi_ocr.engines.base import OCREngine
+from multi_ocr.engines.dashscope import DashScopeEngine
+from multi_ocr.engines.ollama import OllamaEngine
+from multi_ocr.engines.siliconflow import SiliconFlowEngine
+
+# LiteParse 为可选依赖，仅在已安装时注册
+try:
+    from multi_ocr.engines.liteparse import LiteParseEngine
+
+    _HAS_LITEPARSE = True
+except ImportError:
+    _HAS_LITEPARSE = False
+
+# 引擎注册表：provider 名 -> Engine 类
+# 添加新提供商时只需在此注册
+_registry: dict[str, type[OCREngine]] = {
+    "dashscope": DashScopeEngine,
+    "ollama": OllamaEngine,
+    "siliconflow": SiliconFlowEngine,
+}
+
+if _HAS_LITEPARSE:
+    _registry["liteparse"] = LiteParseEngine
+
+
+def get_engine(
+    provider: str, model: str, api_key: str, base_url: str | None = None
+) -> OCREngine:
+    """工厂函数：按 provider 名查找并实例化 OCR 引擎。
+
+    Args:
+        provider: OCR 服务提供商名称（如 "siliconflow"）。
+        model: 模型名称（如 "deepseek-ai/DeepSeek-OCR"）。
+        api_key: API 密钥。
+        base_url: 自定义 API 地址（当前仅 ollama 引擎使用）。
+
+    Returns:
+        OCREngine 实例。
+
+    Raises:
+        ValueError: 如果 provider 未注册。
+    """
+    engine_cls = _registry.get(provider)
+    if engine_cls is None:
+        available = ", ".join(_registry.keys())
+        raise ValueError(f"未知的 OCR 提供商: {provider}，当前可用: {available}")
+    if base_url is not None:
+        return engine_cls(model=model, api_key=api_key, base_url=base_url)
+    return engine_cls(model=model, api_key=api_key)

multi_ocr/engines/base.py

@@ -0,0 +1,94 @@
+import shutil
+from abc import ABC, abstractmethod
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from pathlib import Path
+from typing import Callable
+
+from multi_ocr.pdf_utils import split_pdf
+
+
+class OCREngine(ABC):
+    """OCR 引擎抽象基类。所有 OCR 引擎必须实现此接口。"""
+
+    @abstractmethod
+    def parse_image(self, image_path: Path) -> str:
+        """对单张图片进行 OCR，返回 markdown 文本。
+
+        Args:
+            image_path: 图片文件路径。
+
+        Returns:
+            识别出的 markdown 文本内容。
+        """
+        ...
+
+    def parse_pdf(
+        self,
+        pdf_path: Path,
+        pages: str | None = None,
+        progress_callback: Callable[[], None] | None = None,
+        concurrency: int = 1,
+    ) -> str:
+        """解析 PDF，返回 markdown 文本。
+
+        默认实现：拆页 → 调用 parse_image() → 合并结果。
+        子类可覆盖以提供原生 PDF 解析（如 LiteParse）。
+
+        Args:
+            pdf_path: PDF 文件路径。
+            pages: 页码范围字符串（如 "1-3,5"），None 表示全部。
+            progress_callback: 每处理完一页时调用（可选）。
+            concurrency: 并发数，默认 1（串行），>1 时使用线程池并发处理多页。
+
+        Returns:
+            解析出的 markdown 文本内容。
+        """
+        image_paths, page_labels = split_pdf(pdf_path, pages)
+        try:
+            if concurrency > 1:
+                results = self._parse_pages_concurrent(
+                    image_paths, page_labels, concurrency, progress_callback
+                )
+            else:
+                results = []
+                for img_path, label in zip(image_paths, page_labels):
+                    text = self.parse_image(img_path)
+                    results.append(f"--- 第 {label} 页 ---\n{text}")
+                    if progress_callback:
+                        progress_callback()
+            return "\n\n".join(results)
+        finally:
+            if image_paths:
+                shutil.rmtree(image_paths[0].parent, ignore_errors=True)
+
+    def _parse_pages_concurrent(
+        self,
+        image_paths: list[Path],
+        page_labels: list[int],
+        concurrency: int,
+        progress_callback: Callable[[], None] | None,
+    ) -> list[str]:
+        """并发解析多页图片，保持页码顺序。
+
+        Args:
+            image_paths: 图片路径列表。
+            page_labels: 页码标签列表（1-based）。
+            concurrency: 并发线程数。
+            progress_callback: 每完成一页时调用（可选）。
+
+        Returns:
+            按页码顺序排列的结果列表，每项格式为 "--- 第 N 页 ---\n{text}"。
+        """
+        results: list[str | None] = [None] * len(image_paths)
+        with ThreadPoolExecutor(max_workers=concurrency) as executor:
+            future_to_idx = {
+                executor.submit(self.parse_image, img_path): idx
+                for idx, img_path in enumerate(image_paths)
+            }
+            for future in as_completed(future_to_idx):
+                idx = future_to_idx[future]
+                text = future.result()
+                results[idx] = f"--- 第 {page_labels[idx]} 页 ---\n{text}"
+                if progress_callback:
+                    progress_callback()
+        return [r for r in results if r is not None]

multi_ocr/engines/dashscope.py

@@ -0,0 +1,85 @@
+import base64
+import re
+from pathlib import Path
+
+from openai import OpenAI
+
+from multi_ocr.engines.base import OCREngine
+
+
+class DashScopeEngine(OCREngine):
+    """DashScope (阿里云百炼) OCR 引擎，兼容 OpenAI SDK。
+
+    支持 Qwen-VL-OCR 模型，通过 OpenAI 兼容接口调用。
+    参考文档：https://help.aliyun.com/zh/model-studio/qwen-ocr
+
+    默认为通用 OCR 场景，如需使用内置任务（高精识别、表格解析、信息抽取等），
+    可参照文档在 prompt 中传入对应指令。
+    """
+
+    BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1"
+
+    # 模型名称 -> 提示词映射（按前缀匹配）
+    _PROMPT_MAP: dict[str, str] = {
+        "qwen-vl-ocr": "OCR this image and output in markdown format.",
+    }
+
+    _FALLBACK_PROMPT = "OCR this image and output in markdown format."
+
+    def __init__(self, model: str, api_key: str, base_url: str | None = None) -> None:
+        self._model = model
+        self._client = OpenAI(
+            api_key=api_key,
+            base_url=base_url or self.BASE_URL,
+            timeout=120.0,
+        )
+
+    def _get_prompt(self) -> str:
+        """根据模型名称匹配对应的提示词，未匹配则使用默认提示词。"""
+        for prefix, prompt in self._PROMPT_MAP.items():
+            if prefix in self._model:
+                return prompt
+        return self._FALLBACK_PROMPT
+
+    def parse_image(self, image_path: Path) -> str:
+        with open(image_path, "rb") as f:
+            image_data = base64.b64encode(f.read()).decode("utf-8")
+
+        # 根据扩展名确定 MIME 类型
+        suffix = image_path.suffix.lower()
+        mime_map = {".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg"}
+        mime_type = mime_map.get(suffix, "image/png")
+
+        data_url = f"data:{mime_type};base64,{image_data}"
+
+        prompt = self._get_prompt()
+
+        response = self._client.chat.completions.create(
+            model=self._model,
+            messages=[
+                {
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "image_url",
+                            "image_url": {"url": data_url},
+                        },
+                        {
+                            "type": "text",
+                            "text": prompt,
+                        },
+                    ],
+                }
+            ],
+        )
+
+        content = response.choices[0].message.content
+        if not content:
+            return ""
+        # 清理模型可能输出的特殊标记
+        content = re.sub(r"<\|/?ref\|>", "", content)
+        content = re.sub(r"<\|/?det\|>", "", content)
+        # 剥离 markdown 代码块包裹（如 ```markdown ... ```）
+        content = re.sub(r"^```(?:markdown)?\s*\n", "", content, count=1)
+        content = re.sub(r"\n```\s*$", "", content)
+        return content.strip()

multi_ocr/engines/liteparse.py

@@ -0,0 +1,60 @@
+from pathlib import Path
+import tempfile
+from typing import Callable
+
+from liteparse import LiteParse as LiteParseLib
+
+from multi_ocr.engines.base import OCREngine
+from multi_ocr.pdf_utils import images_to_pdf
+
+
+class LiteParseEngine(OCREngine):
+    """LiteParse 本地 PDF 解析引擎。
+
+    基于 Rust 实现，无需 API Key、无需联网，直接解析 PDF 并输出 markdown。
+    图片通过自动转换为 PDF 后解析来支持。
+    """
+
+    def __init__(
+        self,
+        model: str = "",
+        api_key: str = "",
+        base_url: str | None = None,
+    ) -> None:
+        # model / api_key / base_url 不使用，保留参数以兼容工厂函数签名
+        self._model = model
+        self._api_key = api_key
+
+    def parse_image(self, image_path: Path) -> str:
+        """将图片转为 PDF 后解析，返回 markdown 文本。"""
+        with tempfile.NamedTemporaryFile(suffix=".pdf", delete=False) as f:
+            tmp_pdf = Path(f.name)
+        try:
+            images_to_pdf([image_path], tmp_pdf)
+            return self.parse_pdf(tmp_pdf)
+        finally:
+            tmp_pdf.unlink(missing_ok=True)
+
+    def parse_pdf(
+        self,
+        pdf_path: Path,
+        pages: str | None = None,
+        progress_callback: Callable[[], None] | None = None,
+        concurrency: int = 1,
+    ) -> str:
+        """直接解析 PDF，返回 markdown 文本。
+
+        Args:
+            pdf_path: PDF 文件路径。
+            pages: 页码范围字符串（如 "1-3,5"），None 表示全部。
+            concurrency: 并发数（LiteParse 为本地引擎，忽略此参数）。
+
+        Returns:
+            解析出的 markdown 文本内容。
+        """
+        kwargs: dict = {}
+        if pages:
+            kwargs["target_pages"] = pages
+        parser = LiteParseLib(output_format="markdown", **kwargs)
+        result = parser.parse(str(pdf_path))
+        return result.text

multi_ocr/engines/ollama.py

@@ -0,0 +1,61 @@
+import re
+from pathlib import Path
+
+from ollama import Client
+
+from multi_ocr.engines.base import OCREngine
+
+
+class OllamaEngine(OCREngine):
+    """Ollama 本地 OCR 引擎。
+
+    通过 Ollama 调用本地部署的视觉模型进行 OCR 识别。
+    无需 API Key，支持自定义 base_url 连接远程 Ollama 实例。
+    """
+
+    DEFAULT_BASE_URL = "http://127.0.0.1:11434"
+
+    # 模型名称 -> 提示词映射（按前缀匹配）
+    _PROMPT_MAP: dict[str, str] = {
+        "deepseek-ocr": "<image>\nFree OCR. Output in markdown format.",
+    }
+
+    _FALLBACK_PROMPT = "<image>\nFree OCR. Output in markdown format."
+
+    def __init__(
+        self,
+        model: str,
+        api_key: str = "",
+        base_url: str = DEFAULT_BASE_URL,
+    ) -> None:
+        self._model = model
+        self._client = Client(host=base_url)
+
+    def _get_prompt(self) -> str:
+        """根据模型名称匹配对应的提示词，未匹配则使用默认提示词。"""
+        for prefix, prompt in self._PROMPT_MAP.items():
+            if prefix in self._model:
+                return prompt
+        return self._FALLBACK_PROMPT
+
+    def parse_image(self, image_path: Path) -> str:
+        prompt = self._get_prompt()
+
+        response = self._client.chat(
+            model=self._model,
+            messages=[
+                {
+                    "role": "user",
+                    "content": prompt,
+                    "images": [str(image_path)],
+                }
+            ],
+        )
+
+        content = response.message.content
+        if not content:
+            return ""
+        # 清理模型可能输出的特殊标记
+        content = re.sub(r"<\|/?ref\|>", "", content)
+        content = re.sub(r"<\|/?det\|>", "", content)
+        return content.strip()

multi_ocr/engines/siliconflow.py

@@ -0,0 +1,80 @@
+import base64
+import re
+from pathlib import Path
+
+from openai import OpenAI
+
+from multi_ocr.engines.base import OCREngine
+
+
+class SiliconFlowEngine(OCREngine):
+    """SiliconFlow API OCR 引擎，兼容 OpenAI SDK。
+
+    不同模型使用不同的提示词以达到最佳识别效果。
+    """
+
+    BASE_URL = "https://api.siliconflow.cn/v1"
+
+    # 模型名称 -> 提示词映射（按前缀匹配）
+    _PROMPT_MAP: dict[str, str] = {
+        "deepseek-ai/DeepSeek-OCR": "<image>\nFree OCR. Output in markdown format.",
+        "PaddlePaddle/PaddleOCR-VL-1.5": "OCR this image and output in markdown format.",
+    }
+
+    _FALLBACK_PROMPT = "OCR this image and output in markdown format."
+
+    def __init__(self, model: str, api_key: str, base_url: str | None = None) -> None:
+        self._model = model
+        self._client = OpenAI(
+            api_key=api_key,
+            base_url=base_url or self.BASE_URL,
+            timeout=120.0,
+        )
+
+    def _get_prompt(self) -> str:
+        """根据模型名称匹配对应的提示词，未匹配则使用默认提示词。"""
+        for prefix, prompt in self._PROMPT_MAP.items():
+            if prefix in self._model:
+                return prompt
+        return self._FALLBACK_PROMPT
+
+    def parse_image(self, image_path: Path) -> str:
+        with open(image_path, "rb") as f:
+            image_data = base64.b64encode(f.read()).decode("utf-8")
+
+        # 根据扩展名确定 MIME 类型
+        suffix = image_path.suffix.lower()
+        mime_map = {".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg"}
+        mime_type = mime_map.get(suffix, "image/png")
+
+        data_url = f"data:{mime_type};base64,{image_data}"
+
+        prompt = self._get_prompt()
+
+        response = self._client.chat.completions.create(
+            model=self._model,
+            temperature=0,
+            messages=[
+                {
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "image_url",
+                            "image_url": {"url": data_url},
+                        },
+                        {
+                            "type": "text",
+                            "text": prompt,
+                        },
+                    ],
+                }
+            ],
+        )
+
+        content = response.choices[0].message.content
+        if not content:
+            return ""
+        # 清理模型可能输出的特殊标记
+        content = re.sub(r"<\|/?ref\|>", "", content)
+        content = re.sub(r"<\|/?det\|>", "", content)
+        return content.strip()

multi_ocr/pdf_utils.py

@@ -0,0 +1,146 @@
+import sys
+import tempfile
+from pathlib import Path
+
+import fitz  # pymupdf
+
+
+def parse_pages(pages_str: str, total_pages: int) -> list[int]:
+    """解析页码范围字符串，返回 0-based 页码列表。
+
+    格式：逗号分隔的页码和范围，如 "1,3-5,8"。
+
+    Args:
+        pages_str: 页码范围字符串。
+        total_pages: PDF 总页数。
+
+    Returns:
+        0-based 页码列表（已去重并排序）。
+
+    Raises:
+        ValueError: 如果范围格式无效或页码越界。
+    """
+    result: set[int] = set()
+    parts = [p.strip() for p in pages_str.split(",") if p.strip()]
+
+    for part in parts:
+        if "-" in part:
+            try:
+                start_str, end_str = part.split("-", 1)
+                start, end = int(start_str.strip()), int(end_str.strip())
+            except ValueError:
+                raise ValueError(f"无效的页码范围: {part}")
+            if start < 1 or end > total_pages or start > end:
+                raise ValueError(f"页码范围越界: {part}（总页数: {total_pages}）")
+            for i in range(start, end + 1):
+                result.add(i - 1)
+        else:
+            try:
+                page = int(part)
+            except ValueError:
+                raise ValueError(f"无效的页码: {part}")
+            if page < 1 or page > total_pages:
+                raise ValueError(f"页码越界: {page}（总页数: {total_pages}）")
+            result.add(page - 1)
+
+    return sorted(result)
+
+
+def pdf_to_images(pdf_path: Path, pages: list[int] | None = None) -> list[Path]:
+    """将 PDF 渲染为 PNG 图片列表。
+
+    Args:
+        pdf_path: PDF 文件路径。
+        pages: 要渲染的 0-based 页码列表，None 表示全部页。
+
+    Returns:
+        临时 PNG 图片路径列表。
+    """
+    doc = fitz.open(pdf_path)
+    total = doc.page_count
+
+    if total == 0:
+        doc.close()
+        return []
+
+    if pages is None:
+        pages = list(range(total))
+
+    tmp_dir = Path(tempfile.mkdtemp(prefix="multiocr_"))
+    image_paths: list[Path] = []
+
+    for page_num in pages:
+        if page_num < 0 or page_num >= total:
+            continue
+        page = doc[page_num]
+        pix = page.get_pixmap(dpi=200)
+        img_path = tmp_dir / f"page_{page_num + 1:04d}.png"
+        pix.save(str(img_path))
+        image_paths.append(img_path)
+
+    doc.close()
+    return image_paths
+
+
+def images_to_pdf(image_paths: list[Path], output_path: Path) -> Path:
+    """将多张图片按顺序合并为一个 PDF 文件。
+
+    每张图片作为独立的一页，原图嵌入。
+
+    Args:
+        image_paths: 图片文件路径列表，按页面顺序排列。
+        output_path: 输出的 PDF 文件路径。
+
+    Returns:
+        输出的 PDF 文件路径。
+    """
+    pdf_doc = fitz.open()
+    try:
+        for img_path in image_paths:
+            img_doc = fitz.open(img_path)
+            page = img_doc[0]
+            pix = page.get_pixmap()
+            img_doc.close()
+
+            # 创建新页面，大小与图片一致
+            pdf_page = pdf_doc.new_page(width=pix.width, height=pix.height)
+            pdf_page.insert_image(
+                pdf_page.rect,
+                pixmap=pix,
+            )
+        pdf_doc.save(output_path)
+        return output_path
+    finally:
+        pdf_doc.close()
+
+
+def split_pdf(pdf_path: Path, pages_str: str | None) -> tuple[list[Path], list[int]]:
+    """拆解 PDF：验证页数、解析页码范围、渲染为图片。
+
+    Args:
+        pdf_path: PDF 文件路径。
+        pages_str: 页码范围字符串（如 "1-3,5"），None 表示全部。
+
+    Returns:
+        (图片路径列表, 页码标签列表)，标签为 1-based 页码。
+
+    Raises:
+        ValueError: 页码范围无效或越界。
+    """
+    doc = fitz.open(pdf_path)
+    total = doc.page_count
+    doc.close()
+
+    if total == 0:
+        print("PDF 无内容。", file=sys.stderr)
+        sys.exit(1)
+
+    if pages_str:
+        page_indices = parse_pages(pages_str, total)
+    else:
+        page_indices = list(range(total))
+
+    images = pdf_to_images(pdf_path, page_indices)
+    labels = [i + 1 for i in page_indices]
+
+    return images, labels

multi_ocr/single.py

@@ -0,0 +1,91 @@
+import sys
+from pathlib import Path
+
+import fitz
+from tqdm import tqdm
+
+from multi_ocr.engines.base import OCREngine
+from multi_ocr.pdf_utils import parse_pages
+
+# 支持的图片格式
+_IMAGE_EXTENSIONS = {".png", ".jpg", ".jpeg"}
+
+
+def _is_image(file_path: Path) -> bool:
+    return file_path.suffix.lower() in _IMAGE_EXTENSIONS
+
+
+def _is_pdf(file_path: Path) -> bool:
+    return file_path.suffix.lower() == ".pdf"
+
+
+def ocr_file(
+    input_path: Path,
+    engine: OCREngine,
+    pages: str | None = None,
+    concurrency: int = 1,
+) -> str:
+    """对 PDF 或图片文件执行 OCR。
+
+    Args:
+        input_path: 输入文件路径（PDF 或图片）。
+        engine: OCR 引擎实例。
+        pages: 页码范围字符串（仅对 PDF 有效），如 "1-3,5"。
+        concurrency: 并发数，默认 1（串行），仅对 PDF 多页有效。
+
+    Returns:
+        合并后的 OCR 文本。
+
+    Raises:
+        FileNotFoundError: 文件不存在。
+        ValueError: 不支持的文件格式或页码范围无效。
+    """
+    if not input_path.exists():
+        raise FileNotFoundError(f"文件不存在: {input_path}")
+
+    if _is_pdf(input_path):
+        # 获取实际要处理的页数
+        doc = fitz.open(input_path)
+        total_pages = doc.page_count
+        doc.close()
+
+        if pages:
+            page_indices = parse_pages(pages, total_pages)
+            actual_total = len(page_indices)
+        else:
+            actual_total = total_pages
+
+        if actual_total == 0:
+            merged = ""
+        else:
+            pbar = tqdm(
+                total=actual_total,
+                desc=f"识别 {input_path.name}",
+                file=sys.stderr,
+                unit="页",
+            )
+            try:
+                merged = engine.parse_pdf(
+                    input_path,
+                    pages,
+                    progress_callback=lambda: pbar.update(1),
+                    concurrency=concurrency,
+                )
+                # 确保进度条到达 100%（兼容 LiteParse 等无逐页回调的引擎）
+                pbar.update(pbar.total - pbar.n)
+            finally:
+                pbar.close()
+    elif _is_image(input_path):
+        if pages:
+            raise ValueError("图片不支持 --pages 页码范围，该参数仅对 PDF 有效")
+        merged = engine.parse_image(input_path)
+    else:
+        supported = ", ".join(_IMAGE_EXTENSIONS | {".pdf"})
+        raise ValueError(f"不支持的文件格式: {input_path.suffix}，支持: {supported}")
+
+    # 输出
+    output_path = input_path.with_suffix(".md")
+    output_path.write_text(merged, encoding="utf-8")
+    print(f"已保存: {output_path}")
+
+    return merged

multi_ocr_py-0.1.0.dist-info/METADATA

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: multi-ocr-py
+Version: 0.1.0
+Summary: 多引擎 OCR 工具包：将 PDF 和图片转换为 Markdown，支持 CLI 全局安装和 SDK 依赖两种使用方式
+Project-URL: Repository, https://github.com/BlackBoxRecorder/multi-ocr
+Author-email: Yinnan <im.yinnan@outlook.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,markdown,ocr,pdf,vision-language-model
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.11
+Requires-Dist: liteparse
+Requires-Dist: ollama
+Requires-Dist: openai>=2.45.0
+Requires-Dist: pymupdf>=1.28.0
+Requires-Dist: tqdm>=4.67.0
+Description-Content-Type: text/markdown
+
+# multi-ocr
+
+多引擎 OCR 工具包，将 PDF 和图片转换为 Markdown 文档。
+
+- **CLI 工具**：全局安装后一行命令完成 OCR
+- **SDK 依赖**：作为 Python 库集成到你的项目中
+
+## 支持的引擎
+
+| 引擎 | 说明 | 类型 |
+|---|---|---|
+| SiliconFlow + DeepSeek-OCR | 云端 OCR，精度高 | API |
+| SiliconFlow + PaddleOCR-VL-1.5 | 云端 OCR，轻量快速 | API |
+| DashScope + Qwen-VL-OCR | 阿里云百炼 | API |
+| LiteParse | 本地 PDF 解析，无需联网 | 本地 |
+| Ollama + DeepSeek-OCR | 本地部署 OCR | 本地 |
+
+## 安装
+
+### CLI 全局安装
+
+```bash
+uv tool install multi-ocr
+# 或
+pip install multi-ocr
+```
+
+### SDK 依赖安装
+
+```bash
+pip install multi-ocr
+# 或
+uv add multi-ocr
+```
+
+## CLI 使用
+
+```bash
+# 单文件 OCR
+multi-ocr document.pdf
+
+# 指定引擎和页码范围
+multi-ocr document.pdf --model dashscope-qwen-vl-ocr --pages 1-5
+
+# 批量处理目录
+multi-ocr ./scans/ --model silicon-deepseek-ocr -j 4
+
+# 查看帮助
+multi-ocr --help
+```
+
+### 环境变量
+
+| 引擎 | 环境变量 |
+|---|---|
+| SiliconFlow | `SILICONFLOW_API_KEY` |
+| DashScope | `DASHSCOPE_API_KEY` |
+| Ollama | `OLLAMA_BASE_URL`（可选，默认 http://127.0.0.1:11434）|
+
+也可通过 `--api-key` 参数直接传入。
+
+## SDK 使用
+
+```python
+from pathlib import Path
+from multi_ocr import get_engine, ocr_file, OCREngine
+
+# 创建引擎
+engine = get_engine(
+    provider="siliconflow",
+    model="deepseek-ai/DeepSeek-OCR",
+    api_key="your-api-key",
+)
+
+# 识别图片
+text = engine.parse_image(Path("scan.jpg"))
+
+# 识别 PDF
+result = ocr_file(Path("document.pdf"), engine, pages="1-3")
+
+# 批量处理目录
+from multi_ocr import ocr_directory
+ocr_directory(Path("./scans/"), engine, concurrency=4)
+```
+
+### 自定义引擎
+
+```python
+from multi_ocr import OCREngine
+
+class MyEngine(OCREngine):
+    def parse_image(self, image_path: Path) -> str:
+        # 你的 OCR 逻辑
+        return "recognized text"
+```
+
+## 要求
+
+- Python >= 3.11
+
+## 协议
+
+MIT License

multi_ocr_py-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+multi_ocr/__init__.py,sha256=rJQXDFWGvtpHlr-AEr1jWaAIlcxT4qPTycqYl13ghCg,631
+multi_ocr/batch.py,sha256=m5p6sAvyFUiKNxIzVMYDeCziIhDT3ifftxwPeRR9cpU,4855
+multi_ocr/cli.py,sha256=kDkYWCDTvjJeCd_DkSM95xfW5FUPuKYnDENOl9Ity-0,6299
+multi_ocr/pdf_utils.py,sha256=cArl4cM7WXGCHCpU95JG9e3YBO2daFDffPCh0oMCDbc,4205
+multi_ocr/single.py,sha256=oVQmzz9vOUakp55_6SVSh-PXcZk80EeZ4fBgU0Oz_Lo,2707
+multi_ocr/engines/__init__.py,sha256=9FreP7hz1EoGr5GJp3QwzULYhiJ-UJnHZTFXm3Zx5-s,1616
+multi_ocr/engines/base.py,sha256=pih7Thc65s0pT64NB7C0uYt40kZKYmlAEcAJ36e1yEA,3421
+multi_ocr/engines/dashscope.py,sha256=sdqAxUSc5eGNM68BRSvj_7ypZfAfDsS9XjZppRj-OZ4,2950
+multi_ocr/engines/liteparse.py,sha256=XJKHcpLFhHxR1JQDtXELS2iC8ofjvD-HeB54F9cB-D0,1924
+multi_ocr/engines/ollama.py,sha256=020oE0HgODYY6ScZi0GNBhAbiyhNtJ0K0NhLvnVnQWc,1777
+multi_ocr/engines/siliconflow.py,sha256=NhyJNXGaSCyqnbEB8eBK0Z5ibWg4ZDrM2xgujhWVNd4,2620
+multi_ocr_py-0.1.0.dist-info/METADATA,sha256=hyBGVL_6Kbxezn4nMpDDHc_kzg_0mL1ub0_ib5P_tK0,3084
+multi_ocr_py-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+multi_ocr_py-0.1.0.dist-info/entry_points.txt,sha256=vAMqg_Jw9QxagIodm_DGtlYTShMXq3sSqoVHJkitLW4,49
+multi_ocr_py-0.1.0.dist-info/licenses/LICENSE,sha256=UuDhUgdWFxIjPnphLhz1Ped4u4oSGDpfLLoyO9v8Lks,1063
+multi_ocr_py-0.1.0.dist-info/RECORD,,

multi_ocr_py-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

multi_ocr_py-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+multi-ocr = multi_ocr.cli:main

multi_ocr_py-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yinnan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.