ocr_platform/docs/ocr_tools/universal_doc_parser/debug参数控制.md

Debug 参数控制设计文档 v2

当前实现方案（v2 - 分模块控制）

设计理念：提供全局和精细两种控制方式，命令行参数直接覆盖配置文件设置。

控制层级

命令行参数（4个独立开关）
    ↓ 调用
_apply_debug_overrides() 函数
    ↓ 直接修改
pipeline.config['xxx']['debug_options']['enabled'] = True
    ↓ 各模块读取
layout_detector / table_classifier / wired_table 等使用各自的 debug_options

---

命令行参数设计

新增 4 个 debug 参数

parser.add_argument("--debug", action="store_true",
    help="开启全局debug模式（启用所有模块的调试输出）")

parser.add_argument("--debug-layout", action="store_true",
    help="仅开启布局检测的debug输出")

parser.add_argument("--debug-table", action="store_true",
    help="仅开启表格识别的debug输出")

parser.add_argument("--debug-ocr", action="store_true",
    help="仅开启OCR识别的debug输出")

使用示例

# 1. 全局 debug（开发阶段完整调试）
python main_v2.py -i test.pdf -c config.yaml --debug

# 2. 定位布局问题（只看 layout 输出）
python main_v2.py -i test.pdf -c config.yaml --debug-layout

# 3. 定位表格问题（只看 table 输出）
python main_v2.py -i test.pdf -c config.yaml --debug-table

# 4. 组合使用（layout + table，不包括OCR）
python main_v2.py -i test.pdf -c config.yaml --debug-layout --debug-table

# 5. 正常运行（无 debug 输出）
python main_v2.py -i test.pdf -c config.yaml

---

核心实现：_apply_debug_overrides() 函数

函数签名

def _apply_debug_overrides(
    pipeline,
    debug: bool,
    debug_layout: bool,
    debug_table: bool,
    debug_ocr: bool,
    output_config: dict
):

覆盖逻辑

# 1. 确定需要启用哪些模块的 debug
enable_layout_debug = debug or debug_layout
enable_table_debug = debug or debug_table
enable_ocr_debug = debug or debug_ocr

# 2. 更新 pipeline 全局状态
if debug or debug_layout or debug_table or debug_ocr:
    pipeline.debug_mode = True
    output_config['debug_mode'] = True

# 3. 直接修改配置文件中的 debug_options.enabled
if enable_layout_debug:
    config['layout_detection']['debug_options']['enabled'] = True

if enable_table_debug:
    config['table_classification']['debug_options']['enabled'] = True
    config['table_recognition_wired']['debug_options']['enabled'] = True

if enable_ocr_debug:
    config['ocr_recognition']['debug_options']['enabled'] = True

优先级规则

条件	结果
命令行无任何 debug 参数	使用配置文件默认值（通常为 false）
命令行有 --debug	所有模块 debug 启用
命令行有 --debug-layout	仅布局检测 debug 启用
命令行有 --debug-table	仅表格相关 debug 启用
命令行有 --debug-layout --debug-table	布局+表格 debug 启用，OCR 不启用

---

YAML 配置文件规范

推荐配置（enabled 默认 false）

各模块的 debug_options 只描述"调试时保存什么内容"，enabled 字段默认为 false，由命令行参数动态控制：

# ✅ 推荐：enabled: false，由命令行控制
layout_detection:
  debug_options:
    enabled: false              # 默认关闭，--debug 或 --debug-layout 时启用
    output_dir: null            # null = 跟随主输出目录
    prefix: ""                  # 文件名前缀

table_classification:
  debug_options:
    enabled: false              # 默认关闭，--debug 或 --debug-table 时启用
    output_dir: null
    save_table_lines: true      # 描述保存哪些内容
    image_format: "png"
    prefix: ""

table_recognition_wired:
  debug_options:
    enabled: false              # 默认关闭，--debug 或 --debug-table 时启用
    output_dir: null
    save_table_lines: true
    save_connected_components: true
    save_grid_structure: true
    save_text_overlay: true
    image_format: "png"
    prefix: ""

❌ 不推荐的配置

# ❌ enabled: true 会导致永远开启，无法被命令行关闭
table_recognition_wired:
  debug_options:
    enabled: true               # 硬编码为 true，会绕过命令行控制

