PDF论文处理器 - 完整使用指南
📖 概述
PDF论文处理器是一个专门为网安科研论文设计的PDF文本分割工具，旨在将英文论文PDF文件转化为Dify知识库可直接使用的高质量数据块。
核心功能
- 智能文本提取 - 从PDF中准确提取论文内容
- 语义感知分割 - 基于论文章节结构进行智能分割
- 元数据增强 - 自动提取论文类型、年份等元数据
- Dify兼容输出 - 生成可直接导入Dify的CSV/JSON格式
- CSV模式选择 - 支持Merged和Standard两种CSV输出模式
🚀 快速开始
1. 环境准备
确保已安装Python 3.8+，然后安装依赖：
pip install -r requirements_pdf_processor.txt 2. 准备论文数据
将你的PDF论文按照以下目录结构组织：
papers/ ├── 漏洞挖掘/ │ ├── 2024/ │ │ ├── paper1.pdf │ │ └── paper2.pdf │ └── 2023/ │ └── paper3.pdf ├── 漏洞修复/ │ └── 2024/ │ └── paper4.pdf ├── LLM安全/ │ └── 2024/ │ └── paper5.pdf └── 其他/ └── 2024/ └── paper6.pdf 注意：文件夹名称必须使用中文（漏洞挖掘、漏洞修复、LLM安全、其他），以便程序自动识别论文类型。
3. 运行处理脚本
默认使用（推荐，Merged模式 + Dify分隔符）
python process_papers.py --input ./papers 自定义参数
python process_papers.py \ --input ./papers \ --output ./output \ --chunk-size 800 \ --overlap 200 \ --csv-mode merged \ --add-separator 📊 CSV输出模式
Merged模式（推荐，默认）
特点：
- ✅ 所有信息合并到content列
- ✅ 分隔符在最末尾
- ✅ Dify可以准确分段
- ✅ 元数据完整保留
CSV格式：
content,metadata,source "论文文本内容...[Metadata: {...}] [Source: paper.pdf]<<<>",, 使用方法：
# 默认使用 python process_papers.py --input ./papers # 显式指定 python process_papers.py --input ./papers --csv-mode merged Standard模式（不推荐）
特点：
- ⚠️ 三列独立格式
- ⚠️ 分隔符在content末尾
- ⚠️ 可能导致分段不准确
CSV格式：
content,metadata,source "论文文本内容...<<<>>>","{...}",paper.pdf 使用方法：
python process_papers.py --input ./papers --csv-mode standard 🎯 元数据结构
精简后的元数据字段
{ "category": "vulnerability_mining", "category_cn": "漏洞挖掘", "year": "2024", "section": "Abstract", "char_count": 135, "source_file": "paper.pdf", "title": "Novel Approach for Vulnerability Detection" } 字段说明
| 字段 | 说明 | 示例 |
|---|---|---|
| category | 论文类型英文 | vulnerability_mining |
| category_cn | 论文类型中文 | 漏洞挖掘 |
| year | 发表年份 | 2024 |
| section | 所属章节 | Abstract |
| char_count | 字符数 | 135 |
| source_file | 来源文件 | paper.pdf |
| title | 论文标题 | Novel Approach... |
已移除的冗余字段
- chunk_id: 在merged模式下不需要
🏷️ Dify分隔符功能
问题背景
当使用Dify上传CSV时，如果使用\n或.pdf等常见字符作为分段标识符，会导致chunk被错误切割，破坏元数据的完整性。
解决方案
在每个chunk的末尾添加一个唯一的、不会出现在正文中的特殊分隔符，Dify使用这个分隔符来准确切割chunk。
默认分隔符
<<E>>> Dify导入设置
- 上传CSV文件到Dify
- 设置分段标识符：
<<<E>>> - 开始处理
自定义分隔符
python process_papers.py --input ./papers \ --separator "<<<MY_CUSTOM_SEPARATOR>>>" ⚙️ 参数说明
基本参数
| 参数 | 简写 | 默认值 | 说明 |
|---|---|---|---|
--input |
-i |
必需 | 输入目录或PDF文件路径 |
--output |
-o |
output |
输出目录 |
--format |
- | csv |
输出格式（csv/json） |
分割参数
| 参数 | 默认值 | 说明 |
|---|---|---|
--chunk-size |
700 |
Chunk大小（字符数） |
--overlap |
150 |
Chunk重叠大小（字符数） |
CSV模式参数
| 参数 | 默认值 | 说明 |
|---|---|---|
--csv-mode |
merged |
CSV输出模式（merged/standard） |
分隔符参数
| 参数 | 默认值 | 说明 |
|---|---|---|
--add-separator |
True |
启用Dify分隔符 |
--no-separator |
False |
禁用分隔符 |
--separator |
特殊字符串 | 自定义Dify分隔符 |
💡 使用建议
Chunk大小选择
| 大小 | 适用场景 | 优缺点 |
|---|---|---|
| 300-500 | 精确检索、快速响应 | ✓ 精度高 ✗ 上下文少 |
| 500-800 | 平衡选择（推荐） | ✓ 兼顾精度和上下文 |
| 800-1200 | 长文理解、深度分析 | ✓ 上下文完整 ✗ 响应慢 |
| 1200+ | 复杂推理、综合分析 | ✓ 信息完整 ✗ 检索效率低 |
重叠率设置
| 重叠率 | 适用场景 |
|---|---|
| 50-100 | 较短的chunk（300-500字符） |
| 100-200 | 推荐值（500-800字符） |
| 200-300 | 较长的chunk（800-1200字符） |
场景推荐
1. 研究现状总结
python process_papers.py \ --input ./papers \ --chunk-size 800 \ --overlap 200 \ --csv-mode merged 2. 对比查新
python process_papers.py \ --input ./papers \ --chunk-size 600 \ --overlap 150 \ --csv-mode merged 3. 创新点挖掘
python process_papers.py \ --input ./papers \ --chunk-size 700 \ --overlap 180 \ --csv-mode merged 4. 领域展望
python process_papers.py \ --input ./papers \ --chunk-size 800 \ --overlap 200 \ --csv-mode merged 🧪 测试工具
1. 诊断PDF文件
# 快速检查前10个 python diagnose_pdfs.py -i ./papers -s 10 # 检查所有 python diagnose_pdfs.py -i ./papers -s 100 2. 测试单个PDF
python test_pdf_extraction.py -i ./papers/some.pdf 3. 测试处理器
python test_processor.py 4. 测试CSV模式
python test_csv_modes.py 5. 测试Dify分隔符
python test_dify_separator.py 6. 完整工作流测试
python test_complete_workflow.py 🔧 故障排除
所有PDF失败
# 1. 诊断 python diagnose_pdfs.py -i ./papers -s 5 # 2. 组织（中文文件名问题） python organize_papers.py -i ./papers -o ./papers_english # 3. 重试 python process_papers.py -i ./papers_english Dify分段不准确
问题：chunk边界不正确
解决：
# 1. 验证分隔符 python test_dify_separator.py # 2. 使用merged模式（推荐） python process_papers.py -i ./papers --csv-mode merged # 3. 重新处理，使用更独特的分隔符 python process_papers.py -i ./papers \ --separator "<<<>>" # 4. 在Dify中设置正确的分段标识符 📚 文档
README_PDF_PROCESSOR.md- 项目详细说明QUICKSTART.md- 快速开始指南CSV_MODE_GUIDE.md- CSV模式详细说明DIFY_SEPARATOR_GUIDE.md- Dify分隔符详细说明QUICK_REFERENCE.md- 快速参考卡片TROUBLESHOOTING.md- 故障排除指南
🎉 完整工作流
# 1. 诊断PDF文件 python diagnose_pdfs.py -i ./papers -s 10 # 2. 处理论文（使用默认merged模式） python process_papers.py --input ./papers # 3. 查看生成的CSV文件 ls output/ # 4. 在Dify中导入 # - 上传CSV文件 # - 设置分段标识符：<<<>>> # - 开始处理 # 5. 测试检索 # - 在知识库中测试查询 # - 验证chunk边界是否正确 ✅ 推荐配置
python process_papers.py \ --input ./papers \ --output ./output \ --chunk-size 700 \ --overlap 150 \ --csv-mode merged \ --add-separator 这是经过测试和验证的最佳配置，适合大多数场景。