企业官网建设流程全解析

• 人工智能
• 机器学习
• 深度学习
• 数据分析

BasicTS 的核心设计理念是 "All-in-configuration"（配置即一切）：一个配置类即包含执行时间序列任务所需的全部信息，用户只需聚焦模型与数据，无需手工搭建繁琐的训练流程。本文基于仓库文档 config_design.md 与 config_design_cn.md，结合 src/basicts/configs/ 下的实际源码，完整讲解 BasicTS 1.x 配置类的层级结构、各配置分区与默认值、"既是类也是字典"的双重使用方式、对象延迟构造的参数传递机制，以及配置的序列化、持久化与执行入口调用链。

设计哲学：从"py 文件 + 命令行"到"配置类"

在早期版本中，BasicTS 采用 Python 配置文件配合命令行指定配置路径的方式来组织实验。从1.0 版本开始，这一方式被彻底替换为基于配置类（configuration class）的系统（当前仓库版本为 1.1.0，见 src/basicts/__init__.py）。该设计带来三个直接收益：

1. 单一入口：一个配置类实例承载任务的全部设定，BasicTSLauncher.launch_training(cfg)只需接收这一个对象即可启动训练；
2. 类型与文档内聚：每个字段通过 dataclass 的metadata提供默认值说明与用法描述，配置本身即是文档；
3. 可序列化、可复现：配置类可整体导出为 JSON 并保存为cfg.json，同时计算内容 MD5 作为目录名，保证同配置重跑结果目录可对齐。

配置类层级：基类与四类任务配置

配置类的继承结构在 src/basicts/configs/__init__.py 中导出：

基类BasicTSConfig声明了所有子类共享的必填字段（base_config.py#L29-L44）：

@dataclass(init=False) class BasicTSConfig(EasyDict): model: type # 模型类，必须显式指定 model_config: BasicTSModelConfig # 模型参数，必须显式指定 dataset_name: str # 数据集名，必须显式指定 taskflow: "BasicTSTaskFlow" callbacks: List["BasicTSCallback"]

四个任务配置类在各自文件中以@dataclass(init=False)派生，将"执行该任务需要的一切参数"（默认数据集类型、默认评估指标、默认损失函数、taskflow类型等）内聚到子类中。例如分类任务默认指标为["Accuracy"]且best_metric="max"（tsc_config.py#L123-L135），而预测任务默认指标为["MAE", "MSE", "RMSE", "MAPE", "WAPE"]、target_metric="MAE"（tsf_config.py#L130-L142）。用户可以在这些配置类中灵活地导入任意模型类并设置所有必要选项。

各任务配置类的关键差异

从源码对比可以看出四个任务配置类在默认值上的任务特化：

此外，插补任务独有mask_ratio: float = 0.25字段（tsi_config.py#L116）；基础模型任务独有model_dtype（默认"bfloat16"）字段用于指定模型精度（tsfm_config.py#L122）。各任务类的__post_init__会在ckpt_save_dir未指定时按上述模式自动生成默认目录（如 tsf_config.py#L268-L271）。

配置分区总览与默认值

文档指出，配置类通常包含以下分区；对照 tsf_config.py 的完整实现，可以把每个分区的关键字段与默认值整理如下（以预测任务为例，默认值均以源码为准）：

常规选项（General）

环境选项（Environment）

数据集与缩放器选项（Dataset & Scaler）

模型选项（Model）

• model（模型类，必须显式指定）与model_config（模型参数，必须显式指定）是全部必填字段的核心。model_config的基类是 model_config.py 中的BasicTSModelConfig（同样继承自EasyDict），每个模型仓库内都自带一个带metadata的子类。以 iTransformer 为例（itransformer_config.py）：

@dataclass class iTransformerConfig(BasicTSModelConfig): input_len: int = field(default=None, metadata={"help": "Input sequence length."}) output_len: int = field(default=None, metadata={"help": "Output sequence length for forecasting task."}) num_features: int = field(default=None, metadata={"help": "Number of features."}) hidden_size: int = field(default=256, metadata={"help": "Hidden size."}) n_heads: int = field(default=1, metadata={"help": "Number of heads in multi-head attention."}) # ... 其余字段略

