ocr_verify/config

📋 配置文件说明

本目录包含 OCR 验证系统的所有配置文件，用于管理数据源、OCR 工具参数和项目特定配置。

📁 文件结构

config/
├── global.yaml                    # 全局配置（必需）
├── 至远彩色_2023年报.yaml         # 年报类项目配置
├── A用户_单元格扫描流水.yaml      # 流水表格配置
├── B用户_扫描流水.yaml            # 流水表格配置
├── 德_内蒙古银行照.yaml           # 银行流水配置
├── 对公_招商银行图.yaml           # 银行流水配置
└── README.md                      # 配置文档（本文件）

🔧 配置文件类型

1. 全局配置 (global.yaml)

用途：引用所有项目特定配置文件，作为配置入口。

示例：

data_sources:
  - 德_内蒙古银行照.yaml
  - 对公_招商银行图.yaml
  - A用户_单元格扫描流水.yaml
  - B用户_扫描流水.yaml
  - 至远彩色_2023年报.yaml

说明：

• 全局配置文件仅列出需要加载的项目配置文件
• 每个项目的具体配置在单独的 YAML 文件中
• 系统启动时会自动加载所有引用的配置文件

2. 项目特定配置

用途：定义每个项目的文档信息和 OCR 工具结果路径。

配置结构说明

document:
  name: "项目名称"
  base_dir: "/绝对路径/到/项目根目录"
  
  ocr_results:
    - tool: "工具标识"
      result_dir: "结果目录名"
      image_dir: "图像目录路径（支持模板变量）"
      description: "工具描述"
      enabled: true/false

模板变量

配置文件支持以下模板变量：

变量	说明	示例
{{name}}	项目名称（来自 document.name）	"B用户_扫描流水"

示例：

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)

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

示例：

document:
  name: "B用户_扫描流水"
  
ocr_results:
  - image_dir: "paddleocr_vl_results/{{name}}"
    # 实际路径：paddleocr_vl_results/B用户_扫描流水

5. 合并结果配置

当使用合并工具（如 merge_mineru_paddle_ocr.py）生成带坐标的结果时：

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：

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，添加新配置文件：

data_sources:
  - 德_内蒙古银行照.yaml
  - 对公_招商银行图.yaml
  - A用户_单元格扫描流水.yaml
  - B用户_扫描流水.yaml
  - 至远彩色_2023年报.yaml
  - 新文档名.yaml          # 新增

步骤 3：验证配置

# 验证 YAML 语法
python -c "import yaml; yaml.safe_load(open('config/新文档名.yaml'))"

# 启动应用测试
python -m streamlit run streamlit_ocr_validator.py

🔧 调试配置

验证配置文件语法

# 验证单个配置文件
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))
"

检查路径有效性

# 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 - 系统总览
• Comparator 模块文档 - 对比算法详解
• Merger 模块文档 - OCR 结果合并
• Batch OCR 模块文档 - 批量处理工具

📋 配置文件模板

基础模板

document:
  name: "项目名称"
  base_dir: "/绝对路径/到/项目根目录"
  
  ocr_results:
    - tool: "工具标识"
      result_dir: "结果目录名"
      image_dir: "图像目录路径"
      description: "工具描述"
      enabled: true

多工具模板

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

包含合并结果的模板

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日