Skip to content

li-xiu-qi/remote_pdf_parse_serve

BranchesTags

Repository files navigation

Remote PDF Parse Service

🚀 一个基于 FastAPI 的智能 PDF 解析和图片处理服务，能够将 PDF 文件转换为 Markdown 格式，并使用多种 AI 视觉模型对图片进行智能分析和描述。

✨ 功能特性

📄 PDF 智能处理

  • PDF转Markdown: 使用 MinerU 技术将 PDF 精确转换为 Markdown 格式
  • 图片自动提取: 自动提取 PDF 中的图片并保存到指定目录
  • AI图片分析: 可选使用 AI 视觉模型生成图片的智能描述和标题
  • 路径自动替换: 将本地图片路径替换为远程访问 URL
  • 多提供商支持: 支持 GUIJI、智谱AI、豆包、OpenAI 等多种 AI 服务提供商

🖼️ 图片处理功能

  • 批量上传: 支持单个或多个图片文件同时上传
  • 智能分析: AI 自动生成图片标题和详细描述
  • 多格式支持: 支持 JPG、PNG、GIF、BMP、WebP 等常见格式
  • 异步处理: 高并发异步处理，提升处理效率
  • 实时反馈: 上传进度实时显示，错误信息详细反馈

🌐 Web 界面

  • 用户友好界面: 提供直观的 Web 操作界面
  • 拖拽上传: 支持文件拖拽上传和点击选择
  • 实时预览: 图片和文件信息实时预览
  • API 文档: 完整的 Swagger UI 和 ReDoc 接口文档

🛠️ 技术栈

  • 后端框架: FastAPI (高性能异步 Web 框架)
  • PDF 处理: MinerU、magic-pdf (先进的 PDF 解析技术)
  • AI 视觉模型: 多提供商 API 集成
  • 异步处理: aiohttp、aiofiles (高效异步 I/O)
  • 图像处理: Pillow (专业图像处理库)
  • 深度学习: PyTorch、Transformers (AI 模型支持)

📁 项目结构

remote_pdf_parse_serve/
├── 📄 README.md                    # 项目说明文档
├── 📄 requirements.txt             # 依赖包清单
├── 🚀 run_server.py                # 服务器启动脚本
├── 📁 assets/                      # 测试资源文件
│   ├── 📁 pdfs/                   # 测试 PDF 文件
│   └── 📁 images/                 # 测试图片文件
├── 📁 tests/                      # 自动化测试
│   ├── 🧪 test_api_pdf.py         # PDF 接口测试
│   └── 🧪 test_api_image.py       # 图片接口测试
├── 📁 utils/                      # 通用工具
│   └── 🔧 download_mineru_models.py
└── 📁 web_serves/                 # 核心服务代码
    ├── 🎯 app.py                  # FastAPI 应用入口
    ├── ⚙️ config.py               # 配置管理
    ├── ⚙️ config.json             # 主配置文件
    ├── ❌ exceptions.py           # 自定义异常
    ├── 📁 routers/                # API 路由模块
    │   ├── 📄 pdf_processing.py   # PDF 处理路由
    │   └── 🖼️ image_upload.py     # 图片上传路由
    ├── 📁 utils/                  # 工具模块
    │   ├── 📂 file_handler.py     # 文件处理工具
    │   └── 📝 logger.py           # 日志管理
    ├── 📁 pdf_utils/              # PDF 处理模块
    │   └── 🔄 mineru_parse.py     # MinerU PDF 解析
    ├── 📁 image_utils/            # 图像分析模块
    │   ├── 🤖 async_image_analysis.py    # 异步图像分析
    │   ├── 🔧 image_analysis_utils.py    # 图像分析工具
    │   └── 💬 prompts.py                 # AI 提示词管理
    ├── 📁 markdown_utils/         # Markdown 处理
    │   ├── 🔄 markdown_image_processor.py
    │   └── 📝 update_markdown_with_analysis.py
    ├── 📁 static/                 # 静态文件
    ├── 📁 templates/              # HTML 模板 (Ant Design 风格)
    │   ├── 🏠 simple_index_antd.html      # 主页
    │   ├── 🖼️ simple_image_upload_antd.html # 图片上传页面
    │   ├── 📄 simple_pdf_upload_antd.html   # PDF上传页面
    │   └── 🎨 simple_base_antd.html        # 基础模板
    ├── 📁 uploads/                # 文件存储
    │   ├── 📁 pdfs/              # PDF 文件存储
    │   ├── 📁 images/            # 图片文件存储
    │   └── 📁 markdown/          # Markdown 文件存储
    └── 📁 temp/                   # 临时文件处理

