编写配置文件.md

编写配置文件

配置字典

配置字典是一个字典对象，其中的每个键值对代表一个配置项。配置字典被用于训练器的构造，并在那之后成为训练器中的一个属性。从训练器构造开始，配置字典贯穿始终，可将其看做是一个保存有各种配置信息的全局对象。特别的，建造器接受配置字典为输入参数，并可以自由地读取其中的配置信息，以实现不同规格的组件构造。

例如，配置文件中定义了一个条目：

custom_item: yes

经过读取、转换后，在配置字典中将存在一个键值对 ('custom_item', 'yes')，假设配置字典为 C，可通过 C['custom_item'] 访问到值 'yes'。

修改现有配置文件

增加新的配置项

如果开发者希望新增一项新的功能，或是针对某个模型增加一个新的超参数，本项目提供增加静态配置项与增加动态配置项两种方法。关于静态配置项和动态配置项的区别可参见此处。在本文档的末尾给出了 src/train.py 可用的静态配置项的完整列表。

增加静态配置项

开发者可在 src/train.py 的 parser_configurator 函数定义中，为 parser 新增更多的命令行选项，从而添加全局配置项。添加完毕后，使用者可以在配置文件或命令行指定新的配置项。这种方法适用于添加一些不同方法、数据集间通用的配置。

增加动态配置项

开发者可在配置文件中按照 yaml 语法添加新的配置项，当配置文件被加载时，该配置项的键名和值类型将被程序自动解析，从而动态地添加到配置字典中。使用这种方法能够添加类型更复杂的配置项，但在某些场合可能无法充分利用项目提供的三级可复写配置系统。

可用的静态配置项列表

配置项名	功能	值类型	备注
cmd	指定训练器工作状态	字符串	只能为 'train' 或 'eval'
exp_config	指定配置文件路径	字符串	支持相对路径
inherit_off	禁用配置文件继承功能	布尔型
dataset	指定数据集目标名称	字符串	参考
num_workers	指定数据加载器 prefetch 所用进程数	整型	并非所有数据集都支持此配置项
repeats	指定数据集重复次数	整型	参考
subset	指定模型评估所用子集	字符串	参考
optimizer	指定优化器目标名称	字符串	参考
lr	指定学习率大小	浮点型	若指定了 sched_on 为 True， 则真实学习率大小以 schedulers 中的设置为准
weight_decay	指定权重衰减系数	浮点型
load_optim	启用从检查点中加载优化器状态功能	布尔型
save_optim	启用向检查点中存储优化器状态功能	布尔型
sched_on	启用学习率调度器	布尔型
schedulers	配置学习率调度器	字典列表	参考
batch_size	指定 mini-batch 大小	整型
num_epochs	指定训练的 epoch 数	整型
resume	指定加载的检查点路径	字符串
anew	启用从头训练功能	布尔型	参考
device	指定设备	字符串
exp_dir	指定实验目录路径	字符串
tag	指定实验标识符	字符串	一般无需手工指定，从配置文件名自动解析
suffix	指定细粒度实验标识符	字符串	一般无需手工指定，从配置文件名自动解析
debug_on	启用调试模式	布尔型	参考
log_off	禁用日志功能	布尔型
track_intvl	指定训练器存储检查点的间隔 epoch 数	整型
criterion	指定损失函数目标名称	字符串	参考
model	指定模型目标名称	字符串	参考
crop_size	指定裁块大小	整型	并非所有数据集都支持此配置项
mu	指定图像预处理均值大小	浮点型列表	参考
sigma	指定图像预处理方差大小	浮点型列表	参考
vdl_on	启用 VisualDL 日志功能	布尔型
vdl_intvl	指定 VisualDL 在训练阶段可视化非标量数据的间隔	整型
vdl_vis_bands	指定 VisualDL 可视化输入影像时使用的波段	整型列表
vdl_vis_norm	指定 VisualDL 可视化输入影像时使用的归一化方式	字符串	目前只支持 '8bit' 和 'minmax' 两种方式
suffix_off	禁用在保存图像文件名末尾添加细粒度实验标识符的功能	布尔型
save_on	启用保存输出图像功能	布尔型
out_dir	指定额外层级的输出目录名	字符串
weights	指定加权损失函数的权重	浮点型列表	并非所有损失函数都支持此配置项
out_type	指定模型输出类型	字符串	只能为 'logits'、'logits2' 或 'dist'， 参见此文档