桌面应用

想要图形界面吗？ 试试我们的桌面应用程序，体验更友好的用户界面！

npx -y markpdfdown

查看桌面应用仓库

概述

MarkPDFDown旨在简化将PDF文档转换为整洁、可编辑的Markdown文本的过程。通过LiteLLM调用先进的多模态AI模型，它可以准确提取文本、保留格式，并处理包含表格、公式和图表等复杂结构的文档。

特性

• PDF转Markdown：将任何PDF文档转换为格式良好的Markdown
• 图片转Markdown：将图片转换为格式良好的Markdown
• 多提供商支持：通过LiteLLM支持OpenAI和OpenRouter
• 灵活的CLI：支持基于文件和管道的使用方式
• 格式保留：保持标题、列表、表格等格式元素
• 页码范围选择：从PDF文档中转换特定页码范围
• 模块化架构：代码结构清晰、易于维护，关注点分离

演示

安装

使用uv（推荐）

# 如果尚未安装uv，请先安装
curl -LsSf https://astral.sh/uv/install.sh | sh

# 克隆仓库
git clone https://github.com/MarkPDFdown/markpdfdown.git
cd markpdfdown

# 安装依赖并创建虚拟环境
uv sync

# 以开发模式安装包
uv pip install -e .

使用conda

conda create -n markpdfdown python=3.9
conda activate markpdfdown

# 克隆仓库
git clone https://github.com/MarkPDFdown/markpdfdown.git
cd markpdfdown

# 安装依赖
pip install -e .

配置

MarkPDFDown使用环境变量进行配置。在项目目录下创建一个.env文件：

# 复制示例配置
cp .env.sample .env

编辑.env文件以设置您的参数：

# 模型配置
MODEL_NAME=gpt-4o

# API密钥（LiteLLM会自动检测）
OPENAI_API_KEY=your-openai-api-key
# 或者对于OpenRouter
OPENROUTER_API_KEY=your-openrouter-api-key

# 可选参数
TEMPERATURE=0.3
MAX_TOKENS=8192
RETRY_TIMES=3

支持的模型

OpenAI模型

MODEL_NAME=gpt-4o
MODEL_NAME=gpt-4o-mini
MODEL_NAME=gpt-4-vision-preview

OpenRouter模型

MODEL_NAME=openrouter/anthropic/claude-3.5-sonnet
MODEL_NAME=openrouter/google/gemini-pro-vision
MODEL_NAME=openrouter/meta-llama/llama-3.2-90b-vision

使用方法

文件模式（推荐）

# 基本转换
markpdfdown --input document.pdf --output output.md

# 转换特定页码范围
markpdfdown --input document.pdf --output output.md --start 1 --end 10

# 将图片转换为Markdown
markpdfdown --input image.png --output output.md

# 使用Python模块
python -m markpdfdown --input document.pdf --output output.md

管道模式（适合Docker）

# 通过管道将PDF转换为Markdown
markpdfdown < document.pdf > output.md

# 使用Python模块
python -m markpdfdown < document.pdf > output.md

进阶用法

# 转换PDF中的第5至15页
markpdfdown --input large_document.pdf --output chapter.md --start 5 --end 15

# 处理多个文件
for file in *.pdf; do
    markpdfdown --input "$file" --output "${file%.pdf}.md"
done

Docker使用

# 构建镜像（如果需要）
docker build -t markpdfdown .

# 使用环境变量运行
docker run -i \
  -e MODEL_NAME=gpt-4o \
  -e OPENAI_API_KEY=your-api-key \
  markpdfdown < input.pdf > output.md

# 使用OpenRouter
docker run -i \
  -e MODEL_NAME=openrouter/anthropic/claude-3.5-sonnet \
  -e OPENROUTER_API_KEY=your-openrouter-key \
  markpdfdown < input.pdf > output.md

开发环境搭建

代码质量工具

该项目使用ruff进行代码检查和格式化，以及pre-commit进行自动化代码质量检查。

安装开发依赖

# 如果使用uv
uv sync --group dev

# 如果使用pip
pip install -e ".[dev]"

设置pre-commit钩子

# 安装pre-commit钩子
pre-commit install

# 对所有文件运行pre-commit（可选）
pre-commit run --all-files

代码格式化和检查

# 使用ruff格式化代码
ruff format

# 运行代码检查
ruff check

# 自动修复可修复的问题
ruff check --fix

系统要求

• Python 3.9及以上
• uv（推荐用于包管理）或conda/pip
• pyproject.toml中指定的依赖
• 访问支持的LLM提供商（OpenAI或OpenRouter）

