DeepLearning

Structured Python package dlp consolidating experiments from Deep Learning with Python: supervised learning → regularization/generalization → functional & residual nets → computer vision (ResNet CNN) → time series forecasting → NLP/Transformer → generative models (DeepDream, Style Transfer, text generation).

目录结构 (Top-level)

MySourceCode/
  dlp/
    ├─ data/         # 文本向量化 / 序列 / 时间序列窗口 / 批处理
    ├─ models/       # 分类 / 回归 / CNN / 残差 / 序列 / Transformer / 时间序列
    ├─ training/     # 手写 & 增强训练循环 / 回调 / 自定义指标
    ├─ creative/     # Chapter 12 生成式 (DeepDream / Style / 文本生成)
    ├─ utils/        # 随机种子 / 通用工具
    └─ cli.py        # 命令行入口 (train/eval/infer)
  tests/             # 单元测试
  train.py           # 方便 python 直接调用 CLI
  CHAPTER0X_INTEGRATION.md  # 各章节整合映射（02~12）
  TEACHING_ROADMAP.md
  README_DLP_PACKAGE.md
  README.md          # (当前文件)
  pyproject.toml

模块总览 / 文件作用速查

dlp.data

文件	作用
vectorization.py	多标签 / 文本 multi-hot 与 one-hot 转换函数
batching.py	BatchGenerator 简化手写训练循环批次迭代
text_datasets.py	IMDB / Reuters multi-hot 数据加载 (bag-of-words)
text_seq.py	序列 Tokenizer、padding、IMDB 序列化加载
time_series.py	滑动窗口 window_dataset + naive_forecast_baseline 时间序列基线
__init__.py	汇总导出统一 API

dlp.models

分组	主要函数/类	说明
基础/自定义层	SimpleDense	手写 Dense 教学示例
经典 MLP	mnist_mlp, Classifier	MNIST / 通用分类 MLP
任务型示例	CustomerTicketModel	多输出示例 (章节多任务)
回归	linear_regression	Chapter 2 线性回归 (合成数据)
CNN 基础	cnn_basic	简单 Conv / Pool / Dense
正则化	mnist_baseline, mnist_l2, mnist_dropout_l2	Chapter 05 泛化对比
Functional / 残差	multi_input_concat, residual_mlp	Functional API / 简单残差 MLP
残差 CNN	conv_res_block, cnn_resnet_tiny, cnn_resnet_deeper	Chapter 09 残差堆叠示例
文本 (multi-hot)	imdb_mlp, reuters_mlp	Multi-hot 输入 MLP
序列文本 (Embedding/RNN)	embedding_average_classifier, lstm_text_classifier, bidir_gru_classifier	序列嵌入与双向循环网络
Transformer	transformer_text_classifier	简化 Transformer Encoder 分类
时间序列	dense_forecast, lstm_forecast	滑动窗口输入的单/多步预测
生成式 (Char RNN)	CharRNNGenerator (creative)	字符级语言模型+采样

符号 ↔ 源文件精确映射

符号	源文件	备注
SimpleDense	dlp/models/simple_layers.py	自定义 Dense 层实现
mnist_mlp	dlp/models/mnist.py	MNIST 全连接示例
Classifier	dlp/models/classifier.py	通用分类封装
CustomerTicketModel	dlp/models/ticket.py	多输出工单示例
linear_regression	dlp/models/linear_regression.py	合成线性数据回归
cnn_basic	dlp/models/cnn_basic.py	基础 CNN 结构
mnist_baseline	dlp/models/regularization.py	无正则基线
mnist_l2	dlp/models/regularization.py	L2 正则版本
mnist_dropout_l2	dlp/models/regularization.py	Dropout+L2
multi_input_concat	dlp/models/functional_examples.py	多输入 Functional 示例
residual_mlp	dlp/models/functional_examples.py	残差 MLP 堆叠
conv_res_block	dlp/models/cnn_residual.py	残差卷积块 (返回层函数)
cnn_resnet_tiny	dlp/models/cnn_residual.py	小型残差 CNN
cnn_resnet_deeper	dlp/models/cnn_residual.py	更深残差 CNN
imdb_mlp	dlp/models/text_models.py	IMDB multi-hot 二分类
reuters_mlp	dlp/models/text_models.py	Reuters multi-hot 多分类
embedding_average_classifier	dlp/models/text_sequence_models.py	Embedding 平均分类
lstm_text_classifier	dlp/models/text_sequence_models.py	单层 LSTM 分类
bidir_gru_classifier	dlp/models/text_sequence_models.py	双向 GRU 分类
transformer_text_classifier	dlp/models/text_sequence_models.py	简化 Transformer Encoder
dense_forecast	dlp/models/time_series.py	Dense 多步/单步预测
lstm_forecast	dlp/models/time_series.py	LSTM 多步预测
CharRNNGenerator	dlp/creative/textgen.py	字符级生成 (creative 子包)
deep_dream	dlp/creative/dream.py	DeepDream 功能
style_transfer	dlp/creative/style.py	风格迁移

