# 📋 配置文件说明

本目录包含 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日