AI 项目目录结构管理 v2.0

适用于涉及数据清洗、分词/Tokenization、模型训练、后训练、强化学习等完整 AI 管线的项目。

🔴 文档铁律（AI 助手必须遵守）

⚠️ 这是本 skill 最重要的部分。违反任何一条都应被视为严重错误。

原则

1. 表 > 文 — 能用表格记录的，不写段落。表格可扫描、可对比、不冗余。
2. 记录决策，不写教程 — 文档回答"做了什么选择、为什么"，不写"怎么用、是什么"。
3. 一处一真理 — 同一信息绝不出现在两个文件里。信息有且仅有一个权威位置。
4. 日志即文档 — experiment_log.md 是唯一持续增长的文档。其他 README 只在结构变化时更新。
5. 写完删一半 — 写完任何文档后，删掉至少一半字数。留下的才是精华。

禁止清单

文档命名规范

✅ 好命名:
  architecture_decision_001_transformer.md  # ADR 风格
  qc_report_wikipedia_zh_2024-03-15.md      # 数据集_日期
  eval_benchmark_mmlu_v2.md                 # 主题_版本

❌ 坏命名:
  notes.md                                  # 太模糊
  final_report.md                           # 哪个 final？
  test.md                                   # 测什么？
  new_doc_v3_final_revised.md               # 💀

允许的文档类型及字数上限

超过字数上限的文档应拆分为多个文件，或用表格代替段落。

设计理念

1. 分层管理 — 数据层 / 分词层 / 模型层 各自独立，互不污染
2. 多方案并行 — 每层支持多种技术方案/尝试并存，各自有独立空间
3. 来源可追溯 — 数据从哪来、经过什么处理、用到了哪个模型，全程可追踪
4. 质量可见 — 数据质量、分词效果、模型评估都有独立的记录空间
5. 文档极简 — 遵循上方🔴铁律，拒绝 AI 生成冗余文档

目录结构

\x3Cproject_name>/
├── README.md                          # 项目总览（≤300字）
├── _project_config.yaml               # 项目元信息
├── .gitignore                         # 自动生成，忽略 checkpoints/logs/数据/.env
├── scripts/                           # 管理脚本（自动复制）
│   ├── check_project.py               # 健康检查
│   ├── trace.py                       # 追踪链生成
│   ├── compare_runs.py                # 实验对比
│   └── checkpoint_mgmt.py             # Checkpoint 管理
│
├── 01_data/                           # 📊 数据层
│   ├── README.md                      # 数据来源登记表（表格，≤300字）
│   ├── 01_raw/                        # 原始数据（按来源分目录）
│   │   └── source_\x3Cname>/
│   │       ├── metadata.yaml          # 结构化元信息
│   │       └── data/
│   ├── 02_qc/                         # 质量控制
│   │   ├── scripts/                   # QC 脚本
│   │   ├── reports/                   # QC 报告（命名: qc_report_\x3Cdataset>_YYYY-MM-DD.md）
│   │   └── cleaned/                   # 清洗后数据
│   ├── 03_processed/                  # 处理后
│   │   ├── text/
│   │   ├── image/
│   │   ├── audio/
│   │   └── multimodal/                # 多模态细化
│   │       ├── image_text/
│   │       ├── video_text/
│   │       ├── audio_text/
│   │       └── interleaved/
│   └── 04_quality_log.md              # 数据质量追踪日志（表格追加）
│
├── 02_tokenization/                   # 🔤 分词层
│   ├── README.md                      # 分词策略总览（表格，≤300字）
│   ├── 01_existing/                   # 现成 tokenizer
│   │   └── \x3Ctokenizer_name>/
│   │       ├── config.yaml
│   │       └── notes.md               # 选用理由（≤150字）
│   ├── 02_custom/                     # 自制
│   │   └── \x3Capproach_name>/
│   │       ├── README.md              # 方案说明（≤200字）
│   │       ├── scripts/
│   │       ├── configs/
│   │       ├── vocab_output/
│   │       └── eval.md                # 评估结果（表格，≤500字）
│   ├── 03_training/                   # token 相关训练
│   ├── 04_evaluation/                 # 内在 + 下游评估
│   │   ├── intrinsic/
│   │   └── extrinsic/
│   └── 05_generated/                  # 分词产生的新数据记录
│
├── 03_models/                         # 🧠 模型层
│   ├── README.md                      # 架构选型决策（表格，≤300字）
│   ├── 01_pretraining/
│   │   └── \x3Carch_name>/\x3Crun_name>/
│   │       ├── configs/               # 训练配置
│   │       ├── scripts/               # 训练脚本
│   │       ├── checkpoints/           # gitignored
│   │       ├── logs/                  # gitignored
│   │       └── eval/
│   ├── 02_post_training/
│   │   ├── sft/                       # 监督微调
│   │   ├── dpo/                       # DPO
│   │   ├── orpo/                      # ORPO
│   │   ├── kto/                       # KTO
│   │   ├── simpo/                     # SimPO
│   │   └── rlhf/                      # RLHF 流程
│   ├── 03_rl/
│   │   ├── ppo/
│   │   ├── grpo/
│   │   └── reward_models/
│   ├── 04_evaluation/
│   │   ├── benchmarks/
│   │   └── reports/
│   └── 05_deployment/
│
├── 04_experiments/                    # 🔬 实验管理
│   ├── experiment_log.md              # 时间线日志（唯一可无限增长的文件）
│   └── runs/
│
├── 05_docs/                           # 📚 文档（严格遵守铁律）
│   ├── design/                        # 架构决策记录（ADR 风格）
│   ├── meetings/                      # 会议记录（命名: meeting_YYYY-MM-DD_主题.md）
│   └── references/                    # 外部参考文献
│
└── 06_shared/                         # 🔧 共享资源
    ├── scripts/                       # 通用脚本
    └── configs/
        ├── training/                  # DeepSpeed/LoRA/QLoRA/WandB 模板
        ├── data/                      # 数据处理配置模板
        └── deployment/                # 部署配置模板