架构

项目采用模块化架构：

src/markpdfdown/
├── __init__.py          # 包初始化
├── __main__.py          # python -m 的入口点
├── cli.py               # 命令行接口
├── main.py              # 核心转换逻辑
├── config.py            # 配置管理
└── core/                # 核心模块
    ├── llm_client.py    # LiteLLM集成
    ├── file_worker.py   # 文件处理
    └── utils.py         # 工具函数

贡献

欢迎贡献！请随时提交拉取请求。

1. 分支仓库
2. 创建功能分支（ git checkout -b feature/amazing-feature ）
3. 搭建开发环境：

   uv sync --group dev
   pre-commit install
   

4. 进行更改并确保代码质量：

   ruff format
   ruff check --fix
   pre-commit run --all-files
   

5. 提交更改（ git commit -m 'feat: Add some amazing feature' ）
6. 推送到分支（ git push origin feature/amazing-feature ）
7. 打开拉取请求

请确保您的代码遵循项目的编码标准，在提交前运行代码检查和格式化工具。

许可证

本项目采用Apache License 2.0许可。详情请参阅LICENSE文件。

致谢

• 感谢 LiteLLM 的开发者提供了统一的 LLM 访问接口
• 感谢为本工具提供支持的多模态 AI 模型的开发者
• 受到对更高效 PDF 转 Markdown 工具需求的启发

MarkPDFDown 快速上手指南

MarkPDFDown 是一款利用多模态大语言模型（LLM）将 PDF 文件或图片高精度转换为 Markdown 格式的强大工具。它支持表格、公式和复杂排版的保留，并通过 LiteLLM 兼容 OpenAI 及 OpenRouter 等多种模型提供商。

环境准备

在开始之前，请确保满足以下系统要求：

• 操作系统：Linux, macOS, 或 Windows
• Python 版本：Python 3.9 或更高版本
• 包管理工具（推荐）：uv (极速 Python 包管理器) 或 Conda/pip
• API 密钥：需拥有 OpenAI API Key 或 OpenRouter API Key

国内开发者提示：如果无法直接访问 astral.sh 安装 uv，可尝试使用国内镜像源安装 pip 依赖，或通过 Conda 进行环境管理。

安装步骤

方式一：使用 uv（推荐，速度最快）

# 1. 安装 uv (如已安装可跳过)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. 克隆项目仓库
git clone https://github.com/MarkPDFdown/markpdfdown.git
cd markpdfdown

# 3. 同步依赖并创建虚拟环境
uv sync

# 4. 以开发模式安装包
uv pip install -e .

方式二：使用 Conda

# 1. 创建并激活虚拟环境
conda create -n markpdfdown python=3.9
conda activate markpdfdown

# 2. 克隆项目仓库
git clone https://github.com/MarkPDFdown/markpdfdown.git
cd markpdfdown

# 3. 安装依赖
pip install -e .

方式三：桌面版（无需配置环境）

如果你更喜欢图形界面（GUI），可以直接运行桌面应用：

npx -y markpdfdown

配置模型

工具通过环境变量读取配置。在项目根目录下创建 .env 文件：

cp .env.sample .env

编辑 .env 文件，填入你的 API 密钥和模型名称：

# 模型配置 (支持 gpt-4o, claude-3.5-sonnet 等)
MODEL_NAME=gpt-4o

# API 密钥 (根据使用的服务商填写其一)
OPENAI_API_KEY=your-openai-api-key
# 或者使用 OpenRouter
# OPENROUTER_API_KEY=your-openrouter-api-key

# 可选参数
TEMPERATURE=0.3
MAX_TOKENS=8192
RETRY_TIMES=3

基本使用

安装并配置完成后，即可开始转换。

1. 基础转换（PDF 转 Markdown）

将 document.pdf 转换为 output.md：

markpdfdown --input document.pdf --output output.md

2. 指定页码范围

仅转换第 1 到第 10 页：

markpdfdown --input document.pdf --output output.md --start 1 --end 10

3. 图片转 Markdown

直接识别图片内容并转为 Markdown：

markpdfdown --input image.png --output output.md

4. 管道模式（适合 Docker 或脚本流）

markpdfdown < document.pdf > output.md

5. 批量处理示例

遍历当前目录下所有 PDF 文件进行转换：

for file in *.pdf; do
    markpdfdown --input "$file" --output "${file%.pdf}.md"
done

注意：首次运行时会根据配置的模型拉取相应的 AI 能力，请确保网络连接正常且 API 密钥有效。