基于 FastAPI 的 PDF 转换服务，支持将 PDF 文件转换为 Markdown 和 TXT 格式。
- PDF 转 Markdown: 使用 MinerU 技术进行高质量转换
- Markdown 转 TXT: 使用 Pandoc 进行格式转换
- 文件去重: 基于 BLAKE3/SHA256 哈希的重复检测，极大的提升了用户侧感知的服务速度
- 碰撞处理: 自动处理哈希碰撞，确保文件安全存储
- 异步处理: 支持大文件的异步转换
- RESTful API: 完整的 REST API 接口
- 静态文件服务: 提供转换后文件的下载服务
- Python 3.8+
- PostgreSQL 数据库
- Pandoc
- MinerU vLLM 后端服务
git clone <repository-url>
cd pdf2othersAPIInstall a software renderer that provides libGL.so.1; on Debian/Ubuntu use sudo apt-get update && sudo apt-get install -y libgl1-mesa-glx libglib2.0-0, on CentOS/RHEL use sudo yum install -y mesa-libGL mesa-libGLU. If you only run OpenCV in scripts (no GUI), switch to the headless wheel: pip install --upgrade opencv-python-headless (and uninstall opencv-python if present) so no GL dependency is required. For containers or CI, bake the same packages into the image or extend your Dockerfile with the install commands above. After changing the environment, reboot the service or reload the virtualenv, then re-run the conversion to confirm cv2 imports cleanly. Once the environment imports cv2 without raising ImportError: libGL.so.1, the MinerU conversion should proceed normally; if it still fails, check the virtualenv path and ensure the service is using the updated interpreter.
conda create -n pdf2othersAPI python=3.12
conda activate pdf2othersAPI
pip install --upgrade pip
pip install uv
uv pip install -U "mineru[core]"
conda install -c conda-forge pandoc
uv pip install -r requirements.txt编辑 .env 文件，设置必要的配置：
# vLLM 后端配置
VLLM_API_KEY=your_vllm_api_key
VLLM_API_URL=http://localhost:8000
# 数据库配置
DB_PASSWORD=your_db_password
SECRET_KEY=your_secret_key
# 其他配置...docker compose up -d依次导入数据库初始化脚本
- scripts/1init_database.sql
- scripts/2steps.sql
python3 main.py启动服务后，访问以下地址查看 API 文档：
- Swagger UI: http://localhost:8008/docs
- ReDoc: http://localhost:8008/redoc
项目初始化后会自动创建默认的API密钥，你可以通过以下方式获取：
数据库初始化后，会显示默认API密钥信息：
- 管理员密钥:
pdf2others-admin-2024-demo - 转换密钥:
pdf2others-convert-2024-demo - 只读密钥:
pdf2others-readonly-2024-demo
# 使用管理工具
python3 tools/api_key_manager.py create
# 或使用API（需要admin权限）
curl -X POST "http://localhost:8008/auth/keys" \
-H "X-API-Key: pdf2others-admin-2024-demo" \
-H "Content-Type: application/json" \
-d '{
"name": "my-converter-key",
"description": "我的转换密钥",
"permissions": ["convert:pdf", "status:view"],
"expires_days": 30,
"rate_limit_per_hour": 100
}'项目提供了批量转换客户端，使用方法请查看pdf2othersApiClient
注意：所有API调用都需要认证。使用以下任一方式提供API密钥：
方式1：使用 X-API-Key 请求头（推荐）
curl -X POST "http://localhost:8008/api/v1/convert" \
-H "X-API-Key: your-api-key-here" \
-F "file=@document.pdf" \
-F "output_format=both"方式2：使用 Authorization Bearer 头
curl -X POST "http://localhost:8008/api/v1/convert" \
-H "Authorization: Bearer your-api-key-here" \
-F "file=@document.pdf" \
-F "output_format=both"方式3：使用查询参数
curl -X POST "http://localhost:8008/api/v1/convert?api_key=your-api-key-here" \
-F "file=@document.pdf" \
-F "output_format=both"# 下载 Markdown
curl "http://localhost:8008/md/{hash}/{collision_id}.md" \
-H "X-API-Key: your-api-key-here"
# 下载 TXT
curl "http://localhost:8008/txt/{hash}/{collision_id}.txt" \
-H "X-API-Key: your-api-key-here"
# 下载图片
curl "http://localhost:8008/images/{hash}/{collision_id}/{filename}" \
-H "X-API-Key: your-api-key-here"curl "http://localhost:8008/health"启动服务后，访问以下地址查看 API 文档：
- Swagger UI: http://localhost:8008/docs
- ReDoc: http://localhost:8008/redoc
本API使用API密钥进行认证，支持三种方式提供密钥：
-
X-API-Key 请求头（推荐）：
-H "X-API-Key: your-api-key-here" -
Authorization Bearer 头：
-H "Authorization: Bearer your-api-key-here" -
查询参数：
"?api_key=your-api-key-here"
API密钥具有不同的权限级别：
convert:pdf- PDF转换权限status:view- 查看任务状态权限files:manage- 文件管理权限admin:keys- 管理API密钥权限admin:*- 完全管理权限
以下端点无需认证：
/- 首页/health- 健康检查/info- 系统信息/version- 版本信息/docs- API文档/redoc- ReDoc文档
使用默认的转换密钥进行快速测试：
# 使用默认转换密钥测试PDF转换
curl -X POST "http://localhost:8008/api/v1/convert" \
-H "X-API-Key: pdf2others-convert-2024-demo" \
-F "file=@your-document.pdf" \
-F "output_format=both"
# 查看当前密钥信息
curl "http://localhost:8008/auth/me" \
-H "X-API-Key: pdf2others-convert-2024-demo"客户端应用
↓
FastAPI 服务层
↓
┌─────────────────┬─────────────────┬─────────────────┐
│ 文件上传处理 │ 哈希管理模块 │ PDF转换模块 │
└─────────────────┴─────────────────┴─────────────────┘
↓ ↓ ↓
文件存储系统 PostgreSQL数据库 MinerU + Pandoc
pdf2othersAPI/
├── app/ # 应用主包
│ ├── api/ # API 路由
│ ├── core/ # 核心功能
│ ├── models/ # 数据模型
│ ├── schemas/ # Pydantic 模式
│ ├── middleware/ # 中间件
│ ├── config.py # 配置管理
│ └── database.py # 数据库连接
├── tests/ # 测试文件
├── tools/ # 工具脚本
├── main.py # 应用入口
├── requirements.txt # Python 依赖
├── setup.py # 安装脚本
└── README.md # 项目文档
# 运行所有测试
pytest
# 运行特定测试
pytest tests/test_hash_utils.py
# 生成覆盖率报告
pytest --cov=app tests/| 变量名 | 描述 | 默认值 |
|---|---|---|
VLLM_API_KEY |
vLLM API 密钥 | 必需 |
VLLM_API_URL |
vLLM 服务地址 | http://localhost:8000 |
DB_PASSWORD |
数据库密码 | 必需 |
SECRET_KEY |
应用密钥 | 必需 |
PDFs_PATH |
文件存储路径 | /var/lib/pdf2others/storage |
TMP_TRS_DIR |
临时目录 | /tmp/pdf2others |
MAX_FILE_SIZE_MB |
最大文件大小 | 100 |
# if vllm>=0.10.1
pip install "mineru-vl-utils[vllm]==0.1.13"
# elif vllm<0.10.1 (例如一些国产GPU适配时)
# 安装vLLM对应的docker镜像
pip install modelscope
modelscope download --model OpenDataLab/MinerU2.5-2509-1.2B --local_dir MinerU2.5-2509-1.2B
# if vllm>=0.10.1
vllm serve MinerU2.5-2509-1.2B \
--host 0.0.0.0 \
--port 8000 \
--tensor-parallel-size 1 \
--gpu-memory-utilization 0.5 \
--logits-processors mineru_vl_utils:MinerULogitsProcessor
# elif vllm<0.10.1 (例如一些国产GPU适配时)
vllm serve MinerU2.5-2509-1.2B --host 0.0.0.0 --port 8000 --trust-remote-code --tensor-parallel-size 1 --gpu-memory-utilization 0.95-
MinerU 转换失败
- 检查 vLLM 服务是否运行
- 验证 API 密钥和地址配置
-
Pandoc 未找到
- 安装 Pandoc:
brew install pandoc(macOS) 或apt-get install pandoc(Linux)
- 安装 Pandoc:
-
数据库连接失败
- 检查 PostgreSQL 服务状态
- 验证数据库配置
-
文件上传失败
- 检查文件大小限制
- 验证文件格式（仅支持 PDF）
# 查看应用日志
tail -f logs/app.log
# 查看错误日志
tail -f logs/error.log- Fork 项目
- 创建功能分支 (
git checkout -b feature/amazing-feature) - 提交更改 (
git commit -m 'Add amazing feature') - 推送到分支 (
git push origin feature/amazing-feature) - 创建 Pull Request
本项目基于 AGPL 许可证开源。详见 LICENSE 文件。
如有问题或建议，请创建 Issue 或联系项目维护者。