marker Python API：程序化调用的完整指南

劳丽娓Fern

761人浏览 · 2025-09-03 04:25:06

劳丽娓Fern · 2025-09-03 04:25:06 发布

marker Python API：程序化调用的完整指南

【免费下载链接】marker 一个高效、准确的工具，能够将 PDF 和图像快速转换为 Markdown、JSON 和 HTML 格式，支持多语言和复杂布局处理，可选集成 LLM 提升精度，适用于学术文档、表格提取等多种场景。源项目地址：https://github.com/VikParuchuri/marker 项目地址: https://gitcode.com/GitHub_Trending/ma/marker

还在为PDF文档转换而烦恼？想要在Python程序中直接调用marker的强大转换能力？本文将为你提供marker Python API的完整使用指南，从基础转换到高级定制，让你彻底掌握程序化调用的精髓。

🎯 读完本文你将获得

marker核心API的全面理解
多种输出格式的转换示例
自定义配置和处理器的高级用法
批量处理和性能优化技巧
实际应用场景的最佳实践

📦 安装与环境准备

首先确保已安装marker：

pip install marker-pdf
# 如需支持更多文档格式
pip install marker-pdf[full]

🔧 基础转换：快速上手

最简单的PDF转Markdown

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(),
)

# 转换PDF文件
rendered = converter("document.pdf")
text, _, images = text_from_rendered(rendered)

print(text)  # 输出Markdown内容

支持多种输入格式

import io

# 支持文件路径
result1 = converter("document.pdf")
result2 = converter("image.png")

# 支持内存中的字节流
with open("document.pdf", "rb") as f:
    pdf_bytes = io.BytesIO(f.read())
result3 = converter(pdf_bytes)

🎨 输出格式全解析

Markdown输出示例

from marker.config.parser import ConfigParser

config = {"output_format": "markdown"}
config_parser = ConfigParser(config)

converter = PdfConverter(
    config=config_parser.generate_config_dict(),
    artifact_dict=create_model_dict(),
    renderer=config_parser.get_renderer(),
)

rendered = converter("document.pdf")
# rendered.markdown 包含完整的Markdown内容

JSON结构化输出

config = {"output_format": "json"}
config_parser = ConfigParser(config)

converter = PdfConverter(
    config=config_parser.generate_config_dict(),
    artifact_dict=create_model_dict(),
    renderer=config_parser.get_renderer(),
)

rendered = converter("document.pdf")
# rendered 包含完整的JSON树结构

JSON输出结构示意：

mermaid

HTML输出配置

config = {"output_format": "html"}
config_parser = ConfigParser(config)

converter = PdfConverter(
    config=config_parser.generate_config_dict(),
    artifact_dict=create_model_dict(),
    renderer=config_parser.get_renderer(),
)

rendered = converter("document.pdf")
# rendered.html 包含完整的HTML内容

⚙️ 高级配置与自定义

自定义处理器链

from marker.config.parser import ConfigParser

config = {
    "output_format": "markdown",
    "processors": "marker.processors.table.TableProcessor,marker.processors.code.CodeProcessor"
}
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增强模式

config = {
    "output_format": "markdown",
    "use_llm": True,
    "gemini_api_key": "your-api-key"
}
config_parser = ConfigParser(config)

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

页面范围控制

config = {
    "output_format": "markdown",
    "page_range": [0, 5, "10-15"]  # 处理第0、5、10-15页
}
config_parser = ConfigParser(config)

converter = PdfConverter(
    config=config_parser.generate_config_dict(),
    artifact_dict=create_model_dict(),
)

🏗️ 专用转换器详解

表格提取专用转换器

from marker.converters.table import TableConverter
from marker.models import create_model_dict

converter = TableConverter(
    artifact_dict=create_model_dict(),
)

# 只提取文档中的表格
rendered = converter("financial_report.pdf")

OCR专用转换器

from marker.converters.ocr import OCRConverter
from marker.models import create_model_dict

converter = OCRConverter(
    artifact_dict=create_model_dict(),
)

# 仅执行OCR处理
rendered = converter("scanned_document.pdf")

📊 批量处理与性能优化

多文件批量处理

import os
from concurrent.futures import ThreadPoolExecutor
from marker.converters.pdf import PdfConverter
from marker.models import create_model_dict