---

代码修改清单

1. main_v2.py（已完成）

新增参数：

parser.add_argument("--debug", ...)
parser.add_argument("--debug-layout", ...)
parser.add_argument("--debug-table", ...)
parser.add_argument("--debug-ocr", ...)

新增函数：

def _apply_debug_overrides(pipeline, debug, debug_layout, debug_table, debug_ocr, output_config):
    # 实现配置覆盖逻辑

更新调用：

def process_single_input(..., debug, debug_layout, debug_table, debug_ocr, ...):
    pipeline = _create_pipeline(...)
    _apply_debug_overrides(pipeline, debug, debug_layout, debug_table, debug_ocr, output_config)

2. 配置文件（需要更新）

所有场景配置文件中的 debug_options.enabled 改为 false：

• bank_statement_yusys_v4.yaml
• bank_statement_yusys_v3.yaml
• bank_statement_mineru_vl.yaml
• 等其他配置文件...

---

优势对比

新方案优势（v2）

✅ 灵活性高

• 全局开关：--debug 一键全开
• 精细控制：--debug-layout 定位特定问题
• 组合使用：可以同时启用多个特定模块

✅ 实现简洁

• 无需逐层传递参数（避免穿透5层架构）
• 直接修改配置字典（一次性生效）
• 各模块独立读取（解耦合）

✅ 易于扩展

• 新增模块只需在 _apply_debug_overrides() 添加一个 if 分支
• 不需要修改处理流水线的参数传递链路

✅ 用户体验好

• 减少不必要的 debug 输出（针对性调试）
• 加快调试速度（只看关心的模块）

旧方案问题（v1）

❌ 需要逐层穿透传递 debug_mode 参数：

main_v2.py → pipeline → _process_all_elements → element_processors → 各子模块

❌ 参数传递链路长，容易在某一层断裂

❌ 只有全局开关，无法精细控制

---

Debug 输出内容

布局检测 debug（--debug-layout）

输出文件：

• {basename}_page_{n}_layout.png - 布局检测框可视化

表格识别 debug（--debug-table）

表格分类：

• {basename}_page_{n}_table_{i}_classification.png - 有线/无线分类结果

有线表格识别：

• {basename}_page_{n}_table_{i}_lines.png - UNet 表格线检测
• {basename}_page_{n}_table_{i}_cells.png - 单元格连通域
• {basename}_page_{n}_table_{i}_grid.png - 逻辑网格结构
• {basename}_page_{n}_table_{i}_text_overlay.png - 文本填充结果

OCR 识别 debug（--debug-ocr）

输出文件：

• {basename}_page_{n}_ocr.png - OCR 检测框和识别结果

---

与日志系统的关系

Debug 输出 和 日志级别 是两个独立维度：

参数	控制内容	输出位置
--debug 系列	可视化图片输出	文件系统（output_dir）
--log_level	日志消息详细程度	控制台 / 日志文件

可以组合使用：

# 开启详细日志 + 表格 debug 图片
python main_v2.py -i test.pdf -c config.yaml --log_level DEBUG --debug-table

---

未来扩展建议

1. 支持环境变量控制

export DEBUG_LAYOUT=1
export DEBUG_TABLE=1
python main_v2.py -i test.pdf -c config.yaml

2. 支持配置文件全局 debug 开关

global:
  debug_mode: false         # 全局默认值
  debug_modules: []         # 或指定 ["layout", "table"]

3. 支持 debug 输出到独立目录

python main_v2.py -i test.pdf -c config.yaml --debug --debug-dir ./debug_output/

---

总结

当前实现（v2）的核心特点：

1. ✅ 命令行优先：--debug 参数是唯一的顶层开关
2. ✅ 直接覆盖：通过 _apply_debug_overrides() 直接修改配置字典
3. ✅ 精细控制：支持全局和分模块两种模式
4. ✅ 配置解耦：YAML 只描述"保存什么"，不控制"是否启用"
5. ✅ 易于维护：无需修改处理流水线的参数传递链路

最佳实践：

• 开发阶段：使用 --debug 全局调试
• 生产环境：不加任何 debug 参数
• 问题定位：使用 --debug-layout / --debug-table 精准排查