citu_vanna/docs/分步执行使用指南.md

Data Pipeline 分步执行使用指南

问题背景

在之前的版本中，分步执行脚本存在以下问题：

1. 缺少 --task-id 参数，无法自动定位到正确的任务目录
2. 需要手动指定完整的文件路径，容易出错
3. 与完整执行方式的行为不一致

解决方案

现在所有分步执行脚本都支持 --task-id 参数，当提供该参数时：

• 自动构建正确的输出目录路径（基础目录/task_id）
• 自动查找相关的输入文件
• 保持与完整执行方式的一致性
• 向后兼容原有的使用方式

使用方法

方式1：使用 task_id 参数（推荐）

# 步骤1：生成DDL和MD文件
python -m data_pipeline.ddl_generation.ddl_md_generator \
  --task-id manual_20250720_130541 \
  --db-connection "postgresql://user:pass@localhost:5432/dbname" \
  --table-list tables.txt \
  --business-context "高速公路服务区管理系统"

# 步骤2：生成Question-SQL对
python -m data_pipeline.qa_generation.qs_generator \
  --task-id manual_20250720_130541 \
  --table-list tables.txt \
  --business-context "高速公路服务区管理系统"

# 步骤3：验证和修正SQL
python -m data_pipeline.validators.sql_validate_cli \
  --task-id manual_20250720_130541 \
  --db-connection "postgresql://user:pass@localhost:5432/dbname"

# 步骤4：训练数据加载
python -m data_pipeline.trainer.run_training \
  --task-id manual_20250720_130541

方式2：手动指定路径（向后兼容）

# 步骤1：生成DDL和MD文件
python -m data_pipeline.ddl_generation.ddl_md_generator \
  --db-connection "postgresql://user:pass@localhost:5432/dbname" \
  --table-list tables.txt \
  --business-context "高速公路服务区管理系统" \
  --output-dir ./data_pipeline/training_data/manual_20250720_130541

# 步骤2：生成Question-SQL对
python -m data_pipeline.qa_generation.qs_generator \
  --output-dir ./data_pipeline/training_data/manual_20250720_130541 \
  --table-list tables.txt \
  --business-context "高速公路服务区管理系统"

# 步骤3：验证和修正SQL
python -m data_pipeline.validators.sql_validate_cli \
  --db-connection "postgresql://user:pass@localhost:5432/dbname" \
  --input-file ./data_pipeline/training_data/manual_20250720_130541/highway_db_20250720_pair.json

# 步骤4：训练数据加载
python -m data_pipeline.trainer.run_training \
  --data_path ./data_pipeline/training_data/manual_20250720_130541

参数说明

共同参数

• --task-id：任务ID，当提供时会自动构建输出目录路径
• --verbose：启用详细日志输出
• --log-file：指定日志文件路径

DDL生成器 (ddl_md_generator.py)

新增参数：

• --task-id：任务ID，指定后将自动构建输出目录路径

必需参数：

• --db-connection：数据库连接字符串
• --table-list：表清单文件路径
• --business-context：业务上下文描述

可选参数：

• --output-dir：输出目录路径（当未指定task-id时必需）
• --pipeline：处理链类型（full/ddl_only/analysis_only）

QA生成器 (qs_generator.py)

新增参数：

• --task-id：任务ID，指定后将自动构建输出目录路径

必需参数：

• --table-list：表清单文件路径
• --business-context：业务上下文描述

可选参数：

• --output-dir：输出目录路径（当未指定task-id时必需）
• --db-name：数据库名称

SQL验证器 (sql_validate_cli.py)

新增参数：

• --task-id：任务ID，指定后将自动在任务目录中查找Question-SQL文件

必需参数：

• --db-connection：数据库连接字符串

可选参数：

• --input-file：输入JSON文件路径（当未指定task-id时必需）
• --output-dir：验证报告输出目录
• --disable-llm-repair：禁用LLM修复功能
• --modify-original-file：修改原始JSON文件

训练器 (run_training.py)

新增参数：

• --task-id：任务ID，指定后将自动构建训练数据目录路径

可选参数：

• --data_path：训练数据目录路径（当未指定task-id时使用）
• --backup-vector-tables：备份vector表数据
• --truncate-vector-tables：清空vector表数据