评估指标选项（Metrics）

• metrics：评估指标函数列表。字符串形式时必须在basicts.metrics模块的ALL_METRICS中；也可以传(指标名, 函数)元组来自定义；
• target_metric：用于保存最佳 checkpoint 的目标指标，必须在metrics中或为字符串"loss"；
• best_metric："min"或"max"，指明指标越小越好还是越大越好。

训练 / 验证 / 测试选项（Train / Val / Test）

• 常规：num_epochs（默认 100）/num_steps（默认None，二者只应指定其一）；loss（默认"MAE"，字符串须可被basicts.metrics解析）。
• 优化器：optimizer（默认Adam）+optimizer_params（默认{"lr": 2e-4, "weight_decay": 5e-4}）。
• 调度器：lr_scheduler（默认None）+lr_scheduler_params（默认{}）。
• 数据：batch_size或分别设置train_batch_size/val_batch_size/test_batch_size（默认均为 64），以及*_data_num_workers（默认 0）、*_data_pin_memory（默认False）、*_data_prefetch（默认False）等。
• 验证/测试频率：val_interval、test_interval（默认均为 1，即每 epoch 验证/测试一次）。
• checkpoint 相关：ckpt_save_dir（未指定时按任务默认模式生成）、ckpt_save_strategy（None/int/List[int]，控制保存节奏）、finetune_from（微调起点，默认None）、strict_load（默认True）。

每个字段都带有metadata={"help": ...}，提供默认值、详细含义与使用方法——这也是文档所说"字段 metadata 即文档"的源码落地形式（如 tsf_config.py#L83-L117）。

构造配置类：既是类，也是字典

双重身份的实现机制

BasicTS 的配置类继承自EasyDict，因此既可以作为 Python 类使用，也可以作为字典使用，方便扩展且灵活易用。这一双重身份由@dataclass(init=False)与自定义__init__共同实现，其初始化流程见 base_config.py#L170-L204：

1. 从kwargs中挑出与已声明 dataclass 字段同名的参数，逐项写入属性，并补全所有默认值 /default_factory；
2. 其余参数整体透传给EasyDict，成为字典键值——这就是"不能直接在构造方法中添加未定义字段"约束背后的机制：未定义字段不会报错，而是落入 EasyDict 的自由键空间；
3. 执行子类的__post_init__（例如生成默认ckpt_save_dir）；
4. 若设置了统一batch_size，将其同步到train_batch_size/val_batch_size/test_batch_size；
5. 调用_pack_params把"快捷字段"回填进model_config、dataset_params、optimizer_params、lr_scheduler_params；
6. 由gpus计算gpu_num。

基于此，两种使用方式都可以直接落地：

方式一：像类一样使用——一切参数都是类的字段，可以像访问类字段一样访问、修改以及添加新的参数：

model = config.model config.gpus = "0" config.new_field = new_value

方式二：像字典一样使用——一切参数都是字典的键值，可以像访问字典一样访问、修改、添加、删除参数：

model = config["model"] optimizer = config.get("optimizer", Adam) config["new_key"] = new_value config.pop("not_used")

源码中__getitem__还做了一层兼容处理（base_config.py#L210-L218）：先按属性（含md5、serialized等 property）取值，失败后再回退到字典取值，并对旧版本键名做"." -> "_"归一化，保证新旧键名混用时不致 404 式的KeyError。

配置类中的对象：延迟构造与两种传参方式

配置中存在许多需要进一步构造的对象——模型、数据集、优化器、调度器等。BasicTS 的做法是：在配置中只传入"类 + 参数"，把实际对象构造延迟到执行任务时。真正的实例化发生在 src/basicts/runners/builder.py 的Builder中，例如：

# _build_model（builder.py#L47） model = cfg.model(cfg.model_config) # _build_optimizer（builder.py#L143-L145） return cfg.optimizer(model.parameters(), **cfg.optimizer_params) # _build_lr_scheduler（builder.py#L147-L149） return cfg.lr_scheduler(optimizer, **cfg.lr_scheduler_params)