🛠 管理工具

新建项目

python3 init_ai_project.py --name "MyLLM" [--output /path/to/parent]

自动生成：完整目录 + 各层 README 模板 + .gitignore + 5 个配置模板 + 管理脚本副本

添加组件

# 数据来源（自动生成 metadata.yaml）
--add-source --source \x3C名称>

# 分词方案（自动创建 scripts/configs/vocab/eval）
--add-tokenizer --approach \x3C方案名>

# 预训练运行
--add-training --arch \x3C架构> --run \x3C运行名>

# 后训练运行
--add-posttrain --method \x3Csft/dpo/orpo/kto/simpo/rlhf> --run \x3C运行名>

# RL 运行
--add-rl --method \x3Cppo/grpo/...> --run \x3C运行名>

升级已有项目

python3 init_ai_project.py --name "MyLLM" --upgrade
# 补充缺失目录 + .gitignore + 配置模板 + 管理脚本

健康检查

python3 check_project.py --name "MyLLM"
# 扫描: 目录完整度 / metadata 字段 / eval 是否填写 / 日志是否更新
# 输出: 健康评分 0-100 + 具体问题清单

追踪链

python3 trace.py --name "MyLLM"                    # 全局追踪
python3 trace.py --name "MyLLM" --layer models      # 只看模型层
python3 trace.py --name "MyLLM" --full              # 含文件详情

实验对比

python3 compare_runs.py --name "MyLLM"                          # 全部对比
python3 compare_runs.py --name "MyLLM" --arch llama3             # 指定架构
python3 compare_runs.py --name "MyLLM" --stage post_training     # 只看后训练

Checkpoint 管理

python3 checkpoint_mgmt.py --name "MyLLM" list                      # 列出所有
python3 checkpoint_mgmt.py --name "MyLLM" clean --keep 3 --dry-run  # 预览清理
python3 checkpoint_mgmt.py --name "MyLLM" clean --keep 3            # 每运行保留3个最新
python3 checkpoint_mgmt.py --name "MyLLM" archive --to /backup/     # 归档
python3 checkpoint_mgmt.py --name "MyLLM" stats                     # 磁盘统计

命名规范

追踪链

每个阶段记录输入/输出依赖，形成完整链路：

source_wikipedia_zh (01_data/01_raw/)
  → qc_report_wikipedia_2024-03-15.md (01_data/02_qc/reports/)
    → bpe_v1 (02_tokenization/02_custom/)
      → eval.md 评估通过
        → llama3/baseline_v1 (03_models/01_pretraining/)
          → sft/chat_v1 (03_models/02_post_training/)
            → ppo/reward_v2 (03_models/03_rl/)

💡 运行 python3 scripts/trace.py --name \x3C项目> 自动生成追踪链。

AI 助手行为准则

使用本 skill 时，AI 助手必须:

1. 初始化项目时 — 只生成模板骨架，不填充假数据。空表格比假数据好。
2. 写 README 时 — 表格 > 列表 > 段落。默认用表格。
3. 记录实验时 — 追加到 experiment_log.md，用模板格式，不要新建文件。
4. 写评估报告时 — 数字和表格是主角，文字只是表头。
5. 不要做的事:
   • ❌ 不要创建 05_docs/ 下的随意命名的 .md 文件
   • ❌ 不要在多个 README 里重复同一段话
   • ❌ 不要写"本项目旨在..."这种水字数开头
   • ❌ 不要生成超过 300 字的 README
   • ❌ 不要用 final、new、latest、updated 命名文件