汇总入口：dlp/models/__init__.py 中集中 from ... import ...；其中 dense_forecast, lstm_forecast 存在一次重复导出，可在后续清理。

dlp.creative (Chapter 12)

文件	作用
dream.py	DeepDream 多尺度特征放大 (基本版)
style.py	基于 VGG19 的内容/风格迁移 (简化)
textgen.py	字符级文本生成 RNN 封装
__init__.py	导出 deep_dream, style_transfer, CharRNNGenerator

dlp.training

文件	作用
loops.py	fit_basic (教学) 与 fit_supervised (增强指标/验证)
callbacks.py	LossHistorySimple, create_basic_callbacks, EpochJSONLLogger 等
metrics.py	自定义 RootMeanSquaredError, F1Score
__init__.py	聚合导出

dlp.utils

文件	作用
seed.py	set_seed 全局复现控制

其他关键文件

文件	作用
dlp/cli.py	子命令 train / eval / infer 参数解析与训练/推理入口
train.py	便捷脚本 (等效于 python -m dlp.cli)
CHAPTER0X_INTEGRATION.md	各章节概念 ↔ 代码实现映射与 TODO 状态
TEACHING_ROADMAP.md	阶段式教学路线与扩展规划
tests/	单元测试集，验证数据处理 / 指标 / 回调 / 模型前向
pyproject.toml	依赖、元数据、开发配置

新增重点 (相对最初版本)

主题	新增能力
正则化与泛化	L2 / Dropout 对比模型 + F1/RMSE 指标扩展
Functional / 残差	多输入拼接、Residual MLP、残差 CNN Block & 堆叠
时间序列	窗口数据集 + Naive 基线 + Dense/LSTM 预测模型
NLP 序列	Tokenizer / Padding / Embedding 平均 / LSTM / 双向 GRU / Transformer Encoder
生成式	DeepDream、Style Transfer、Char RNN 文本生成
日志与记录	JSONL Epoch 记录、history JSON、指标可扩展接口
配置化	YAML 合并策略 (配置 -> CLI 覆盖)

高阶 TODO（未完）：CLI 集成时间序列 / 序列 & 生成式命令、Attention 可视化、Seq2Seq、Top-K / Nucleus 采样、DCGAN、特征提取统一工具。

快速开始

安装（开发模式）：

pip install -e .[dev]

训练 MNIST：

dlp train --epochs 3 --evaluate-after

启用自定义 RMSE 与 TensorBoard：

dlp train --epochs 5 --with-rmse --tensorboard

添加 F1 (micro) 指标：

dlp train --epochs 3 --with-f1 --f1-average micro

启用逐 Epoch JSONL 日志：

dlp train --epochs 3 --jsonl-log

评估保存模型：

dlp eval --model-path runs/final_model.keras

也可：

python -m dlp.cli train --epochs 2
python train.py train --epochs 2

线性回归（合成数据）示例：

dlp train --model linear_regression --epochs 10 --evaluate-after

说明：该模式下 CLI 自动生成 y=3x+2+噪声 数据集，监控指标为 val_mae。 调整合成点数量：

dlp train --model linear_regression --reg-points 500 --epochs 8

推理 (回归)：

dlp infer --model-path runs/final_model_linear_regression.keras --values 0.1,0.2,0.3

