# PDF_Detail

**Repository Path**: demo_53_0/pdf_-detail

## Basic Information

- **Project Name**: PDF_Detail
- **Description**: 支持按章节目录和正文进行PDF拆分
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-27
- **Last Updated**: 2025-12-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PDF章节拆分API

一个基于FastAPI的PDF文档章节自动拆分服务，能够智能识别PDF文档的章节结构，并将其拆分为独立的PDF文件。

## 功能特点

- 🚀 基于FastAPI的高性能异步API
- 📄 智能PDF章节识别与拆分
- 🧠 **高级算法加持**：集成 L.I.S. (最长递增子序列) 算法与 Gap Filling 技术，自动修复章节断号
- 🛡️ **通用噪音过滤**：智能剔除"附图目录"等全书容器章节，不依赖硬编码黑名单
- ⚖️ **双轨提取策略**：同时保留目录提取与正文扫描结果，自动推荐最优方案
- 🔍 自动检测目录与内容的一致性
- 📊 提供详细的处理进度和状态查询
- ⚙️ 支持内容验证模式，处理不一致的文档
- 📁 完整的文件管理和任务管理
- 📝 完善的日志记录和错误处理

## 项目结构

```
Pdf_detil/
├── app/                    # 应用主目录
│   ├── __init__.py
│   ├── main.py            # 应用入口文件
│   ├── core/              # 核心配置
│   │   ├── __init__.py
│   │   ├── config.py      # 应用配置
│   │   └── logger.py      # 日志配置
│   ├── models/            # 数据模型
│   │   ├── __init__.py
│   │   └── schemas.py     # Pydantic模型
│   ├── routers/           # 路由模块
│   │   ├── __init__.py
│   │   ├── main.py        # 主路由
│   │   ├── upload.py      # 文件上传路由
│   │   ├── tasks.py       # 任务管理路由
│   │   └── download.py    # 文件下载路由
│   ├── services/          # 业务逻辑层
│   │   ├── __init__.py
│   │   ├── task_manager.py    # 任务管理器
│   │   ├── pdf_processor.py   # PDF处理器
│   │   └── file_manager.py   # 文件管理器
│   └── utils/             # 高级策略层
│       ├── __init__.py
│       ├── enhanced_pdf_processor.py  # [策略大脑] 负责流程编排、双轨验证、L.I.S.清洗与最终决策
│       └── example_usage.py          # 使用示例
├── utils/                 # 基础工具层
│   └── pdf_utils_sy.py   # [执行工兵] 提供正则扫描、文本提取、页面切割等底层原子操作
├── venv/                  # 虚拟环境
├── uploads/               # 上传文件目录
├── outputs/               # 输出文件目录
├── temp/                  # 临时文件目录
├── requirements.txt       # 项目依赖
├── run.py                # 启动脚本
└── README.md             # 项目说明
```

## 安装与运行

### 1. 环境准备

确保已安装Python 3.8+，然后创建虚拟环境：

```bash
# 创建虚拟环境
python -m venv venv

# 激活虚拟环境 (Windows)
.\venv\Scripts\Activate.ps1

# 激活虚拟环境 (Linux/Mac)
source venv/bin/activate
```

### 2. 安装依赖

```bash
pip install -r requirements.txt
```

### 3. 运行应用

```bash
# 方法1: 使用启动脚本
python run.py

# 方法2: 直接使用uvicorn
uvicorn app.main:app --reload

# 方法3: 指定主机和端口
uvicorn app.main:app --host 0.0.0.0 --port 8000
```

应用启动后，访问 http://localhost:8000 查看API文档。

## API接口

### 1. 基本信息接口

- `GET /` - 获取API基本信息
- `GET /health` - 健康检查

### 2. 文件上传接口

- `POST /upload-pdf` - 上传PDF文件并启动处理任务

  请求参数：
  - `file`: PDF文件 (multipart/form-data)

  响应示例：
  ```json
  {
    "message": "文件上传成功，正在处理中",
    "task_id": "task_12345678-1234-1234-1234-123456789012",
    "file_id": "12345678-1234-1234-1234-123456789012"
  }
  ```

### 3. 任务管理接口

- `GET /status/{task_id}` - 查询任务处理状态
- `GET /result/{task_id}` - 获取完整的处理结果
- `DELETE /task/{task_id}` - 删除任务及其相关文件

### 4. 文件下载接口

- `GET /download/{task_id}/{chapter_id}` - 下载拆分后的章节文件

## 使用示例

### Python示例

