feat: 新增MinerU处理流程图文档，详细说明Pipeline和VLM后端的处理流程及关键差异

zhch/mineru_pipeline.md

@@ -1,105 +0,0 @@
-zhch158: @workspace 根据demo/demo.py, 生成流水线执行markdown mermaid流程图，图中需要注明调用的模型以及传递的数据
-
-Workspace: 正在收集工作区信息根据 demo.py 文件，我为您生成了 MinerU 的流水线执行流程图：
-
-```mermaid
-flowchart TD
-    A[开始] --> B[读取PDF文件]
-    B --> C{选择后端类型}
-    
-    C -->|Pipeline后端| D[PDF页面范围处理<br/>convert_pdf_bytes_to_bytes_by_pypdfium2]
-    C -->|VLM后端| N[PDF页面范围处理<br/>convert_pdf_bytes_to_bytes_by_pypdfium2]
-    
-    D --> E[PDF文档分析<br/>pipeline_doc_analyze]
-    E --> F[获取推理结果、图像列表、PDF文档、语言列表、OCR开关列表]
-    
-    F --> G[遍历每个PDF文档]
-    G --> H[创建输出目录<br/>prepare_env]
-    H --> I[创建文件写入器<br/>FileBasedDataWriter]
-    I --> J[转换为中间JSON<br/>pipeline_result_to_middle_json]
-    
-    J --> K{输出选项}
-    
-    K -->|f_draw_layout_bbox=True| L[绘制布局边界框<br/>draw_layout_bbox]
-    K -->|f_draw_span_bbox=True| M[绘制文本跨度边界框<br/>draw_span_bbox]
-    K -->|f_dump_orig_pdf=True| O[保存原始PDF文件]
-    K -->|f_dump_md=True| P[生成Markdown内容<br/>pipeline_union_make]
-    K -->|f_dump_content_list=True| Q[生成内容列表JSON<br/>MakeMode.CONTENT_LIST]
-    K -->|f_dump_middle_json=True| R[保存中间JSON文件]
-    K -->|f_dump_model_output=True| S[保存模型输出JSON文件]
-    
-    N --> T[VLM文档分析<br/>vlm_doc_analyze]
-    T --> U[获取中间JSON和推理结果]
-    U --> V[创建输出目录和文件写入器]
-    V --> W{VLM输出选项}
-    
-    W -->|f_draw_layout_bbox=True| X[绘制布局边界框]
-    W -->|f_dump_orig_pdf=True| Y[保存原始PDF文件]
-    W -->|f_dump_md=True| Z[生成Markdown内容<br/>vlm_union_make]
-    W -->|f_dump_content_list=True| AA[生成内容列表JSON]
-    W -->|f_dump_middle_json=True| BB[保存中间JSON文件]
-    W -->|f_dump_model_output=True| CC[保存模型输出TXT文件]
-    
-    L --> DD[输出完成]
-    M --> DD
-    O --> DD
-    P --> DD
-    Q --> DD
-    R --> DD
-    S --> DD
-    X --> DD
-    Y --> DD
-    Z --> DD
-    AA --> DD
-    BB --> DD
-    CC --> DD
-    
-    style A fill:#e8f5e8
-    style B fill:#e8f5e8
-    style E fill:#bbdefb
-    style T fill:#bbdefb
-    style J fill:#fff3e0
-    style P fill:#f3e5f5
-    style Z fill:#f3e5f5
-    style DD fill:#c8e6c9
-    
-    classDef process fill:#e3f2fd,stroke:#333,stroke-width:2px
-    classDef model fill:#fff3e0,stroke:#ff9800,stroke-width:2px
-    classDef output fill:#f3e5f5,stroke:#9c27b0,stroke-width:2px
-    classDef decision fill:#fff8e1,stroke:#ffc107,stroke-width:2px
-    
-    class D,H,I,V decision
-    class E,T,J model
-    class L,M,O,P,Q,R,S,X,Y,Z,AA,BB,CC output
-```
-
-这个流程图展示了 MinerU 的主要执行流程：
-
-## 主要组件说明：
-
-1. **输入处理**：
-   - 读取PDF文件并根据页面范围进行处理
-   - 支持 Pipeline 和 VLM 两种后端模式
-
-2. **Pipeline 后端流程**：
-   - 调用 `pipeline_doc_analyze` 进行文档分析
-   - 使用 `pipeline_result_to_middle_json` 转换结果
-   - 通过 `pipeline_union_make` 生成最终内容
-
-3. **VLM 后端流程**：
-   - 调用 `vlm_doc_analyze` 进行分析
-   - 使用 `vlm_union_make` 生成内容
-
-4. **输出文件类型**：
-   - Markdown文件 (`.md`)
-   - 中间JSON文件 (`_middle.json`)
-   - 模型输出文件 (`_model.json` 或 `_model_output.txt`)
-   - 内容列表文件 (`_content_list.json`)
-   - 可视化PDF文件 (`_layout.pdf`, `_span.pdf`)
-   - 原始PDF文件 (`_origin.pdf`)
-
-流程图中的颜色编码：
-- 🔵 蓝色：数据处理流程
-- 🟠 橙色：模型推理相关
-- 🟣 紫色：输出生成
-- 🟡 黄色：决策分支