推理 (分类 Top-K)：

numpy.save('sample.npy', some_flattened_28x28_arrays)
dlp infer --model-path runs/final_model_mnist_mlp.keras --input-npy sample.npy --top-k 5

原始概率张量输出加 --raw。

使用 YAML 配置 (Configuration)

支持通过全局 --config path.yaml 载入训练参数，未在 CLI 显式指定的字段由配置填充，CLI 明确给出的参数仍会覆盖配置。

示例配置 configs/mnist_baseline.yaml：

model: mnist_mlp
epochs: 3
batch_size: 128
val_split: 0.1
output_dir: runs
patience: 3
tensorboard: false
with_rmse: false
with_f1: false
f1_average: micro
reg_points: 1000
jsonl_log: false
seed: 42
no_history: false
evaluate_after: true

运行：

dlp --config configs/mnist_baseline.yaml train

覆盖部分参数：

dlp --config configs/mnist_baseline.yaml train --epochs 1 --model linear_regression

说明：--config 需放在子命令 train 前；内部合并策略为“配置先整体写入，再由后续 CLI 明确参数覆盖”。

Python API 使用

from dlp.models import mnist_mlp
from dlp.training import create_basic_callbacks
from dlp.utils import set_seed

set_seed(42)
model = mnist_mlp()
model.compile(optimizer="rmsprop", loss="sparse_categorical_crossentropy", metrics=["accuracy"])
callbacks = create_basic_callbacks(output_dir="runs", patience=2)
model.fit(x_train, y_train, validation_split=0.1, epochs=3, callbacks=callbacks)

教育版训练循环：

from dlp.training import fit_basic
model = mnist_mlp()
fit_basic(model, x_train, y_train, epochs=1)

教学路线图（概览）

阶段0 环境 & 复现基础
  - 安装 / GPU / 随机种子 set_seed

阶段1 张量 & 手写层
  - 手写 SimpleDense / 前向 / 梯度概念 (Ch02 前置)

阶段2 模型范式
  - Sequential vs Functional vs Subclassing (mnist_mlp / multi_input_concat / Classifier)

阶段3 数据表示与批处理
  - multi-hot / one-hot / 序列 tokenizer / 时间序列窗口 (Ch04, Ch10 基础数据管线)

阶段4 训练机制深入
  - GradientTape 对比 model.fit / 教学循环 fit_basic / 过拟合迹象

阶段5 泛化与正则化 (Ch05)
  - L2 / Dropout 对比基线 & 监控 train-val gap

阶段6 多任务 & 自定义结构 (Ch07 部分)
  - CustomerTicketModel 多输出 / Residual MLP / 模块化组织

阶段7 计算机视觉卷积基础 (Ch08)
  - 卷积+池化基本结构 / 数据增强 / 迁移特征提取

阶段8 残差网络深化 (Ch09)
  - 残差卷积块 / 深层堆叠 & 参数效率 / 梯度流动

阶段9 序列建模 & Transformer (Ch11)
  - Embedding 平均 / LSTM / 双向 GRU / 简化 Transformer Encoder / mask_zero

阶段10 时间序列预测 (Ch10)
  - 滑动窗口生成 / naive baseline / Dense & LSTM 多步预测 / MAE 对比

阶段11 生成式模型 (Ch12)
  - DeepDream / Style Transfer / 字符级语言模型

阶段12 工程化与实验管理
  - 包结构 / 单元测试 / 配置化 (YAML) / 日志 / 模型注册表 & 导出规划

阶段13 扩展规划
  - CLI 创意子命令 / Attention 可视化 / Seq2Seq / GAN / 实验结果聚合

完整详细路线见 TEACHING_ROADMAP.md。

核心组件映射 (精选)