def process_file(file_path):
    converter = PdfConverter(artifact_dict=create_model_dict())
    return converter(file_path)

pdf_files = [f for f in os.listdir("documents") if f.endswith(".pdf")]

with ThreadPoolExecutor(max_workers=4) as executor:
    results = list(executor.map(process_file, pdf_files))

内存优化配置

config = {
    "disable_image_extraction": True,  # 禁用图片提取节省内存
    "disable_multiprocessing": False   # 启用多进程（默认）
}
config_parser = ConfigParser(config)

converter = PdfConverter(
    config=config_parser.generate_config_dict(),
    artifact_dict=create_model_dict(),
)

🔍 高级功能：块级操作

提取特定类型的内容块

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")

# 提取所有表格
tables = document.contained_blocks((BlockTypes.Table,))

# 提取所有代码块
code_blocks = document.contained_blocks((BlockTypes.Code,))

# 提取所有图片
figures = document.contained_blocks((BlockTypes.Figure,))

自定义块处理逻辑

from marker.schema.blocks import Block

def custom_block_processor(block: Block):
    """自定义块处理逻辑"""
    if block.block_type == BlockTypes.Table:
        # 对表格进行特殊处理
        processed_content = process_table(block)
        return processed_content
    return block

# 在转换后处理
document = converter.build_document("document.pdf")
for page in document.pages:
    for block in page.structure:
        custom_block_processor(block)

🚀 性能优化指南

GPU加速配置

import torch
from marker.models import create_model_dict

# 自动检测最佳设备
device = "cuda" if torch.cuda.is_available() else "cpu"

artifact_dict = create_model_dict(device=device)

converter = PdfConverter(artifact_dict=artifact_dict)

批量处理最佳实践

from marker.utils.batch import batch_process

def process_batch(file_paths):
    """批量处理函数"""
    results = []
    for file_path in file_paths:
        converter = PdfConverter(artifact_dict=create_model_dict())
        results.append(converter(file_path))
    return results

# 分批处理大量文件
all_files = [...]  # 大量文件列表
batch_size = 10
batches = [all_files[i:i+batch_size] for i in range(0, len(all_files), batch_size)]

for batch in batches:
    batch_process(batch, process_batch)

📋 配置选项参考表

配置项	类型	默认值	描述
`output_format`	str	`"markdown"`	输出格式：markdown/json/html/chunks
`use_llm`	bool	`False`	是否使用LLM增强处理
`page_range`	list	`None`	处理的页面范围
`debug`	bool	`False`	启用调试模式
`disable_image_extraction`	bool	`False`	禁用图片提取
`force_ocr`	bool	`False`	强制OCR处理
`processors`	str	`None`	自定义处理器列表

🎯 实际应用场景

学术论文处理管道

class AcademicPaperProcessor:
    def __init__(self):
        self.converter = PdfConverter(artifact_dict=create_model_dict())
    
    def process_paper(self, paper_path):
        # 转换论文
        rendered = self.converter(paper_path)
        
        # 提取关键信息
        metadata = self.extract_metadata(rendered)
        references = self.extract_references(rendered)
        figures = self.extract_figures(rendered)
        
        return {
            "content": rendered.markdown,
            "metadata": metadata,
            "references": references,
            "figures": figures
        }

企业文档自动化

def enterprise_document_processing(doc_path, output_dir):
    """企业级文档处理流水线"""
    
    # 1. 文档转换
    converter = PdfConverter(artifact_dict=create_model_dict())
    rendered = converter(doc_path)
    
    # 2. 质量检查
    if self.quality_check(rendered):
        # 3. 后处理
        processed_content = self.post_process(rendered)
        
        # 4. 保存结果
        self.save_results(processed_content, output_dir)
        
        return True
    return False

⚠️ 常见问题与解决方案

内存不足问题

# 减少工作进程数
config = {"pdftext_workers": 1}  # 单进程模式
config_parser = ConfigParser(config)

# 使用轻量模式
config = {
    "disable_image_extraction": True,
    "disable_multiprocessing": True
}

处理失败重试机制

from tenacity import retry, stop_after_attempt, wait_exponential

@retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=4, max=10))
def safe_conversion(file_path):
    converter = PdfConverter(artifact_dict=create_model_dict())
    return converter(file_path)