对于这类对象，BasicTS 支持两种灵活的配置方式：

方式一：将构造对象所需的全部参数以字典形式传入。例如通过dataset_params指定数据集创建参数：

config = BasicTSForecastingConfig( dataset_params={ 'input_len': 336, 'output_len': 336, ... }, ... )

Builder._build_dataset在dataset_params非None时直接以它构造cfg.dataset_type(**dataset_params, mode=mode)（builder.py#L114-L141）。

方式二：直接将构造对象需要的参数作为顶层字段传入。可以直接配置 Config 类的input_len、output_len等已声明的快捷字段，并在初始化后再以字典/属性方式追加自定义参数（注意：初始化时只能传已定义的字段，未定义字段需构造后添加）：

config = BasicTSForecastingConfig( input_len=336, output_len=336, ... ) config.your_dataset_param_1 = param_1 config.your_dataset_param_2 = param_2

这种"快捷字段"（shortcut）机制的源码核心是_pack_params（base_config.py#L262-L287）：它在初始化时检查目标类（数据集/优化器/调度器）__init__的签名，把出现在配置顶层且非 None 的同名字段回填进参数 dict，且快捷字段的优先级高于参数 dict 中已有的同名值（源码注释 "short cut has higher priority than params in config"）。参与回填的快捷键由_SHORTCUT_KEYS声明，为["batch_size", "input_len", "output_len", "use_timestamps", "memmap", "lr"]（base_config.py#L147-L148）。同时该函数会对LRScheduler子类跳过optimizer形参——因为优化器实例由Builder._build_lr_scheduler在运行时传入。

当dataset_params为None且用户完全以顶层字段方式传参时，Builder._build_dataset会按dataset_type.__init__签名从配置中逐键收集参数；若某个必填参数在配置中缺失，将显式抛出KeyError，提示 "Please add it to the config for building the dataset"（builder.py#L125-L139）——这是一个值得注意的边界：自定义数据集使用字段式传参时，签名里的每个必填参数都必须能在配置顶层找到。

序列化、保存与 MD5：配置的持久化细节

基类把"打印、保存、加载、摘要"内建到了配置本身：

• 打印即 JSON：__str__将配置序列化为缩进 JSON（base_config.py#L207-L208）；serialized属性在导出时剔除私有字段（_前缀）与快捷键，避免冗余；
• 对象还原：from_json类方法配合_construct_obj可以从 JSON 重建对象——键集为{name, module}的字典被解析为"导入模块并取同名类"，键集为{name, module, params}的字典则直接实例化，列表/元组/嵌套字典递归处理（base_config.py#L220-L260）。反向的_serialize_obj会把类/函数写成{name, module}、partial写成{name, params}、Enum写成其值、slice写成"[a:b]"字符串等（base_config.py#L296-L352）；
• 保存：save()将cfg.json写入{ckpt_save_dir}/{md5}/目录（base_config.py#L289-L294）；
• MD5 的"训练相关"口径：_get_md5在哈希前会剔除_TRAINING_INDEPENDENT_KEYS（如gpus、各 dataloader 的 workers/pin_memory/prefetch、val_interval、test_interval等）再计算（base_config.py#L149-L154、#L354-L361）。含义是：改变硬件资源或数据加载方式不会改变配置指纹，而改变会实质影响训练的配置（模型、损失、超参等）则会得到新指纹、落在新的实验目录中。

完整实战：从配置到训练的一条龙

预测任务完整示例

官方示例 examples/forecasting/forecasting_demo.py 展示了配置类在真实实验中的用法——在 ETTh1 上训练 iTransformer，并用 4×4 的input_len/output_len网格批量跑实验：