🚀 快速开始

📋 当前状态: 本项目已完成主要Bug修复和架构优化，前后端功能正常，无轮询机制，采用同步处理模式。

1. 环境准备

# 克隆项目
git clone https://github.com/li-xiu-qi/remote_pdf_parse_serve.git
cd remote_pdf_parse_serve

# 创建虚拟环境 (推荐)
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate     # Windows

# 安装依赖
pip install -r requirements.txt

2. 环境配置

创建 .env 文件并配置 AI 服务密钥（至少配置一个）：

# 🤖 GUIJI (硅基流动) API
GUIJI_API_KEY=your_guiji_api_key_here
GUIJI_BASE_URL=https://api.siliconflow.cn/v1/
GUIJI_VISION_MODEL=Pro/Qwen/Qwen2.5-VL-7B-Instruct

# 🧠 智谱 AI
ZHIPU_API_KEY=your_zhipu_api_key_here  
ZHIPU_BASE_URL=https://open.bigmodel.cn/api/paas/v4/
ZHIPU_VISION_MODEL=glm-4v-flash

# 🌋 豆包 (Volces)
VOLCES_API_KEY=your_volces_api_key_here
VOLCES_BASE_URL=https://ark.cn-beijing.volces.com/api/v3/
VOLCES_VISION_MODEL=doubao-1.5-vision-lite-250315

# 🔥 OpenAI
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_API_BASE=https://api.openai.com/v1/
OPENAI_VISION_MODEL=gpt-4o

3. 下载模型 (可选)

建议运行的时候让他自动下载模型。

python utils/download_mineru_models.py

4. 启动服务

🔴 开发模式 (直接启动)

python run_server.py

🚀 生产模式 (使用 PM2 守护进程)

安装 PM2:

# 安装 PM2 (全局安装)
sudo npm install -g pm2

基本启动命令:

# 1. 默认环境启动
pm2 start ecosystem.config.js

# 2. 开发环境启动
pm2 start ecosystem.config.js --env development

# 3. 生产环境启动
pm2 start ecosystem.config.js --env production

# 4. 查看启动状态
pm2 status

PM2 管理命令:

# 查看服务状态
pm2 status                          # 查看所有服务状态
pm2 describe pdf-parse-server       # 查看详细信息
pm2 info pdf-parse-server           # 查看进程信息

# 日志管理
pm2 logs pdf-parse-server           # 查看实时日志
pm2 logs pdf-parse-server --lines 100  # 查看最近100行日志
pm2 logs pdf-parse-server --err     # 只查看错误日志
pm2 flush pdf-parse-server          # 清空日志

# 服务管理
pm2 restart pdf-parse-server        # 重启服务
pm2 reload pdf-parse-server         # 零停机重启
pm2 stop pdf-parse-server           # 停止服务
pm2 start pdf-parse-server          # 启动服务
pm2 delete pdf-parse-server         # 删除服务

# 监控和调试
pm2 monit                           # 监控界面
pm2 show pdf-parse-server           # 显示进程详情
pm2 prettylist                      # 美化显示进程列表

# 开机自启设置
pm2 startup                         # 设置开机自启
pm2 save                           # 保存当前进程列表
pm2 unstartup                      # 取消开机自启

高级 PM2 命令:

# 扩展和缩放
pm2 scale pdf-parse-server 2        # 扩展到2个实例
pm2 scale pdf-parse-server +1       # 增加1个实例

# 内存和性能监控
pm2 show pdf-parse-server           # 显示CPU和内存使用
pm2 reset pdf-parse-server          # 重置重启计数器

# 更新和部署
pm2 update                          # 更新PM2
pm2 ecosystem                       # 生成示例配置文件

🎉 服务成功启动后，访问以下地址：

🏗️ 架构设计

处理模式

  • 同步处理: 文件上传后立即进行处理，无需轮询等待
  • 实时反馈: 前端直接获取处理结果，包括文件信息和访问URL
  • 错误透明: 处理失败时立即返回详细错误信息

核心组件

  • FastAPI Backend: 高性能异步Web框架，提供RESTful API
  • MinerU Engine: PDF解析核心，支持复杂文档结构
  • Multi-AI Integration: 支持多家AI服务商的视觉分析能力
  • File Management: 统一的文件处理和存储管理系统

安全机制

  • 文件类型检查: 严格的文件格式和大小限制
  • 路径安全: 防止目录遍历攻击
  • 临时文件清理: 自动清理处理过程中的临时文件
  • 错误隔离: 单个文件处理失败不影响其他文件