自动路径解析逻辑

当使用 --task-id 参数时，系统会：

1. 读取配置：从 data_pipeline.config.SCHEMA_TOOLS_CONFIG 读取基础目录
2. 处理相对路径：如果基础目录是相对路径，会相对于项目根目录解析
3. 构建任务目录：基础目录 + task_id
4. 自动查找文件：在任务目录中查找相关文件

例如：

• 配置基础目录：./data_pipeline/training_data/
• task_id：manual_20250720_130541
• 最终路径：/项目根目录/data_pipeline/training_data/manual_20250720_130541

文件查找规则

DDL生成器

• 输出目录：{基础目录}/{task_id}/

QA生成器

• 输入目录：{基础目录}/{task_id}/（查找.md和.ddl文件）
• 输出文件：{基础目录}/{task_id}/{db_name}_pair.json

SQL验证器

• 输入文件：自动查找 {基础目录}/{task_id}/*_pair.json（选择最新的）
• 输出目录：{基础目录}/{task_id}/

训练器

• 训练数据目录：{基础目录}/{task_id}/

错误处理

常见错误及解决方法

1. 任务目录不存在

   错误: 输出目录不存在: /path/to/task_dir
   

   解决：确保先执行DDL生成步骤，或手动创建任务目录

2. 找不到Question-SQL文件

   错误: 在任务目录中未找到Question-SQL文件 (*_pair.json)
   

   解决：确保先执行QA生成步骤

3. 表清单文件不存在

   错误: 表清单文件不存在: tables.txt
   

   解决：检查表清单文件路径，确保文件存在

最佳实践

1. 使用完整的task_id：推荐使用 manual_YYYYMMDD_HHMMSS 格式
2. 按顺序执行：确保按照 DDL生成 → QA生成 → SQL验证 → 训练加载 的顺序执行
3. 检查输出：每个步骤完成后检查输出目录中的文件
4. 使用详细日志：添加 --verbose 参数获取更多信息
5. 备份重要数据：在训练前使用 --backup-vector-tables 备份现有数据

与完整执行方式的对比

特性	完整执行	分步执行（使用task-id）
路径管理	自动创建task目录	需手动创建或从DDL步骤开始
参数传递	自动传递task_id	需手动指定task_id
错误处理	统一错误处理	每步独立处理
灵活性	较低	较高
适用场景	标准流程	调试、测试、部分重跑

示例：完整的分步执行流程

# 设置变量
TASK_ID="manual_$(date +%Y%m%d_%H%M%S)"
DB_CONN="postgresql://user:pass@localhost:5432/highway_db"
TABLE_LIST="tables.txt"
BUSINESS_CONTEXT="高速公路服务区管理系统"

echo "开始分步执行，任务ID: $TASK_ID"

# 步骤1：DDL和MD生成
echo "步骤1: 生成DDL和MD文件..."
python -m data_pipeline.ddl_generation.ddl_md_generator \
  --task-id "$TASK_ID" \
  --db-connection "$DB_CONN" \
  --table-list "$TABLE_LIST" \
  --business-context "$BUSINESS_CONTEXT" \
  --verbose

# 步骤2：Question-SQL生成
echo "步骤2: 生成Question-SQL对..."
python -m data_pipeline.qa_generation.qs_generator \
  --task-id "$TASK_ID" \
  --table-list "$TABLE_LIST" \
  --business-context "$BUSINESS_CONTEXT" \
  --verbose

# 步骤3：SQL验证
echo "步骤3: 验证SQL..."
python -m data_pipeline.validators.sql_validate_cli \
  --task-id "$TASK_ID" \
  --db-connection "$DB_CONN" \
  --verbose

# 步骤4：训练数据加载
echo "步骤4: 加载训练数据..."
python -m data_pipeline.trainer.run_training \
  --task-id "$TASK_ID" \
  --verbose

echo "分步执行完成！"

总结

通过添加 --task-id 参数，现在的分步执行方式：

• ✅ 解决了路径管理问题
• ✅ 保持了与完整执行的一致性
• ✅ 提供了更好的用户体验
• ✅ 保持了向后兼容性

推荐在调试、测试或需要重跑特定步骤时使用分步执行方式。