机器学习与深度学习 / 系统课时

建立标准项目结构

建立标准项目结构

学习目标

完成本课后,你将能够:

  • 规划机器学习项目的数据、源码、模型和输出目录
  • 区分原始数据、处理中间数据和最终产物
  • 建立可复现的依赖、配置和运行入口

推荐目录结构

一个适合入门和中小型项目的结构如下:

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.md

raw 保存不可修改的原始数据,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/.gitignore

Windows 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 可以重新创建环境并复现实验。

本课练习

  1. 按推荐结构创建课程项目,并说明每个数据目录的职责。
  2. 把 Notebook 中的一段数据清洗逻辑迁移到 src/data.py。
  3. 编写 README.md,包含环境创建、依赖安装和运行命令。
按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

建立标准项目结构

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通