AI项目需规范工程结构：根目录含src/、data/、models/等标准子目录；src/按data/、models/、utils/、pipeline/分包；配置用configs/分级管理；测试覆盖数据、模型、流程；日志结构化并记录Git信息。

明确项目根目录与核心模块划分

AI项目不是脚本堆砌，而是可复用、可部署的工程。根目录下应直接包含 src/（源码）、data/（原始与中间数据）、models/（训练产出与权重）、notebooks/（探索性分析）、configs/（参数与环境配置）、tests/（单元与集成测试）和 requirements.txt 或 pyproject.toml。避免把训练脚本、模型文件、配置全扔进同一层，否则三个月后自己都难定位数据预处理逻辑在哪。

src/ 内部按职责分包，拒绝单文件大杂烩

src/ 是代码主干，建议按功能切分为：

• src/data/：负责数据加载、清洗、划分、增强。含 loader.py、preprocessor.py、dataset.py
• src/models/：定义网络结构（architectures/）、训练循环（trainer.py）、评估逻辑（evaluator.py）
• src/utils/：通用工具，如日志封装、随机种子控制、路径解析、指标计算函数
• src/pipeline/：组装端到端流程，例如 train_pipeline.py 或 inference_pipeline.py，只做调度，不写业务逻辑

每个包内保留 __init__.py，对外暴露清晰接口，比如 from src.data import load_dataset, split_by_ratio，而非 from src.data.loader import load_csv。

配置与实验管理分离，支持快速复现

硬编码超参或路径是复现灾难的起点。用 configs/ 目录管理配置：

立即学习“Python免费学习笔记（深入）”；

• configs/base.yaml：通用字段（数据路径、随机种子、设备类型）
• configs/models/resnet18.yaml：模型专属参数（层数、学习率、优化器）
• configs/experiments/exp001.yaml：一次实验的完整快照（继承 base + 覆盖 model + 指定 data.version）

训练入口统一接收配置路径，如 python -m src.pipeline.train --config configs/experiments/exp001.yaml。配合 Hydra 或 OmegaConf 可自动合并层级配置，无需改代码就能切实验。

测试与日志不为形式，要嵌入开发闭环

AI项目常忽略测试，但关键环节必须覆盖：

• tests/test_data.py：验证 load_dataset() 输出 shape 和 dtype 符合预期
• tests/test_models.py：对小批量 dummy 输入，检查 forward 不报错、梯度可反传
• tests/test_pipeline.py：端到端跑通一个 mini-train 步骤，保存 checkpoint 并加载验证

日志统一用 logging 配置，输出结构化信息（时间、级别、模块名、消息），并记录配置摘要与 Git commit ID。训练中关键指标（loss、acc、lr）同步写入 logs/ 下带时间戳的子目录，方便 TensorBoard 或自定义看板读取。