能力	示例文件	抽象模块
手写层/参数	naiveclasses.py	dlp.models.simple_layers.SimpleDense
模型结构	分散脚本	dlp.models.mnist_mlp, Classifier, CustomerTicketModel
线性回归 (Chapter2)	零散示例	dlp.models.linear_regression + CLI 合成数据
数据向量化	commonMethods.vectorize_sequences	dlp.data.vectorization
批处理	batchclasses 思想	dlp.data.BacthGenerator + tf.data
训练循环	batchclasses.py	dlp.training.fit_basic / Keras fit
指标	RootMeanSquaredError_Class.py	dlp.training.metrics.RootMeanSquaredError
回调	LossHistory_Class.py	LossHistorySimple, create_basic_callbacks
复现	零散 set_seed	dlp.utils.set_seed
质量保障	无	tests/*

回调工厂

from dlp.training import create_basic_callbacks
callbacks = create_basic_callbacks(output_dir="runs", monitor="val_loss", patience=2, enable_tensorboard=True)

返回：EarlyStopping + ModelCheckpoint (+ 可选 TensorBoard) + 可附加 LossHistorySimple。

测试覆盖 (按主题分组简表)

主题	测试文件	要点
向量化 / 数据	tests/test_vectorization.py	multi-hot / one-hot 正确性
配置 / CLI	tests/test_config_yaml.py, tests/test_cli_help.py, tests/test_cli_infer.py, tests/test_cli_reg_points.py	配置合并 / help / 推理 / 合成数据点数
指标	tests/test_metric_rmse.py, tests/test_metric_f1.py	RMSE / F1 micro & macro
回调 & 日志	tests/test_callback_losshistory.py, tests/test_callback_history_json.py, tests/test_basic_callbacks_factory.py, tests/test_epoch_jsonl_logger.py	历史记录 / JSON / EarlyStopping / JSONL
基础模型	tests/test_linear_regression.py	回归收敛
CNN 基础 (Ch08)	tests/test_cnn_basic.py, tests/test_cnn_basic_train.py, tests/test_chapter08_convnet.py	前向 / 训练冒烟 / 卷积核形状 / 数据增强 / 冻结特征提取
残差 CNN (Ch09)	tests/test_cnn_residual.py	残差块投影 / deeper 结构命名 / 参数量 / 前向与训练稳定
正则化 (Ch05)	tests/test_regularization_models.py	L2 / Dropout 参数一致 & gap 对比
Functional / Residual MLP (Ch07)	tests/test_functional_examples.py	多输入拼接训练 / 残差块存在
文本 Multi‑hot (Ch04)	tests/test_text_models.py	imdb / reuters 前向 + 可学习规则收敛
序列 NLP & Transformer (Ch11)	tests/test_text_sequence.py	Tokenizer / Embedding 平均 / LSTM / BiGRU / Transformer / mask_zero / CharRNN 采样温度
时间序列 (Ch10)	tests/test_time_series.py	窗口化 shape / naive baseline / Dense & LSTM 多步 / 模型 vs baseline MAE
生成式 (Ch12)	tests/test_creative_ch12.py	DeepDream 基础 / Style Transfer mock / Char RNN 生成

说明：测试偏重教学可运行性与核心结构/行为验证（shape、loss 收敛、功能开关），未做性能回归或全量数据集验证；适合快速迭代场景。

CLI 设计与模型覆盖 (Ch02~Ch12)

当前 train 子命令统一覆盖各章节核心模型；通过 --model 选择：

章节	模型键	说明
Ch02 基础	linear_regression	合成 y=3x+2 回归 (--reg-points 控制数据量)
Ch02/通用	mnist_mlp	MNIST 全连接基线
Ch05 正则化	mnist_baseline, mnist_l2, mnist_dropout_l2	泛化策略对比
Ch07 Functional	multi_input_concat, residual_mlp	多输入拼接 / 残差 MLP
Ch08 基础 CNN	cnn_basic	简单卷积堆叠
Ch09 残差 CNN	cnn_resnet_tiny, cnn_resnet_deeper	小/深残差网络
Ch04 文本 multi-hot	imdb_mlp, reuters_mlp	IMDB 二分类 / Reuters 多分类
Ch10 时间序列	dense_forecast, lstm_forecast	滑动窗口单/多步预测 (合成正弦)
Ch11 序列 NLP	embedding_avg, lstm_text, bidir_gru, transformer_text	嵌入平均 / LSTM / 双向GRU / Transformer 分类
Ch12 生成式*	(后续)	DeepDream / Style / CharRNN 计划集成到 CLI

*生成式目前通过 Python API (dlp.creative) 使用，CLI 集成待补。

关键子命令

子命令	功能	关键参数 (核心/新增)
train	训练任一注册模型	--model / --epochs / --batch-size / --patience / --with-rmse / --with-f1 / --f1-average / --jsonl-log / --tensorboard / --seed
	线性回归特有	--reg-points
	序列 NLP	--vocab / --seq-maxlen
	时间序列	--input-width / --label-width / --horizon / --ts-length
eval	评估保存模型 (当前 MNIST 兼容路径)	--model-path
infer	推理：分类 Top-K / 回归值	--model-path / (--input-npy

后续计划：export (SavedModel)、dream/style/textgen 子命令、profile 性能基线。

使用示例 (新增场景)

时间序列 Dense 单步预测：

dlp train --model dense_forecast --epochs 5 --input-width 60 --label-width 1 --evaluate-after

时间序列多步 LSTM (预测未来 5 步)：

dlp train --model lstm_forecast --input-width 60 --label-width 5 --epochs 8

序列文本 Transformer (截断长度 200, 词表 20k)：

dlp train --model transformer_text --vocab 20000 --seq-maxlen 200 --epochs 3

IMDb multi-hot：

dlp train --model imdb_mlp --epochs 4 --with-f1

Reuters 多分类：

dlp train --model reuters_mlp --epochs 4

残差 CNN：

dlp train --model cnn_resnet_tiny --epochs 3

线性回归 (2000 点)：

dlp train --model linear_regression --reg-points 2000 --epochs 12

推理 (MNIST 分类 Top-5)：

dlp infer --model-path runs/final_model_mnist_mlp.keras --input-npy sample_mnist.npy --top-k 5

回归值序列直接输入：

dlp infer --model-path runs/final_model_linear_regression.keras --values 0.1,0.2,0.3

注意：时间序列当前使用合成正弦数据 + 简单切分；生成式模型 (DeepDream/Style/CharRNN) 通过 Python API 调用，CLI 版本将提供独立子命令与可视化输出目录。

训练产物建议结构

runs/
  2025YYMMDD_HHMMSS_best_model.keras
  final_model.keras
  history.json
  tb_<timestamp>/  # TensorBoard 日志（可选）

推荐实践任务 (节选)

任务	目标
T1 SimpleDense 增加 L2 正则	理解正则化
T2 新增 CNN 模型	扩展结构
T3 LossHistorySimple 导出 JSON	实验记录
T4 重构 notebook 为包调用	降低重复
T5 YAML 配置驱动训练	参数集中
T6 F1 / ROC-AUC 指标	评估扩展
T7 模型保存与推理脚本	生命周期

质量保证

• 运行测试：

pytest -q

• 新增功能：添加最少单元测试 & 更新 README / ROADMAP

后续扩展方向 (节选)

• 配置化训练 (YAML + dataclasses)
• 模型注册表 / 自动发现
• 训练日志统一 JSON / CSV 导出
• 指标抽象扩展 (F1, ROC-AUC, PR 曲线)
• 导出部署 (SavedModel / ONNX)
• 简易实验管理脚本 (对比多次 run)

License

本项目已采用 MIT License 开源，详见根目录 LICENSE 文件。可自由用于学习、再分发与修改，但需在副本中保留版权与许可声明。

快速 FAQ

问题	答案
为什么再写一个训练循环?	教学对照，帮助理解框架背后机制。
CLI 与脚本重复吗?	train.py 只是 CLI 便捷入口；真正逻辑在 dlp.cli。
如何增加新模型?	在 dlp/models/ 中添加并注册到 cli.py 的 MODEL_REGISTRY。
如何确保结果复现?	使用 dlp.utils.set_seed + 记录依赖版本 + 固定数据切分。

ROADMAP 详细分解 (摘录)

阶段	主题 & 目标	核心概念	对应模块 / 文件	可衡量里程碑	推荐实践 / 任务
0	环境 & 复现	venv / pip / 种子	pyproject.toml, dlp.utils.set_seed	成功跑通 dlp train --epochs 1	记录依赖版本 (pip freeze)
1	手写层/参数	权重初始化 / 前向传播	dlp.models.simple_layers.SimpleDense	自定义层与 Dense 结果一致	T1 L2 正则
2	模型范式	Sequential vs Functional vs Subclassing	dlp.models.mnist_mlp, linear_regression, cnn_basic	三种范式最小 demo	编写 Subclass 模型输出多头
3	数据表示	向量化 / multi-hot / batching	dlp.data.vectorization, dlp.data.batching.BatchGenerator	对比手写 batch vs Keras fit	扩展 BatchGenerator 支持 class weights
4	训练机制	GradientTape / 自定义循环	dlp.training.fit_basic	手写循环与 model.fit 损失走势接近	增加梯度裁剪选项
5	度量 & 回调	指标状态 / 早停 / 日志	RootMeanSquaredError, create_basic_callbacks, LossHistorySimple	早停触发 & history.json 生成	T3 导出 JSON + 可视化脚本
6	多任务 & 自定义	多输出 / 不同 loss 加权	CustomerTicketModel	成功同时收敛两个输出	增加 loss 权重 CLI 参数
7	工程化	包结构 / 测试 / CI 草稿	tests/*, pyproject.toml	覆盖率>50% & 所有测试绿	增加 GitHub Actions (T 新)
8	扩展 & 部署	配置化 / 导出 / 注册表	(待实现) config, infer, export	dlp export 子命令可产出 SavedModel	T5 YAML, T7 推理脚本
9*	进阶模型	CNN / RNN / Transformer	(计划) dlp.models.cnn_basic 等	CNN 在 MNIST >99%	T2 CNN, 新增注意力示例
10*	监控 & 追踪	实验日志 / 指标聚合	(计划) JSON/CSV logger, tensorboard	自动化对比多 run	集成简单 experiment index

注：标 * 阶段可与前面交叉进行；里程碑设计以“最小可验证成果”为准。

下一步优先级建议 (短期节选)

1. T2: cnn_basic 已添加 (Conv2D->MaxPool->Conv2D->MaxPool->Dense) + 前向/训练冒烟测试。后续可基准 3~5 epoch >99% accuracy。
2. T3: LossHistorySimple JSON + EpochJSONLLogger 已实现 (逐 epoch JSONL)。下一步：整合到 CLI 默认可选。
3. T5: YAML 配置已实现 (全局 --config)。
4. 增补 infer 子命令：加载模型 + 单样本/批量预测 (MNIST: 传入 .npy)。

规划中的新任务编号扩展

任务	描述	输出成果
T8	YAML 配置支持 (cli: --config config.yaml)	dlp/config.py + 示例 configs/mnist_baseline.yaml
T9	JSON 日志统一 (训练过程逐 epoch 追加)	runs/log_<timestamp>.jsonl
T10	推理子命令 infer	dlp cli infer --model-path ... --input ...
T11	模型导出 export (SavedModel/ONNX)	export/ 目录产物
T12	模型注册表自动发现	扫描 dlp/models 动态填充 MODEL_REGISTRY
T13	评估指标扩展 F1 / ROC-AUC	新增 dlp.training.metrics.F1Score
T14	简易实验对比脚本	统计多个 history JSON -> 表格
T15	训练过程梯度/权重统计	可视化梯度范数曲线

验收清单模板 (供后续 PR 使用)

变更类型: Feature / Fix / Docs / Refactor
涉及阶段: (勾选) 0 1 2 3 4 5 6 7 8 9 10
新增文件:
测试: [ ] 新增 / [ ] 覆盖已有
文档: README / ROADMAP / Docstring 已更新
回滚策略: (简述)

最终目标 (Vision)

形成一个“从零到部署”教学/演示路径：

1. 学习者可顺序执行阶段 0→8；
2. 每阶段具备一个最小可运行脚本或 CLI 命令；
3. 支持通过配置文件快速重现实验；
4. 提供基础导出 + 推理 + 指标扩展，利于继续迁移到生产级 MLOps。

License

This project is released under the MIT License. See the root LICENSE file for full text. You may use, modify, and redistribute with attribution and inclusion of the license notice.