```python
import requests

# 1. 上传PDF文件
with open('document.pdf', 'rb') as f:
    response = requests.post(
        'http://localhost:8000/upload-pdf',
        files={'file': f}
    )
    result = response.json()
    task_id = result['task_id']
    print(f"任务ID: {task_id}")

# 2. 查询任务状态
response = requests.get(f'http://localhost:8000/status/{task_id}')
status = response.json()
print(f"任务状态: {status['status']}")

# 3. 获取处理结果
if status['status'] == 'completed':
    response = requests.get(f'http://localhost:8000/result/{task_id}')
    result = response.json()
    
    print(f"处理成功: {result['success']}")
    print(f"章节数量: {len(result['chapters'])}")
    
    # 4. 下载第一章
    response = requests.get(f'http://localhost:8000/download/{task_id}/0')
    with open('chapter_1.pdf', 'wb') as f:
        f.write(response.content)
```

### cURL示例

```bash
# 上传PDF文件
curl -X POST "http://localhost:8000/upload-pdf" -H "accept: application/json" -H "Content-Type: multipart/form-data" -F "file=@document.pdf"

# 查询任务状态
curl -X GET "http://localhost:8000/status/task_12345678-1234-1234-1234-123456789012" -H "accept: application/json"

# 获取处理结果
curl -X GET "http://localhost:8000/result/task_12345678-1234-1234-1234-123456789012" -H "accept: application/json"

# 下载章节文件
curl -X GET "http://localhost:8000/download/task_12345678-1234-1234-1234-123456789012/0" -H "accept: application/pdf" -o chapter_1.pdf
```

## 配置说明

应用配置位于 `app/core/config.py`，主要配置项包括：

- `app_name`: 应用名称
- `app_version`: 应用版本
- `host`: 服务器主机地址
- `port`: 服务器端口
- `upload_dir`: 上传文件目录
- `output_dir`: 输出文件目录
- `temp_dir`: 临时文件目录
- `log_level`: 日志级别
- `log_file`: 日志文件路径

可以通过环境变量或创建 `.env` 文件来覆盖这些配置。

## PDF处理功能

### 智能章节识别与清洗

- **多模式标题识别**：
  - 第X章 模式
  - 数字+点模式 (1. 标题)
  - 数字+空格模式 (1 标题)
  - 大写字母/罗马数字模式
- **序列连续性分析 (Sequence Continuity)**：
  - 采用 **L.I.S. (Longest Increasing Subsequence)** 算法识别核心章节骨架，有效剔除孤立的页码数字或年份噪音。
  - **Gap Filling (锚点回溯)**：利用确定的章节链条作为锚点，自动找回被误过滤的中间章节（如 6->8 之间找回 7）。

### 智能噪音过滤

- **通用容器检测**：基于页码范围占比（>90%）和同级重叠率，自动剔除"附图目录"等包含全书的噪音章节，不再依赖硬编码的黑名单。
- **前置噪音剔除**：根据目录页结束位置，智能过滤封面、版权页等前置噪音。

### 双轨提取与验证

- **独立双轨策略**：同时执行目录提取（TOC Extraction）和正文扫描（Content Scanning）。
- **一致性对比**：
  - 自动检测目录与实际内容的一致性
  - 优先推荐 TOC 结果（通常更准确且包含层级），除非 TOC 严重缺失
  - 识别页码不匹配问题并提供处理建议

### 内容验证模式

对于目录与内容不一致的文档，提供内容验证模式，通过扫描实际内容来确定章节位置。

## 开发指南

### 添加新的PDF处理功能

1. 在 `utils/pdf_utils_sy.py` 中添加核心处理函数
2. 在 `app/utils/enhanced_pdf_processor.py` 中添加增强处理逻辑
3. 在 `app/services/pdf_processor.py` 中集成新功能
4. 更新相应的数据模型和API接口

### 自定义配置

创建 `.env` 文件：

```
APP_NAME=我的PDF处理服务
HOST=0.0.0.0
PORT=8000
LOG_LEVEL=INFO
```

### 日志查看

应用日志保存在 `pdf_api.log` 文件中，同时也会输出到控制台。

## 常见问题

### Q: 支持哪些PDF格式？

A: 支持标准的PDF格式，包括文本型PDF和扫描型PDF（扫描型PDF的章节识别精度可能较低）。

### Q: 处理大文件时性能如何？

A: 应用使用异步处理，大文件会在后台处理，不会阻塞API响应。处理进度可以通过任务状态接口查询。

### Q: 如何提高章节识别的准确性？

A: 对于格式不规范的文档，建议使用内容验证模式。应用会自动分析文档结构并推荐最适合的处理模式。

## 许可证

本项目采用 MIT 许可证。

## 贡献

欢迎提交Issue和Pull Request来改进这个项目。

## 联系方式

如有问题或建议，请通过Issue联系我们。