PDF 论文处理器 — 技术报告文档适用项目数据处理脚本 / Dify 知识库数据生成工具文档性质技术剖析与归档1. 文档说明本文档覆盖以下内容系统总体架构与分层设计核心模块职责、关键类与关键函数数据处理全流程与数据形态演变数据输入 / 输出规范与元数据结构外部依赖与运行环境要求关键算法原理说明部署与运行指南2. 项目概述2.1 项目定位本工具是一个面向网络安全网安科研论文的领域专用 PDF 文本预处理流水线。其目标是将分散存储的英文论文 PDF转化为 Dify 知识库可直接导入的高质量数据块chunk服务于 RAG检索增强生成场景下的论文检索、研究现状总结与创新点挖掘。2.2 设计理念工具在提取 → 清洗 → 语义分块 → 元数据增强 → Dify 兼容输出的流水线中刻意融入了两类领域特征结构感知依据论文标准章节Abstract / Introduction / Method …进行分块而非无差别固定长度切分保留章节语义边界。元数据驱动从目录结构 文件名自动推断论文类别漏洞挖掘 / 漏洞修复 / LLM 安全 / 其他与发表年份并将章节、字数、来源等字段随块输出提升检索可过滤性与可追溯性。2.3 技术栈概览维度选型语言Python 3源码兼容 3.8详见 7.3PDF 抽取PyMuPDF1.24.5进度显示tqdm 4.66.1落盘格式标准库csv/json声明了 pandas 但未使用命令行标准库argparse3. 系统总体架构3.1 分层结构系统自上而下分为四层依赖方向单一上层依赖下层配置层被各层共享┌─────────────────────────────────────────────────────────────┐ │ ① 命令行入口层 process_papers.pyargparse 解析与配置改写 │ └───────────────────────────────┬─────────────────────────────┘ │ 创建并驱动 ┌───────────────────────────────▼─────────────────────────────┐ │ ② 流程编排层 PDFProcessorprocessor.py │ │ process_file / process_directory / save_results │ └───┬───────────────┬───────────────┬───────────────┬──────────┘ │ │ │ │ ┌───▼───┐ ┌──────▼─────┐ ┌──────▼─────┐ ┌──────▼─────┐ │PDFEx- │ │Semantic- │ │Metadata- │ │Output- │ │tractor│ │Chunker │ │Manager │ │Manager │ └───────┘ └────────────┘ └────────────┘ └────────────┘ │ │ │ │ └───────────────────────┬───────────────────────────────┘ ┌───────▼────────┐ │ ③ 配置层 config.py │ │ CHUNK / CLEAN / │ │ OUTPUT / CATEGORY│ │ / SECTION_HEADERS│ └─────────────────┘3.2 组件清单与职责文件核心类 / 函数职责process_papers.pymain()CLI 入口解析参数、改写全局配置、打印运行提示、驱动PDFProcessorsrc/pdf_processor/__init__.py__all__包导出统一对外暴露 5 个公共类src/pdf_processor/config.pyCHUNK_CONFIG/CLEAN_CONFIG/OUTPUT_CONFIG/CATEGORY_MAPPING/SECTION_HEADERS集中式配置字典src/pdf_processor/pdf_extractor.pyPDFExtractorPDF 文本抽取、清洗、基础元数据提取src/pdf_processor/chunker.pySemanticChunker章节识别 滑动窗口分块 句末对齐src/pdf_processor/metadata_manager.pyMetadataManager路径元数据提取、元数据精简、Dify 格式化src/pdf_processor/output_manager.pyOutputManagerCSV/JSON 落盘、统计生成与保存src/pdf_processor/processor.pyPDFProcessor串联上述四模块提供文件 / 目录级处理接口4. 核心模块详解4.1 PDFExtractorpdf_extractor.py职责打开 PDF、逐页抽取纯文本、执行清洗规则、提取基础元数据对单页异常做容错。关键方法extract_text(pdf_path) - (cleaned_text, metadata)L28 主入口。先调用_extract_metadata在文档打开态取元数据随后逐页page.get_text(text)抽取并在finally块中doc.close()确保句柄释放L70-75。单页异常被try/except捕获后跳过该页L65-68避免整篇失败。_remove_page_numbers(text, page_num)L85 用\b{page_num}\b、Page\s*{n}、page\s*{n}三种正则移除页码。_remove_headers_footers(text)L99 移除孤立数字行^\d\s*$并丢弃短于min_paragraph_length且不以大写字母开头的行。_clean_text(text)L117 标准化空白→单空格、\n{3,}→\n\n、去行首尾空格移除引用标记[\d]与年份(YYYY)。_extract_metadata(doc, pdf_path)L134 记录filename / file_path / total_pages若 PDF 元信息含title则取之否则以第一页首行长度 10–200作为标题。4.2 SemanticChunkerchunker.py职责将长文本按章节切分再对每个章节做带重叠的滑动窗口分块并尽量对齐到句子边界。关键方法chunk_text(text, metadata)L19 对外主接口。调用_identify_sections得到(section_name, section_text)列表逐章节_sliding_window_chunk为每个块补充section / chunk_id / char_count元数据。_identify_sections(text)L58 将SECTION_HEADERS中所有模式拼为(?m)^escaped\s*$的多选正则定位章节标题行按匹配位置切片得到各章节文本。若无匹配则返回单段(Full Text, text)。_sliding_window_chunk(text, section_name)L125 若整段 ≤max_chunk_size直接整体输出否则以chunk_size为步长、回退chunk_overlap作为下一段起点循环切片。_find_sentence_boundary(text, target_pos)L163 在目标位置 ±100 字符范围内按优先级.\n/!/?/./;\n/:\n向后搜索句末标点将切分点对齐到句子结束处。4.3 MetadataManagermetadata_manager.py职责元数据全生命周期管理——从路径提取、合并精简、到 Dify 格式输出。关键方法extract_from_path(file_path)L24 按/规范化路径遍历层级若某层命中CATEGORY_MAPPING则记录category / category_cn并取下一层若为合法年份2000–2030记为year目录中未取到年份时回退到文件名年份正则20\d{2}/24。enrich_metadata(chunk, pdf_metadata)L113 合并 PDF 元数据后精简为 6 个核心字段category / category_cn / year / section / char_count / source_file存在title时追加。format_for_dify(chunk, output_config)L151 按csv_mode分发到_format_standard或_format_merged并在末尾追加 Dify 分隔符。_format_standardL179三列独立metadata为 JSON 串。_format_mergedL198将metadata与source拼接到content末尾带前缀[Metadata:、[Source:再追加分隔符CSV 的metadata / source列置空。_generate_chunk_markerL231基于模板生成标记字符串主流程当前未启用。4.4 OutputManageroutput_manager.py职责落盘与统计。关键方法save_chunks(chunks, base_filename)L30按self.formatcsv/json与时间戳命名写入。_save_csvL60以utf-8-sig编码写content,metadata,source三列BOM 头便于 Excel 打开。_save_jsonL85ensure_asciiFalse美化输出。generate_statistics(chunks)L99统计总量 / 字数 / 均值 / 极值并按category / year / section三维聚合merged 模式下从content内正则回抽元数据。print_statistics/save_statistics控制台打印与 JSON 落盘。4.5 PDFProcessorprocessor.py职责组装四模块提供统一处理接口。关键方法process_file(pdf_path)L38单文件流水线——extract_from_path→extract_text→ 元数据合并 →chunk_text→ 逐块enrich_metadataformat_for_dify。process_directory(root_dir, recursive)L70os.walk收集 PDF用tqdm显示进度逐文件处理并收集失败清单最后汇总成功 / 失败 / 总块数。_find_pdf_filesL117递归或非递归收集.pdf结果排序保证可复现。save_results(chunks, output_filename)L144落盘主数据 生成 / 打印 / 保存统计。5. 数据处理流程5.1 端到端流程输入目录/文件 │ ▼ [CLI] 解析参数 → 改写全局 CHUNK_CONFIG / OUTPUT_CONFIG │ ▼ PDFProcessor.process_directory / process_file │ ├─① MetadataManager.extract_from_path │ 产出: {category, category_cn, year, source_file} (来自路径/文件名) │ ├─② PDFExtractor.extract_text │ 产出: (cleaned_text, {title, total_pages, ...}) (来自 PDF 元信息/首页) │ ├─③ 元数据合并 (base_metadata.update(pdf_metadata)) │ ├─④ SemanticChunker.chunk_text │ 产出: [{content, metadata{...section,chunk_id,char_count}}] │ ├─⑤ 逐块 MetadataManager.enrich_metadata │ 产出: 精简后 metadata (6 字段) │ ├─⑥ 逐块 MetadataManager.format_for_dify │ 产出: {content, metadata, source} (按 csv_mode 组织 分隔符) │ ▼ PDFProcessor.save_results ├─ OutputManager.save_chunks → *.csv / *.json └─ OutputManager.generate/save_statistics → *_statistics.json5.2 数据形态演变阶段数据形态关键字段原始磁盘 PDF二进制① 路径解析dictcategory, category_cn, year, source_file② 抽取清洗(str, dict)cleaned_text, title, total_pages④ 分块List[{content, metadata}]追加section, chunk_id, char_count⑥ 格式化List[{content, metadata, source}]merged 模式 metadata/source 为空串落盘CSV / JSON 文件见第 6 节6. 数据输入 / 输出规范6.1 输入规范目录模式推荐papers/ ├── 漏洞挖掘/ │ ├── 2024/ paper1.pdf, paper2.pdf │ └── 2023/ paper3.pdf ├── 漏洞修复/ │ └── 2024/ paper4.pdf ├── LLM安全/ │ └── 2024/ paper5.pdf └── 其他/ └── 2024/ paper6.pdf类别文件夹须使用约定中文名漏洞挖掘 / 漏洞修复 / LLM安全 / 其他用于自动映射英文标识。年份文件夹格式为 4 位年份缺失时回退文件名年份识别。单文件模式直接传.pdf路径并加--single-file。6.2 输出规范主数据文件列含义merged 模式standard 模式content文本 merged元数据/来源 分隔符完整拼接纯文本 分隔符metadata元数据 JSON 串空{category:...}source来源文件名空paper1.pdf统计文件*_statistics_*.json{ total_chunks: 123, total_chars: 86000, avg_chunk_size: 699, min_chunk_size: 105, max_chunk_size: 1198, by_category: {vulnerability_mining: 60, llm_security: 40, other: 23}, by_year: {2024: 90, 2023: 33}, by_section: {Abstract: 12, Method: 40, Conclusion: 18} }6.3 元数据结构精简后字段类型说明categorystr英文类别标识vulnerability_mining等category_cnstr中文类别名yearstr发表年份sectionstr所属章节Abstract / Method …char_countint块字符数source_filestr原始 PDF 文件名titlestr可选论文标题命中时存在7. 外部依赖与运行环境7.1 运行环境要求项目要求操作系统Windows / Linux / macOS路径分隔符已兼容Python源码语法兼容 3.8注意requirements.txt中pandas2.2.0实际需要 Python ≥ 3.9见 7.3内存随 PDF 总量线性增长建议 ≥ 4 GB磁盘输出目录需可写7.2 第三方依赖包版本用途实际调用位置PyMuPDF1.24.5PDF 文本抽取pdf_extractor.pytqdm4.66.1目录处理进度条processor.pypandas2.2.0声明但全项目未 import冗余依赖无安装pip install -r requirements.txt7.3 版本一致性说明README 标注Python 3.8但pandas2.2.0官方要求 Python ≥ 3.9。由于 pandas 实际未被使用若移除该依赖则代码在 3.8 即可运行若保留则应同步将最低版本声明修正为 3.9。8. 关键算法说明8.1 章节识别算法基于配置SECTION_HEADERS章节名 → 多别名列表构造多选正则(?m)^(别名1|别名2|…)\s*$以整行精确匹配定位章节标题。匹配点按位置排序后相邻匹配点之间的文本即一个章节。该方案零依赖、开销低但对编号章节如2. Related Work、内联标题、非英文标题识别有限。8.2 滑动窗口与重叠对每个章节独立分块若len(section) ≤ max_chunk_size整段作为单个块不再细分。否则end start chunk_size下一段起点start end - chunk_overlap。重叠区overlap使块边界处的上下文在相邻块中重复缓解语义割裂。8.3 句末对齐在理想切分点chunk_size处不强制切断而是在其 ±100 字符范围内按优先级寻找句末标点.\n最优先将end后移至句末使切块落在句子边界提升文本完整度。min_chunk_size用于防止回退后块过短。8.4 路径元数据提取将路径\\统一为/后按层遍历命中类别映射层即记录类别并取紧邻下层若为合法年份则记为年份该机制无需读取 PDF 内容即可获得领域标签是零成本元数据的关键设计。9. 部署与运行指南9.1 安装pip install -r requirements.txt9.2 基本运行# 处理整个目录默认输出到 ./outputCSV merged 模式 python process_papers.py --input ./papers # 指定输出、块大小、格式 python process_papers.py \ --input ./papers \ --output ./dify_data \ --chunk-size 800 --overlap 200 \ --format csv --csv-mode merged \ --output-name cyber_security_papers # 单文件 python process_papers.py --input ./papers/漏洞挖掘/2024/paper.pdf --single-file9.3 主要命令行参数参数默认值说明--input / -i必填输入目录或 PDF 路径--output / -ooutput输出目录--chunk-size700块大小字符--overlap150块重叠字符--formatcsvcsv/json--csv-modemergedmerged推荐/standard--single-fileFalse单文件模式--output-namedify_knowledge_base输出文件名--add-separator/--no-separator启用Dify 分隔符开关--separator见 config自定义分隔符--csv-modemergedCSV 列组织方式9.4 Dify 导入要点merged 模式上传 CSV 时在 Dify 设置分段标识符为上述分隔符可实现精准分段并保留元数据于content。推荐索引模式高质量Embedding 选支持中英文的模型。
PDF 论文处理器 — 技术报告文档
PDF 论文处理器 — 技术报告文档适用项目数据处理脚本 / Dify 知识库数据生成工具文档性质技术剖析与归档1. 文档说明本文档覆盖以下内容系统总体架构与分层设计核心模块职责、关键类与关键函数数据处理全流程与数据形态演变数据输入 / 输出规范与元数据结构外部依赖与运行环境要求关键算法原理说明部署与运行指南2. 项目概述2.1 项目定位本工具是一个面向网络安全网安科研论文的领域专用 PDF 文本预处理流水线。其目标是将分散存储的英文论文 PDF转化为 Dify 知识库可直接导入的高质量数据块chunk服务于 RAG检索增强生成场景下的论文检索、研究现状总结与创新点挖掘。2.2 设计理念工具在提取 → 清洗 → 语义分块 → 元数据增强 → Dify 兼容输出的流水线中刻意融入了两类领域特征结构感知依据论文标准章节Abstract / Introduction / Method …进行分块而非无差别固定长度切分保留章节语义边界。元数据驱动从目录结构 文件名自动推断论文类别漏洞挖掘 / 漏洞修复 / LLM 安全 / 其他与发表年份并将章节、字数、来源等字段随块输出提升检索可过滤性与可追溯性。2.3 技术栈概览维度选型语言Python 3源码兼容 3.8详见 7.3PDF 抽取PyMuPDF1.24.5进度显示tqdm 4.66.1落盘格式标准库csv/json声明了 pandas 但未使用命令行标准库argparse3. 系统总体架构3.1 分层结构系统自上而下分为四层依赖方向单一上层依赖下层配置层被各层共享┌─────────────────────────────────────────────────────────────┐ │ ① 命令行入口层 process_papers.pyargparse 解析与配置改写 │ └───────────────────────────────┬─────────────────────────────┘ │ 创建并驱动 ┌───────────────────────────────▼─────────────────────────────┐ │ ② 流程编排层 PDFProcessorprocessor.py │ │ process_file / process_directory / save_results │ └───┬───────────────┬───────────────┬───────────────┬──────────┘ │ │ │ │ ┌───▼───┐ ┌──────▼─────┐ ┌──────▼─────┐ ┌──────▼─────┐ │PDFEx- │ │Semantic- │ │Metadata- │ │Output- │ │tractor│ │Chunker │ │Manager │ │Manager │ └───────┘ └────────────┘ └────────────┘ └────────────┘ │ │ │ │ └───────────────────────┬───────────────────────────────┘ ┌───────▼────────┐ │ ③ 配置层 config.py │ │ CHUNK / CLEAN / │ │ OUTPUT / CATEGORY│ │ / SECTION_HEADERS│ └─────────────────┘3.2 组件清单与职责文件核心类 / 函数职责process_papers.pymain()CLI 入口解析参数、改写全局配置、打印运行提示、驱动PDFProcessorsrc/pdf_processor/__init__.py__all__包导出统一对外暴露 5 个公共类src/pdf_processor/config.pyCHUNK_CONFIG/CLEAN_CONFIG/OUTPUT_CONFIG/CATEGORY_MAPPING/SECTION_HEADERS集中式配置字典src/pdf_processor/pdf_extractor.pyPDFExtractorPDF 文本抽取、清洗、基础元数据提取src/pdf_processor/chunker.pySemanticChunker章节识别 滑动窗口分块 句末对齐src/pdf_processor/metadata_manager.pyMetadataManager路径元数据提取、元数据精简、Dify 格式化src/pdf_processor/output_manager.pyOutputManagerCSV/JSON 落盘、统计生成与保存src/pdf_processor/processor.pyPDFProcessor串联上述四模块提供文件 / 目录级处理接口4. 核心模块详解4.1 PDFExtractorpdf_extractor.py职责打开 PDF、逐页抽取纯文本、执行清洗规则、提取基础元数据对单页异常做容错。关键方法extract_text(pdf_path) - (cleaned_text, metadata)L28 主入口。先调用_extract_metadata在文档打开态取元数据随后逐页page.get_text(text)抽取并在finally块中doc.close()确保句柄释放L70-75。单页异常被try/except捕获后跳过该页L65-68避免整篇失败。_remove_page_numbers(text, page_num)L85 用\b{page_num}\b、Page\s*{n}、page\s*{n}三种正则移除页码。_remove_headers_footers(text)L99 移除孤立数字行^\d\s*$并丢弃短于min_paragraph_length且不以大写字母开头的行。_clean_text(text)L117 标准化空白→单空格、\n{3,}→\n\n、去行首尾空格移除引用标记[\d]与年份(YYYY)。_extract_metadata(doc, pdf_path)L134 记录filename / file_path / total_pages若 PDF 元信息含title则取之否则以第一页首行长度 10–200作为标题。4.2 SemanticChunkerchunker.py职责将长文本按章节切分再对每个章节做带重叠的滑动窗口分块并尽量对齐到句子边界。关键方法chunk_text(text, metadata)L19 对外主接口。调用_identify_sections得到(section_name, section_text)列表逐章节_sliding_window_chunk为每个块补充section / chunk_id / char_count元数据。_identify_sections(text)L58 将SECTION_HEADERS中所有模式拼为(?m)^escaped\s*$的多选正则定位章节标题行按匹配位置切片得到各章节文本。若无匹配则返回单段(Full Text, text)。_sliding_window_chunk(text, section_name)L125 若整段 ≤max_chunk_size直接整体输出否则以chunk_size为步长、回退chunk_overlap作为下一段起点循环切片。_find_sentence_boundary(text, target_pos)L163 在目标位置 ±100 字符范围内按优先级.\n/!/?/./;\n/:\n向后搜索句末标点将切分点对齐到句子结束处。4.3 MetadataManagermetadata_manager.py职责元数据全生命周期管理——从路径提取、合并精简、到 Dify 格式输出。关键方法extract_from_path(file_path)L24 按/规范化路径遍历层级若某层命中CATEGORY_MAPPING则记录category / category_cn并取下一层若为合法年份2000–2030记为year目录中未取到年份时回退到文件名年份正则20\d{2}/24。enrich_metadata(chunk, pdf_metadata)L113 合并 PDF 元数据后精简为 6 个核心字段category / category_cn / year / section / char_count / source_file存在title时追加。format_for_dify(chunk, output_config)L151 按csv_mode分发到_format_standard或_format_merged并在末尾追加 Dify 分隔符。_format_standardL179三列独立metadata为 JSON 串。_format_mergedL198将metadata与source拼接到content末尾带前缀[Metadata:、[Source:再追加分隔符CSV 的metadata / source列置空。_generate_chunk_markerL231基于模板生成标记字符串主流程当前未启用。4.4 OutputManageroutput_manager.py职责落盘与统计。关键方法save_chunks(chunks, base_filename)L30按self.formatcsv/json与时间戳命名写入。_save_csvL60以utf-8-sig编码写content,metadata,source三列BOM 头便于 Excel 打开。_save_jsonL85ensure_asciiFalse美化输出。generate_statistics(chunks)L99统计总量 / 字数 / 均值 / 极值并按category / year / section三维聚合merged 模式下从content内正则回抽元数据。print_statistics/save_statistics控制台打印与 JSON 落盘。4.5 PDFProcessorprocessor.py职责组装四模块提供统一处理接口。关键方法process_file(pdf_path)L38单文件流水线——extract_from_path→extract_text→ 元数据合并 →chunk_text→ 逐块enrich_metadataformat_for_dify。process_directory(root_dir, recursive)L70os.walk收集 PDF用tqdm显示进度逐文件处理并收集失败清单最后汇总成功 / 失败 / 总块数。_find_pdf_filesL117递归或非递归收集.pdf结果排序保证可复现。save_results(chunks, output_filename)L144落盘主数据 生成 / 打印 / 保存统计。5. 数据处理流程5.1 端到端流程输入目录/文件 │ ▼ [CLI] 解析参数 → 改写全局 CHUNK_CONFIG / OUTPUT_CONFIG │ ▼ PDFProcessor.process_directory / process_file │ ├─① MetadataManager.extract_from_path │ 产出: {category, category_cn, year, source_file} (来自路径/文件名) │ ├─② PDFExtractor.extract_text │ 产出: (cleaned_text, {title, total_pages, ...}) (来自 PDF 元信息/首页) │ ├─③ 元数据合并 (base_metadata.update(pdf_metadata)) │ ├─④ SemanticChunker.chunk_text │ 产出: [{content, metadata{...section,chunk_id,char_count}}] │ ├─⑤ 逐块 MetadataManager.enrich_metadata │ 产出: 精简后 metadata (6 字段) │ ├─⑥ 逐块 MetadataManager.format_for_dify │ 产出: {content, metadata, source} (按 csv_mode 组织 分隔符) │ ▼ PDFProcessor.save_results ├─ OutputManager.save_chunks → *.csv / *.json └─ OutputManager.generate/save_statistics → *_statistics.json5.2 数据形态演变阶段数据形态关键字段原始磁盘 PDF二进制① 路径解析dictcategory, category_cn, year, source_file② 抽取清洗(str, dict)cleaned_text, title, total_pages④ 分块List[{content, metadata}]追加section, chunk_id, char_count⑥ 格式化List[{content, metadata, source}]merged 模式 metadata/source 为空串落盘CSV / JSON 文件见第 6 节6. 数据输入 / 输出规范6.1 输入规范目录模式推荐papers/ ├── 漏洞挖掘/ │ ├── 2024/ paper1.pdf, paper2.pdf │ └── 2023/ paper3.pdf ├── 漏洞修复/ │ └── 2024/ paper4.pdf ├── LLM安全/ │ └── 2024/ paper5.pdf └── 其他/ └── 2024/ paper6.pdf类别文件夹须使用约定中文名漏洞挖掘 / 漏洞修复 / LLM安全 / 其他用于自动映射英文标识。年份文件夹格式为 4 位年份缺失时回退文件名年份识别。单文件模式直接传.pdf路径并加--single-file。6.2 输出规范主数据文件列含义merged 模式standard 模式content文本 merged元数据/来源 分隔符完整拼接纯文本 分隔符metadata元数据 JSON 串空{category:...}source来源文件名空paper1.pdf统计文件*_statistics_*.json{ total_chunks: 123, total_chars: 86000, avg_chunk_size: 699, min_chunk_size: 105, max_chunk_size: 1198, by_category: {vulnerability_mining: 60, llm_security: 40, other: 23}, by_year: {2024: 90, 2023: 33}, by_section: {Abstract: 12, Method: 40, Conclusion: 18} }6.3 元数据结构精简后字段类型说明categorystr英文类别标识vulnerability_mining等category_cnstr中文类别名yearstr发表年份sectionstr所属章节Abstract / Method …char_countint块字符数source_filestr原始 PDF 文件名titlestr可选论文标题命中时存在7. 外部依赖与运行环境7.1 运行环境要求项目要求操作系统Windows / Linux / macOS路径分隔符已兼容Python源码语法兼容 3.8注意requirements.txt中pandas2.2.0实际需要 Python ≥ 3.9见 7.3内存随 PDF 总量线性增长建议 ≥ 4 GB磁盘输出目录需可写7.2 第三方依赖包版本用途实际调用位置PyMuPDF1.24.5PDF 文本抽取pdf_extractor.pytqdm4.66.1目录处理进度条processor.pypandas2.2.0声明但全项目未 import冗余依赖无安装pip install -r requirements.txt7.3 版本一致性说明README 标注Python 3.8但pandas2.2.0官方要求 Python ≥ 3.9。由于 pandas 实际未被使用若移除该依赖则代码在 3.8 即可运行若保留则应同步将最低版本声明修正为 3.9。8. 关键算法说明8.1 章节识别算法基于配置SECTION_HEADERS章节名 → 多别名列表构造多选正则(?m)^(别名1|别名2|…)\s*$以整行精确匹配定位章节标题。匹配点按位置排序后相邻匹配点之间的文本即一个章节。该方案零依赖、开销低但对编号章节如2. Related Work、内联标题、非英文标题识别有限。8.2 滑动窗口与重叠对每个章节独立分块若len(section) ≤ max_chunk_size整段作为单个块不再细分。否则end start chunk_size下一段起点start end - chunk_overlap。重叠区overlap使块边界处的上下文在相邻块中重复缓解语义割裂。8.3 句末对齐在理想切分点chunk_size处不强制切断而是在其 ±100 字符范围内按优先级寻找句末标点.\n最优先将end后移至句末使切块落在句子边界提升文本完整度。min_chunk_size用于防止回退后块过短。8.4 路径元数据提取将路径\\统一为/后按层遍历命中类别映射层即记录类别并取紧邻下层若为合法年份则记为年份该机制无需读取 PDF 内容即可获得领域标签是零成本元数据的关键设计。9. 部署与运行指南9.1 安装pip install -r requirements.txt9.2 基本运行# 处理整个目录默认输出到 ./outputCSV merged 模式 python process_papers.py --input ./papers # 指定输出、块大小、格式 python process_papers.py \ --input ./papers \ --output ./dify_data \ --chunk-size 800 --overlap 200 \ --format csv --csv-mode merged \ --output-name cyber_security_papers # 单文件 python process_papers.py --input ./papers/漏洞挖掘/2024/paper.pdf --single-file9.3 主要命令行参数参数默认值说明--input / -i必填输入目录或 PDF 路径--output / -ooutput输出目录--chunk-size700块大小字符--overlap150块重叠字符--formatcsvcsv/json--csv-modemergedmerged推荐/standard--single-fileFalse单文件模式--output-namedify_knowledge_base输出文件名--add-separator/--no-separator启用Dify 分隔符开关--separator见 config自定义分隔符--csv-modemergedCSV 列组织方式9.4 Dify 导入要点merged 模式上传 CSV 时在 Dify 设置分段标识符为上述分隔符可实现精准分段并保留元数据于content。推荐索引模式高质量Embedding 选支持中英文的模型。