机器学习与深度学习 / 系统课时
建立标准项目结构
建立标准项目结构
学习目标
完成本课后,你将能够:
- 规划机器学习项目的数据、源码、模型和输出目录
- 区分原始数据、处理中间数据和最终产物
- 建立可复现的依赖、配置和运行入口
推荐目录结构
一个适合入门和中小型项目的结构如下:
text
ml-project/
├── data/
│ ├── raw/
│ ├── interim/
│ └── processed/
├── notebooks/
├── src/
│ ├── __init__.py
│ ├── data.py
│ ├── features.py
│ ├── train.py
│ └── evaluate.py
├── models/
├── reports/
│ └── figures/
├── tests/
├── config.yaml
├── requirements.txt
├── .gitignore
└── README.mdraw 保存不可修改的原始数据,interim 保存处理中间结果,processed 保存可直接训练的数据。这样可以追踪每一步输入与输出。
目录职责与边界
| 目录或文件 | 职责 |
|---|---|
notebooks/ |
探索分析和实验记录 |
src/ |
可复用、可测试的正式代码 |
models/ |
训练得到的模型文件 |
reports/ |
指标、图表和分析报告 |
tests/ |
数据处理与模型逻辑测试 |
config.yaml |
路径、参数和实验配置 |
requirements.txt |
项目依赖版本 |
Notebook 中经过验证的逻辑应逐步迁移到 src/,避免生产流程依赖按顺序手动运行多个单元格。
创建项目骨架
macOS 或 Linux 可执行:
bash
mkdir -p ml-project/{data/raw,data/interim,data/processed,notebooks,src,models,reports/figures,tests}
touch ml-project/src/__init__.py ml-project/config.yaml ml-project/requirements.txt ml-project/README.md ml-project/.gitignoreWindows PowerShell 可执行:
powershell
$dirs = @(
"ml-project/data/raw",
"ml-project/data/interim",
"ml-project/data/processed",
"ml-project/notebooks",
"ml-project/src",
"ml-project/models",
"ml-project/reports/figures",
"ml-project/tests"
)
$dirs | ForEach-Object { New-Item -ItemType Directory -Force -Path $_ | Out-Null }
New-Item -ItemType File -Force -Path "ml-project/src/__init__.py", "ml-project/config.yaml", "ml-project/requirements.txt", "ml-project/README.md", "ml-project/.gitignore" | Out-Null预期结果:
text
ml-project 目录下出现数据、源码、模型、报告和测试等子目录。配置依赖与忽略规则
生成当前环境依赖清单:
bash
python -m pip freeze > requirements.txt.gitignore 可以包含:
text
.venv/
__pycache__/
.ipynb_checkpoints/
models/*.pkl
data/raw/
.env原始数据和模型是否提交版本库取决于体积、隐私和团队规则。敏感数据、密钥和访问令牌不得提交。
可复现运行入口
将训练流程收敛为一个明确入口,例如:
bash
python -m src.train运行前应能从配置文件读取路径和参数,运行后将模型写入 models/,将指标写入 reports/。判断项目结构是否合格的标准是:另一名开发者按照 README.md 可以重新创建环境并复现实验。
本课练习
- 按推荐结构创建课程项目,并说明每个数据目录的职责。
- 把 Notebook 中的一段数据清洗逻辑迁移到
src/data.py。 - 编写
README.md,包含环境创建、依赖安装和运行命令。
按自己的节奏,确认真正理解。