数据清洗 Agent

面向训练数据治理的数据清洗工作台。项目把“格式转化、格式检查、内容审查、修复候选生成”串成一个可在浏览器中操作的流程，同时保留 CLI 和可测试的 Python 模块。

GitHub 仓库信息建议

推荐仓库名：data-cleaning-agent

备选仓库名：

• dataset-cleaning-workbench
• format-layer
• data-format-audit-agent
• meta-turns-cleaning-agent

推荐仓库描述：

基于 FastAPI 的训练数据清洗工作台，支持格式转化、确定性格式检查、内容审查和修复候选生成。

推荐 topics：

data-cleaning, dataset-quality, fastapi, jsonl, format-conversion, content-audit, llm-tools, python

建议先建私有仓库。确认没有真实业务数据、模型密钥、网关地址和运行产物后，再考虑公开。

功能概览

• 格式转化：上传 CSV / XLSX / JSONL，根据目标格式、映射规则和标准样例生成目标 JSONL。
• 格式检查：对转化结果或独立文件做确定性检查，输出可自动修复数据、复核队列和格式报告。
• 内容审查：针对实体增强类训练数据做内容层预筛和可选模型复核，区分通过数据、复核队列、忽略样本和问题明细。
• 修复候选：基于内容复核队列生成修复计划、可自动修复数据和未修复复核队列。
• 运行面板：Web UI 展示当前任务、历史任务、进度、指标、日志和下载产物。

技术栈

• Python 3.11+
• FastAPI + Uvicorn
• LangGraph
• OpenAI-compatible API client
• Pytest
• 原生 HTML / CSS / JavaScript 前端

快速开始

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
python -m pytest -q

启动 Web UI：

format-layer-web

默认地址：

http://127.0.0.1:8000

如果 8000 端口被占用，可以手动指定端口：

python -m uvicorn format_layer.web_app:app --host 127.0.0.1 --port 8002

CLI 用法

项目也提供命令行入口，可直接运行结构化请求：

format-layer run --request examples/sample_request.json

如果当前 shell 的 Python 和安装包的 Python 不一致，可以使用：

python -m format_layer.cli run --request examples/sample_request.json

环境变量

模型解析、报告生成、内容复核和修复候选支持 OpenAI-compatible API。不要把密钥提交到 GitHub，建议在本机 shell、CI secrets 或部署平台中配置。

常用变量：

OPENAI_API_KEY
OPENAI_BASE_URL
FORMAT_LAYER_PARSER_MODEL
FORMAT_LAYER_PARSER_MODE=auto|openai
FORMAT_LAYER_REPORT_TIMEOUT_SECONDS
FORMAT_LAYER_REPORT_MAX_OUTPUT_TOKENS
FORMAT_LAYER_DEFAULT_OPENAI_API_KEY
FORMAT_LAYER_DEFAULT_OPENAI_BASE_URL

可以从模板开始：

Copy-Item .env.example .env

没有可用模型配置时，部分流程会退回确定性解析或确定性 Markdown 报告；需要模型判断的内容复核和修复候选会受影响。

核心流程

1. 上传源文件并填写目标格式、映射规则、标准样例。
2. 系统解析输入，生成结构化任务规格。
3. 查找 converter_registry 中可复用的转换器。
4. 运行样例测试和预览行测试。
5. 生成转化产物：clean.jsonl、rejected.jsonl、report.json、report.md。
6. 自动或手动运行格式检查，生成 format_clean.jsonl、format_report.md、review_queue.jsonl 等。
7. 可选运行内容审查，生成 content_clean.jsonl、content_review_queue.jsonl、content_report.md 等。
8. 可选基于复核队列生成修复候选，输出 content_repaired.jsonl、content_unrepaired_review_queue.jsonl 和修复报告。

主要产物

格式转化：

• clean.jsonl：转化后的数据。
• rejected.jsonl：转化失败或无法安全生成的记录。
• report.json / report.md：转化报告。

格式检查：

• format_clean.jsonl：格式检查和确定性修复后的数据。
• format_rejected.jsonl：格式层面无法通过的数据。
• format_issues.jsonl：格式问题明细。
• auto_fix_log.jsonl：自动修复日志。
• review_queue.jsonl：需要人工处理的复核队列。
• format_report.json / format_report.md：格式检查报告。

内容审查：

• content_clean.jsonl：内容审查通过的数据。
• content_ignored.jsonl：统计行等被忽略的样本。
• content_prescreen.jsonl：脚本预筛记录。
• content_model_reviews.jsonl：模型复核记录。
• content_review_queue.jsonl：需要人工复核的内容队列。
• content_issues.jsonl：内容问题明细。
• content_report.json / content_report.md：内容审查报告。

内容修复候选：

• content_repair_candidates.jsonl：修复计划和候选。
• content_repaired.jsonl：可自动修复的数据。
• content_unrepaired_review_queue.jsonl：未修复、仍需人工复核的数据。
• content_repair_report.json / content_repair_report.md：修复报告。

项目结构

format_layer/
  assemble.py          # 前端输入组装为结构化任务
  cli.py               # CLI 入口
  codegen.py           # 转换器生成与安全校验
  content_audit.py     # 内容审查与修复候选
  format_check.py      # 格式检查与确定性修复
  intent_parser.py     # 输入意图解析
  pipeline.py          # 格式转化工作流
  registry.py          # 转换器注册表
  web_app.py           # FastAPI Web 服务
  web_assets/          # 前端静态资源
  validation/          # 校验规划和校验器
converter_registry/
  conv_meta_turns_entity_template_v1/
examples/
tests/

测试

python -m pytest -q

当前测试覆盖：

• 任务组装和输入解析
• 转换器复用和生成安全校验
• 格式检查、确定性修复和复检
• Web API 流程
• 内容审查预筛、模型复核、取消和修复候选

Git 初始化和推送

第一次建仓可以这样做：

git init
git add README.md .gitignore .env.example pyproject.toml format_layer tests examples converter_registry\conv_meta_turns_entity_template_v1
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/<your-name>/data-cleaning-agent.git
git push -u origin main

如果你决定提交整个目录，也要先确认 .gitignore 已生效：

git status --ignored

不要提交以下内容：

• .env 和任何密钥文件
• runs/、web_runtime/ 运行产物
• 真实业务数据
• __pycache__/、.pytest_cache/、*.pyc
• 临时截图和本地调试文件

开发备注

• converter_registry/conv_meta_turns_entity_template_v1 是内置可复用转换器，建议提交。
• converter_registry/*_generated/ 多数是本地运行生成的转换器，默认不提交。
• Web UI 的运行目录默认在 web_runtime/，命令行示例输出默认在 runs/。
• 生产部署时建议把模型配置放到环境变量或 secrets，不要写进代码或 README。