资料来源：README.md

核心功能

Marker 提供了以下核心功能：

资料来源：README.md

系统架构

Marker 采用模块化的流水线架构，由多个深度学习模型和处理阶段组成。

整体架构图

graph TD
    A[输入文档] --> B[文档提供者<br/>Document Provider]
    B --> C[布局检测<br/>Layout Detection]
    C --> D[行检测<br/>Line Detection]
    D --> E{是否需要 OCR?}
    E -->|有可提取文本| F[文本提取]
    E -->|扫描/图像| G[OCR 识别]
    F --> H[结构分析<br/>Structure Analysis]
    G --> H
    H --> I[处理器链<br/>Processors]
    I --> J[LLM 增强<br/>可选]
    J --> K[渲染输出<br/>Renderer]
    K --> L[Markdown/JSON/HTML/Chunks]
    
    subgraph 处理阶段
        C
        D
        E
        F
        G
        H
    end
    
    subgraph 后处理阶段
        I
        J
        K
    end

核心组件

资料来源：marker/converters/pdf.py, marker/builders/document.py

工作流程

Marker 的转换流程分为以下几个关键阶段：

流水线处理流程

flowchart LR
    subgraph 阶段1[文档加载]
        A1[获取低分辨率图像<br/>96 DPI] --> A2[获取高分辨率图像<br/>192 DPI]
    end
    
    subgraph 阶段2[模型推理]
        B1[布局检测] --> B2[行检测] --> B3[文本提取/OCR]
    end
    
    subgraph 阶段3[后处理]
        C1[结构分析] --> C2[块处理]
        C2 --> C3[LLM 增强]
    end
    
    subgraph 阶段4[输出]
        D1[渲染器] --> D2[最终输出]
    end
    
    A1 --> B1
    A2 --> B3
    B1 --> B2
    B2 --> B3
    B3 --> C1
    C1 --> C2
    C3 --> D1

处理阶段详解

#### 1. 文档加载阶段

# 资料来源：marker/builders/document.py:15-30
class DocumentBuilder(BaseBuilder):
    lowres_image_dpi: Annotated[int, "低分辨率图像 DPI，用于布局和行检测"] = 96
    highres_image_dpi: Annotated[int, "高分辨率图像 DPI，用于 OCR"] = 192
    
    def __call__(self, provider, layout_builder, line_builder, ocr_builder):
        document = self.build_document(provider)
        layout_builder(document, provider)
        line_builder(document, provider)
        if not self.disable_ocr:
            ocr_builder(document, provider)
        return document

Marker 在此阶段从 PDF 中提取两种分辨率的页面图像：

• 低分辨率 (96 DPI)：用于布局检测和行检测
• 高分辨率 (192 DPI)：用于 OCR 识别

资料来源：marker/builders/document.py

#### 2. 模型推理阶段

Marker 采用"按需使用模型"策略，只在必要时调用模型，提高速度和准确性。

资料来源：README.md

#### 3. 后处理阶段

Marker 使用处理器链对文档进行后处理，主要包括：

资料来源：marker/converters/pdf.py

使用方式

Marker 提供多种使用方式，满足不同场景需求。

命令行使用

#### 单文件转换

marker_single /path/to/document.pdf

#### 批量转换

marker /path/to/input/folder

Marker 会自动处理文件夹中的所有文档。

#### 多 GPU 批量转换

NUM_DEVICES=4 NUM_WORKERS=15 marker_chunk_convert ../pdf_in ../md_out

• NUM_DEVICES：使用的 GPU 数量（至少 2 个）
• NUM_WORKERS：每个 GPU 上的并行进程数

资料来源：README.md

Python API 使用

from marker.converters.pdf import PdfConverter
from marker.models import create_model_dict
from marker.output import text_from_rendered

# 创建转换器
converter = PdfConverter(
    artifact_dict=create_model_dict(),
)

# 执行转换
rendered = converter("FILEPATH")

# 提取输出
text, _, images = text_from_rendered(rendered)

rendered 对象是一个 Pydantic BaseModel，根据输出格式包含不同的属性：

• Markdown 输出：包含 markdown、metadata、images 属性
• JSON 输出：包含完整的结构化数据

资料来源：README.md

Web 服务部署

Marker 提供了 FastAPI 服务器用于 API 部署：

# 资料来源：marker/scripts/server.py
from fastapi import FastAPI, File, UploadFile
from marker.converters.pdf import PdfConverter
from marker.models import create_model_dict

app = FastAPI()

@app.post("/marker")
async def convert_pdf(file: UploadFile = File(...)):
    # 处理上传的 PDF 文件
    content = await file.read()
    # ... 转换逻辑

详细部署示例请参考 examples/marker_modal_deployment.py。

Streamlit GUI

Marker 提供了基于 Streamlit 的图形界面：

marker_gui

资料来源：marker/scripts/streamlit_app.py

命令行参数

资料来源：README.md, marker/config/parser.py

LLM 集成

Marker 支持使用 LLM 提升转换质量，可用于：

• 合并跨页表格
• 处理内联数学公式
• 正确格式化表格
• 从表单中提取值

支持的 LLM 服务

资料来源：README.md

LLM 配置示例

# 使用 Gemini
converter = PdfConverter(
    config={"use_llm": True},
    llm_service=GoogleGeminiService
)

# 使用 Ollama
converter = PdfConverter(
    config={"use_llm": True},
    llm_service=OllamaService
)

自定义 LLM 提示词

marker_single document.pdf --use_llm --block_correction_prompt "你的自定义提示词"

性能与基准测试

性能对比

测试在 H100 GPU 上进行。Marker 在速度和准确性方面均表现出色。

资料来源：README.md

资源需求

• VRAM：每个 worker 峰值使用 5GB，平均 3.5GB
• Worker 数量：可通过 --workers 参数调整，默认自动设置

已知限制与常见问题

文档格式限制

根据社区反馈，Marker 在以下情况下可能表现不佳：

资料来源：GitHub Issue #583

平台特定问题

资料来源：GitHub Issue #960, GitHub Issue #818, GitHub Issue #919

Gemini API 限制

当使用 Gemini API 时，注意速率限制：

• 免费层级约 15 请求/分钟
• 建议实现请求间隔控制

资料来源：GitHub Issue #490

输出格式详解

Markdown 输出

默认输出格式，包含：

• 格式化文本
• 表格（Markdown 或 HTML 格式）
• 代码块
• 数学公式（使用 <math> 标签）
• 图片引用

JSON 输出

结构化输出，包含：

• blocks：文档块列表
• metadata：文档元数据
• images：提取的图像信息
• page_count：页数

HTML 输出

保留布局的 HTML 输出，适合网页展示。

Chunks 输出

分块输出，适合 RAG（检索增强生成）应用。

结构化数据提取

Marker 支持基于 JSON Schema 的结构化数据提取（Beta 功能）：

# 资料来源：marker/converters/extraction.py
from marker.converters.extraction import ExtractionConverter

extractor = ExtractionConverter(
    artifact_dict=create_model_dict(),
    config={"output_format": "markdown"}
)

result = extractor("document.pdf", schema=your_schema)

详细使用请参考 marker/scripts/extraction_app.py。

扩展与自定义

自定义处理器

通过 --processors 参数覆盖默认处理器：

marker_single document.pdf --processors "module1.processor1,module2.processor2"

自定义渲染器

Marker 支持自定义渲染器实现：

• MarkdownRenderer：Markdown 格式输出
• JSONRenderer：JSON 格式输出
• HTMLRenderer：HTML 格式输出
• ChunkRenderer：分块输出

Modal 部署示例

# 资料来源：examples/marker_modal_deployment.py
import modal

app = modal.App("marker-service")
image = modal.Image.debian_slim().pip_install(["marker-pdf[full]"])

@app.function(image=image, gpu="L40S")
def convert_pdf_handle(file_data):
    from marker.converters.pdf import PdfConverter
    # 转换逻辑

完整部署示例请参考 examples/marker_modal_deployment.py。

版本历史

资料来源：GitHub Releases

相关链接

• 项目主页
• Surya OCR 库
• Texify 公式识别
• Datalab 托管平台
• 在线试用

系统要求

硬件要求

软件要求

• Python 3.9 - Python 3.12
• pip 或 conda 包管理器
• PyTorch (自动安装)
• CUDA 11.8+ (仅 GPU 加速需要)

Marker 支持三种计算后端：

• CUDA: NVIDIA GPU 加速，推荐用于生产环境
• MPS: Apple Silicon (M1/M2/M3) GPU 加速
• CPU: 纯 CPU 推理，兼容所有平台

资料来源：marker/utils/gpu.py:1-50

基本安装

基础安装 (仅 PDF)

安装 Marker 用于处理 PDF 文件：

pip install marker-pdf

此安装包含处理 PDF 文件所需的所有依赖项。

完整安装 (支持多种文件格式)

如果需要处理 PDF 以外的文件格式（如图片、PPTX、DOCX、XLSX、HTML、EPUB），请安装完整版本：

pip install marker-pdf[full]

完整安装包含的额外依赖：

资料来源：pyproject.toml

GPU 配置

Marker 会自动检测可用的计算设备，但您也可以手动指定设备类型。

自动检测

Marker 在启动时会自动检测系统中的 GPU 设备：

# Marker 会依次检查: CUDA > MPS > CPU
# 自动选择可用的最优设备

资料来源：marker/utils/gpu.py:20-35

手动指定设备

通过环境变量强制 Marker 使用特定设备：

# 强制使用 CUDA GPU
export TORCH_DEVICE=cuda

# 强制使用 Apple MPS
export TORCH_DEVICE=mps

# 强制使用 CPU
export TORCH_DEVICE=cpu

NVIDIA GPU 配置

1. 安装 NVIDIA 驱动: 确保系统已安装最新的 NVIDIA 驱动程序

1. 安装 CUDA Toolkit: Marker 需要 CUDA 11.8 或更高版本

# 检查 CUDA 版本
nvcc --version

1. 配置 cuDNN (可选): 安装 cuDNN 可进一步提升性能

1. 多 GPU 配置: 使用多块 GPU 进行并行处理：

NUM_DEVICES=4 NUM_WORKERS=15 marker_chunk_convert /path/to/input /path/to/output

参数说明：

• NUM_DEVICES: GPU 数量（至少 2 块）
• NUM_WORKERS: 每块 GPU 的并行进程数

资料来源：marker/models.py:1-30

Docker 部署

基础镜像

Marker 提供官方 Docker 镜像：

FROM python:3.10-slim