zhch/mineru_处理流程.md

@@ -0,0 +1,161 @@
+正在收集工作区信息正在筛选到最相关的信息根据 demo.py 的代码分析，我来生成 MinerU 的处理流程图：
+
+## MinerU 处理流程图
+
+```mermaid
+graph TB
+    Start([开始: 输入PDF/图片文件]) --> ReadFile[read_fn: 读取文件字节]
+    ReadFile --> CheckBackend{选择后端?}
+    
+    %% Pipeline 后端流程
+    CheckBackend -->|backend=pipeline| ConvertPDF1[convert_pdf_bytes_to_bytes_by_pypdfium2<br/>转换PDF字节流]
+    ConvertPDF1 --> PipelineAnalyze[pipeline_doc_analyze<br/>批量分析文档]
+    
+    PipelineAnalyze --> CheckMethod{检查解析方法}
+    CheckMethod -->|parse_method=auto| Classify[classify模型<br/>PDF分类: txt/ocr]
+    CheckMethod -->|parse_method=txt| SetTxt[设置txt模式]
+    CheckMethod -->|parse_method=ocr| SetOcr[设置ocr模式]
+    
+    Classify --> PDFType{PDF类型?}
+    SetTxt --> LoadImages1
+    SetOcr --> LoadImages1
+    
+    PDFType -->|文字PDF txt模式| LoadImages1[load_images_from_pdf<br/>加载PDF页面图像<br/>data: images_list, pdf_doc]
+    PDFType -->|图片PDF ocr模式| LoadImages1
+    
+    LoadImages1 --> BatchInfer[batch_image_analyze<br/>批量推理]
+    
+    BatchInfer --> LayoutModel[布局检测模型<br/>MinerU Layout Detection]
+    LayoutModel --> LayoutResult[layout_det结果<br/>检测文本/表格/图片区域]
+    
+    LayoutResult --> OCRBranch{需要OCR?}
+    OCRBranch -->|txt模式: 文字PDF| ExtractText[提取嵌入文本<br/>直接读取PDF文本层]
+    OCRBranch -->|ocr模式: 图片PDF| OCRModel[OCR识别模型<br/>PaddleOCR/Surya]
+    
+    ExtractText --> MergeText[文本合并]
+    OCRModel --> OCRResult[OCR识别结果<br/>文本块坐标+内容]
+    OCRResult --> MergeText
+    
+    MergeText --> FormulaCheck{公式识别?}
+    FormulaCheck -->|formula_enable=True| FormulaModel[公式识别模型<br/>UniMERNet]
+    FormulaCheck -->|formula_enable=False| TableCheck
+    FormulaModel --> FormulaResult[公式LaTeX结果]
+    FormulaResult --> TableCheck
+    
+    TableCheck{表格识别?}
+    TableCheck -->|table_enable=True| TableModel[表格识别模型<br/>StructEqTable]
+    TableCheck -->|table_enable=False| ModelList
+    TableModel --> TableResult[表格HTML结果]
+    TableResult --> ModelList
+    
+    ModelList[生成model_list<br/>原始模型输出JSON] --> ToMiddleJson[pipeline_result_to_middle_json<br/>转换为中间JSON格式]
+    
+    ToMiddleJson --> MiddleJson[middle_json<br/>包含pdf_info数组]
+    MiddleJson --> ProcessOutput1[_process_output<br/>处理输出]
+    
+    %% VLM 后端流程
+    CheckBackend -->|backend=vlm-xxx| ConvertPDF2[convert_pdf_bytes_to_bytes_by_pypdfium2<br/>转换PDF字节流]
+    ConvertPDF2 --> VLMAnalyze[vlm_doc_analyze<br/>VLM端到端分析]
+    
+    VLMAnalyze --> CheckVLMBackend{VLM后端类型?}
+    CheckVLMBackend -->|transformers| VLMTransformers[加载本地VLM模型<br/>MinerU-VLM/MinerU2.5-2509-1.2B]
+    CheckVLMBackend -->|vllm-engine| VLMEngine[vLLM引擎<br/>本地GPU推理]
+    CheckVLMBackend -->|http-client| VLMClient[HTTP客户端<br/>连接远程vLLM服务器]
+    
+    VLMTransformers --> VLMInfer[VLM模型推理<br/>输入: PDF图像<br/>输出: 结构化JSON]
+    VLMEngine --> VLMInfer
+    VLMClient --> HTTPRequest[发送HTTP请求<br/>server_url]
+    HTTPRequest --> VLMInfer
+    
+    VLMInfer --> VLMResult[VLM输出结果<br/>直接生成结构化内容]
+    VLMResult --> VLMMiddleJson[result_to_middle_json<br/>转换为middle_json格式]
+    VLMMiddleJson --> ProcessOutput2[_process_output<br/>处理输出]
+    
+    %% 输出处理流程
+    ProcessOutput1 --> DrawLayout{绘制布局框?}
+    ProcessOutput2 --> DrawLayout
+    
+    DrawLayout -->|f_draw_layout_bbox=True| DrawLayoutPDF[draw_layout_bbox<br/>生成layout.pdf]
+    DrawLayout -->|False| DrawSpan
+    DrawLayoutPDF --> DrawSpan
+    
+    DrawSpan{绘制span框?}
+    DrawSpan -->|f_draw_span_bbox=True| DrawSpanPDF[draw_span_bbox<br/>生成span.pdf]
+    DrawSpan -->|False| MakeMarkdown
+    DrawSpanPDF --> MakeMarkdown
+    
+    MakeMarkdown{生成Markdown?}
+    MakeMarkdown -->|f_dump_md=True| UnionMake1[pipeline_union_make 或<br/>vlm_union_make]
+    MakeMarkdown -->|False| ContentList
+    
+    UnionMake1 --> MarkdownFile[输出: xxx.md<br/>包含文本/公式/表格/图片]
+    MarkdownFile --> ContentList
+    
+    ContentList{生成内容列表?}
+    ContentList -->|f_dump_content_list=True| UnionMake2[union_make<br/>MakeMode.CONTENT_LIST]
+    ContentList -->|False| MiddleJsonOut
+    UnionMake2 --> ContentListFile[输出: xxx_content_list.json<br/>结构化内容列表]
+    ContentListFile --> MiddleJsonOut
+    
+    MiddleJsonOut{保存中间JSON?}
+    MiddleJsonOut -->|f_dump_middle_json=True| MiddleJsonFile[输出: xxx_middle.json<br/>中间处理结果]
+    MiddleJsonOut -->|False| ModelOut
+    MiddleJsonFile --> ModelOut
+    
+    ModelOut{保存模型输出?}
+    ModelOut -->|f_dump_model_output=True| ModelFile[输出: xxx_model.json<br/>原始模型输出]
+    ModelOut -->|False| End
+    ModelFile --> End([结束: 所有文件保存到output_dir])
+    
+    %% 样式定义
+    classDef modelClass fill:#e1f5ff,stroke:#01579b,stroke-width:2px
+    classDef dataClass fill:#fff3e0,stroke:#e65100,stroke-width:2px
+    classDef processClass fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
+    
+    class LayoutModel,OCRModel,FormulaModel,TableModel,VLMTransformers,VLMEngine,Classify modelClass
+    class LayoutResult,OCRResult,FormulaResult,TableResult,ModelList,MiddleJson,VLMResult dataClass
+    class PipelineAnalyze,VLMAnalyze,ToMiddleJson,VLMMiddleJson,ProcessOutput1,ProcessOutput2 processClass
+```
+
+## 关键差异说明
+
+### 1. **文字PDF (txt模式) vs 图片PDF (ocr模式)**
+
+| 维度 | 文字PDF (txt模式) | 图片PDF (ocr模式) |
+|------|------------------|------------------|
+| **检测方式** | `classify` 模型自动判断 | 手动指定或分类识别 |
+| **文本提取** | 直接读取PDF嵌入的文本层 | 使用OCR模型识别图像中的文字 |
+| **处理速度** | 快速（无需OCR） | 较慢（需要OCR推理） |
+| **准确性** | 高（原生文本） | 取决于OCR模型质量 |
+| **典型场景** | Word转PDF、电子书 | 扫描件、截图PDF |
+
+### 2. **Pipeline vs VLM 后端差异**
+
+| 特性 | Pipeline后端 | VLM后端 |
+|------|-------------|---------|
+| **模型架构** | 多个专用模型（Layout+OCR+公式+表格） | 单一端到端VLM模型 |
+| **处理流程** | 分步骤处理，每步调用不同模型 | 一次性输出结构化结果 |
+| **优势** | 可控性强，每步可优化 | 简化流程，理解能力强 |
+| **劣势** | 流程复杂，错误累积 | 需要大模型支持 |
+| **适用场景** | 通用文档解析 | 复杂布局/多语言混排 |
+
+### 3. **关键数据流**
+
+```python
+# Pipeline模式数据流
+PDF字节流 → 图像列表(images_list) → 模型推理(model_list) → 中间JSON(middle_json) → Markdown
+
+# VLM模式数据流
+PDF字节流 → 图像列表 → VLM推理(infer_result) → 中间JSON(middle_json) → Markdown
+```
+
+### 4. **输出文件说明**
+
+- **xxx.md**: 最终Markdown文档
+- **xxx_content_list.json**: 结构化内容列表（用于程序化处理）
+- **xxx_middle.json**: 中间处理结果（包含完整的`pdf_info`数组）
+- **xxx_model.json**: 原始模型输出（用于调试）
+- **xxx_layout.pdf**: 布局可视化（标注文本/表格/图片区域）
+- **xxx_span.pdf**: span级别可视化（标注每个文本块）
+
+这个流程图清晰展示了 MinerU 如何根据不同的 PDF 类型和后端选择，采用不同的处理路径最终生成 Markdown 输出。