` | ### Chunks 格式 Chunks 格式将文档分割为更小的可管理单元，便于大型文档的流式处理和增量处理。 资料来源：[marker/renderers/chunk.py](https://github.com/datalab-to/marker/blob/main/marker/renderers/chunk.py) ## 配置与使用 ### 命令行配置 通过 `--output_format` 参数指定输出格式： ```bash # 输出为 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 ``` #### 输出目录配置 ```bash marker_single /path/to/file.pdf --output_dir /path/to/output/ ``` 默认输出目录由 `settings.OUTPUT_DIR` 配置项指定。 资料来源：[marker/config/parser.py:28-30]() ### Python API 使用 #### 基础用法 ```python 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) ``` #### 指定渲染器 ```python 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, ) ``` #### 配置分页输出 ```python 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 配置文件： ```bash marker_single /path/to/file.pdf --config_json /path/to/config.json ``` 配置文件示例： ```json { "output_format": "markdown", "output_dir": "./output", "paginate_output": true, "html_tables_in_markdown": true, "debug": false } ``` ## 渲染器与转换器的集成 ### PdfConverter 中的渲染器注入 `PdfConverter` 类接收渲染器作为构造参数： ```python 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` 参数自动选择对应的渲染器： ```python 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` 函数提供统一的输出解析接口： ```python def text_from_rendered(rendered): """ 返回: (text, extension, images) """ ``` 根据输出格式不同，返回值有所差异： | 格式 | text | extension | images | |------|------|-----------|--------| | markdown | Markdown 文本字符串 | ".md" | 图片路径字典 | | json | JSON 字符串 | ".json" | 空字典 | | html | HTML 字符串 | ".html" | 空字典 | | chunks | Chunks 列表 | ".json" | 空字典 | 资料来源：[marker/output.py](https://github.com/datalab-to/marker/blob/main/marker/output.py) ## 常见问题与解决方案 ### 内存相关问题 处理大型 PDF 文件时可能出现内存不足问题。社区反馈显示，750 页的 PDF 可能消耗约 20GB 内存。 **建议方案：** - 使用 `--paginate_output` 启用分页处理 - 限制 `--workers` 数量减少并发内存占用 - 考虑使用批量处理模式 资料来源：[GitHub Issue #583](https://github.com/datalab-to/marker/issues/583) ### 输出格式选择建议 | 使用场景 | 推荐格式 | |----------|----------| | 文档阅读和编辑 | Markdown | | 程序化数据处理 | JSON | | 网页展示 | HTML | | 大型文档分段处理 | Chunks | | 表格式数据提取 | JSON 或带 `--html_tables_in_markdown` 的 Markdown | ### 表格渲染问题 社区在 v1.9.1 版本中修复了空白表格单元的问题。如果遇到表格渲染异常： 1. 确保使用的是最新版本的 Marker 2. 考虑添加 `--use_llm` 参数，启用 LLM 处理器改进表格识别 3. 使用 `--html_tables_in_markdown` 切换表格渲染方式 资料来源：[GitHub Release v1.9.1](https://github.com/datalab-to/marker/releases/tag/v1.9.1) ### 公式渲染问题 对于复杂的数学公式，建议： - 使用 `--force_ocr` 强制 OCR 处理 - 配合 `--use_llm` 启用 LLM 改进公式识别 - 检查行内公式分隔符配置是否与源文档冲突 ## 扩展渲染器 如需自定义输出格式，可以继承 `BaseRenderer` 类： ```python 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 ``` 然后在转换器中指定自定义渲染器： ```python converter = PdfConverter( artifact_dict=model_dict, renderer=CustomRenderer, ) ``` ## 参见 - [安装与快速开始](../Installation/README.md) - [处理器详解](./Processors.md) - [命令行工具](../CLI/README.md) - [Python API 使用](../Python_API/README.md) - [LLM 服务配置](./LLM-Services.md) --- ## LLM 集成与混合模式 ### 相关页面 相关主题：[处理器详解](#processors), [配置与自定义](#configuration) 相关源码文件 以下源码文件用于生成本页说明： - [marker/converters/pdf.py](https://github.com/datalab-to/marker/blob/main/marker/converters/pdf.py) - [marker/services/__init__.py](https://github.com/datalab-to/marker/blob/main/marker/services/__init__.py) - [marker/services/gemini.py](https://github.com/datalab-to/marker/blob/main/marker/services/gemini.py) - [marker/services/ollama.py](https://github.com/datalab-to/marker/blob/main/marker/services/ollama.py) - [marker/services/azure_openai.py](https://github.com/datalab-to/marker/blob/main/marker/services/azure_openai.py) - [marker/processors/llm/llm_table.py](https://github.com/datalab-to/marker/blob/main/marker/processors/llm/llm_table.py) - [marker/processors/llm/llm_complex.py](https://github.com/datalab-to/marker/blob/main/marker/processors/llm/llm_complex.py) - [marker/processors/llm/llm_form.py](https://github.com/datalab-to/marker/blob/main/marker/processors/llm/llm_form.py) - [marker/config/parser.py](https://github.com/datalab-to/marker/blob/main/marker/config/parser.py) - [marker/settings.py](https://github.com/datalab-to/marker/blob/main/marker/settings.py) # LLM 集成与混合模式 ## 概述 Marker 的 LLM 集成功能通过将深度学习模型与大型语言模型相结合，显著提升 PDF 转换的准确性和输出质量。混合模式（Hybrid Mode）允许 Marker 在处理复杂布局、表格格式化、数学公式和表单识别时调用外部 LLM 服务进行后处理，从而解决纯模型方法难以处理的边缘情况。 根据 v1.9.2 版本的更新说明，LLM 处理器支持循环改进表格内容，并能够检测并修复表格单元格切割文本行的问题，有效减少 LLM 幻觉（hallucination）现象。资料来源：[marker/processors/llm/llm_table.py:1-100]() ## 架构设计 ### 整体处理流程 Marker 的混合模式采用流水线架构，LLM 在特定处理阶段介入以增强输出质量： ```mermaid 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]() ```mermaid 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-2.0-flash | 低 | | Ollama (本地) | ❌ | 取决于模型 | llama3 | 中 | | Azure OpenAI | ✅ | ✅ | gpt-4o | 高 | | Anthropic Claude | ✅ | ✅ | claude-3-5-sonnet | 中 | | Vertex AI | ✅ | ✅ | gemini-2.0-flash | 高 | ### Google Gemini 服务 Gemini 是 Marker 的默认 LLM 服务，通过 `GoogleGeminiService` 类实现。服务默认使用 `gemini-2.0-flash` 模型，该模型在速度和准确性之间取得了良好平衡。资料来源：[marker/services/gemini.py:1-100]() **环境变量配置：** ```bash export GEMINI_API_KEY="your-api-key-here" ``` ### Ollama 本地服务 对于需要完全离线或私有化部署的场景，Marker 支持 Ollama 本地 LLM 服务。Ollama 服务允许使用本地运行的模型，如 Llama 3、Code Llama 等。资料来源：[marker/services/ollama.py:1-100]() **环境变量配置：** ```bash export OLLAMA_BASE_URL="http://localhost:11434" # 默认值 ``` **示例配置：** ```python 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]() **环境变量配置：** ```bash 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 | `marker/processors/llm/llm_table.py` | 表格结构修复、跨页表格合并、单元格内容优化 | | LLMTableMergeProcessor | `marker/processors/llm/llm_table_merge.py` | 跨页表格合并处理 | | LLMComplexRegionProcessor | `marker/processors/llm/llm_complex.py` | 复杂布局区域处理、内联数学公式 | | LLMFormProcessor | `marker/processors/llm/llm_form.py` | 表单字段识别与提取 | | LLMImageDescriptionProcessor | `marker/processors/llm/llm_image_description.py` | 图片内容描述生成 | ### 表格处理器详解 `LLMTableProcessor` 是最常用的 LLM 处理器，专门处理 PDF 中复杂表格的识别和格式化。该处理器能够： - 检测并修复被单元格边界切割的文本行 - 识别跨越多行或多列的表头单元格 - 合并因分页而分割的表格 - 优化表格单元格内容的格式 根据 v1.9.2 版本的更新，表格处理器支持循环改进机制，可以多次调用 LLM 直到表格质量达到预期标准。资料来源：[marker/processors/llm/llm_table.py:50-150]() ### 复杂区域处理器 `LLMComplexRegionProcessor` 专门处理文档中结构复杂的区域，包括： - 多栏布局中的嵌套内容块 - 内联数学公式的正确渲染 - 脚注和边注的关联处理 - 代码块与普通文本的边界识别 ## 配置与使用 ### 命令行启用 LLM 模式 通过 `--use_llm` 标志启用 LLM 混合模式： ```bash marker_single document.pdf --output_dir ./output --use_llm ``` ### 指定 LLM 服务 使用 `--llm_service` 参数指定要使用的 LLM 服务： ```bash # 使用 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` 参数添加自定义校正指令： ```bash marker_single document.pdf --use_llm --block_correction_prompt "请保持所有技术术语的英文原文" ``` ### Python API 配置 在 Python 代码中配置 LLM 集成： ```python 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` 配置文件： ```json { "use_llm": true, "llm_service": "marker.services.gemini.GoogleGeminiService", "output_format": "markdown", "debug": false, "block_correction_prompt": "Your custom prompt here" } ``` 使用配置文件： ```bash marker_single document.pdf --config_json ./config.json ``` ## 性能考虑 ### 资源消耗 启用 LLM 模式会显著增加处理时间和 API 调用成本： | 处理模式 | GPU 内存 | 每页处理时间 | API 调用 | |---------|---------|-------------|---------| | 纯模型 | 3-5 GB | 1-3 秒 | 0 | | 混合模式 | 3-5 GB | 5-30 秒 | 每页 3-10 次 | ### 批量处理优化 对于大量文档的批量处理，建议： 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： ```bash pip install marker-pdf==1.8.0 ``` ## 最佳实践 ### 何时使用 LLM 模式 **建议启用 LLM 模式的场景：** - 包含复杂表格的学术论文或报告 - 多栏布局的技术文档 - 含有表单字段的政府或法律文件 - 需要准确提取数学公式的科学文献 - 需要识别内联代码和代码块的开发者文档 **可跳过 LLM 模式的场景：** - 简单布局的单栏文档 - 以纯文本为主的书籍或文章 - 对处理速度有严格要求的实时应用 - 离线或资源受限的部署环境 ### 提示工程建议 使用 `--block_correction_prompt` 时，遵循以下原则： 1. **保持简洁**：提示应简短明确，避免过长指令 2. **指定格式**：明确说明期望的输出格式 3. **语言一致**：对于多语言文档，指定输出语言 4. **术语处理**：对于专业术语，提供翻译或保留原文的指导 **示例提示：** ```bash # 保持英文技术术语 --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 本地部署 ## 参见 - [快速入门指南](./Quick-Start) - Marker 基础使用教程 - [配置选项参考](./Configuration) - 完整的命令行参数说明 - [支持的文档格式](./Supported-Formats) - PDF 及其他格式详解 - [部署指南](./Deployment) - 生产环境部署最佳实践 - [API 参考](./API-Reference) - Python API 详细文档 --- ## 配置与自定义 ### 相关页面 相关主题：[转换器详解](#converters), [LLM 集成与混合模式](#llm-integration), [处理器详解](#processors) 相关源码文件 以下源码文件用于生成本页说明： - [marker/config/parser.py](https://github.com/datalab-to/marker/blob/main/marker/config/parser.py) - [marker/settings.py](https://github.com/datalab-to/marker/blob/main/marker/settings.py) - [marker/models.py](https://github.com/datalab-to/marker/blob/main/marker/models.py) - [marker/converters/pdf.py](https://github.com/datalab-to/marker/blob/main/marker/converters/pdf.py) - [marker/builders/document.py](https://github.com/datalab-to/marker/blob/main/marker/builders/document.py) - [marker/scripts/convert.py](https://github.com/datalab-to/marker/blob/main/marker/scripts/convert.py) # 配置与自定义 Marker 提供了灵活的配置系统，允许用户通过多种方式自定义文档转换行为。本页详细介绍 Marker 的配置机制、环境变量设置、命令行参数、JSON 配置文件以及 Python API 的使用方法。 ## 配置系统概述 Marker 的配置系统采用分层架构，支持以下配置方式（优先级从高到低）： 1. **Python API 直接传入参数** 2. **JSON 配置文件** 3. **命令行参数** 4. **环境变量** 5. **settings.py 默认配置** ```mermaid 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](https://github.com/datalab-to/marker/blob/main/marker/config/parser.py) ## 环境变量配置 Marker 支持通过环境变量进行全局配置。以下是主要支持的环境变量： | 环境变量 | 说明 | 默认值 | |---------|------|--------| | `TORCH_DEVICE` | 指定 PyTorch 运行设备 | 自动检测 (`cuda`/`mps`/`cpu`) | | `PYTORCH_ENABLE_MPS_FALLBACK` | 启用 MPS 后备到 CPU | `1` | | `TOKENIZERS_PARALLELISM` | tokenizers 并行处理 | `false` | | `IN_STREAMLIT` | Streamlit 环境标识 | - | | `NUM_DEVICES` | 多 GPU 并行转换时的 GPU 数量 | `1` | | `NUM_WORKERS` | 每个 GPU 的并行进程数 | `15` | | `MARKERNCORES` | 覆盖 CPU 核心数检测 | 自动检测 | 资料来源：[marker/settings.py](https://github.com/datalab-to/marker/blob/main/marker/settings.py) ### 设备配置示例 ```bash # 使用 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](https://github.com/datalab-to/marker/issues/960) ## 命令行参数详解 Marker 提供了丰富的命令行参数用于控制转换行为。 ### marker_single 单文件转换 ```bash marker_single /path/to/file.pdf [选项] ``` | 参数 | 说明 | 类型 | |------|------|------| | `--page_range TEXT` | 指定处理的页面范围，如 `"0,5-10,20"` | 字符串 | | `--output_format` | 输出格式：`markdown`/`json`/`html`/`chunks` | 枚举 | | `--output_dir PATH` | 输出目录路径 | 路径 | | `--paginate_output` | 在页面间添加分页标记 | 布尔 | | `--use_llm` | 启用 LLM 提升准确性 | 布尔 | | `--force_ocr` | 强制对所有页面执行 OCR | 布尔 | | `--strip_existing_ocr` | 移除现有 OCR 文本后重新识别 | 布尔 | | `--redo_inline_math` | 重新处理行内数学公式（需配合 `--use_llm`） | 布尔 | | `--disable_image_extraction` | 禁用图片提取 | 布尔 | | `--debug` | 启用调试模式 | 布尔 | | `--disable_ocr_math` | 禁用 OCR 数学公式识别 | 布尔 | | `--html_tables_in_markdown` | Markdown 输出中使用 HTML 表格格式 | 布尔 | | `--config_json PATH` | JSON 配置文件路径 | 路径 | | `--converter_cls` | 转换器类：`PdfConverter`/`TableConverter` | 字符串 | | `--llm_service` | LLM 服务类 | 字符串 | | `--block_correction_prompt` | LLM 修正提示词 | 字符串 | 资料来源：[marker/scripts/convert.py](https://github.com/datalab-to/marker/blob/main/marker/scripts/convert.py) ### marker 批量转换 ```bash marker /path/to/input/folder [选项] ``` | 参数 | 说明 | 默认值 | |------|------|--------| | `--workers` | 并行转换的工作进程数 | 自动设置 | | `--recursive` | 递归处理子目录 | - | 每个 worker 峰值使用约 5GB VRAM，平均 3.5GB。资料来源：[README.md](https://github.com/datalab-to/marker/blob/main/README.md) ### 多 GPU 并行转换 ```bash NUM_DEVICES=4 NUM_WORKERS=15 marker_chunk_convert ../pdf_in ../md_out ``` - `NUM_DEVICES`：使用的 GPU 数量（至少 2 个） - `NUM_WORKERS`：每个 GPU 的并行进程数 ## JSON 配置文件 通过 `--config_json` 参数可以指定 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` 类负责加载和合并配置： ```python 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](https://github.com/datalab-to/marker/blob/main/marker/config/parser.py) ## Python API 配置 在 Python 代码中直接使用 Marker 提供了最大的灵活性。 ### 基础用法 ```python 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) ``` ### 完整配置示例 ```python 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](https://github.com/datalab-to/marker/blob/main/marker/converters/pdf.py) ### 增量转换（跳过已处理内容） ```python # 首次转换 rendered = converter("FILEPATH") # 后续转换，传入已转换的 markdown converter_with_existing = PdfConverter( config={"existing_markdown": rendered.original_markdown}, ... ) ``` 当传入 `existing_markdown` 时，转换器会跳过已解析的文档部分。 ## LLM 服务配置 Marker 支持通过 LLM 提升转换质量。 ### 可用的 LLM 服务 | 服务 | 类路径 | 说明 | |------|--------|------| | Google Gemini | `marker.services.gemini.GoogleGeminiService` | 默认服务 | | Ollama | `marker.services.ollama.OllamaService` | 本地模型支持 | ### Gemini 配置 ```python # 通过环境变量 export GOOGLE_API_KEY="your-api-key" # 或在代码中设置 import os os.environ["GOOGLE_API_KEY"] = "your-api-key" ``` 默认使用 `gemini-2.0-flash` 模型。如需使用其他模型： ```python from marker.services.gemini import GoogleGeminiService service = GoogleGeminiService( model_name="gemini-1.5-pro" ) ``` ### 自定义 LLM 提示词 ```bash marker_single file.pdf --use_llm --block_correction_prompt "请确保输出格式规范，中文翻译准确" ``` 资料来源：[marker/scripts/convert.py:100-150](https://github.com/datalab-to/marker/blob/main/marker/scripts/convert.py) **注意**：Gemini API 有速率限制（约 15 请求/分钟），大量转换时需注意控制请求频率。资料来源：[Issue #490](https://github.com/datalab-to/marker/issues/490) ## 模型配置 ### 模型字典 `create_model_dict()` 函数创建并返回所有必需的模型： ```python 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 配置 ```python from marker.builders.document import DocumentBuilder builder = DocumentBuilder(config={ "lowres_image_dpi": 96, # 布局检测 DPI "highres_image_dpi": 192, # OCR 高分辨率 DPI "disable_ocr": False, # 禁用 OCR }) ``` | 参数 | 说明 | 默认值 | |------|------|--------| | `lowres_image_dpi` | 布局和行检测的低分辨率图像 DPI | 96 | | `highres_image_dpi` | OCR 使用的高分辨率图像 DPI | 192 | | `disable_ocr` | 完全禁用 OCR 处理 | False | 资料来源：[marker/builders/document.py:15-40](https://github.com/datalab-to/marker/blob/main/marker/builders/document.py) ## 处理器列表 Marker 使用处理器链对文档进行后处理： | 处理器 | 说明 | LLM 增强版 | |-------|------|-----------| | `BlockquoteProcessor` | 块引用处理 | - | | `CodeProcessor` | 代码块识别 | - | | `DebugProcessor` | 调试信息注入 | - | | `DocumentTOCProcessor` | 目录生成 | - | | `EquationProcessor` | 数学公式处理 | `LLMComplexRegionProcessor` | | `FootnoteProcessor` | 脚注处理 | - | | `IgnoreTextProcessor` | 忽略文本过滤 | - | | `LineNumbersProcessor` | 行号移除 | - | | `ListProcessor` | 列表识别 | - | | `LLMFormProcessor` | 表单提取 | ✓ | | `LLMTableMergeProcessor` | 表格合并 | ✓ | | `LLMTableProcessor` | 表格优化 | ✓ | | `LLMImageDescriptionProcessor` | 图片描述 | ✓ | | `PageHeaderProcessor` | 页眉页脚移除 | - | | `ReferenceProcessor` | 引用处理 | - | | `SectionHeaderProcessor` | 章节标题识别 | - | 资料来源：[marker/converters/pdf.py:30-55](https://github.com/datalab-to/marker/blob/main/marker/converters/pdf.py) ## 输出格式配置 ### Markdown 输出 ```python config = { "output_format": "markdown", "html_tables_in_markdown": False, # True 则使用 HTML 表格 } ``` ### JSON 输出 ```python config = { "output_format": "json", } ``` JSON 输出结构： ```json { "pages": [ { "page_id": 0, "blocks": [ { "id": "block_0", "block_type": "Text", "content": "..." } ] } ] } ``` ### HTML 输出 ```python config = { "output_format": "html", } ``` ### Chunks 输出 ```python config = { "output_format": "chunks", } ``` ## 常见问题与故障排除 ### 内存问题 处理大型 PDF 时可能遇到内存问题： | 问题 | 解决方案 | |------|---------| | 内存不足 | 减少 `--workers` 数量 | | 内存泄漏 | 升级到最新版本 (v1.10.2+) | | VRAM 占用低 | 确保 `TORCH_DEVICE=cuda` 已设置 | 资料来源：[Issue #583](https://github.com/datalab-to/marker/issues/583)、[Issue #919](https://github.com/datalab-to/marker/issues/919) ### 依赖缺失 Docker 环境中可能缺少 `psutil`： ```bash pip install psutil ``` 资料来源：[Issue #818](https://github.com/datalab-to/marker/issues/818) ### Mac 性能问题 在 macOS M1+ 芯片上 v1.9.0+ 版本性能下降： ```bash pip install marker-pdf==1.8.0 ``` 资料来源：[Issue #960](https://github.com/datalab-to/marker/issues/960) ### 模块导入错误 确保安装完整依赖： ```bash pip install marker-pdf[full] ``` 资料来源：[Issue #575](https://github.com/datalab-to/marker/issues/575) ## 配置最佳实践 1. **开发调试**：启用 `--debug` 参数，输出详细日志 2. **生产环境**：使用 JSON 配置文件便于管理和版本控制 3. **大规模处理**：使用多 GPU 配置 + 批量处理 4. **高质量需求**：启用 `--use_llm` 并配置 API Key 5. **资源受限**：使用 `--disable_image_extraction` 减少内存占用 ## 相关页面 - [安装指南](./Installation) - [CLI 使用教程](./CLI-Usage) - [Python API 参考](./Python-API) - [LLM 集成](./LLM-Integration) - [部署示例](./Deployment) --- *最后更新：v1.10.2* --- ## API 服务器部署 ### 相关页面 相关主题：[配置与自定义](#configuration) 相关源码文件 以下源码文件用于生成本页说明： - [marker_server.py](https://github.com/datalab-to/marker/blob/main/marker_server.py) - [marker/scripts/server.py](https://github.com/datalab-to/marker/blob/main/marker/scripts/server.py) - [marker/scripts/streamlit_app.py](https://github.com/datalab-to/marker/blob/main/marker/scripts/streamlit_app.py) - [marker/scripts/extraction_app.py](https://github.com/datalab-to/marker/blob/main/marker/scripts/extraction_app.py) - [examples/marker_modal_deployment.py](https://github.com/datalab-to/marker/blob/main/examples/marker_modal_deployment.py) # API 服务器部署 本文档详细介绍 Marker 项目提供的 API 服务器部署方案，包括基于 FastAPI 的 REST API 服务、Streamlit Web 应用以及 Modal 云端部署示例。 ## 概述 Marker 提供了多种部署方式以满足不同的使用场景： | 部署方式 | 适用场景 | 特点 | |---------|---------|------| | FastAPI REST API | 生产环境、集成到现有系统 | 高性能、异步处理、支持批量转换 | | Streamlit Web 应用 | 交互式测试、原型开发 | 界面友好、易于调试 | | Modal 云端部署 | 云原生环境、自动扩展 | 无需管理基础设施、按需扩展 | | Datalab 托管平台 | 企业级应用 | 完全托管、SOC 2 合规 | 资料来源：[marker_server.py:1-20](https://github.com/datalab-to/marker/blob/main/marker_server.py) ## FastAPI REST API 服务 ### 服务架构 Marker 提供基于 FastAPI 的 REST API 服务，支持文件上传、批量处理和异步转换。 ```mermaid 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 服务可选] ``` ### 核心组件 | 组件 | 文件位置 | 职责 | |-----|---------|------| | `convert_pdf` 函数 | [marker/scripts/server.py](https://github.com/datalab-to/marker/blob/main/marker/scripts/server.py) | PDF 转换核心逻辑 | | `ConfigParser` | marker/config/parser.py | 配置解析和服务初始化 | | `PdfConverter` | [marker/converters/pdf.py](https://github.com/datalab-to/marker/blob/main/marker/converters/pdf.py) | 转换器实现 | | 模型字典 | marker/models.py | 模型加载和管理 | ### 服务启动 FastAPI 服务可以通过以下方式启动： ```python # 方式一：直接运行 python -m uvicorn marker.scripts.server:app --host 0.0.0.0 --port 8000 # 方式二：使用 marker_server.py python marker_server.py ``` ### API 端点 服务提供以下核心端点： | 端点 | 方法 | 描述 | |-----|------|------| | `/convert` | POST | 单个文件转换 | | `/convert/batch` | POST | 批量文件转换 | | `/health` | GET | 健康检查 | ### 转换函数实现 核心转换逻辑封装在 `convert_pdf` 函数中： ```python 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](https://github.com/datalab-to/marker/blob/main/marker/scripts/streamlit_app.py) ### 配置参数 | 参数 | 类型 | 默认值 | 说明 | |-----|------|--------|------| | `output_format` | str | "markdown" | 输出格式：markdown/json/html/chunks | | `page_range` | str | None | 页面范围，如 "0,5-10,20" | | `force_ocr` | bool | False | 强制 OCR 处理 | | `use_llm` | bool | False | 使用 LLM 提升准确性 | | `debug` | bool | False | 启用调试模式 | | `output_dir` | str | None | 输出目录 | ## Streamlit Web 应用 ### 应用类型 Marker 提供两种 Streamlit Web 应用： | 应用 | 文件 | 用途 | |-----|------|-----| | 主转换应用 | [marker/scripts/streamlit_app.py](https://github.com/datalab-to/marker/blob/main/marker/scripts/streamlit_app.py) | PDF 转 Markdown/JSON/HTML | | 数据提取应用 | [marker/scripts/extraction_app.py](https://github.com/datalab-to/marker/blob/main/marker/scripts/extraction_app.py) | 基于 Schema 的结构化数据提取 | ### 主转换应用架构 ```mermaid graph LR A[文件上传] --> B[参数配置] B --> C[Marker 转换] C --> D[输出渲染] D --> E1[Markdown 预览] D --> E2[JSON 查看] D --> E3[HTML 渲染] D --> E4[分块查看] ``` ### 数据提取应用 数据提取应用支持基于 JSON Schema 或 Pydantic Schema 的结构化数据提取： ```python # 提取应用核心流程 rendered = extract_data( temp_pdf, # PDF 文件路径 cli_options, # 命令行选项 schema, # 数据 Schema markdown # 可选的已有 Markdown ) ``` 资料来源：[marker/scripts/extraction_app.py:80-90](https://github.com/datalab-to/marker/blob/main/marker/scripts/extraction_app.py) ### 启动命令 ```bash # 主转换应用 streamlit run marker/scripts/streamlit_app.py # 数据提取应用 streamlit run marker/scripts/extraction_app.py ``` ### 环境变量配置 ```python # 必须设置的环境变量 os.environ["PYTORCH_ENABLE_MPS_FALLBACK"] = "1" # 启用 MPS 后备 os.environ["IN_STREAMLIT"] = "true" # 标识在 Streamlit 环境中运行 ``` ## Modal 云端部署 ### 部署概述 Modal 是一个无服务器 GPU 平台，适合部署需要 GPU 加速的 Marker 服务。 ```mermaid 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[返回结果] ``` ### 部署配置 | 配置项 | 值 | 说明 | |-------|-----|------| | GPU 类型 | L40S | 推荐的 GPU 类型 | | Python 版本 | 3.10 | 容器 Python 版本 | | 模型缓存路径 | /root/.cache/datalab/models | 模型存储位置 | | 依赖包 | marker-pdf[full], fastapi, uvicorn | 核心依赖 | 资料来源：[examples/marker_modal_deployment.py:15-35](https://github.com/datalab-to/marker/blob/main/examples/marker_modal_deployment.py) ### 容器镜像定义 ```python 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 部署支持模型缓存以加快冷启动速度： ```python 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 资源配置 | 场景 | 推荐 GPU | VRAM 需求 | 并行 worker 数 | |-----|---------|----------|---------------| | 开发/测试 | RTX 3090+ | 24GB | 1 | | 生产环境 | A100/H100 | 40-80GB | 5+ | | 多卡部署 | 多卡 L40S | 48GB+ | 每卡 3-5 个 worker | 资料来源：[README.md - 多 GPU 部署说明](https://github.com/datalab-to/marker/blob/main/README.md) ### 内存配置 ```python # 环境变量配置 os.environ["PYTORCH_ENABLE_MPS_FALLBACK"] = "1" # Mac MPS 后备 # 每个 worker 的内存需求 # 峰值: 5GB VRAM # 平均: 3.5GB VRAM # 系统内存: 建议预留 4GB+ per worker ``` ### 多进程配置 ```bash # 单 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+ 芯片上性能严重下降。 **解决方案**： ```bash # 降级到 v1.8.0 pip install marker==1.8.0 ``` 相关 issue：[Issue #960](https://github.com/datalab-to/marker/issues/960) ### 问题 2：内存溢出 (OOM) **问题描述**：处理大型 PDF 时内存耗尽。 **解决方案**： 1. 减少并发 worker 数量 2. 分批处理页面 3. 使用 `--page_range` 限制处理范围 相关 issue：[Issue #1032](https://github.com/datalab-to/marker/issues/1032) ### 问题 3：依赖缺失 **问题描述**：缺少 psutil 等依赖。 **解决方案**： ```bash # 安装完整依赖 pip install marker-pdf[full] # 或单独安装 pip install psutil ``` 相关 issue：[Issue #818](https://github.com/datalab-to/marker/issues/818) ### 问题 4：Gemini API 限流 **问题描述**：Gemini API 请求超过速率限制。 **解决方案**： 1. 实现请求间隔控制 2. 使用本地 LLM (Ollama) 3. 减少 `--use_llm` 的使用场景 相关 issue：[Issue #490](https://github.com/datalab-to/marker/issues/490) ## 配置示例 ### 基础配置 (JSON) ```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 配置 ```python # 使用 Gemini 服务 from marker.services.gemini import GoogleGeminiService llm_service = GoogleGeminiService() # 或使用 Ollama (本地) # 配置 ollama 服务的 URL 和模型名称 ``` ### 使用已有 Markdown 跳过解析 ```python # 如果已有转换后的 Markdown，可以复用以跳过解析步骤 config["existing_markdown"] = previous_markdown converter = PdfConverter(config=config, ...) ``` 资料来源：[marker/converters/extraction.py:15-20](https://github.com/datalab-to/marker/blob/main/marker/converters/extraction.py) ## 生产环境部署建议 ### 容器化部署 ```dockerfile 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"] ``` ### 监控指标 建议监控以下指标： | 指标 | 说明 | 告警阈值 | |-----|------|---------| | 请求延迟 | P50/P95/P99 | P99 > 30s | | 错误率 | 5xx 响应比例 | > 5% | | GPU 利用率 | VRAM 使用率 | < 30% 持续 > 5min | | 队列长度 | 等待处理的任务数 | > 100 | ### 高可用配置 ```yaml # 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: ``` ## 相关文档 - [安装指南](../Installation) - 环境配置和依赖安装 - [命令行工具](../CLI-Usage) - marker 和 marker_single 使用方法 - [Python API](../Python-API) - PdfConverter 和相关类 - [输出格式](../Output-Formats) - Markdown/JSON/HTML 格式详解 - [LLM 集成](../LLM-Integration) - LLM 服务配置 - [性能优化](../Performance) - 性能调优指南 --- --- ## Doramagic 踩坑日志 项目：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