# 安装系统依赖
RUN apt-get update && apt-get install -y \
    libgl1-mesa-glx \
    libglib2.0-0 \
    libsm6 \
    libxext6 \
    libxrender-dev \
    libgomp1 \
    && rm -rf /var/lib/apt/lists/*

# 安装 marker
RUN pip install marker-pdf

WORKDIR /workspace

运行 Docker 容器

# 构建镜像
docker build -t marker:latest .

# 运行容器 (CPU 模式)
docker run -v /path/to/pdfs:/data marker:latest marker_single /data/input.pdf

# 运行容器 (GPU 模式)
docker run --gpus all -v /path/to/pdfs:/data marker:latest marker_single /data/input.pdf

注意事项

1. psutil 依赖: 确保 Docker 镜像中安装了 psutil 库，这是 Marker 运行所必需的依赖项。某些精简镜像可能缺少此包。

1. GPU 支持: 在 Docker 中使用 GPU 需要安装 NVIDIA Container Toolkit

1. 内存限制: 处理大型 PDF 文件时，建议分配至少 16GB 内存给容器

资料来源：marker/settings.py:1-50

Streamlit GUI 安装

Marker 提供交互式 Web 界面用于测试和探索：

# 安装 GUI 依赖
pip install streamlit streamlit-ace

# 启动 GUI
marker_gui

GUI 启动后会在浏览器中打开 http://localhost:8501。

GUI 功能

资料来源：marker/scripts/streamlit_app.py:1-80

模型下载与缓存

首次运行时，Marker 会自动下载所需的深度学习模型：

模型文件默认缓存在 ~/.cache/marker/ 目录。

自定义模型缓存位置

export MARKER_CACHE_DIR=/path/to/custom/cache

验证安装

安装完成后，使用以下命令验证安装是否成功：

# 检查版本
marker --version

# 查看可用选项
marker --help

# 测试转换
marker_single /path/to/test.pdf

Python API 验证

from marker.converters.pdf import PdfConverter
from marker.models import create_model_dict

# 创建模型字典
model_dict = create_model_dict()

# 初始化转换器
converter = PdfConverter(artifact_dict=model_dict)

# 测试转换
result = converter("/path/to/test.pdf")
print("转换成功！")

常见问题与解决方案

Mac M 系列芯片性能问题

问题: 在 macOS M1/M2/M3 芯片上，v1.9.0 及以上版本出现 20 倍以上的性能下降。

解决方案: 降级到 v1.8.0 版本

pip install marker==1.8.0

相关 Issue: #960

缺少 psutil 依赖

问题: 在某些 Docker 环境中运行时报错 ModuleNotFoundError: No module named 'psutil'

解决方案: 手动安装 psutil

pip install psutil

相关 Issue: #818

GPU 内存不足

问题: 处理大文件时出现 OOM (Out of Memory) 错误。

解决方案:

1. 减少并行工作进程数量：

marker --workers 1 /path/to/large.pdf

1. 减少每批处理的页数

1. 拆分大型 PDF 文件为多个小文件

1. 使用 CPU 模式作为备选：

TORCH_DEVICE=cpu marker_single /path/to/large.pdf

相关 Issue: #1032

OCR 文本质量差

问题: 提取的文本出现乱码或乱序。

解决方案: 强制使用 OCR 处理

marker_single --force_ocr /path/to/document.pdf

Gemini API 限流

问题: 使用 LLM 增强功能时遇到 API 限流错误。

解决方案: Marker 会在收到限流错误时自动重试，但建议：

1. 设置合适的请求间隔
2. 使用本地 Ollama 模型作为替代

LLM 服务配置

Marker 支持使用 LLM 提升转换质量，需要配置以下环境变量之一：

Google Gemini (默认)

export GOOGLE_API_KEY=your_api_key_here

本地 Ollama

export OLLAMA_HOST=http://localhost:11434
marker_single --use_llm --llm_service marker.services.ollama.OllamaService /path/to/doc.pdf

卸载

如需完全卸载 Marker：

# 卸载 marker-pdf
pip uninstall marker-pdf

# 清理缓存模型
rm -rf ~/.cache/marker/

# 清理配置 (可选)
rm -rf ~/.config/marker/

另请参阅

• 使用指南 - Marker 命令行工具详细用法
• API 参考 - Python API 文档
• 架构设计 - Marker 内部架构说明
• 性能优化 - 提升处理速度的技巧
• 故障排除 - 常见问题排查指南

整体架构概述

Marker 采用模块化设计，核心转换流程由以下几个关键阶段组成：

graph TD
    A[输入文件] --> B[Provider 供应层]
    B --> C[Builder 构建层]
    C --> D[Processor 处理层]
    D --> E[Renderer 渲染层]
    E --> F[输出格式]
    
    C --> C1[DocumentBuilder]
    C --> C2[LayoutBuilder]
    C --> C3[LineBuilder]
    C --> C4[OcrBuilder]
    C --> C5[StructureBuilder]
    
    D --> D1[ListProcessor]
    D --> D2[CodeProcessor]
    D --> D3[EquationProcessor]
    D --> D4[TableProcessor]
    D --> D5[LLM processors]

架构的核心设计理念是按需调用模型，仅在必要时使用深度学习模型，从而提升处理速度和准确性。资料来源：README.md:1-20

核心组件详解

1. Provider 供应层

Provider 负责从各种文件格式中提取页面图像和文本内容。项目使用注册表模式动态选择合适的 Provider：

from marker.providers.registry import provider_from_filepath

provider_cls = provider_from_filepath(filepath)
provider = provider_cls(filepath, self.config)

资料来源：marker/converters/extraction.py:1-20

当前支持的 Provider 类型包括：

Provider 的核心职责是根据文件路径动态选择对应的 Provider 类，并提供统一的图像提取接口。资料来源：marker/providers/pdf.py

2. Builder 构建层

Builder 层负责构建文档的内部结构，识别页面布局和文本内容。

#### 2.1 DocumentBuilder

DocumentBuilder 是文档构建的入口，负责协调所有子 Builder：

from marker.builders.document import DocumentBuilder

def __call__(self, provider, layout_builder, line_builder, ocr_builder):
    document = self.build_document(provider)
    layout_builder(document, provider)
    line_builder(document, provider)
    if not self.disable_ocr:
        ocr_builder(document, provider)
    return document

资料来源：marker/builders/document.py:1-50

DocumentBuilder 的关键配置参数：

#### 2.2 LayoutBuilder

LayoutBuilder 负责检测页面布局，识别不同内容区域（如标题、段落、表格、图表等），并确定阅读顺序。该组件依赖于 surya 的布局模型。

#### 2.3 OcrBuilder

OcrBuilder 执行 OCR 光学字符识别，将图像中的文本提取出来：

class OcrBuilder(BaseBuilder):
    recognition_batch_size = None  # 使用模型默认批处理大小
    disable_tqdm = False
    skip_ocr_blocks = [BlockTypes.Equation, BlockTypes.Table, BlockTypes.Figure, BlockTypes.Picture]

资料来源：marker/builders/ocr.py:1-30

OcrBuilder 的关键特性：

• 支持跳过特定块类型（如公式和表格），因为它们由专门的处理器处理
• 使用 ftfy 库进行文本修复
• 支持配置识别批处理大小

3. Processor 处理层

Processor 层对文档内容进行细粒度处理和格式化。Marker 内置多种专用处理器：

#### LLM 增强处理器

当启用 --use_llm 选项时，系统会调用一系列 LLM 处理器来提升输出质量：

from marker.processors.llm.llm_table_merge import LLMTableMergeProcessor
from marker.processors.llm.llm_complex import LLMComplexRegionProcessor
from marker.processors.llm.llm_form import LLMFormProcessor
from marker.processors.llm.llm_table import LLMTableProcessor
from marker/processors.llm.llm_image_description import LLMImageDescriptionProcessor

资料来源：marker/converters/pdf.py:1-50

这些处理器可以实现：

• 跨页表格合并
• 内联数学公式处理
• 表结构优化
• 图像描述生成
• 表单字段提取

4. Renderer 渲染层

Renderer 负责将处理后的文档渲染为最终输出格式：

转换流程详解

单文件转换流程

sequenceDiagram
    participant User as 用户
    participant Converter as PdfConverter
    participant Builder as DocumentBuilder
    participant Provider as Provider
    participant Layout as LayoutBuilder
    participant Line as LineBuilder
    participant OCR as OcrBuilder
    participant Processor as Processors
    participant Renderer as Renderer
    
    User->>Converter: 调用转换器
    Converter->>Provider: 创建 Provider
    Converter->>Builder: 创建 DocumentBuilder
    Builder->>Provider: 获取页面图像
    Builder->>Layout: 布局检测
    Builder->>Line: 行检测
    Builder->>OCR: OCR 识别
    Converter->>Processor: 处理器链处理
    Processor->>Processor: List → Code → Equation...
    Converter->>Renderer: 渲染输出
    Renderer->>User: 返回结果

批量转换流程

对于批量文件处理，Marker 使用 marker_chunk_convert 脚本支持多 GPU 并行处理：

NUM_DEVICES=4 NUM_WORKERS=15 marker_chunk_convert ../pdf_in ../md_out

参数说明：

• NUM_DEVICES: GPU 数量（需 >= 2）
• NUM_WORKERS: 每个 GPU 的并行进程数

资料来源：README.md:80-100

数据流与内部结构

文档内部 Schema

Marker 使用 Pydantic 模型定义文档的内部数据结构：

classDiagram
    class Document {
        +str filepath
        +List~PageGroup~ pages
        +BlockTypes block_type
    }
    class PageGroup {
        +int page_id
        +List~Block~ contained_blocks
    }
    class Block {
        +BlockId block_id
        +BlockTypes block_type
        +PolygonBox bbox
    }
    
    Document --> PageGroup
    PageGroup --> Block

BlockTypes 定义了所有支持的块类型：

JSON 输出结构

JSON 输出采用树状结构组织：

{
  "pages": [
    {
      "id": "page_0",
      "block_type": "Page",
      "children": [
        {
          "id": "block_0",
          "block_type": "Text",
          "children": [...]
        },
        {
          "id": "block_1",
          "block_type": "TableGroup",
          "children": [...]
        }
      ]
    }
  ]
}

配置系统

ConfigParser 配置解析

Marker 使用 ConfigParser 统一管理配置：

from marker.config.parser import ConfigParser

config_parser = ConfigParser(cli_options)
converter = PdfConverter(
    artifact_dict=create_model_dict(),
    config=config_parser.generate_config_dict(),
    llm_service=config_parser.get_llm_service(),
    processor_list=config_parser.get_processors(),
    renderer=config_parser.get_renderer(),
)

资料来源：marker/scripts/streamlit_app.py:1-50

关键配置项

LLM 服务集成

支持的 LLM 服务

Marker 支持多种 LLM 后端：

资料来源：README.md:60-80

LLM 处理器配置

LLM 处理器在配置文件中启用：

# 启用 LLM 的完整处理器列表
processor_list = [
    BlockquoteProcessor,
    CodeProcessor,
    DebugProcessor,
    DocumentTOCProcessor,
    EquationProcessor,
    FootnoteProcessor,
    IgnoreTextProcessor,
    LineNumbersProcessor,
    ListProcessor,
    LLMTableMergeProcessor,      # LLM 处理器
    LLMComplexRegionProcessor,    # LLM 处理器
    LLMFormProcessor,            # LLM 处理器
    LLMTableProcessor,           # LLM 处理器
    LLMImageDescriptionProcessor, # LLM 处理器
    PageHeaderProcessor,
    ReferenceProcessor,
    SectionHeaderProcessor,
]

资料来源：marker/converters/pdf.py:1-50

部署架构

本地部署

Marker 支持多种运行模式：

Modal 云端部署

Marker 提供了 Modal 平台的部署示例：

# examples/marker_modal_deployment.py
app = modal.App("datalab-marker-modal-demo")
GPU_TYPE = "L40S"
MODEL_PATH_PREFIX = "/root/.cache/datalab/models"

image = (
    modal.Image.debian_slim(python_version="3.10")
    .apt_install(["git", "wget"])
    .env({"TORCH_DEVICE": "cuda"})
    .pip_install(["marker-pdf[full]", "fastapi==0.104.1", ...])
)

models_volume = modal.Volume.from_name("marker-models", create_if_missing=True)

资料来源：examples/marker_modal_deployment.py:1-50

GPU 资源需求

资料来源：README.md:90-100

已知限制与性能问题

社区反馈的性能问题

根据社区 Issue 反馈，以下是已知的性能和稳定性问题：

已知技术限制

Marker 在以下场景可能表现不佳：

资料来源：README.md:25-35

扩展开发

自定义处理器

可以通过继承 BaseProcessor 创建自定义处理器：

from marker.processors import BaseProcessor
from marker.schema.document import Document

class CustomProcessor(BaseProcessor):
    block_types = ("Text", "Code")  # 要处理的块类型
    
    def __call__(self, document: Document):
        # 自定义处理逻辑
        pass

自定义渲染器

创建新的输出格式需要实现 BaseRenderer 接口：

from marker.renderers import BaseRenderer

class CustomRenderer(BaseRenderer):
    def __call__(self, rendered: Document) -> str:
        # 自定义渲染逻辑
        return output

See Also

• 安装指南 - Marker 安装和环境配置
• 命令行使用 - marker 和 marker_single 详细用法
• Python API - 在 Python 代码中集成 Marker
• LLM 集成 - 配置和使用 LLM 增强功能
• 输出格式 - Markdown、JSON、HTML 等输出格式详解
• 性能优化 - GPU 加速和批处理配置
• 故障排除 - 常见问题与解决方案

1. 转换器架构概述

Marker 的转换器系统采用模块化设计，核心类继承自 BaseConverter 基类。根据不同的功能需求，项目提供了多种专用转换器实现。

1.1 转换器类型

1.2 转换器继承关系

classDiagram
    class BaseConverter {
        <<abstract>>
        +config: dict
        +artifact_dict: dict
        +processor_list: list
        +renderer: BaseRenderer
        +llm_service: BaseService
        +build_document(filepath)
        +render(document)
        +__call__(filepath)
    }
    
    class PdfConverter {
        +layout_builder_class
        +resolve_dependencies()
        +build_document()
        +render()
    }
    
    class ExtractionConverter {
        +existing_markdown
        +build_document()
        +__call__()
    }
    
    BaseConverter <|-- PdfConverter
    BaseConverter <|-- ExtractionConverter
    PdfConverter <|-- ExtractionConverter

1.3 核心转换流程

Marker 的转换流程分为三个主要阶段：文档构建、处理器处理、渲染输出。

graph TD
    A[输入文件] --> B[Provider 提供者]
    B --> C[DocumentBuilder 文档构建器]
    C --> D[LayoutBuilder 布局检测]
    C --> E[LineBuilder 行检测]
    C --> F[OcrBuilder OCR识别]
    C --> G[StructureBuilder 结构分析]
    G --> H[处理器链 Processing]
    H --> I[渲染器 Renderer]
    I --> J[输出结果]
    
    H --> H1[EquationProcessor 公式处理]
    H --> H2[TableProcessor 表格处理]
    H --> H3[CodeProcessor 代码处理]
    H --> H4[ListProcessor 列表处理]
    H --> H5[LLM处理器 增强处理]

2. PdfConverter 核心组件

PdfConverter 是 Marker 的主转换器类，负责协调整个文档转换过程。资料来源：marker/converters/pdf.py:1-100

2.1 类结构定义

class PdfConverter(BaseConverter):
    layout_builder_class = LayoutBuilder

PdfConverter 继承自 BaseConverter，主要职责包括：

• 协调各个 Builder 的执行顺序
• 管理处理器的注册和执行
• 处理渲染器的初始化和调用

2.2 依赖解析机制

转换器使用依赖注入模式，通过 resolve_dependencies 方法解析 Builder 实例：

def resolve_dependencies(self, builder_cls):
    return builder_cls(self.config)

此机制确保每个 Builder 都能正确获取配置参数和共享资源。资料来源：marker/converters/pdf.py:60-80

2.3 文档构建流程

build_document 方法是转换的核心入口：

def build_document(self, filepath: str):
    provider_cls = provider_from_filepath(filepath)
    layout_builder = self.resolve_dependencies(self.layout_builder_class)
    line_builder = self.resolve_dependencies(LineBuilder)
    ocr_builder = self.resolve_dependencies(OcrBuilder)
    provider = provider_cls(filepath, self.config)
    
    document = DocumentBuilder(self.config)(
        provider, layout_builder, line_builder, ocr_builder
    )
    
    structure_builder_cls = self.resolve_dependencies(StructureBuilder)
    structure_builder_cls(document)
    
    for processor in self.processor_list:
        processor(document)
    
    return document, provider

构建流程说明：

1. 根据文件扩展名选择对应的 Provider
2. 创建并执行各个 Builder
3. 运行处理器链进行内容后处理
4. 返回完整的 Document 对象和 Provider 实例

3. DocumentBuilder 文档构建器

DocumentBuilder 负责将原始 PDF 文件转换为内部 Document 对象结构。资料来源：marker/builders/document.py:1-50

3.1 配置参数

3.2 构建流程

sequenceDiagram
    participant Provider
    participant DocumentBuilder
    participant LayoutBuilder
    participant LineBuilder
    participant OcrBuilder
    
    Provider->>DocumentBuilder: get_images(page_range, lowres_dpi)
    DocumentBuilder->>LayoutBuilder: build_layout(document, provider)
    DocumentBuilder->>LineBuilder: build_lines(document, provider)
    alt OCR enabled
        DocumentBuilder->>OcrBuilder: run_ocr(document, provider)
    end
    DocumentBuilder-->>PdfConverter: Document

4. OcrBuilder OCR 处理

OcrBuilder 负责对文档页面进行光学字符识别。资料来源：marker/builders/ocr.py:1-100

4.1 关键配置参数

4.2 OCR 执行流程

graph LR
    A[获取高分辨率图像] --> B[Surya RecognitionPredictor]
    B --> C[文本行检测]
    C --> D[字符识别]
    D --> E[文本修复 ftfy]
    E --> F[合并到 Document]

OCR 处理器使用 Surya 库的 RecognitionPredictor 进行文本识别，并对识别结果使用 ftfy 库进行文本修复。

4.3 跳过块类型

默认情况下，以下块类型会被跳过 OCR 处理：

• BlockTypes.Equation - 公式块
• BlockTypes.Table - 表格块
• BlockTypes.Figure - 图表块
• BlockTypes.Picture - 图片块

这些块类型由各自的专用处理器在后续阶段单独处理。资料来源：marker/builders/ocr.py:40-60

5. ExtractionConverter 结构化提取

ExtractionConverter 是专门用于结构化数据提取的转换器，支持基于 JSON Schema 或 Pydantic Schema 的内容提取。资料来源：marker/converters/extraction.py:1-50

5.1 特殊配置

class ExtractionConverter(PdfConverter):
    pattern: str = r"{\d+\}-{48}\n\n"
    existing_markdown: str = None

• pattern: 用于分页的分隔符正则表达式
• existing_markdown: 已转换的 Markdown 内容，用于增量提取

5.2 提取工作流程

graph TD
    A[输入 PDF + Schema] --> B[转换为 Markdown]
    B --> C[分页切分]
    C --> D[多线程推理]
    D --> E[Schema 验证]
    E --> F[JSON 输出]
    
    D --> D1[ThreadPoolExecutor]
    D1 --> D2[LLM 调用]

6. 命令行转换器使用

Marker 提供多个命令行脚本用于文档转换。资料来源：marker/scripts/convert.py

6.1 marker_single 单文件转换

marker_single /path/to/document.pdf --output_format markdown

常用参数说明：

6.2 marker 多文件批量转换

marker /path/to/input/folder --workers 4 --output_format json

批量转换时，每个 worker 会在峰值时使用约 5GB VRAM，平均使用 3.5GB。

6.3 多 GPU 批量转换

NUM_DEVICES=4 NUM_WORKERS=15 marker_chunk_convert ../pdf_in ../md_out

• NUM_DEVICES: GPU 设备数量（至少 2）
• NUM_WORKERS: 每个 GPU 的并行进程数

7. Python API 使用

7.1 基础用法

from marker.converters.pdf import PdfConverter
from marker.models import create_model_dict
from marker.output import text_from_rendered

converter = PdfConverter(
    artifact_dict=create_model_dict(),
)
rendered = converter("document.pdf")
text, _, images = text_from_rendered(rendered)

7.2 自定义配置用法

from marker.converters.pdf import PdfConverter
from marker.models import create_model_dict
from marker.config.parser import ConfigParser

config = {
    "output_format": "json",
    "use_llm": True,
    "page_range": "0,5-10",
}

config_parser = ConfigParser(config)

converter = PdfConverter(
    config=config_parser.generate_config_dict(),
    artifact_dict=create_model_dict(),
    processor_list=config_parser.get_processors(),
    renderer=config_parser.get_renderer(),
    llm_service=config_parser.get_llm_service(),
)
rendered = converter("document.pdf")

7.3 获取块结构

from marker.converters.pdf import PdfConverter
from marker.models import create_model_dict
from marker.schema import BlockTypes

converter = PdfConverter(artifact_dict=create_model_dict())
document = converter.build_document("document.pdf")

# 提取所有表单块
forms = document.contained_blocks((BlockTypes.Form,))

8. 输出格式详解

8.1 Markdown 输出

Markdown 格式包含以下元素：

• 图片引用（图片保存在同目录）
• 格式化表格
• LaTeX 公式（用 $$ 包裹）
• 代码块（用 ``` 包裹）
• 上标脚注

8.2 JSON 输出结构

JSON 输出为树形结构，包含以下关键字段：

支持的块类型：

• Line - 文本行
• Span - 文本片段
• FigureGroup - 图表组
• TableGroup - 表格组
• ListGroup - 列表组
• PictureGroup - 图片组
• Page - 页面
• Caption - 标题
• Code - 代码块
• Figure - 图表
• Footnote - 脚注
• Form - 表单
• Equation - 公式
• Heading - 标题
• Table - 表格
• Text - 文本段落

8.3 HTML 输出

HTML 输出包含：

• img 标签嵌入图片
• <math> 标签包含公式
• pre 标签包含代码

8.4 Chunks 输出

用于将文档切分为可管理的文本块，便于后续处理和检索。

9. 性能与资源管理

9.1 内存使用

根据社区反馈，Marker 在处理大型 PDF 时可能消耗大量内存：

• 单个大型 PDF（750 页，141MB）可能占用约 20GB RAM
• 批量转换时，每个 worker 峰值使用约 5GB VRAM

社区已知问题： 在处理大型或复杂 PDF 时可能出现内存分配错误（OSError: Cannot allocate memory）。资料来源：Issue #1032

9.2 性能优化建议

9.3 常见错误处理

torch.AcceleratorError：

• 某些 PDF 文件可能导致索引越界错误
• 尝试使用 --disable_ocr 参数绕过

ModuleNotFoundError: marker.settings：

• 确保完整安装 marker-pdf：pip install marker-pdf[full]
• 检查依赖项是否正确安装

10. LLM 服务集成

10.1 配置 LLM 增强

marker_single document.pdf --use_llm --llm_service gemini

支持的 LLM 服务：

• marker.services.gemini.GoogleGeminiService - Google Gemini（默认）
• 支持自定义 ollama 模型

10.2 LLM 增强功能

使用 --use_llm 标志可以启用以下增强功能：

• 跨页表格合并
• 内联数学公式格式化
• 表格正确格式处理
• 表单值提取
• 图片描述生成

注意： 使用 Gemini API 时存在速率限制（约 15 请求/分钟），建议实现适当的请求间隔机制。

11. 部署示例

11.1 Modal 部署

Marker 支持通过 Modal 平台进行云端部署：

# examples/marker_modal_deployment.py
import modal
from marker.converters.pdf import PdfConverter
from marker.models import create_model_dict

app = modal.App("marker-service")

@app.function(gpu="L40S")
def convert_pdf_handle(pdf_bytes):
    converter = PdfConverter(artifact_dict=create_model_dict())
    rendered = converter.from_bytes(pdf_bytes)
    return rendered

完整示例请参考：examples/marker_modal_deployment.py

11.2 Streamlit GUI

Marker 提供基于 Streamlit 的图形界面：

streamlit run marker/scripts/streamlit_app.py

支持的参数：

• 输出格式选择
• 页码范围指定
• LLM 增强开关
• OCR 选项配置

12. 相关文档

• 安装指南 - Marker 环境配置和依赖安装
• 处理器详解 - 各处理器功能说明
• 输出格式 - 详细输出格式规范
• API 参考 - Python API 完整文档
• 故障排除 - 常见问题解决方案

概述

文件格式提供者（Provider）是 Marker 项目中负责从不同类型的文档文件中提取内容的核心组件。Provider 系统为 Marker 提供了统一的内容提取接口，使其能够处理 PDF、图片、HTML、EPUB、XLSX、PPTX、DOCX 等多种文件格式。

Provider 架构遵循策略模式，通过文件扩展名自动匹配相应的 Provider 实现。这种设计使得添加新的文件格式支持变得简单，只需实现统一的 Provider 接口即可。

资料来源：marker/providers/registry.py

架构设计

核心组件关系

graph TD
    A[转换请求] --> B[provider_from_filepath]
    B --> C{文件类型判断}
    C -->|PDF| D[PdfProvider]
    C -->|图片| E[ImageProvider]
    C -->|HTML| F[HtmlProvider]
    C -->|EPUB| G[EpubProvider]
    C -->|XLSX/PPTX/DOCX| H[SpreadsheetProvider]
    
    D --> I[DocumentBuilder]
    E --> I
    F --> I
    G --> I
    H --> I
    
    I --> J[统一文档对象]

Provider 注册机制

Provider 通过注册表模式进行管理。provider_from_filepath 函数根据文件路径自动返回对应的 Provider 类。

graph LR
    A[文件路径] --> B[提取扩展名]
    B --> C[查询注册表]
    C --> D[返回 Provider 类]
    D --> E[实例化 Provider]

Provider 类型

支持的文件格式

资料来源：marker/providers/registry.py

Provider 基类接口

所有 Provider 必须实现以下核心方法：

class BaseProvider(ABC):
    @abstractmethod
    def get_images(self, page_range: List[int], dpi: int) -> List[Image.Image]:
        """获取指定页面的图像表示"""
        pass
    
    @abstractmethod
    def get_page_count(self) -> int:
        """获取页面/文件总数"""
        pass
    
    @abstractmethod
    def get_text(self) -> str:
        """提取纯文本内容"""
        pass
    
    @property
    @abstractmethod
    def page_range(self) -> List[int]:
        """返回当前处理的页面范围"""
        pass

资料来源：marker/providers/pdf.py

PdfProvider 详解

PdfProvider 是最常用的 Provider，用于处理 PDF 文档。

核心功能

class PdfProvider(BaseProvider):
    def __init__(self, filepath: str, config: dict):
        self.filepath = filepath
        self.config = config
        self.doc = pymupdf.open(filepath)

主要方法

图像 DPI 配置

PdfProvider 使用两种 DPI 设置来平衡性能和精度：

资料来源：marker/providers/pdf.py 资料来源：marker/builders/document.py

ImageProvider 详解

ImageProvider 用于处理图片文件，将图片作为单页文档处理。

使用方式

from marker.providers.image import ImageProvider
from marker.config.parser import ConfigParser

config = {"page_range": [0]}  # 图片被视为单页文档
provider = ImageProvider("image.jpg", config)

特性

• 将图片文件作为单页 PDF 处理
• 自动检测图片类型并加载
• 支持多种图片格式（JPG、PNG、BMP、TIFF、WEBP）

资料来源：marker/providers/image.py

Provider 注册表

注册表工作原理

Provider 注册表通过文件扩展名映射到对应的 Provider 类：

graph TD
    A[provider_from_filepath] --> B[提取文件扩展名]
    B --> C[小写并去除点号]
    C --> D{匹配注册表}
    D -->|pdf| E[PdfProvider]
    D -->|jpg/jpeg/png| F[ImageProvider]
    D -->|html/htm| G[HtmlProvider]
    D -->|epub| H[EpubProvider]
    D -->|xlsx/pptx/docx| I[SpreadsheetProvider]
    D -->|未知| J[抛出异常]

查找 Provider

def provider_from_filepath(filepath: str):
    """根据文件路径返回对应的 Provider 类"""
    ext = os.path.splitext(filepath)[1].lower().lstrip('.')
    provider_cls = provider_registry.get(ext)
    if provider_cls is None:
        raise ValueError(f"No provider found for extension: {ext}")
    return provider_cls

资料来源：marker/providers/registry.py

在转换流程中的集成

转换流程图

sequenceDiagram
    participant Convert as PdfConverter
    participant Registry as Provider Registry
    participant Provider as 具体 Provider
    participant Builder as DocumentBuilder
    
    Convert->>Registry: provider_from_filepath(filepath)
    Registry-->>Convert: Provider 类
    Convert->>Provider: 实例化 Provider
    Provider->>Provider: 加载文件内容
    Convert->>Builder: 创建 DocumentBuilder
    Builder->>Provider: 调用接口获取数据
    Provider-->>Builder: 返回图像/文本
    Builder-->>Convert: 返回 Document 对象

代码集成示例

from marker.providers.registry import provider_from_filepath

# 在 PdfConverter 中使用
provider_cls = provider_from_filepath(filepath)
provider = provider_cls(filepath, self.config)

资料来源：marker/converters/pdf.py

自定义 Provider

实现步骤

1. 继承 BaseProvider：实现所有抽象方法
2. 注册 Provider：在 provider_registry 中添加扩展名映射
3. 测试 Provider：确保与其他组件兼容

示例模板

from marker.providers.base import BaseProvider

class CustomProvider(BaseProvider):
    def __init__(self, filepath: str, config: dict):
        self.filepath = filepath
        self.config = config
    
    def get_images(self, page_range: List[int], dpi: int) -> List[Image.Image]:
        # 实现图像提取逻辑
        pass
    
    def get_page_count(self) -> int:
        # 返回内容页数
        pass
    
    def get_text(self) -> str:
        # 返回纯文本
        pass
    
    @property
    def page_range(self) -> List[int]:
        # 返回页面范围
        pass

常见问题与排查

问题：Provider 找不到对应扩展名

错误信息：

ValueError: No provider found for extension: xyz

解决方案：检查文件扩展名是否在支持列表中，或使用 marker.converters.pdf.PdfConverter 直接处理。

问题：内存占用过高

背景：处理大型 PDF 文件时，Provider 可能占用大量内存（参见 Issue #583）。

建议：

• 使用 page_range 参数分批处理页面
• 减少 highres_image_dpi 值以降低图像内存占用

问题：图片 Provider 处理缓慢

背景：在 Mac M1+ 芯片上，v1.9.0+ 版本存在性能问题（参见 Issue #960）。

临时解决方案：

pip install marker==1.8.0

配置选项

Provider 相关配置

相关文档

• PDF 转换器 - 了解如何使用 Provider 进行 PDF 转换
• 配置解析器 - 了解如何配置 Provider 参数
• 提取转换器 - 了解如何从转换后的内容中提取结构化数据

See Also

• Marker 主文档
• Surya OCR 集成 - 底层 OCR 模型
• Datalab API - 云端托管的 Marker 服务

概述

Marker 的处理器（Processor）系统是文档转换管道中的后处理核心组件，负责在布局分析、文本识别完成后，对文档中的各类内容块（Block）进行精细化处理和格式化。处理器系统采用模块化设计，通过注册机制将不同类型的处理器串联执行，每个处理器专注于特定内容类型的优化。

处理器的主要职责包括：

• 对识别后的文本进行清洗和格式化
• 处理特殊内容类型（表格、公式、代码块、引用等）
• 合并跨页内容（如表格）
• 使用 LLM 增强内容质量（可选）
• 移除页眉页脚等干扰内容

处理器系统在 marker/processors/ 目录下组织，采用基类继承模式，支持文本处理器、表格处理器、公式处理器和 LLM 处理器等多种类型。

架构设计

处理器基类

所有处理器都继承自 BaseProcessor 基类，定义在 marker/processors/base.py。基类规定了处理器的接口规范和执行流程：

classDiagram
    class BaseProcessor {
        +config: dict
        +disable_tqdm: bool
        +__call__(document: Document)
        +process_block(block, page)
        +should_process_block(block_type): bool
    }
    
    class TextProcessor {
        +process_block(block, page)
    }
    
    class TableProcessor {
        +process_block(block, page)
    }
    
    class EquationProcessor {
        +process_block(block, page)
    }
    
    class LLMProcessor {
        +llm_service: BaseService
        +process_block(block, page)
    }
    
    BaseProcessor <|-- TextProcessor
    BaseProcessor <|-- TableProcessor
    BaseProcessor <|-- EquationProcessor
    BaseProcessor <|-- LLMProcessor

基类 BaseProcessor 提供以下核心方法：

• __call__(document): 处理器入口，遍历文档中的所有页面和块
• process_block(block, page): 抽象方法，由子类实现具体的处理逻辑
• should_process_block(block_type): 判断该处理器是否应处理指定类型的块

处理器注册与执行

处理器通过 ConfigParser 进行注册和管理，在 marker/processors/__init__.py 中定义了默认的处理器列表：

处理器按顺序执行，形成完整的处理管道：

graph LR
    A[Document] --> B[IgnoreTextProcessor]
    B --> C[PageHeaderProcessor]
    C --> D[LineNumbersProcessor]
    D --> E[Text Processors]
    E --> F[EquationProcessor]
    F --> G[TableProcessor]
    G --> H[LLM Processors]
    H --> I[Final Document]
    
    E --> E1[BlockquoteProcessor]
    E --> E2[CodeProcessor]
    E --> E3[ListProcessor]
    E --> E4[SectionHeaderProcessor]
    E --> E5[FootnoteProcessor]
    E --> E6[ReferenceProcessor]

文本处理器

文本处理器负责清洗和格式化普通文本内容，处理文档中的段落、引用、代码、列表等基本元素。

基础文本处理器

基础文本处理器位于 marker/processors/text.py，包括以下处理器：

#### BlockquoteProcessor（引用处理器）

BlockquoteProcessor 负责识别和格式化引用块：

• 检测以 > 开头的文本行
• 添加引用样式标记
• 保留引用层级结构

#### CodeProcessor（代码处理器）

CodeProcessor 处理代码块内容：

• 检测代码块边界
• 识别编程语言（如果指定）
• 保留缩进和格式
• 使用三引号包裹输出

#### ListProcessor（列表处理器）

ListProcessor 处理有序和无序列表：

• 识别列表标记符号（-, *, 1., a) 等）
• 正确嵌套列表层级
• 规范化列表格式

#### SectionHeaderProcessor（章节标题处理器）

SectionHeaderProcessor 检测并格式化章节标题：

• 识别标题样式（大字号、加粗等）
• 生成 Markdown 标题格式
• 处理多级标题结构

#### FootnoteProcessor（脚注处理器）

FootnoteProcessor 处理脚注内容：

• 收集文档中的脚注
• 移动到文档末尾或页面底部
• 保持脚注与引用位置的关联

#### ReferenceProcessor（参考文献处理器）

ReferenceProcessor 处理参考文献部分：

• 识别参考文献列表
• 格式化引用条目
• 处理 DOI 和 URL 链接

文本过滤处理器

以下处理器负责移除不需要的文本内容：

#### IgnoreTextProcessor（忽略文本处理器）

IgnoreTextProcessor 移除不应出现在输出中的内容：

• 空白页检测
• 无意义字符序列
• 重复出现的装饰性文本

#### PageHeaderProcessor（页眉页脚处理器）

PageHeaderProcessor 移除每页的页眉和页脚：

• 基于位置的页眉/页脚检测
• 重复内容识别
• 高度和位置阈值判断

#### LineNumbersProcessor（行号处理器）

LineNumbersProcessor 移除文档中的行号：

• 检测连续数字序列
• 识别行号列位置
• 从正文中分离行号

表格处理器

表格处理是 Marker 中最复杂的处理任务之一，涉及表格检测、结构识别、内容提取和跨页合并等多个阶段。

TableProcessor（表格处理器）

TableProcessor 位于 marker/processors/table.py，负责基础的表格处理：

• 表格检测：识别 PDF 中的表格区域
• 结构分析：确定行、列、单元格结构
• 内容提取：从每个单元格中提取文本
• 格式转换：输出 Markdown 或 HTML 格式的表格

表格处理器的工作流程：

flowchart TD
    A[表格块检测] --> B[单元格边界分析]
    B --> C[行列结构识别]
    C --> D[单元格内容提取]
    D --> E{启用 LLM 增强?}
    E -->|是| F[LLMTableProcessor]
    E -->|否| G[格式转换]
    F --> H[表格质量优化]
    H --> I[跨页合并检查]
    I --> J[LLMTableMergeProcessor]
    G --> J
    J --> K[最终输出]

表格单元格处理

表格处理器处理单元格内容的核心逻辑：

# 单元格处理伪代码
for cell in table.cells:
    if cell.is_blank:
        cell.content = ""
    elif cell.contains_h_line:
        # 处理被水平线切割的单元格
        cell.merge_line_content()
    elif cell.contains_v_line:
        # 处理被垂直线切割的单元格
        cell.merge_column_content()
    else:
        cell.content = extract_text(cell.region)

在 v1.9.1 和 v1.9.2 版本中，修复了表格单元格处理中的多个问题：

• 修复了单元格边界坐标相同时被误判为空白的问题
• 增强了单元格被切割时的文本合并逻辑
• 改进了跨页表格的合并检测

公式处理器

公式处理器负责识别和转换 LaTeX 公式，支持行内公式和块级公式两种类型。

EquationProcessor（公式处理器）

EquationProcessor 位于 marker/processors/equation.py，处理流程：

1. 公式检测：识别页面中的公式区域
2. 类型判断：区分行内公式和块级公式
3. 格式转换：调用 Texify 模型进行 LaTeX 转换
4. 位置插入：将转换后的公式插入到正确位置

公式块使用 $$ 分隔符包裹：

这是一个包含行内公式 $E = mc^2$ 的段落。

块级公式示例：

$$
\int_{0}^{\infty} e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$

LLM 公式增强（可选）

在 --use_llm 模式下，LLMEquationProcessor 会进一步优化公式识别结果。启用 --redo_inline_math 标志可以获得更高质量的行内公式转换。

LLM 处理器

LLM 处理器是 Marker 的可选增强功能，通过调用大型语言模型提升内容识别质量。需要配置 --use_llm 标志才能启用。

LLM 服务配置

LLM 处理器支持多种后端服务：

LLMTableProcessor（LLM 表格处理器）

LLMTableProcessor 位于 marker/processors/llm/llm_table.py，使用 LLM 增强表格识别：

• 分析表格结构和语义
• 修正表格边界识别错误
• 优化单元格内容对齐
• 检测并修复表格空洞

在 v1.9.2 版本中，新增了 LLM 处理器循环优化功能，可以多次迭代调用 LLM 进一步提升表格质量。

LLMTableMergeProcessor（LLM 表格合并处理器）

LLMTableMergeProcessor 位于 marker/processors/llm/llm_table_merge.py，处理跨页表格合并：

• 检测被分割到多页的表格
• 识别表头和表尾
• 合并单元格内容
• 修复合并后的格式问题

LLMComplexRegionProcessor（LLM 复杂区域处理器）

LLMComplexRegionProcessor 位于 marker/processors/llm/llm_complex.py，处理复杂布局区域：

• 嵌套表格和表单
• 多栏复杂布局
• 包含图表的混合内容

LLMFormProcessor（LLM 表单处理器）

LLMFormProcessor 位于 marker/processors/llm/llm_form.py，处理表单内容：

• 识别表单字段标签
• 提取字段值
• 格式化表单结构
• 处理表单中的嵌套内容

LLMImageDescriptionProcessor（LLM 图片描述处理器）

LLMImageDescriptionProcessor 位于 marker/processors/llm/llm_image_description.py，在启用 --use_llm 且未设置 --disable_image_extraction 时：

• 分析图片内容
• 生成图片描述
• 在输出中用描述替换图片引用

处理器配置

自定义处理器列表

可以使用 --processors 参数覆盖默认处理器列表：

marker_single input.pdf --processors "marker.processors.text.ListProcessor,marker.processors.text.CodeProcessor,marker.processors.equation.EquationProcessor"

通过 JSON 配置

创建 JSON 配置文件进行详细配置：

{
    "output_format": "markdown",
    "use_llm": true,
    "llm_service": "marker.services.gemini.GoogleGeminiService",
    "disable_image_extraction": false,
    "force_ocr": false
}

使用配置文件的命令：

marker_single input.pdf --config_json config.json

查看可用处理器

marker_single --help

此命令会列出所有可用的处理器、转换器和渲染器及其配置选项。

处理器执行流程

完整的处理器执行流程如下：

sequenceDiagram
    participant Converter as PdfConverter
    participant Builder as DocumentBuilder
    participant Provider as PdfProvider
    participant Layout as LayoutBuilder
    participant Line as LineBuilder
    participant OCR as OcrBuilder
    participant Processor as Processors
    
    Provider->>Layout: 提供页面图像
    Layout->>Layout: 检测布局块
    Layout->>Line: 传递布局信息
    Line->>Line: 检测文本行
    Line->>OCR: 传递行信息
    OCR->>OCR: OCR 文本识别
    OCR->>Builder: 组装文档结构
    
    Builder->>Processor: 传递完整文档
    loop 每个处理器
        Processor->>Processor: process_block()
    end
    
    Processor->>Converter: 处理完成的文档

常见问题与解决方案

Mac 平台性能问题

问题描述：在 Mac M1+ 芯片上，v1.9.0+ 版本出现 20 倍以上的性能下降。

解决方案：如果遇到此问题，安装 v1.8.0 版本作为临时修复：

pip install marker==1.8.0

资料来源：GitHub Issue #960

内存溢出问题

问题描述：处理大型 PDF（数百页）时出现内存溢出错误：

OSError: [Errno 12] Cannot allocate memory

可能的解决方案：

• 减少并发 worker 数量
• 使用 --paginate_output 分页输出
• 分批处理大型文档

资料来源：GitHub Issue #1032

Gemini API 限流问题

问题描述：使用 Gemini API 时出现请求超限错误：

ResourceExhausted: 429 RESOURCE_EXHAUSTED

解决方案：

• 实现请求间隔机制
• 使用 --llm_service ollama 切换到本地模型
• 联系 Datalab 获取更高的 API 配额

资料来源：GitHub Issue #490

LLM 模式下的表格处理

在 v1.9.2 及之后版本，LLM 处理器支持循环优化以提升表格质量。可以通过配置调整优化次数：

config = {
    "llm_table_iterations": 3  # 默认为 1-2
}

图片提取与 LLM 描述

同时启用图片提取和 LLM 描述时，输出中的图片会被替换为 LLM 生成的描述文本：

marker_single input.pdf --use_llm  # 图片会被描述替换
marker_single input.pdf --disable_image_extraction  # 完全不提取图片
marker_single input.pdf --use_llm --disable_image_extraction  # 图片保留但额外生成描述

性能优化建议

处理器选择

根据文档类型选择性地启用处理器可以显著提升性能：

GPU 内存管理

每个 worker 在峰值时使用约 5GB VRAM，平均使用 3.5GB。根据可用 GPU 内存调整并发数：

# 24GB VRAM 的 GPU
NUM_DEVICES=4 NUM_WORKERS=15 marker_chunk_convert input.pdf output/

# 12GB VRAM 的 GPU
NUM_DEVICES=2 NUM_WORKERS=5 marker_chunk_convert input.pdf output/

批处理优化

对于大量 PDF 文件，使用批量转换模式并调整 worker 数量：

marker /path/to/input/folder --workers 8

参见

• 快速开始指南 - Marker 基础使用教程
• 配置参考 - 完整的配置选项说明
• 输出格式详解 - Markdown、JSON、HTML 输出格式说明
• 部署指南 - 生产环境部署建议
• API 参考 - Python API 详细文档

架构概述

Marker 的渲染系统采用分层架构，渲染器作为转换管道的最终环节，负责将处理完成的文档对象渲染为特定格式的输出。

graph TD
    A[PDF 输入文件] --> B[DocumentBuilder 文档构建]
    B --> C[LayoutBuilder 布局检测]
    C --> D[LineBuilder 行检测]
    D --> E[OcrBuilder OCR识别]
    E --> F[StructureBuilder 结构分析]
    F --> G[处理器链 ProcessorList]
    G --> H[渲染器 Renderer]
    H --> I[Markdown 输出]
    H --> J[JSON 输出]
    H --> K[HTML 输出]
    H --> L[Chunks 输出]

渲染器基类

所有渲染器都继承自 BaseRenderer 基类，定义在 marker/renderers/__init__.py。每个渲染器接收一个 Document 对象并返回对应格式的输出对象。

资料来源：marker/converters/pdf.py:42-43

输出格式详解

Markdown 格式

Markdown 是 Marker 的默认输出格式，能够保留文档的大部分格式信息。

#### 输出特性

资料来源：README.md

#### HTML 表格选项

在 v1.10.0 版本中引入了 --html_tables_in_markdown 参数，当 output_format 设置为 markdown 时，可以选择使用 HTML 标签渲染表格，替代默认的 Markdown 语法。

marker /path/to/file.pdf --output_format markdown --html_tables_in_markdown

#### MarkdownRenderer 配置

MarkdownRenderer 类的核心配置参数：

资料来源：marker/renderers/markdown.py:29-52

JSON 格式

JSON 输出提供完整的结构化数据，适合程序化处理和二次开发。

#### JSON 结构

JSON 输出按页面组织，每个页面作为一个块（block）呈现：

{
  "pages": [
    {
      "page_id": "page_0",
      "block_type": "Page",
      "children": [...]
    }
  ],
  "metadata": {
    "total_pages": 10,
    "file_path": "document.pdf"
  }
}

#### 块类型

Marker 内部定义的块类型包括：

资料来源：marker/schema/__init__.py

HTML 格式

HTML 输出与 Markdown 输出类似，但使用 HTML 标签替代 Markdown 语法：

Chunks 格式

Chunks 格式将文档分割为更小的可管理单元，便于大型文档的流式处理和增量处理。

资料来源：marker/renderers/chunk.py

配置与使用

命令行配置

通过 --output_format 参数指定输出格式：

# 输出为 Markdown
marker_single /path/to/file.pdf --output_format markdown

# 输出为 JSON
marker_single /path/to/file.pdf --output_format json

# 输出为 HTML
marker_single /path/to/file.pdf --output_format html

# 输出为 Chunks
marker_single /path/to/file.pdf --output_format chunks

#### 输出目录配置

marker_single /path/to/file.pdf --output_dir /path/to/output/

默认输出目录由 settings.OUTPUT_DIR 配置项指定。

资料来源：marker/config/parser.py:28-30

Python API 使用

#### 基础用法

from marker.converters.pdf import PdfConverter
from marker.models import create_model_dict
from marker.output import text_from_rendered

converter = PdfConverter(
    artifact_dict=create_model_dict(),
)
rendered = converter("FILEPATH")
text, _, images = text_from_rendered(rendered)

#### 指定渲染器

from marker.renderers.json import JSONRenderer
from marker.renderers.html import HTMLRenderer
from marker.renderers.chunk import ChunkRenderer

# 使用 JSON 渲染器
converter = PdfConverter(
    artifact_dict=model_dict,
    renderer=JSONRenderer,
)

# 使用 HTML 渲染器
converter = PdfConverter(
    artifact_dict=model_dict,
    renderer=HTMLRenderer,
)

#### 配置分页输出

from marker.renderers.markdown import MarkdownRenderer

renderer = MarkdownRenderer(
    paginate_output=True,
    page_separator="\n\n{PAGE_NUMBER}\n" + "-" * 48 + "\n\n"
)

资料来源：marker/renderers/markdown.py:54-63

JSON 配置文件

可以通过 --config_json 参数传入 JSON 配置文件：

marker_single /path/to/file.pdf --config_json /path/to/config.json

配置文件示例：

{
  "output_format": "markdown",
  "output_dir": "./output",
  "paginate_output": true,
  "html_tables_in_markdown": true,
  "debug": false
}

渲染器与转换器的集成

PdfConverter 中的渲染器注入

PdfConverter 类接收渲染器作为构造参数：

class PdfConverter(BaseConverter):
    def __init__(
        self,
        config: dict,
        artifact_dict: dict,
        processor_list: List[BaseProcessor],
        renderer: Type[BaseRenderer] = MarkdownRenderer,
        llm_service: Optional[BaseService] = None,
    ):
        self.renderer = renderer

资料来源：marker/converters/pdf.py:57-63

ConfigParser 的渲染器选择

ConfigParser 根据 output_format 参数自动选择对应的渲染器：

def get_renderer(self):
    output_format = self.get("output_format", "markdown")
    renderer_map = {
        "markdown": MarkdownRenderer,
        "json": JSONRenderer,
        "html": HTMLRenderer,
        "chunks": ChunkRenderer,
    }
    return renderer_map.get(output_format, MarkdownRenderer)

资料来源：marker/config/parser.py:10-23

输出处理

text_from_rendered 函数

marker/output.py 中的 text_from_rendered 函数提供统一的输出解析接口：

def text_from_rendered(rendered):
    """
    返回: (text, extension, images)
    """

根据输出格式不同，返回值有所差异：

资料来源：marker/output.py

常见问题与解决方案

内存相关问题

处理大型 PDF 文件时可能出现内存不足问题。社区反馈显示，750 页的 PDF 可能消耗约 20GB 内存。

建议方案：

• 使用 --paginate_output 启用分页处理
• 限制 --workers 数量减少并发内存占用
• 考虑使用批量处理模式

资料来源：GitHub Issue #583

输出格式选择建议

表格渲染问题

社区在 v1.9.1 版本中修复了空白表格单元的问题。如果遇到表格渲染异常：

1. 确保使用的是最新版本的 Marker
2. 考虑添加 --use_llm 参数，启用 LLM 处理器改进表格识别
3. 使用 --html_tables_in_markdown 切换表格渲染方式

资料来源：GitHub Release v1.9.1

公式渲染问题

对于复杂的数学公式，建议：

• 使用 --force_ocr 强制 OCR 处理
• 配合 --use_llm 启用 LLM 改进公式识别
• 检查行内公式分隔符配置是否与源文档冲突

扩展渲染器

如需自定义输出格式，可以继承 BaseRenderer 类：

from marker.renderers import BaseRenderer

class CustomRenderer(BaseRenderer):
    def __init__(self, config: dict):
        self.config = config
    
    def __call__(self, document: Document) -> Any:
        # 自定义渲染逻辑
        return custom_output

然后在转换器中指定自定义渲染器：

converter = PdfConverter(
    artifact_dict=model_dict,
    renderer=CustomRenderer,
)

参见

• 安装与快速开始
• 处理器详解
• 命令行工具
• Python API 使用
• LLM 服务配置

概述

Marker 的 LLM 集成功能通过将深度学习模型与大型语言模型相结合，显著提升 PDF 转换的准确性和输出质量。混合模式（Hybrid Mode）允许 Marker 在处理复杂布局、表格格式化、数学公式和表单识别时调用外部 LLM 服务进行后处理，从而解决纯模型方法难以处理的边缘情况。

根据 v1.9.2 版本的更新说明，LLM 处理器支持循环改进表格内容，并能够检测并修复表格单元格切割文本行的问题，有效减少 LLM 幻觉（hallucination）现象。资料来源：marker/processors/llm/llm_table.py:1-100

架构设计

整体处理流程

Marker 的混合模式采用流水线架构，LLM 在特定处理阶段介入以增强输出质量：

graph TD
    A[PDF 输入] --> B[布局检测 Layout Detection]
    B --> C[行检测 Line Detection]
    C --> D[OCR 识别]
    D --> E{是否启用 LLM?}
    E -->|否| F[基础后处理]
    E -->|是| G[LLM 处理器链]
    G --> H[表格格式化 LLMTableProcessor]
    G --> I[复杂区域 LLMComplexRegionProcessor]
    G --> J[表单识别 LLMFormProcessor]
    G --> K[图片描述 LLMImageDescriptionProcessor]
    H --> L[块校正 Block Correction]
    I --> L
    J --> L
    K --> L
    L --> M[最终输出]
    F --> M

LLM 服务层抽象

Marker 通过抽象的 BaseService 类实现 LLM 服务的解耦，支持多种后端服务。服务层负责处理 API 调用、重试逻辑和响应解析。资料来源：marker/services/__init__.py:1-50

classDiagram
    class BaseService {
        +abstractmethod call(messages: List) str
        +abstractmethod supports_vision() bool
        +abstractmethod supports_function_calling() bool
    }
    
    class GoogleGeminiService {
        +call()
        +supports_vision()
        +supports_function_calling()
    }
    
    class OllamaService {
        +call()
        +supports_vision()
        +supports_function_calling()
    }
    
    class AzureOpenAIService {
        +call()
        +supports_vision()
        +supports_function_calling()
    }
    
    BaseService <|-- GoogleGeminiService
    BaseService <|-- OllamaService
    BaseService <|-- AzureOpenAIService

支持的 LLM 服务

服务对比表

Google Gemini 服务

Gemini 是 Marker 的默认 LLM 服务，通过 GoogleGeminiService 类实现。服务默认使用 gemini-2.0-flash 模型，该模型在速度和准确性之间取得了良好平衡。资料来源：marker/services/gemini.py:1-100

环境变量配置：

export GEMINI_API_KEY="your-api-key-here"

Ollama 本地服务

对于需要完全离线或私有化部署的场景，Marker 支持 Ollama 本地 LLM 服务。Ollama 服务允许使用本地运行的模型，如 Llama 3、Code Llama 等。资料来源：marker/services/ollama.py:1-100

环境变量配置：

export OLLAMA_BASE_URL="http://localhost:11434"  # 默认值

示例配置：

from marker.services.ollama import OllamaService

service = OllamaService(
    base_url="http://localhost:11434",
    model="llama3"
)

Azure OpenAI 服务

企业用户可以通过 Azure OpenAI 服务使用 Marker，该服务支持 Azure 的安全合规特性和托管基础设施。资料来源：marker/services/azure_openai.py:1-100

环境变量配置：

export AZURE_OPENAI_API_KEY="your-azure-key"
export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com"
export AZURE_OPENAI_API_VERSION="2024-02-01"
export AZURE_OPENAI_DEPLOYMENT_NAME="your-deployment-name"

LLM 处理器

Marker 在混合模式下使用多个专门的 LLM 处理器，每个处理器负责特定类型的内容优化。

处理器列表与职责

表格处理器详解

LLMTableProcessor 是最常用的 LLM 处理器，专门处理 PDF 中复杂表格的识别和格式化。该处理器能够：

• 检测并修复被单元格边界切割的文本行
• 识别跨越多行或多列的表头单元格
• 合并因分页而分割的表格
• 优化表格单元格内容的格式

根据 v1.9.2 版本的更新，表格处理器支持循环改进机制，可以多次调用 LLM 直到表格质量达到预期标准。资料来源：marker/processors/llm/llm_table.py:50-150

复杂区域处理器

LLMComplexRegionProcessor 专门处理文档中结构复杂的区域，包括：

• 多栏布局中的嵌套内容块
• 内联数学公式的正确渲染
• 脚注和边注的关联处理
• 代码块与普通文本的边界识别

配置与使用

命令行启用 LLM 模式

通过 --use_llm 标志启用 LLM 混合模式：

marker_single document.pdf --output_dir ./output --use_llm

指定 LLM 服务

使用 --llm_service 参数指定要使用的 LLM 服务：

# 使用 Gemini（默认）
marker_single document.pdf --use_llm --llm_service marker.services.gemini.GoogleGeminiService

# 使用 Ollama
marker_single document.pdf --use_llm --llm_service marker.services.ollama.OllamaService

# 使用 Azure OpenAI
marker_single document.pdf --use_llm --llm_service marker.services.azure_openai.AzureOpenAIService

自定义校正提示

通过 --block_correction_prompt 参数添加自定义校正指令：

marker_single document.pdf --use_llm --block_correction_prompt "请保持所有技术术语的英文原文"

Python API 配置

在 Python 代码中配置 LLM 集成：

from marker.converters.pdf import PdfConverter
from marker.models import create_model_dict
from marker.config.parser import ConfigParser
from marker.services.gemini import GoogleGeminiService

# 创建配置解析器
cli_options = {
    "output_format": "markdown",
    "use_llm": True,
    "llm_service": "marker.services.gemini.GoogleGeminiService"
}
config_parser = ConfigParser(cli_options)

# 创建转换器
converter = PdfConverter(
    config=config_parser.generate_config_dict(),
    artifact_dict=create_model_dict(),
    processor_list=config_parser.get_processors(),
    renderer=config_parser.get_renderer(),
    llm_service=config_parser.get_llm_service(),
)

# 执行转换
rendered = converter("document.pdf")

资料来源：marker/converters/pdf.py:50-100

JSON 配置文件

创建 config.json 配置文件：

{
  "use_llm": true,
  "llm_service": "marker.services.gemini.GoogleGeminiService",
  "output_format": "markdown",
  "debug": false,
  "block_correction_prompt": "Your custom prompt here"
}

使用配置文件：

marker_single document.pdf --config_json ./config.json

性能考虑

资源消耗

启用 LLM 模式会显著增加处理时间和 API 调用成本：

批量处理优化

对于大量文档的批量处理，建议：

1. 使用支持函数调用的模型以减少 API 调用次数
2. 启用 --disable_image_extraction 减少处理内容
3. 考虑使用本地 Ollama 服务降低 API 成本

Gemini API 速率限制

根据社区反馈（Issue #490），Gemini API 存在每分钟 15 次请求的限制。在处理大批量文档时，可能会遇到 ResourceExhausted 错误。建议：

• 在高负载场景下添加请求间隔
• 使用支持更高限额的付费 API 套餐
• 考虑使用 Ollama 进行本地部署

常见问题与故障排除

API 密钥配置错误

错误表现：

AuthenticationError: Invalid API key provided

解决方案：

1. 确认环境变量 GEMINI_API_KEY 已正确设置
2. 检查 API 密钥是否有效且未过期
3. 对于 Azure OpenAI，确认 AZURE_OPENAI_API_KEY 和 AZURE_OPENAI_ENDPOINT 都已配置

JSON 解析失败

Marker 内置了无效 JSON 的重试机制。v1.8.4 版本添加了对 Gemini 返回无效 JSON 时的自动重试功能。资料来源：marker/services/gemini.py:100-150

错误表现：

JSONDecodeError: Expecting value

解决方案：

1. 检查 LLM 服务是否可用
2. 确认网络连接稳定
3. 降低单次处理的页数，减少响应长度

模型版本不兼容

错误表现：

TypeError: VariableDonutSwinEmbeddings.forward() got an unexpected keyword argument 'interpolate_pos_encoding'

此问题常见于 Docker 容器环境，原因是依赖库版本不匹配。解决方案包括：

1. 更新 marker-pdf 到最新版本
2. 确保 transformers 库版本兼容
3. 使用官方提供的 Docker 镜像

Mac M1/M2 性能问题

社区反馈（Issue #960）显示，v1.9.0 及以上版本在 Mac M1+ 芯片上存在 20 倍以上的性能下降。如遇此问题，可临时降级至 v1.8.0：

pip install marker-pdf==1.8.0

最佳实践

何时使用 LLM 模式

建议启用 LLM 模式的场景：

• 包含复杂表格的学术论文或报告
• 多栏布局的技术文档
• 含有表单字段的政府或法律文件
• 需要准确提取数学公式的科学文献
• 需要识别内联代码和代码块的开发者文档

可跳过 LLM 模式的场景：

• 简单布局的单栏文档
• 以纯文本为主的书籍或文章
• 对处理速度有严格要求的实时应用
• 离线或资源受限的部署环境

提示工程建议

使用 --block_correction_prompt 时，遵循以下原则：

1. 保持简洁：提示应简短明确，避免过长指令
2. 指定格式：明确说明期望的输出格式
3. 语言一致：对于多语言文档，指定输出语言
4. 术语处理：对于专业术语，提供翻译或保留原文的指导

示例提示：

# 保持英文技术术语
--block_correction_prompt "Keep all technical terms like API, SDK, JSON in English. Format tables with proper alignment."

# 中文输出
--block_correction_prompt "将所有内容翻译为简体中文，保持专业术语的准确性。"

安全与隐私

使用 LLM 服务时需注意：

1. API 密钥保护：不要在代码中硬编码 API 密钥
2. 数据隐私：确认 LLM 服务提供商的数据处理政策
3. 敏感文档：对于包含敏感信息的文档，考虑使用 Ollama 本地部署

参见

• 快速入门指南 - Marker 基础使用教程
• 配置选项参考 - 完整的命令行参数说明
• 支持的文档格式 - PDF 及其他格式详解
• 部署指南 - 生产环境部署最佳实践
• API 参考 - Python API 详细文档

配置系统概述

Marker 的配置系统采用分层架构，支持以下配置方式（优先级从高到低）：

1. Python API 直接传入参数
2. JSON 配置文件
3. 命令行参数
4. 环境变量
5. settings.py 默认配置

graph TD
    A[配置输入] --> B[Python API]
    A --> C[JSON 配置文件]
    A --> D[命令行参数]
    A --> E[环境变量]
    B --> F[ConfigParser 统一处理]
    C --> F
    D --> F
    E --> F
    F --> G[配置合并与验证]
    G --> H[PdfConverter 执行转换]

配置解析器 ConfigParser 负责整合所有配置源并生成最终配置字典。资料来源：marker/config/parser.py:30-80

环境变量配置

Marker 支持通过环境变量进行全局配置。以下是主要支持的环境变量：

资料来源：marker/settings.py

设备配置示例

# 使用 CUDA GPU
export TORCH_DEVICE=cuda

# 使用 Apple MPS (M1/M2 芯片)
export TORCH_DEVICE=mps

# 使用 CPU
export TORCH_DEVICE=cpu

注意：在 macOS 上使用 Marker v1.9.0+ 存在性能问题（比 v1.8.0 慢 20 倍以上），如遇此问题可暂时降级至 v1.8.0。资料来源：Issue #960

命令行参数详解

Marker 提供了丰富的命令行参数用于控制转换行为。

marker_single 单文件转换

marker_single /path/to/file.pdf [选项]

资料来源：marker/scripts/convert.py

marker 批量转换

marker /path/to/input/folder [选项]

每个 worker 峰值使用约 5GB VRAM，平均 3.5GB。资料来源：README.md

多 GPU 并行转换

NUM_DEVICES=4 NUM_WORKERS=15 marker_chunk_convert ../pdf_in ../md_out

• NUM_DEVICES：使用的 GPU 数量（至少 2 个）
• NUM_WORKERS：每个 GPU 的并行进程数

JSON 配置文件

通过 --config_json 参数可以指定 JSON 配置文件，实现配置的持久化和复用。

配置结构

{
  "output_format": "markdown",
  "output_dir": "/path/to/output",
  "page_range": [0, 1, 2, "5-10"],
  "use_llm": true,
  "force_ocr": false,
  "strip_existing_ocr": false,
  "disable_image_extraction": false,
  "debug": false,
  "disable_ocr_math": false,
  "html_tables_in_markdown": false,
  "llm_service": "marker.services.gemini.GoogleGeminiService",
  "block_correction_prompt": "Your custom prompt here",
  "converters": {
    "pdf": {
      "artifact_dict": {...},
      "processor_list": [...],
      "renderer": "..."
    }
  }
}

配置解析机制

ConfigParser 类负责加载和合并配置：

class ConfigParser:
    def __init__(self, cli_options: Dict[str, Any] = None):
        self.cli_options = cli_options or {}
    
    def generate_config_dict(self) -> Dict[str, Any]:
        # 合并默认配置、JSON 配置、CLI 配置
        ...
    
    def get_llm_service(self) -> Type[BaseService]:
        # 获取 LLM 服务实例
        ...
    
    def get_processors(self) -> List[BaseProcessor]:
        # 获取处理器列表
        ...
    
    def get_renderer(self) -> BaseRenderer:
        # 获取渲染器
        ...

资料来源：marker/config/parser.py:40-100

Python API 配置

在 Python 代码中直接使用 Marker 提供了最大的灵活性。

基础用法

from marker.converters.pdf import PdfConverter
from marker.models import create_model_dict
from marker.output import text_from_rendered

# 创建转换器
converter = PdfConverter(
    artifact_dict=create_model_dict(),
)

# 执行转换
rendered = converter("/path/to/file.pdf")
text, _, images = text_from_rendered(rendered)

完整配置示例

from marker.converters.pdf import PdfConverter
from marker.models import create_model_dict
from marker.config.parser import ConfigParser
from marker.output import text_from_rendered

# 定义 CLI 选项
cli_options = {
    "output_format": "markdown",
    "page_range": "0-5",
    "use_llm": True,
    "force_ocr": False,
    "debug": False,
}

# 创建配置解析器
config_parser = ConfigParser(cli_options)

# 创建转换器
converter = PdfConverter(
    config=config_parser.generate_config_dict(),
    artifact_dict=create_model_dict(),
    processor_list=config_parser.get_processors(),
    renderer=config_parser.get_renderer(),
    llm_service=config_parser.get_llm_service(),
)

# 执行转换
rendered = converter("/path/to/file.pdf")

资料来源：marker/converters/pdf.py:50-120

增量转换（跳过已处理内容）

# 首次转换
rendered = converter("FILEPATH")

# 后续转换，传入已转换的 markdown
converter_with_existing = PdfConverter(
    config={"existing_markdown": rendered.original_markdown},
    ...
)

当传入 existing_markdown 时，转换器会跳过已解析的文档部分。

LLM 服务配置

Marker 支持通过 LLM 提升转换质量。

可用的 LLM 服务

Gemini 配置

# 通过环境变量
export GOOGLE_API_KEY="your-api-key"

# 或在代码中设置
import os
os.environ["GOOGLE_API_KEY"] = "your-api-key"

默认使用 gemini-2.0-flash 模型。如需使用其他模型：

from marker.services.gemini import GoogleGeminiService

service = GoogleGeminiService(
    model_name="gemini-1.5-pro"
)

自定义 LLM 提示词

marker_single file.pdf --use_llm --block_correction_prompt "请确保输出格式规范，中文翻译准确"

资料来源：marker/scripts/convert.py:100-150

注意：Gemini API 有速率限制（约 15 请求/分钟），大量转换时需注意控制请求频率。资料来源：Issue #490

模型配置

模型字典

create_model_dict() 函数创建并返回所有必需的模型：

from marker.models import create_model_dict

model_dict = create_model_dict()
# 返回:
# {
#     "ocr_model": ...,
#     "layout_model": ...,
#     "order_model": ...,
#     "table_model": ...,
#     "lang_model": ...,
#     "texify_model": ...
# }

模型缓存

模型默认缓存在 ~/.cache/datalab/models 目录。

DocumentBuilder 配置

from marker.builders.document import DocumentBuilder

builder = DocumentBuilder(config={
    "lowres_image_dpi": 96,    # 布局检测 DPI
    "highres_image_dpi": 192,   # OCR 高分辨率 DPI
    "disable_ocr": False,       # 禁用 OCR
})

资料来源：marker/builders/document.py:15-40

处理器列表

Marker 使用处理器链对文档进行后处理：

资料来源：marker/converters/pdf.py:30-55

输出格式配置

Markdown 输出

config = {
    "output_format": "markdown",
    "html_tables_in_markdown": False,  # True 则使用 HTML 表格
}

JSON 输出

config = {
    "output_format": "json",
}

JSON 输出结构：

{
  "pages": [
    {
      "page_id": 0,
      "blocks": [
        {
          "id": "block_0",
          "block_type": "Text",
          "content": "..."
        }
      ]
    }
  ]
}

HTML 输出

config = {
    "output_format": "html",
}

Chunks 输出

config = {
    "output_format": "chunks",
}

常见问题与故障排除

内存问题

处理大型 PDF 时可能遇到内存问题：

资料来源：Issue #583、Issue #919

依赖缺失

Docker 环境中可能缺少 psutil：

pip install psutil

资料来源：Issue #818

Mac 性能问题

在 macOS M1+ 芯片上 v1.9.0+ 版本性能下降：

pip install marker-pdf==1.8.0

资料来源：Issue #960

模块导入错误

确保安装完整依赖：

pip install marker-pdf[full]

资料来源：Issue #575

配置最佳实践

1. 开发调试：启用 --debug 参数，输出详细日志
2. 生产环境：使用 JSON 配置文件便于管理和版本控制
3. 大规模处理：使用多 GPU 配置 + 批量处理
4. 高质量需求：启用 --use_llm 并配置 API Key
5. 资源受限：使用 --disable_image_extraction 减少内存占用

相关页面

• 安装指南
• CLI 使用教程
• Python API 参考
• LLM 集成
• 部署示例

概述

Marker 提供了多种部署方式以满足不同的使用场景：

资料来源：marker_server.py:1-20

FastAPI REST API 服务

服务架构

Marker 提供基于 FastAPI 的 REST API 服务，支持文件上传、批量处理和异步转换。

graph TD
    A[客户端请求] --> B[FastAPI 端点]
    B --> C[文件上传/验证]
    C --> D[ConfigParser 配置解析]
    D --> E[PdfConverter 转换器]
    E --> F[模型推理]
    F --> G[渲染输出]
    G --> H[JSON/Markdown/HTML 响应]
    
    F --> F1[Layout 模型]
    F --> F2[OCR 模型]
    F --> F3[Equation 模型]
    F --> F4[LLM 服务可选]

核心组件

服务启动

FastAPI 服务可以通过以下方式启动：

# 方式一：直接运行
python -m uvicorn marker.scripts.server:app --host 0.0.0.0 --port 8000

# 方式二：使用 marker_server.py
python marker_server.py

API 端点

服务提供以下核心端点：

转换函数实现

核心转换逻辑封装在 convert_pdf 函数中：

def convert_pdf(fname: str, config_parser: ConfigParser) -> (str, Dict[str, Any], dict):
    config_dict = config_parser.generate_config_dict()
    config_dict["pdftext_workers"] = 1
    converter_cls = PdfConverter
    converter = converter_cls(
        config=config_dict,
        artifact_dict=model_dict,
        processor_list=config_parser.get_processors(),
        renderer=config_parser.get_renderer(),
        llm_service=config_parser.get_llm_service(),
    )
    return converter(fname)

资料来源：marker/scripts/streamlit_app.py:40-55

配置参数

Streamlit Web 应用

应用类型

Marker 提供两种 Streamlit Web 应用：

主转换应用架构

graph LR
    A[文件上传] --> B[参数配置]
    B --> C[Marker 转换]
    C --> D[输出渲染]
    
    D --> E1[Markdown 预览]
    D --> E2[JSON 查看]
    D --> E3[HTML 渲染]
    D --> E4[分块查看]

数据提取应用

数据提取应用支持基于 JSON Schema 或 Pydantic Schema 的结构化数据提取：

# 提取应用核心流程
rendered = extract_data(
    temp_pdf,      # PDF 文件路径
    cli_options,   # 命令行选项
    schema,        # 数据 Schema
    markdown       # 可选的已有 Markdown
)

资料来源：marker/scripts/extraction_app.py:80-90

启动命令

# 主转换应用
streamlit run marker/scripts/streamlit_app.py

# 数据提取应用
streamlit run marker/scripts/extraction_app.py

环境变量配置

# 必须设置的环境变量
os.environ["PYTORCH_ENABLE_MPS_FALLBACK"] = "1"  # 启用 MPS 后备
os.environ["IN_STREAMLIT"] = "true"              # 标识在 Streamlit 环境中运行

Modal 云端部署

部署概述

Modal 是一个无服务器 GPU 平台，适合部署需要 GPU 加速的 Marker 服务。

graph TD
    A[API 请求] --> B[Modal 端点]
    B --> C[容器初始化]
    C --> D[模型加载]
    D --> E{缓存检查}
    E -->|模型存在| F[跳过下载]
    E -->|模型不存在| G[下载模型]
    G --> H[缓存到 Volume]
    F --> I[执行转换]
    H --> I
    I --> J[返回结果]

部署配置

资料来源：examples/marker_modal_deployment.py:15-35

容器镜像定义

image = (
    modal.Image.debian_slim(python_version="3.10")
    .apt_install(["git", "wget"])
    .env({"TORCH_DEVICE": "cuda"})
    .pip_install([
        "marker-pdf[full]",
        "fastapi==0.104.1",
        "uvicorn==0.24.0",
        "python-multipart==0.0.6",
        "torch>=2.2.2,<3.0.0",
        "torchvision>=0.17.0",
        "torchaudio>=2.2.0",
    ])
)

模型缓存管理

Modal 部署支持模型缓存以加快冷启动速度：

def setup_models_with_cache_check(logger, commit_volume=False):
    """
    检查并管理模型缓存
    """
    models_dir_exists = os.path.exists(MODEL_PATH_PREFIX)
    models_dir_contents = os.listdir(MODEL_PATH_PREFIX) if models_dir_exists else []
    
    logger.info(f"Models cache directory exists: {models_dir_exists}")
    logger.info(f"Models cache directory contents: {models_dir_contents}")

性能优化与资源配置

GPU 资源配置

资料来源：README.md - 多 GPU 部署说明

内存配置

# 环境变量配置
os.environ["PYTORCH_ENABLE_MPS_FALLBACK"] = "1"  # Mac MPS 后备

# 每个 worker 的内存需求
# 峰值: 5GB VRAM
# 平均: 3.5GB VRAM
# 系统内存: 建议预留 4GB+ per worker

多进程配置

# 单 GPU 多进程
marker /path/to/input --workers 4

# 多 GPU 配置
NUM_DEVICES=4 NUM_WORKERS=15 marker_chunk_convert ../pdf_in ../md_out

常见问题与解决方案

问题 1：Mac 上性能下降 20 倍

问题描述：v1.9.0+ 版本在 Mac M1+ 芯片上性能严重下降。

解决方案：

# 降级到 v1.8.0
pip install marker==1.8.0

相关 issue：Issue #960

问题 2：内存溢出 (OOM)

问题描述：处理大型 PDF 时内存耗尽。

解决方案：

1. 减少并发 worker 数量
2. 分批处理页面
3. 使用 --page_range 限制处理范围

相关 issue：Issue #1032

问题 3：依赖缺失

问题描述：缺少 psutil 等依赖。

解决方案：

# 安装完整依赖
pip install marker-pdf[full]

# 或单独安装
pip install psutil

相关 issue：Issue #818

问题 4：Gemini API 限流

问题描述：Gemini API 请求超过速率限制。

解决方案：

1. 实现请求间隔控制
2. 使用本地 LLM (Ollama)
3. 减少 --use_llm 的使用场景

相关 issue：Issue #490

配置示例

基础配置 (JSON)

{
  "output_format": "markdown",
  "output_dir": "./output",
  "page_range": "0,5-10,20",
  "force_ocr": false,
  "use_llm": false,
  "debug": false,
  "disable_image_extraction": false
}

LLM 配置

# 使用 Gemini 服务
from marker.services.gemini import GoogleGeminiService

llm_service = GoogleGeminiService()

# 或使用 Ollama (本地)
# 配置 ollama 服务的 URL 和模型名称

使用已有 Markdown 跳过解析

# 如果已有转换后的 Markdown，可以复用以跳过解析步骤
config["existing_markdown"] = previous_markdown
converter = PdfConverter(config=config, ...)

资料来源：marker/converters/extraction.py:15-20

生产环境部署建议

容器化部署

FROM python:3.10-slim

WORKDIR /app

# 安装系统依赖
RUN apt-get update && apt-get install -y \
    libgl1-mesa-glx \
    libglib2.0-0 \
    && rm -rf /var/lib/apt/lists/*

# 安装 marker
RUN pip install marker-pdf[full]

# 复制应用代码
COPY . /app

# 运行服务
CMD ["uvicorn", "marker.scripts.server:app", "--host", "0.0.0.0", "--port", "8000"]

监控指标

建议监控以下指标：

高可用配置

# docker-compose.yml 示例
services:
  marker-api:
    image: marker-pdf:latest
    deploy:
      replicas: 3
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
    environment:
      - NUM_DEVICES=1
      - MODEL_CACHE=/models
    volumes:
      - model-cache:/models

volumes:
  model-cache:

相关文档

• 安装指南 - 环境配置和依赖安装
• 命令行工具 - marker 和 marker_single 使用方法
• Python API - PdfConverter 和相关类
• 输出格式 - Markdown/JSON/HTML 格式详解
• LLM 集成 - LLM 服务配置
• 性能优化 - 性能调优指南

Pitfall Log / 踩坑日志

项目：datalab-to/marker

摘要：发现 23 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：[BUG: Breaking]。

1. 安装坑 · 来源证据：[BUG: Breaking]

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG: Breaking]
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_5e263773fc84449f88bdf5f4ec5dfeba | https://github.com/datalab-to/marker/issues/1032 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：[BUG: Breaking] Marker is 20x+ slower since v1.9.0+ in Mac

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG: Breaking] Marker is 20x+ slower since v1.9.0+ in Mac
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_310c8ea2147f416597bcff9cc1438928 | https://github.com/datalab-to/marker/issues/960 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

3. 安装坑 · 来源证据：[BUG: Breaking] missing dependency: psutil

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG: Breaking] missing dependency: psutil
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_7b635cb675114e8fa34251c940ce4a92 | https://github.com/datalab-to/marker/issues/818 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

4. 安装坑 · 失败模式：installation: [BUG: Breaking]

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: [BUG: Breaking]
• 对用户的影响：Developers may fail before the first successful local run: [BUG: Breaking]
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [BUG: Breaking]. Context: Observed when using python, linux
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_163a0175abe51d147c94b98207ebbc97 | https://github.com/datalab-to/marker/issues/1032 | [BUG: Breaking]

5. 安装坑 · 失败模式：installation: [BUG: Breaking] Marker is 20x+ slower since v1.9.0+ in Mac

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: [BUG: Breaking] Marker is 20x+ slower since v1.9.0+ in Mac
• 对用户的影响：Developers may fail before the first successful local run: [BUG: Breaking] Marker is 20x+ slower since v1.9.0+ in Mac
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [BUG: Breaking] Marker is 20x+ slower since v1.9.0+ in Mac. Context: Observed when using python, cuda
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_17d2e6761f9590ea709f9a3c31258ef2 | https://github.com/datalab-to/marker/issues/960 | [BUG: Breaking] Marker is 20x+ slower since v1.9.0+ in Mac

6. 安装坑 · 失败模式：installation: [BUG: Breaking] missing dependency: psutil

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: [BUG: Breaking] missing dependency: psutil
• 对用户的影响：Developers may fail before the first successful local run: [BUG: Breaking] missing dependency: psutil
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [BUG: Breaking] missing dependency: psutil. Context: Observed when using python, docker
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_7f0847da6ce4e932ebb7040531b8c2fb | https://github.com/datalab-to/marker/issues/818 | [BUG: Breaking] missing dependency: psutil

7. 配置坑 · 失败模式：configuration: Minor fixes

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Minor fixes
• 对用户的影响：Upgrade or migration may change expected behavior: Minor fixes
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Minor fixes. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_9bd20653f46c11589bffedacd93a5209 | https://github.com/datalab-to/marker/releases/tag/v1.10.1 | Minor fixes

8. 配置坑 · 失败模式：configuration: [BUG: Breaking]torch.AcceleratorError: index 8192 is out of bounds: 2, range 0 to 4756

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: [BUG: Breaking]torch.AcceleratorError: index 8192 is out of bounds: 2, range 0 to 4756
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [BUG: Breaking]torch.AcceleratorError: index 8192 is out of bounds: 2, range 0 to 4756
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [BUG: Breaking]torch.AcceleratorError: index 8192 is out of bounds: 2, range 0 to 4756. Context: Observed when using python
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_7f14e833dcd25affa00b77c20fbaedad | https://github.com/datalab-to/marker/issues/1036 | [BUG: Breaking]torch.AcceleratorError: index 8192 is out of bounds: 2, range 0 to 4756

9. 配置坑 · 失败模式：configuration: [FEAT] Export converter: save extracted tables and structured content to SQLite / CSV

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: [FEAT] Export converter: save extracted tables and structured content to SQLite / CSV
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [FEAT] Export converter: save extracted tables and structured content to SQLite / CSV
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [FEAT] Export converter: save extracted tables and structured content to SQLite / CSV. Context: Observed when using python
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_e892a62132667ffb55c57d798a583266 | https://github.com/datalab-to/marker/issues/1035 | [FEAT] Export converter: save extracted tables and structured content to SQLite / CSV

10. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:712111618 | https://github.com/datalab-to/marker | README/documentation is current enough for a first validation pass.

11. 维护坑 · 失败模式：migration: New Layout Model + Misc Updates

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: New Layout Model + Misc Updates
• 对用户的影响：Upgrade or migration may change expected behavior: New Layout Model + Misc Updates
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: New Layout Model + Misc Updates. Context: Observed during version upgrade or migration.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_3cec5d48af0c019538adcffcc51dc987 | https://github.com/datalab-to/marker/releases/tag/v1.10.0 | New Layout Model + Misc Updates

12. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:712111618 | https://github.com/datalab-to/marker | last_activity_observed missing

13. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:712111618 | https://github.com/datalab-to/marker | no_demo; severity=medium

14. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:712111618 | https://github.com/datalab-to/marker | no_demo; severity=medium

15. 安全/权限坑 · 来源证据：[BUG: Breaking]torch.AcceleratorError: index 8192 is out of bounds: 2, range 0 to 4756

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG: Breaking]torch.AcceleratorError: index 8192 is out of bounds: 2, range 0 to 4756
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_eace2619e1024c419e1242df73aaf3f0 | https://github.com/datalab-to/marker/issues/1036 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

16. 安全/权限坑 · 来源证据：[FEAT] Export converter: save extracted tables and structured content to SQLite / CSV

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[FEAT] Export converter: save extracted tables and structured content to SQLite / CSV
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_70e8e2088e4c436a95dd0365706b7b2d | https://github.com/datalab-to/marker/issues/1035 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。

17. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:712111618 | https://github.com/datalab-to/marker | issue_or_pr_quality=unknown

18. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:712111618 | https://github.com/datalab-to/marker | release_recency=unknown

19. 维护坑 · 失败模式：maintenance: Fix Blank Table Cells

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: Fix Blank Table Cells
• 对用户的影响：Upgrade or migration may change expected behavior: Fix Blank Table Cells
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Fix Blank Table Cells. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_8ac77244e8c38bde37f8a27b18d4c27b | https://github.com/datalab-to/marker/releases/tag/v1.9.1 | Fix Blank Table Cells

20. 维护坑 · 失败模式：maintenance: Gemini JSON fix

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: Gemini JSON fix
• 对用户的影响：Upgrade or migration may change expected behavior: Gemini JSON fix
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Gemini JSON fix. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_4e0c87210e57ba3ec44117b72dfa6ac3 | https://github.com/datalab-to/marker/releases/tag/v1.8.5 | Gemini JSON fix

21. 维护坑 · 失败模式：maintenance: Misc fixes

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: Misc fixes
• 对用户的影响：Upgrade or migration may change expected behavior: Misc fixes
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Misc fixes. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_b182e2f94e1cb3edbea1719efb541b42 | https://github.com/datalab-to/marker/releases/tag/v1.8.4 | Misc fixes

22. 维护坑 · 失败模式：maintenance: v1.10.2

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v1.10.2
• 对用户的影响：Upgrade or migration may change expected behavior: v1.10.2
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.10.2. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_0e94de04462b9ca441634cc7890e07f9 | https://github.com/datalab-to/marker/releases/tag/v1.10.2 | v1.10.2

23. 维护坑 · 失败模式：maintenance: v1.9.2

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v1.9.2
• 对用户的影响：Upgrade or migration may change expected behavior: v1.9.2
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.9.2. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_a8c3d6ab87f5c49ef3715080875c2dab | https://github.com/datalab-to/marker/releases/tag/v1.9.2 | v1.9.2