from torch.optim.lr_scheduler import MultiStepLR from basicts import BasicTSLauncher from basicts.configs import BasicTSForecastingConfig from basicts.metrics import masked_mse from basicts.models.iTransformer import (iTransformerConfig, iTransformerForForecasting) from basicts.runners.callback import EarlyStopping, GradientClipping def main(): # train iTransformer on ETTh1 # run 4 experiments with different `input_len` and `output_len` for input_len in [96, 192, 336, 720]: for output_len in [96, 192, 336, 720]: # config iTransformer model_config = iTransformerConfig( num_features=7, hidden_size=32, intermediate_size=32, n_heads=1, num_layers=1, dropout=0.1, use_revin=True ) BasicTSLauncher.launch_training(BasicTSForecastingConfig( model=iTransformerForForecasting, model_config=model_config, dataset_name="ETTh1", input_len=input_len, # 快捷字段：自动回填进 dataset_params 与 model_config output_len=output_len, gpus="0", callbacks=[EarlyStopping(), GradientClipping(1.0)], # use callbacks seed=233, num_epochs=100, batch_size=64, metrics=["MSE", "MAE"], loss=masked_mse, optimizer_params={ "lr": 5e-4 }, lr_scheduler=MultiStepLR, lr_scheduler_params={ "milestones": [25, 50], "gamma": 0.5 } ))

这里体现了前文全部机制的协作：input_len/output_len是顶层快捷字段（会被_pack_params回填进model_config与dataset_params）；loss直接传函数对象masked_mse；callbacks传回调实例列表；batch_size会同步到三个 dataloader。

冒烟测试的最小配置

仓库的冒烟测试 tests/smoke_test/test_itransformerforr.py 展示了插补任务下最精简的可运行配置（配套微型数据集位于 tests/smoke_test/datasets/）：

def test_itransformerforr_smoke_test(): input_len = 32 model_config = iTransformerConfig( input_len=input_len, num_features=7 ) BasicTSLauncher.launch_training(BasicTSImputationConfig( model=iTransformerForReconstruction, model_config=model_config, dataset_name="ETTh1_mini", mask_ratio=0.25, gpus=None, # 无 GPU 环境 batch_size=16, input_len=input_len, num_epochs=5, ))

配置如何被执行链消费

配置对象进入执行链后的调用过程由 src/basicts/launcher.py 定义：

1. BasicTSLauncher.launch_training(cfg, node_rank=0)在 rank 0 节点调用cfg.save()落盘cfg.json；
2. 依据gpus字段选择gpu/mlu/cpu设备类型并设置可见设备，再通过dist_wrap进入分布式包装；
3. 最终的training_func用该配置构造BasicTSRunner(cfg)，初始化日志并执行runner.train()（launcher.py#L102-L113）；
4. 推理侧另有BasicTSLauncher.launch_evaluation(cfg, ckpt_path, gpus=None, batch_size=None)，它会在运行时改写cfg.gpus、cfg.gpu_num与cfg.test_batch_size，再调用runner.eval(ckpt_path)（launcher.py#L60-L100）——再次印证配置对象在运行时被直接读写的特点。

小结与延伸阅读

BasicTS 的配置体系可以概括为三句话：一个 EasyDict 继承的 dataclass 承载任务全部设定；"类 + 参数"的字段支持延迟构造对象并以快捷字段或参数字典两种方式传参；配置自身可打印、可保存、可从 JSON 重建，并以训练相关指纹（MD5）管理实验目录。掌握这套机制后，无论是复用基线模型还是接入自定义数据集、自定义模型，都只需要写一个配置类实例并调用BasicTSLauncher。

仓库中与配置体系强相关、可进一步深入的文档：

• 快速上手 / Getting Started
• 了解 BasicTS 的设计理念 / Overall Design
• 探索数据集设计并自定义数据集 / Dataset Design
• 了解数据缩放器设计并创建自定义缩放器 / Scaler Design
• 深入了解模型设计并构建自定义模型 / Model Design
• 了解评估指标设计并开发自定义损失函数与评估指标 / Metrics Design
• 掌握执行器设计并创建自定义执行器 / Runner and Pipeline
• 配置设计中文原文：config_design_cn.md；英文原文：config_design.md

适用前提说明：本文所有默认值、字段与行为均以当前仓库（版本 1.1.0）源码为准；若上游迭代调整了配置字段，请以 src/basicts/configs/ 下的最新实现为准。

• 人工智能
• 机器学习
• 深度学习
• 数据分析