【知识库文档】数据预处理PDF文档转成MD格式（gptpdf ）
gptpdf 简介及详细使用步骤
一、gptpdf 简介
gptpdf 是一款基于大语言模型（如GPT、通义千问等）的开源PDF解析工具，核心功能是将本地PDF文件精准转换为Markdown格式。它通过调用多模态大模型（支持文本、表格、图片等复杂内容识别），保留PDF中的排版结构（如段落、表格、公式、图表引用），适用于学术论文、技术报告、文档资料等场景的格式转换。
核心特点：
- 支持复杂内容解析：文本、多层嵌套表格、LaTeX公式、图片提取及引用；
- 适配主流大模型：可对接OpenAI的GPT系列、通义千问的qwen-vl-max等多模态模型；
- 轻量易用：通过简单API调用即可实现转换，无需复杂配置。
二、gptpdf 详细使用步骤
Step 1：环境准备
需在本地或服务器（如Ubuntu）配置基础运行环境：
- 安装Python及pip
gptpdf依赖Python 3.8及以上版本，需先确认环境：# 检查Python版本（需≥3.8） python3 --version # 检查pip版本（Python包管理器） pip3 --version # 若未安装pip，执行以下命令（Ubuntu示例） sudo apt update && sudo apt install python3-pip -y # 升级pip到最新版本（避免依赖安装失败） pip3 install --upgrade pip
Step 2：安装gptpdf
通过pip安装gptpdf核心库，推荐使用国内源加速下载：
# 国内源安装（阿里云，速度更快）
pip3 install gptpdf -i https://mirrors.aliyun.com/pypi/simple/ # 升级到最新版本（解决参数兼容问题）
pip3 install --upgrade gptpdf -i https://mirrors.aliyun.com/pypi/simple/
验证安装：
# 查看gptpdf版本（显示版本号即成功）
pip3 show gptpdf
Step 3：获取大模型API密钥
gptpdf需调用外部大模型（如通义千问qwen-vl-max），需提前获取API密钥：
- 选择模型：推荐使用通义千问qwen-vl-max（多模态能力强，支持PDF复杂内容解析）；
- 获取密钥：
- 登录阿里云DashScope平台（需注册账号）；
- 进入“API密钥”页面，创建并复制密钥（格式如
sk-xxxxxxxxxxxxxxxx）； - 开通qwen-vl-max模型权限（进入“模型列表”，找到qwen-vl-max并开通，确保有调用额度）。
Step 4：准备PDF文件
- 确保PDF文件路径正确（绝对路径如
/gptpdf/test.pdf，相对路径如./test.pdf）； - 优先测试简单PDF（1-2页纯文本），再尝试复杂文件（含表格、公式、图片）。
Step 5：编写转换代码
gptpdf的核心函数是parse_pdf()，需按其参数要求编写代码（关键参数需严格匹配，避免类型/名称错误）。
示例代码框架：
from gptpdf import parse_pdf
import os# 配置参数（替换为你的信息）
API_KEY = "sk-xxxxxxxxxxxxxxxx" # 通义千问API密钥
PDF_PATH = "/gptpdf/test.pdf" # PDF文件路径
OUTPUT_DIR = "/gptpdf/output" # Markdown及图片输出目录
MODEL = "qwen-vl-max" # 模型名称# 确保输出目录存在
os.makedirs(OUTPUT_DIR, exist_ok=True)# 调用parse_pdf转换PDF（仅传支持的参数）
md_content, image_paths = parse_pdf(pdf_path=PDF_PATH,output_dir=OUTPUT_DIR,api_key=API_KEY,base_url="https://dashscope.aliyuncs.com/compatible-mode/v1", # 通义千问API地址model=MODEL,gpt_worker=2, # 解析线程数（1-4，根据CPU调整）prompt="精准解析PDF内容，表格用|分隔，公式用$包裹，保留原始格式。" # 字符串类型提示词
)# 保存Markdown文件
md_filename = os.path.splitext(os.path.basename(PDF_PATH))[0] + ".md"
with open(os.path.join(OUTPUT_DIR, md_filename), "w", encoding="utf-8") as f:f.write(md_content)print(f"转换完成！Markdown文件：{os.path.join(OUTPUT_DIR, md_filename)}")
Step 6：运行代码并查看结果
-
运行脚本：
# 在代码所在目录执行 python3 your_script.py -
查看输出：
- Markdown文件：保存于
OUTPUT_DIR，与原PDF同名（如test.pdf→test.md）； - 图片文件：提取的图片自动保存于输出目录，Markdown中会通过路径引用图片。
- Markdown文件：保存于
三、关键参数说明（避免常见错误）
parse_pdf() 仅支持以下核心参数，多余参数会导致报错：
| 参数名 |
|---|