使用PDF到Markdown API实现高效文档转换

项目地址：https://github.com/xiaozhch5/pdf2md-server

在数字化时代，文档格式的转换是日常工作中常见的需求。尤其是将PDF文件转换为Markdown格式，可以大大提升文档的可编辑性和可维护性。本文将深入介绍一个名为“PDF to Markdown API”的开源项目，该项目利用了marker^[1]工具，将PDF文件高效地转换为高质量的Markdown格式，并将结果存储在腾讯云COS对象存储中。

项目概述

PDF to Markdown API 是一个基于REST的API服务，旨在提供简便的PDF到Markdown转换功能。它支持多种PDF格式，包括科学论文、书籍等，并通过执行marker_single命令行工具实现转换，无需预加载模型。转换后的Markdown文件及其相关资源文件将自动上传到腾讯云COS对象存储，并将Markdown中的本地图片引用替换为COS远程URL，确保在任何环境中都能正确显示图片。

功能特点

• REST API：通过简单的HTTP请求即可实现PDF到Markdown的转换。
• 高质量转换：利用marker工具确保转换后的Markdown保持原始PDF的格式和结构。
• 多格式支持：适用于科学论文、书籍以及其他多种PDF格式。
• 自动化上传：将转换后的Markdown文件及其图片资源自动上传到腾讯云COS。
• 图片URL替换：自动将Markdown中的本地图片路径替换为COS远程URL，确保图片在任何地方都能正确显示。

安装与配置

先决条件

• Python 3.12 或更高版本。
• marker_single 命令可执行（由marker包提供）。
• 腾讯云COS 账号及相关配置。

安装步骤

# 安装项目
python -m pip install uv
uv venv
source .venv/bin/activate  # 在Windows上使用 .venv\Scriptsctivate
uv pip install -e .

以上命令依次完成项目的安装、创建虚拟环境并激活，以及安装项目的依赖包。

配置腾讯云COS

1. 创建一个 .env 文件，参考 .env.example 文件的格式。
2. 填入您的腾讯云COS配置信息：

COS_SECRET_ID=your_secret_id_here
COS_SECRET_KEY=your_secret_key_here
COS_REGION=ap-guangzhou
COS_BUCKET=your-bucket-name-1250000000

确保将上述配置项替换为您在腾讯云COS上的实际信息。

运行服务

安装和配置完成后，通过以下命令启动API服务：

python run.py

服务将在 http://localhost:8000 上运行，并且可以访问 http://localhost:8000/docs 查看详细的API文档。

API使用指南

转换PDF到Markdown

通过发送POST请求到 /api/v1/convert 端点，可以将指定的PDF文件转换为Markdown格式：

curl -X 'POST' \
  'http://localhost:8000/api/v1/convert' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "pdf_url": "https://example.com/sample.pdf"
}'

响应示例

成功转换后，API将返回转换后的Markdown文件在COS上的URL：

{
  "file_url": "https://your-bucket-1250000000.cos.ap-guangzhou.myqcloud.com/tmp/sample_1628123456/sample.md"
}

图片URL替换功能

在转换过程中，API会自动将Markdown文本中的本地图片引用替换为COS远程URL。例如，原始Markdown中的图片引用：

![图片描述](images/example.png)

将被替换为：

![图片描述](https://your-bucket-1250000000.cos.ap-guangzhou.myqcloud.com/pdf-name_timestamp/images/example.png)

这种替换逻辑支持以下几种情况：

1. 完整路径匹配（如images/example.png）
2. 文件名匹配（如example.png）
3. 智能忽略已经是HTTP/HTTPS URL的图片引用

工作原理

1. 接收请求：API服务接收包含PDF URL的请求。
2. 下载PDF：将PDF文件下载到临时位置，保留原始文件名并添加随机字符串。
3. 执行转换：通过marker_single命令行工具处理PDF文件。
4. 读取Markdown：读取生成的Markdown内容。
5. 上传资源：将所有图片等资源文件上传到腾讯云COS。
6. 替换图片路径：将Markdown中的本地图片引用替换为COS远程URL。
7. 上传Markdown：将替换后的Markdown内容上传到COS。
8. 返回结果：返回Markdown文件的COS URL。
9. 清理临时文件：删除所有临时文件，确保系统整洁。

整个过程自动化且高效，用户只需提供PDF文件的URL，即可获得对应的Markdown文件。

实际应用与优势

• 增强可编辑性：Markdown格式易于编辑和版本控制，适合协作写作和文档管理。
• 便捷分享：通过COS存储的Markdown和图片文件，用户可以轻松分享转换后的文档。
• 自动化流程：减少手动转换和路径替换的繁琐步骤，提升工作效率。
• 适应多种需求：无论是科研论文、技术文档还是书籍，均可高质量转换。

许可证

本项目使用GNU通用公共许可证(GPL-3.0)^[2]发布。请注意，marker项目有其自身的许可证要求，商业使用可能需要额外许可。

结论

PDF to Markdown API 提供了一种高效、自动化的方式，将PDF文件转换为可编辑的Markdown格式，并将结果安全存储在云端。通过简化文档转换和管理流程，极大地提升了工作效率和文档的可维护性。无论是个人用户还是企业团队，都能从中受益，轻松应对日常的文档转换需求。

欢迎访问项目的GitHub页面^[3]获取更多信息和最新更新。

引用链接

[1] marker: https://github.com/VikParuchuri/marker
[2] GNU通用公共许可证(GPL-3.0): LICENSE
[3] GitHub页面: https://github.com/xiaozhch5/pdf2md-server