feat: 添加OCR验证系统配置文件说明文档

config/README.md

@@ -0,0 +1,479 @@
+# 📋 配置文件说明
+
+本目录包含 OCR 验证系统的所有配置文件，用于管理数据源、OCR 工具参数和项目特定配置。
+
+## 📁 文件结构
+
+```
+config/
+├── global.yaml                    # 全局配置（必需）
+├── 至远彩色_2023年报.yaml         # 年报类项目配置
+├── A用户_单元格扫描流水.yaml      # 流水表格配置
+├── B用户_扫描流水.yaml            # 流水表格配置
+├── 德_内蒙古银行照.yaml           # 银行流水配置
+├── 对公_招商银行图.yaml           # 银行流水配置
+└── README.md                      # 配置文档（本文件）
+```
+
+## 🔧 配置文件类型
+
+### 1. 全局配置 (`global.yaml`)
+
+**用途**：引用所有项目特定配置文件，作为配置入口。
+
+**示例**：
+
+```yaml
+data_sources:
+  - 德_内蒙古银行照.yaml
+  - 对公_招商银行图.yaml
+  - A用户_单元格扫描流水.yaml
+  - B用户_扫描流水.yaml
+  - 至远彩色_2023年报.yaml
+```
+
+**说明**：
+- 全局配置文件仅列出需要加载的项目配置文件
+- 每个项目的具体配置在单独的 YAML 文件中
+- 系统启动时会自动加载所有引用的配置文件
+
+### 2. 项目特定配置
+
+**用途**：定义每个项目的文档信息和 OCR 工具结果路径。
+
+#### 配置结构说明
+
+```yaml
+document:
+  name: "项目名称"
+  base_dir: "/绝对路径/到/项目根目录"
+  
+  ocr_results:
+    - tool: "工具标识"
+      result_dir: "结果目录名"
+      image_dir: "图像目录路径（支持模板变量）"
+      description: "工具描述"
+      enabled: true/false
+```
+
+#### 模板变量
+
+配置文件支持以下模板变量：
+
+| 变量 | 说明 | 示例 |
+|------|------|------|
+| `{{name}}` | 项目名称（来自 `document.name`） | `"B用户_扫描流水"` |
+
+**示例**：
+```yaml
+image_dir: "paddleocr_vl_results/{{name}}"
+# 实际路径：paddleocr_vl_results/B用户_扫描流水
+```
+
+## 📝 配置参数详解
+
+### 文档配置 (`document`)
+
+| 参数 | 类型 | 必需 | 说明 | 示例 |
+|------|------|------|------|------|
+| `name` | string | ✅ | 项目名称 | `"B用户_扫描流水"` |
+| `base_dir` | string | ✅ | 项目根目录（绝对路径） | `"/Users/zhch158/workspace/data/流水分析/B用户_扫描流水"` |
+
+### OCR 结果配置 (`ocr_results`)
+
+| 参数 | 类型 | 必需 | 说明 | 示例 |
+|------|------|------|------|------|
+| `tool` | string | ✅ | OCR 工具标识 | `"ppstructv3"` / `"paddleocr_vl"` / `"mineru"` / `"dots_ocr"` |
+| `result_dir` | string | ✅ | OCR 结果目录（相对于 `base_dir`） | `"ppstructurev3_client_results"` |
+| `image_dir` | string | ✅ | 图像目录路径（支持模板变量 `{{name}}`） | `"ppstructurev3_client_results/{{name}}` |
+| `description` | string | ✅ | 工具描述 | `"PPStructV3 图片合成结果"` |
+| `enabled` | boolean | ✅ | 是否启用该数据源 | `true` / `false` |
+
+### 支持的 OCR 工具标识
+
+| 工具标识 | 工具名称 | 适用场景 |
+|---------|---------|---------|
+| `ppstructv3` | PPStructV3 | 结构化文档、表格 |
+| `paddleocr_vl` | PaddleOCR-VL | VLM 文档理解 |
+| `mineru` | MinerU | VLM 表格识别 |
+| `dots_ocr` | Dots OCR | VLM 专业识别 |
+
+**说明**：
+- `mineru` 工具标识也用于 PaddleOCR-VL、Dots OCR 等工具的合并结果
+- 当 `result_dir` 包含 `cell_bbox` 时，表示该结果已与 PaddleOCR 坐标合并
+
+## 🎯 配置示例
+
+### 示例 1：流水表格配置 (`B用户_扫描流水.yaml`)
+
+```yaml
+document:
+  name: "B用户_扫描流水"
+  base_dir: "/Users/zhch158/workspace/data/流水分析/B用户_扫描流水"
+  
+  ocr_results:
+    # PPStructV3
+    - tool: "ppstructv3"
+      result_dir: "ppstructurev3_client_results"
+      image_dir: "ppstructurev3_client_results/{{name}}"
+      description: "PPStructV3 图片合成结果"
+      enabled: true
+    
+    # PaddleOCR-VL
+    - tool: "paddleocr_vl"
+      result_dir: "paddleocr_vl_results"
+      image_dir: "paddleocr_vl_results/{{name}}"
+      description: "PaddleOCR VLM 图片合成结果"
+      enabled: true
+    
+    # PaddleOCR-VL (带 cell bbox)
+    - tool: "mineru"  # 格式同 MinerU
+      result_dir: "paddleocr_vl_results_cell_bbox"
+      image_dir: "paddleocr_vl_results/{{name}}"
+      description: "PaddleOCR VLM + PaddleOCR 坐标"
+      enabled: true
+    
+    # MinerU
+    - tool: "mineru"
+      result_dir: "mineru_vllm_results"
+      image_dir: "mineru_vllm_results/{{name}}"
+      description: "MinerU 图片合成结果"
+      enabled: true
+    
+    # MinerU (带 cell bbox)
+    - tool: "mineru"
+      result_dir: "mineru_vllm_results_cell_bbox"
+      image_dir: "mineru_vllm_results/{{name}}"
+      description: "MinerU + PaddleOCR 坐标"
+      enabled: true
+    
+    # DotsOCR
+    - tool: "dots_ocr"
+      result_dir: "dotsocr_vllm_results"
+      image_dir: "dotsocr_vllm_results/{{name}}"
+      description: "Dots OCR 图片合成结果"
+      enabled: true
+  
+    # DotsOCR (带 cell bbox)
+    - tool: "mineru"
+      result_dir: "dotsocr_vllm_results_cell_bbox"
+      image_dir: "dotsocr_vllm_results/{{name}}"
+      description: "Dots OCR + PaddleOCR 坐标"
+      enabled: true
+```
+
+**目录结构**：
+```
+/Users/zhch158/workspace/data/流水分析/B用户_扫描流水/
+├── ppstructurev3_client_results/
+│   └── B用户_扫描流水/              # {{name}} 替换后
+│       └── *.jpg
+├── paddleocr_vl_results/
+│   └── B用户_扫描流水/
+│       └── *.jpg
+├── paddleocr_vl_results_cell_bbox/
+│   └── *.json
+├── mineru_vllm_results/
+│   └── B用户_扫描流水/
+│       └── *.jpg
+├── mineru_vllm_results_cell_bbox/
+│   └── *.json
+├── dotsocr_vllm_results/
+│   └── B用户_扫描流水/
+│       └── *.jpg
+└── dotsocr_vllm_results_cell_bbox/
+    └── *.json
+```
+
+## 🛠️ 配置最佳实践
+
+### 1. 目录结构规范
+
+```
+项目根目录/
+├── data/
+│   └── 流水分析/
+│       └── B用户_扫描流水/                    # base_dir
+│           ├── ppstructurev3_client_results/  # result_dir
+│           │   ├── B用户_扫描流水/            # image_dir ({{name}})
+│           │   │   ├── page_001.jpg
+│           │   │   └── page_002.jpg
+│           │   └── *.json
+│           ├── paddleocr_vl_results/
+│           │   ├── B用户_扫描流水/
+│           │   │   └── *.jpg
+│           │   └── *.json
+│           └── mineru_vllm_results_cell_bbox/
+│               └── *.json
+└── ocr_verify/
+    └── config/
+        ├── global.yaml
+        └── B用户_扫描流水.yaml
+```
+
+### 2. 路径配置建议
+
+- **使用绝对路径**：`base_dir` 必须是绝对路径
+- **result_dir 使用相对路径**：相对于 `base_dir`
+- **image_dir 支持模板变量**：使用 `{{name}}` 引用项目名称
+- **路径分隔符**：统一使用 `/`
+
+### 3. 工具选择建议
+
+| 场景 | 推荐工具组合 | 配置示例 |
+|------|-------------|---------|
+| 财务报表 | MinerU + MinerU (cell bbox) | `tool: "mineru"` + `result_dir` 包含 `cell_bbox` |
+| 银行流水 | Dots OCR + PaddleOCR-VL | `tool: "dots_ocr"` + `tool: "paddleocr_vl"` |
+| 复杂表格 | 多工具交叉验证 | 启用所有 `enabled: true` 的工具 |
+
+### 4. 模板变量使用
+
+**支持的位置**：
+- `image_dir` 路径中
+
+**变量来源**：
+- `{{name}}`：来自 `document.name`
+
+**示例**：
+```yaml
+document:
+  name: "B用户_扫描流水"
+  
+ocr_results:
+  - image_dir: "paddleocr_vl_results/{{name}}"
+    # 实际路径：paddleocr_vl_results/B用户_扫描流水
+```
+
+### 5. 合并结果配置
+
+当使用合并工具（如 `merge_mineru_paddle_ocr.py`）生成带坐标的结果时：
+
+```yaml
+ocr_results:
+  # 原始 MinerU 结果
+  - tool: "mineru"
+    result_dir: "mineru_vllm_results"
+    image_dir: "mineru_vllm_results/{{name}}"
+    description: "MinerU 图片合成结果"
+    enabled: true
+  
+  # 合并后的结果（MinerU + PaddleOCR 坐标）
+  - tool: "mineru"
+    result_dir: "mineru_vllm_results_cell_bbox"
+    image_dir: "mineru_vllm_results/{{name}}"
+    description: "MinerU + PaddleOCR 坐标"
+    enabled: true
+```
+
+**说明**：
+- 合并结果后的`tool` 统一到**mineru**格式的工具
+- `result_dir` 使用不同的目录名（通常包含 `cell_bbox`）
+- `image_dir` 可以复用原始工具的图像路径
+
+## 🔍 添加新项目配置
+
+### 步骤 1：创建文档配置文件
+
+在 `config/` 目录下创建新的 YAML 文件，如 `新文档名.yaml`：
+
+```yaml
+document:
+  name: "新文档名"
+  base_dir: "/绝对路径/到/新项目"
+  
+  ocr_results:
+    - tool: "ppstructv3"
+      result_dir: "ppstructv3_results"
+      image_dir: "ppstructv3_results/{{name}}"
+      description: "PPStructV3 识别结果"
+      enabled: true
+    
+    - tool: "mineru"
+      result_dir: "mineru_results"
+      image_dir: "mineru_results/{{name}}"
+      description: "MinerU 识别结果"
+      enabled: true
+```
+
+### 步骤 2：在 global.yaml 中引用
+
+编辑 `global.yaml`，添加新配置文件：
+
+```yaml
+data_sources:
+  - 德_内蒙古银行照.yaml
+  - 对公_招商银行图.yaml
+  - A用户_单元格扫描流水.yaml
+  - B用户_扫描流水.yaml
+  - 至远彩色_2023年报.yaml
+  - 新文档名.yaml          # 新增
+```
+
+### 步骤 3：验证配置
+
+```bash
+# 验证 YAML 语法
+python -c "import yaml; yaml.safe_load(open('config/新文档名.yaml'))"
+
+# 启动应用测试
+python -m streamlit run streamlit_ocr_validator.py
+```
+
+## 🔧 调试配置
+
+### 验证配置文件语法
+
+```bash
+# 验证单个配置文件
+python -c "import yaml; yaml.safe_load(open('config/B用户_扫描流水.yaml'))"
+
+# 验证全局配置
+python -c "import yaml; yaml.safe_load(open('config/global.yaml'))"
+
+# 查看解析后的配置
+python -c "
+import yaml
+with open('config/B用户_扫描流水.yaml') as f:
+    config = yaml.safe_load(f)
+    print(yaml.dump(config, default_flow_style=False, allow_unicode=True))
+"
+```
+
+### 检查路径有效性
+
+```bash
+# macOS/Linux
+ls -la /Users/zhch158/workspace/data/流水分析/B用户_扫描流水
+
+# 检查结果目录
+ls -la /Users/zhch158/workspace/data/流水分析/B用户_扫描流水/ppstructurev3_client_results
+
+# 检查图像目录（替换模板变量后）
+ls -la /Users/zhch158/workspace/data/流水分析/B用户_扫描流水/ppstructurev3_client_results/B用户_扫描流水
+```
+
+## 🐛 常见问题
+
+### Q1: 配置文件不生效？
+
+**A:** 
+1. 检查 `global.yaml` 中是否正确引用了项目配置文件
+2. 确认 YAML 语法正确（缩进必须用空格，不能用 Tab）
+3. 确保配置文件在 `config/` 目录下
+4. 重启 Streamlit 应用
+
+### Q2: 找不到 OCR 输出文件？
+
+**A:** 
+- 检查 `base_dir` 路径是否正确（必须是绝对路径）
+- 检查 `result_dir` 是否存在于 `base_dir` 下
+- 确认 `image_dir` 的模板变量 `{{name}}` 是否正确替换
+- 确保目录存在且包含 JSON 和图像文件
+
+### Q3: 模板变量未替换？
+
+**A:** 
+- 确认使用了正确的模板变量语法：`{{name}}`
+- 检查 `document.name` 是否已定义
+- 查看 Streamlit 控制台的路径解析日志
+
+### Q4: 合并结果无法加载？
+
+**A:** 
+- 确认合并结果的 `result_dir` 存在
+- 检查 `tool` 标识是否正确（通常与原始工具一致）
+- 确保 `enabled: true`
+
+### Q5: enabled 参数的作用？
+
+**A:** 
+- `enabled: true`：该数据源会显示在 Streamlit 数据源列表中
+- `enabled: false`：该数据源不会加载，但配置保留（方便临时禁用）
+
+## 📚 参考资料
+
+- [主项目 README](../README.md) - 系统总览
+- [Comparator 模块文档](../comparator/README.md) - 对比算法详解
+- [Merger 模块文档](../merger/README.md) - OCR 结果合并
+- [Batch OCR 模块文档](../batch_ocr/README.md) - 批量处理工具
+
+## 📋 配置文件模板
+
+### 基础模板
+
+```yaml
+document:
+  name: "项目名称"
+  base_dir: "/绝对路径/到/项目根目录"
+  
+  ocr_results:
+    - tool: "工具标识"
+      result_dir: "结果目录名"
+      image_dir: "图像目录路径"
+      description: "工具描述"
+      enabled: true
+```
+
+### 多工具模板
+
+```yaml
+document:
+  name: "项目名称"
+  base_dir: "/绝对路径/到/项目根目录"
+  
+  ocr_results:
+    # PPStructV3
+    - tool: "ppstructv3"
+      result_dir: "ppstructv3_results"
+      image_dir: "ppstructv3_results/{{name}}"
+      description: "PPStructV3 识别结果"
+      enabled: true
+    
+    # PaddleOCR-VL
+    - tool: "paddleocr_vl"
+      result_dir: "paddleocr_vl_results"
+      image_dir: "paddleocr_vl_results/{{name}}"
+      description: "PaddleOCR-VL 识别结果"
+      enabled: true
+    
+    # MinerU
+    - tool: "mineru"
+      result_dir: "mineru_results"
+      image_dir: "mineru_results/{{name}}"
+      description: "MinerU 识别结果"
+      enabled: true
+    
+    # Dots OCR
+    - tool: "dots_ocr"
+      result_dir: "dotsocr_results"
+      image_dir: "dotsocr_results/{{name}}"
+      description: "Dots OCR 识别结果"
+      enabled: true
+```
+
+### 包含合并结果的模板
+
+```yaml
+document:
+  name: "项目名称"
+  base_dir: "/绝对路径/到/项目根目录"
+  
+  ocr_results:
+    # 原始结果
+    - tool: "mineru"
+      result_dir: "mineru_results"
+      image_dir: "mineru_results/{{name}}"
+      description: "MinerU 原始结果"
+      enabled: true
+    
+    # 合并结果（带 cell bbox）
+    - tool: "mineru"
+      result_dir: "mineru_results_cell_bbox"
+      image_dir: "mineru_results/{{name}}"
+      description: "MinerU + PaddleOCR 坐标"
+      enabled: true
+```
+
+---
+
+**最后更新**: 2025年11月7日