Analyzing Data For Cleaning

Analyzing Data for Cleaning

1 概述

使用流程： 用户上传数据文件 → 加载前5行 → LLM 智能分析生成 custom.yaml → 调用 cleaning_data.py 执行清洗 → LLM检查脚本生成的EDA报告并修复异常

核心原则： 永远不要加载整个数据集到 LLM 上下文，但必须加载前5行让 LLM 理解数据含义和业务语义。

2 快速参考

2.1 运行命令

# 优先级1：上传文件后（文件在工作目录）
python3 scripts/cleaning_data.py -c configs/custom.yaml -i 终端默认目录/数据文件名.csv

# 优先级2：指定路径
python3 scripts/cleaning_data.py -c configs/custom.yaml -i /path/to/data.csv

# 优先级3：使用 data/ 目录下的文件
python3 scripts/cleaning_data.py -c configs/custom.yaml

2.2 数据获取方式

2.3 支持的文件格式

• .csv - CSV 文件（编码 utf-8-sig）
• .xlsx / .xls - Excel 文件

3 核心流程

digraph workflow {
    "获取数据文件路径" [shape=box];
    "加载前5行样本" [shape=box];
    "转换为LLM可读格式" [shape=box];
    "LLM智能分析并生成custom.yaml" [shape=box];
    "调用cleaning_data.py" [shape=box];
    "LLM检查脚本生成的EDA报告并修复异常" [shape=box];

    "获取数据文件路径" -> "加载前5行样本";
    "加载前5行样本" -> "转换为LLM可读格式";
    "转换为LLM可读格式" -> "LLM智能分析并生成custom.yaml";
    "LLM智能分析并生成custom.yaml" -> "调用cleaning_data.py";
    "调用cleaning_data.py" -> "LLM检查EDA报告并修复异常";
}

4 第一阶段：数据准备

执行步骤

1. 定位数据文件路径 - 检查 data/ 目录或用户指定路径
2. 加载前5行样本 - 使用 pandas 读取
3. 转换为LLM可读格式 - 输出列信息（列名、类型、样本值）
4. 打印前5行完整数据

代码实现

import pandas as pd
from pathlib import Path

# 步骤1：定位数据文件路径
path = 'data/raw_data.csv'
ext = Path(path).suffix.lower()

# 步骤2：加载前5行样本
if ext == '.csv':
    df = pd.read_csv(path, encoding='utf-8-sig', nrows=5)
else:
    df = pd.read_excel(path, nrows=5)

# 步骤3：转换为LLM可读格式
print('=== 数据样本（仅前5行）===\n')
print('## 列信息 ##')
for col in df.columns:
    dtype = df[col].dtype
    non_null = df[col].dropna()
    sample = non_null.head(5).astype(str).tolist()
    print(f'- {col} ({dtype}), 样本: {sample}')

# 步骤4：打印前5行完整数据
print('\n## 前5行完整数据 ##')
print(df.head().to_string())

5 第二阶段：LLM 生成配置

5.1 LLM 智能分析维度

这是核心步骤！ 将数据样本喂给 LLM，让它基于业务语义判断核心业务规则。

让 LLM 基于以下3个维度智能判断：

⚠️ LLM 必须严格限制在上述3个维度内分析，禁止主动生成其他配置！

上述3个维度以外的配置由 cleaning_data.py 脚本自动检测和补充。

5.2 读取提示词模板

执行步骤：

1. 主动读取提示词模板 - reference/prompt_generate_config.md
2. 将数据样本喂给LLM - 传递第一阶段输出的数据样本
3. LLM基于上述3个维度分析 - 异常值范围、数值分箱、计算列

5.3 LLM 生成 custom.yaml

执行步骤：

1. 分析数据样本的列名语义和业务含义
2. 仅在5.1节规定的3个维度内生成配置
3. 输出的 YAML 仅包含：outliers.ranges、transformations.binning、transformations.computed_columns

输出示例：

# custom.yaml（精简版）
outliers:
  ranges:
    age: [0, 120]      # 年龄范围
    income: [0, null]  # 收入非负
transformations:
  binning:
    age:
      bins: [0, 18, 35, 50, 65, 120]
      labels: ["未成年", "青年", "中年", "壮年", "老年"]
  computed_columns:
    total: "price * quantity"  # 计算列

5.4 保存配置

执行步骤：

1. 使用 YAML 库保存配置
2. 确保编码为 UTF-8

import yaml
from pathlib import Path

def save_custom_config(yaml_content: str, output_path: str = "configs/custom.yaml"):
    """保存 LLM 生成的 custom.yaml"""
    config = yaml.safe_load(yaml_content)
    Path(output_path).parent.mkdir(parents=True, exist_ok=True)
    with open(output_path, 'w', encoding='utf-8') as f:
        yaml.dump(config, f, allow_unicode=True, sort_keys=False, default_flow_style=False)

# 执行保存
save_custom_config(yaml_content)

6 第三阶段：执行清洗

代码实现

# 运行清洗
python3 scripts/cleaning-data.py -c configs/custom.yaml -i data/raw_data.csv

7 第四阶段：EDA 检查与修复

执行步骤

1. 查找最新的 EDA 报告 - 匹配 data/EDA-data_*.json
2. 读取 EDA 报告内容 - 使用 json.load()
3. 主动读取提示词模板 - reference/prompt_eda_analysis.md
4. 分析以下异常并输出报告：
   • 数据类型异常（如 std 为 NaN）
   • 列数异常（如解析错误）
   • 缺失值分布
   • 异常值检测结果
   • 分类列输入变体 - 检查 categorical_distributions 中是否有低频值（如出现1次的可能是输入错误）
5. 如发现问题，更新 custom.yaml 重新运行第三阶段

代码实现

import glob
import json
from pathlib import Path

# 步骤1：查找最新的 EDA 报告
eda_files = glob.glob("data/EDA-data_*.json")
if not eda_files:
    raise FileNotFoundError("未找到 EDA 报告")
latest_file = max(eda_files, key=lambda f: Path(f).stat().st_mtime)

# 步骤2：读取 EDA 报告内容
with open(latest_file, 'r', encoding='utf-8') as f:
    eda_report = json.load(f)

# 步骤3-4：分析异常（提示词模板在 reference/prompt_eda_analysis.md）

# 步骤5：如发现问题，更新配置后重新运行第三阶段

EDA 分析报告模板

状态： 正常 / 存在问题

发现的问题

修复后的 custom.yaml 配置

format_standardization:
  numeric_columns: ["income"]  # 强制转换
  value_correction:            # 字段值纠正
    部门:
      allowed_values: [民政局, 人社局, 市场监管局, 住建局, 税务局]
      threshold: 0.6

8 常见错误

8.1 value_correction 正确格式

# 正确
value_correction:
  部门:
    allowed_values: [民政局, 人社局, 市场监管局, 住建局, 税务局]
    threshold: 0.6

原因： 函数使用模糊匹配自动纠正输入变体，依赖 allowed_values 列表找到最相似标准值。