📡 API 接口说明

🖼️ 图片处理接口

POST /upload/images

批量上传图片文件进行 AI 智能分析

请求参数:

  • files: 图片文件数组 (multipart/form-data)
  • provider (可选): AI 提供商 (guiji|zhipu|volces|openai)
  • max_concurrent (可选): 最大并发数 (默认: 5)

响应示例:

{
  "message": "处理完成。成功: 2, 失败: 0",
  "uploaded_files": [
    {
      "original_filename": "image1.png",
      "filename": "abc123def456.png",
      "saved_filename": "abc123def456.png",
      "file_path": "/path/to/uploads/images/abc123def456.png",
      "url": "/uploads/images/abc123def456.png",
      "file_size": 102400,
      "content_type": "image/png"
    }
  ],
  "failed_files": []
}

POST /upload/image

上传单个图片文件

请求参数:

  • file: 图片文件 (multipart/form-data)

响应示例:

{
  "message": "文件上传成功",
  "file_info": {
    "original_filename": "image.png",
    "filename": "xyz789abc123.png",
    "saved_filename": "xyz789abc123.png",
    "file_path": "/path/to/uploads/images/xyz789abc123.png",
    "url": "/uploads/images/xyz789abc123.png",
    "file_size": 102400,
    "content_type": "image/png"
  }
}

📄 PDF 处理接口

POST /upload/pdf

上传 PDF 文件，转换为 Markdown 并进行图片智能分析

请求参数:

  • file: PDF 文件 (multipart/form-data)
  • provider (可选): AI 提供商 (默认: zhipu)
  • process_images (可选): 是否处理图片 (默认: true)
  • max_concurrent (可选): AI 并发数 (默认: 5)

响应示例:

{
  "message": "PDF处理成功",
  "processing_id": "abc123def456",
  "file_info": {
    "original_filename": "document.pdf",
    "stored_filename": "document_processed.pdf",
    "file_size": 2048000,
    "content_type": "application/pdf",
    "pdf_path": "uploads/pdfs/document_processed.pdf",
    "markdown_path": "uploads/markdown/document_abc123def456.md",
    "creation_time": "2024-12-01T10:00:00",
    "provider": "zhipu",
    "process_images": true
  },
  "markdown_content": "# 文档标题\n\n这是转换后的 Markdown 内容...",
  "processing_info": {
    "pdf_converted": true,
    "images_processed": true,
    "remote_base_url": "http://localhost:8000/uploads/images/",
    "temp_directory_cleaned": true
  }
}

🧪 测试

运行测试套件

# 测试 PDF 处理功能
python tests/test_api_pdf.py

# 测试图片上传功能
python tests/test_api_image.py

准备测试文件

确保测试资源文件存在：

  • assets/pdfs/simcse.pdf - 测试 PDF 文件
  • assets/images/ - 测试图片文件目录

⚙️ 配置详解

主配置文件: web_serves/config.json

{
  "server": {
    "host": "0.0.0.0",        // 服务监听地址
    "port": 10001,            // 服务端口
    "debug": true             // 调试模式
  },
  "api": {
    "title": "PDF解析和图片处理服务",
    "description": "一个支持PDF解析、图片上传和AI图像分析的 FastAPI 服务",
    "version": "1.0.0"
  },
  "upload": {
    "allowed_extensions": [    // 支持的文件格式
      ".jpg", ".jpeg", ".png", ".gif", ".bmp", ".webp", ".pdf"
    ],
    "max_file_size_mb": 50,   // 最大文件大小 (MB)
    "supported_image_extensions": [
      ".jpg", ".jpeg", ".png", ".gif", ".bmp", ".webp"
    ],
    "supported_pdf_extensions": [".pdf"]
  },
  "storage": {
    "pdf_dir": "uploads/pdfs",           // PDF 存储目录
    "markdown_dir": "uploads/markdown",  // Markdown 存储目录
    "images_dir": "uploads/images",      // 图片存储目录  
    "temp_dir": "temp",                  // 临时文件目录
    "keep_original_files": true,         // 保留原始文件
    "keep_markdown_files": true          // 保留 Markdown 文件
  },
  "ai_services": {
    "default_provider": "zhipu",         // 默认 AI 提供商
    "default_max_concurrent_ai": 5,      // 默认并发数
    "title_max_length": 100,             // 标题最大长度
    "description_max_length": 500        // 描述最大长度
  }
}

About

基于mineru封装的远程pdf解析服务。

Resources

Readme
Activity

Stars

12 stars

Watchers

0 watching

Forks

3 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages