From 856700fbe070bdc6f5e398ed422b429803dccba9 Mon Sep 17 00:00:00 2001 From: lanyuanxiaoyao Date: Tue, 17 Feb 2026 15:50:25 +0800 Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0=E8=A7=A3=E6=9E=90=E5=99=A8?= =?UTF-8?q?=E4=BD=BF=E7=94=A8=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- temp/scripts/README.md | 269 ++++++++++++++++++++++------------------- 1 file changed, 145 insertions(+), 124 deletions(-) diff --git a/temp/scripts/README.md b/temp/scripts/README.md index c4828f5..a2eae25 100644 --- a/temp/scripts/README.md +++ b/temp/scripts/README.md @@ -13,6 +13,8 @@ 5. **unstructured / pypdf** (成熟的 PDF 库) - PDF 专用 6. **XML 原生解析** (备选方案) - 无需依赖 +脚本会按照上述优先级依次尝试各解析器，前面的失败后自动回退到下一个，因此建议安装该文档类型对应的所有解析器依赖，以获得最佳兼容性。 + ### 特性 - 支持 DOCX、PPTX、XLSX 和 PDF 格式 @@ -38,85 +40,70 @@ scripts/ └── README.md # 本文档 ``` -## 依赖要求 +## 依赖安装 -### 基础运行（XML 解析） +脚本基于标准 Python 环境运行（Python 3.6+），使用 `pip` 安装依赖。 + +由于每种文档类型有多个解析器按优先级依次尝试，建议安装该类型对应的**所有**解析器依赖，这样当高优先级解析器失败时可以自动回退到下一个。 + +### DOCX 依赖 + +解析优先级：Docling → pypandoc-binary → MarkItDown → python-docx → XML 原生 ```bash -# Python 3.6+ -uv run parser.py file.docx +pip install docling pypandoc-binary "markitdown[docx]" python-docx ``` -### 使用 Docling（推荐） +### PPTX 依赖 + +解析优先级：Docling → MarkItDown → python-pptx → XML 原生 ```bash -# 通用解析方案，覆盖 DOCX/PPTX/XLSX/PDF -uv run --with docling parser.py file.docx -uv run --with docling parser.py file.pptx -uv run --with docling parser.py file.xlsx -uv run --with docling parser.py file.pdf +pip install docling "markitdown[pptx]" python-pptx ``` +### XLSX 依赖 + +解析优先级：Docling → MarkItDown → pandas → XML 原生 + +```bash +pip install docling "markitdown[xlsx]" pandas tabulate +``` + +### PDF 依赖 + +解析优先级：Docling → MarkItDown → unstructured → pypdf + +```bash +pip install docling "markitdown[pdf]" unstructured pypdf +``` + +### 安装所有依赖 + +如果需要处理全部文档类型，可以一次性安装所有解析器依赖： + +```bash +pip install docling pypandoc-binary "markitdown[docx,pptx,xlsx,pdf]" python-docx python-pptx pandas tabulate unstructured pypdf +``` + +> 注意：MarkItDown 需要按文档类型安装对应的可选依赖，如 `markitdown[docx]`、`markitdown[pptx]`、`markitdown[xlsx]`、`markitdown[pdf]`，直接安装 `markitdown` 不会包含任何格式的解析支持。 + +### 仅 XML 原生解析（无需安装依赖） + +如果不安装任何第三方库，脚本仍可通过内置的 XML 原生解析方式工作（DOCX/PPTX/XLSX），但输出格式和质量相对有限。 + +### Docling 说明 + - Docling 是当前的默认第一优先级解析器，单一依赖即可获得统一输出。 -- 首次运行会自动下载 OCR/视觉模型到 `uv` 缓存目录，需保持网络连通。 -- 如果只需要 Docling，可无需安装其他解析依赖，脚本会在 Docling 失败时再回退至其他方案。 - -### 使用 pypandoc-binary（DOCX） - -```bash -# 使用 uv 自动安装 -uv run --with pypandoc-binary parser.py file.docx - -# 或手动安装 -pip install pypandoc-binary -``` - -### 使用 MarkItDown - -```bash -# 使用 uv 自动安装 -uv run --with markitdown parser.py file.docx -uv run --with markitdown parser.py file.pptx -uv run --with markitdown parser.py file.xlsx -uv run --with "markitdown[pdf]" parser.py file.pdf - -# 或手动安装 -pip install markitdown -# 注意：PDF 支持需要额外安装 -pip install "markitdown[pdf]" -``` - -### 使用专用库 - -```bash -# 使用 uv 自动安装 -uv run --with python-docx parser.py file.docx -uv run --with python-pptx parser.py file.pptx -uv run --with pandas --with tabulate parser.py file.xlsx -uv run --with unstructured parser.py file.pdf -uv run --with pypdf parser.py file.pdf - -# 或手动安装 -pip install python-docx -pip install python-pptx -pip install pandas tabulate -pip install unstructured -pip install pypdf -``` - -### 所有依赖 - -```bash -# 安装所有解析库 -uv run --with docling --with pypandoc-binary --with markitdown --with python-docx --with python-pptx --with pandas --with tabulate --with unstructured --with pypdf parser.py file.pdf -``` +- 首次运行会自动下载 OCR/视觉模型到缓存目录，需保持网络连通。 +- 脚本会在 Docling 失败时自动回退至其他方案。 ## 命令行用法 ### 基本语法 ```bash -uv run parser.py [options] +python parser.py [options] ``` ### 必需参数 @@ -142,43 +129,40 @@ uv run parser.py [options] ### 1. 输出完整 Markdown 内容 ```bash -# 推荐：Docling 自动解析 -uv run --with docling parser.py report.docx -uv run --with docling parser.py report.pdf +# 解析 DOCX +python parser.py report.docx -# 使用最佳可用解析器 (DOCX/PPTX/XLSX) -uv run parser.py report.docx +# 解析 PDF +python parser.py report.pdf -# 使用最佳可用解析器 (PDF) -uv run parser.py report.pdf +# 解析 PPTX +python parser.py presentation.pptx + +# 解析 XLSX +python parser.py data.xlsx # 输出到文件 -uv run parser.py report.docx > output.md - -# 使用特定依赖 -uv run --with pypandoc-binary parser.py report.docx > output.md -uv run --with python-docx parser.py report.docx > output.md -uv run --with pypdf parser.py report.pdf > output.md +python parser.py report.docx > output.md ``` ### 2. 统计文档信息 ```bash # 统计字数 -uv run --with markitdown parser.py report.docx -c -uv run --with unstructured parser.py report.pdf -c +python parser.py report.docx -c +python parser.py report.pdf -c # 统计行数 -uv run --with markitdown parser.py report.docx -l -uv run --with pypdf parser.py report.pdf -l +python parser.py report.docx -l +python parser.py report.pdf -l ``` ### 3. 提取标题 ```bash # 提取所有标题 -uv run --with python-docx parser.py report.docx -t -uv run --with unstructured parser.py report.pdf -t +python parser.py report.docx -t +python parser.py report.pdf -t # 输出示例（DOCX）： # 第一章 概述 @@ -194,8 +178,8 @@ uv run --with unstructured parser.py report.pdf -t ```bash # 提取特定章节 -uv run --with python-docx parser.py report.docx -tc "第一章" -uv run --with unstructured parser.py report.pdf -tc "第一章" +python parser.py report.docx -tc "第一章" +python parser.py report.pdf -tc "第一章" # 输出该标题及其所有子内容 ``` @@ -204,16 +188,16 @@ uv run --with unstructured parser.py report.pdf -tc "第一章" ```bash # 搜索关键词 -uv run --with markitdown parser.py report.docx -s "测试" -uv run --with unstructured parser.py report.pdf -s "测试" +python parser.py report.docx -s "测试" +python parser.py report.pdf -s "测试" # 使用正则表达式 -uv run --with markitdown parser.py report.docx -s "章节\s+\d+" -uv run --with pypdf parser.py report.pdf -s "章节\s+\d+" +python parser.py report.docx -s "章节\s+\d+" +python parser.py report.pdf -s "章节\s+\d+" # 带上下文搜索（前后各2行） -uv run --with markitdown parser.py report.docx -s "重要内容" -n 2 -uv run --with "markitdown[pdf]" parser.py report.pdf -s "重要内容" -n 2 +python parser.py report.docx -s "重要内容" -n 2 +python parser.py report.pdf -s "重要内容" -n 2 # 输出示例： --- @@ -223,6 +207,56 @@ uv run --with "markitdown[pdf]" parser.py report.pdf -s "重要内容" -n 2 --- ``` +## 使用 uv 运行 + +如果使用 [uv](https://github.com/astral-sh/uv) 作为 Python 环境管理工具，可以通过 `uv run --with` 自动安装依赖并运行脚本，无需手动 `pip install`。 + +### 基本用法 + +```bash +# 无依赖运行（仅 XML 原生解析） +uv run parser.py file.docx + +# 指定依赖运行 +uv run --with docling parser.py file.docx +``` + +### 按文档类型运行（安装所有解析器依赖） + +```bash +# DOCX - 安装所有 DOCX 解析器 +uv run --with docling --with pypandoc-binary --with "markitdown[docx]" --with python-docx parser.py report.docx + +# PPTX - 安装所有 PPTX 解析器 +uv run --with docling --with "markitdown[pptx]" --with python-pptx parser.py presentation.pptx + +# XLSX - 安装所有 XLSX 解析器 +uv run --with docling --with "markitdown[xlsx]" --with pandas --with tabulate parser.py data.xlsx + +# PDF - 安装所有 PDF 解析器 +uv run --with docling --with "markitdown[pdf]" --with unstructured --with pypdf parser.py report.pdf +``` + +### 安装所有依赖运行 + +```bash +uv run --with docling --with pypandoc-binary --with "markitdown[docx,pptx,xlsx,pdf]" --with python-docx --with python-pptx --with pandas --with tabulate --with unstructured --with pypdf parser.py file.pdf +``` + +### 批量处理 + +```bash +# Linux/Mac +for file in *.docx; do + uv run --with docling --with pypandoc-binary --with "markitdown[docx]" --with python-docx parser.py "$file" > "${file%.docx}.md" +done + +# Windows PowerShell +Get-ChildItem *.docx | ForEach-Object { + uv run --with docling --with pypandoc-binary --with "markitdown[docx]" --with python-docx parser.py $_.FullName > ($_.BaseName + ".md") +} +``` + ## 解析器对比 ### DOCX 解析器 @@ -237,7 +271,7 @@ DOCX 文件会按以下优先级依次尝试解析： | 解析器 | 优点 | 缺点 | 适用场景 | |---------|------|--------|---------| -| **Docling** | • 单一依赖覆盖所有 Office/PDF 格式
• 自动带 OCR，复杂文档召回率高
• 输出 Markdown 结构稳定 | • 首次运行需下载较大的模型
• 运行时内存占用相对更高 | • 需要“一键完成”解析
• 需要 OCR/多模态支持 | +| **Docling** | • 单一依赖覆盖所有 Office/PDF 格式
• 自动带 OCR，复杂文档召回率高
• 输出 Markdown 结构稳定 | • 首次运行需下载较大的模型
• 运行时内存占用相对更高 | • 需要"一键完成"解析
• 需要 OCR/多模态支持 | | **pypandoc-binary** | • 自带 Pandoc，可直接使用
• 输出 Markdown 结构整洁
• 错误信息清晰易排查 | • 仅适用于 DOCX
• 依赖包体积较大 | • 需要标准化 Markdown 输出
• Docling 不可用时的首选 | | **MarkItDown** | • 格式规范
• 微软官方支持
• 兼容性好 | • 需要安装
• 输出较简洁 | • 需要标准格式输出
• 自动化文档处理 | | **python-docx** | • 输出最详细
• 保留完整结构
• 支持复杂样式 | • 需要安装
• 可能包含多余空行 | • 需要精确控制输出
• 分析文档结构 | @@ -400,6 +434,8 @@ PDF 文件会按以下优先级依次尝试解析：Docling → MarkItDown → u ``` 所有解析方法均失败: +- Docling: 库未安装 +- pypandoc-binary: 库未安装 - MarkItDown: 库未安装 - python-docx: 解析失败: ... - XML 原生解析: document.xml 不存在或无法访问 @@ -409,19 +445,12 @@ PDF 文件会按以下优先级依次尝试解析：Docling → MarkItDown → u ``` 所有解析方法均失败: +- Docling: 库未安装 - MarkItDown: MarkItDown 解析失败: ... - unstructured: unstructured 库未安装 - pypdf: pypdf 库未安装 ``` -所有解析方法均失败: - -- MarkItDown: 库未安装 -- python-docx: 解析失败: ... -- XML 原生解析: document.xml 不存在或无法访问 - -``` - ### 搜索错误 ```bash @@ -434,27 +463,17 @@ PDF 文件会按以下优先级依次尝试解析：Docling → MarkItDown → u ## 高级用法 -### 结合 uv 运行 - -```bash -# 自动安装依赖并运行 -uv run --with markitdown --with python-docx parser.py report.docx - -# 输出到文件 -uv run --with python-docx parser.py report.docx > output.md -``` - ### 批量处理 ```bash -# 使用 find 或 glob 批量处理 +# Linux/Mac for file in *.docx; do - uv run --with markitdown parser.py "$file" > "${file%.docx}.md" + python parser.py "$file" > "${file%.docx}.md" done # Windows PowerShell Get-ChildItem *.docx | ForEach-Object { - uv run --with markitdown parser.py $_.FullName > ($_.BaseName + ".md") + python parser.py $_.FullName > ($_.BaseName + ".md") } ``` @@ -462,10 +481,10 @@ Get-ChildItem *.docx | ForEach-Object { ```bash # 进一步处理 Markdown 输出 -uv run --with markitdown parser.py report.docx | grep "重要" > important.md +python parser.py report.docx | grep "重要" > important.md # 统计处理 -uv run --with markitdown parser.py report.docx -l | awk '{print $1}' +python parser.py report.docx -l | awk '{print $1}' ``` ## 常见问题 @@ -478,7 +497,7 @@ A: 不同解析器的输出详细度不同： - `MarkItDown` 输出较简洁 - `XML 原生` 输出原始内容 -如需完整内容，尝试使用专用库解析器。 +建议安装该文档类型对应的所有解析器依赖，脚本会自动按优先级选择最佳可用解析器。 ### Q: PDF 文件没有标题层级？ @@ -508,19 +527,22 @@ export LANG=en_US.UTF-8 A: 当前版本自动选择最佳可用解析器。可以通过注释代码中的解析器列表来限制，或安装/卸载特定依赖。 -### Q: MarkItDown 提示 PDF 依赖未安装？ +### Q: MarkItDown 提示依赖未安装？ -A: MarkItDown 的 PDF 支持是可选依赖，需要使用 `markitdown[pdf]` 而非 `markitdown`： +A: MarkItDown 需要按文档类型安装对应的可选依赖，直接安装 `markitdown` 不会包含任何格式支持： ```bash -# 错误 -uv run --with markitdown parser.py file.pdf +# 错误 - 不包含任何格式支持 +pip install markitdown -# 正确 -uv run --with "markitdown[pdf]" parser.py file.pdf - -# 或手动安装 +# 正确 - 按需安装对应格式 +pip install "markitdown[docx]" +pip install "markitdown[pptx]" +pip install "markitdown[xlsx]" pip install "markitdown[pdf]" + +# 或一次性安装所有格式 +pip install "markitdown[docx,pptx,xlsx,pdf]" ``` ### Q: 大文件处理慢？ @@ -593,5 +615,4 @@ A: 大文件建议使用 XML 原生解析（最快），或在脚本外部处理 - 添加 PDF 文件支持（MarkItDown、unstructured、pypdf） - 增强错误处理（文件存在性检查、无效格式检测） - 完善文档和示例 -- 使用 uv 进行依赖管理和运行 - 所有模块通过语法检查和功能测试