企业官网建设流程全解析

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

本文围绕 BasicTS 配置设计文档 展开，结合 src/basicts/configs/ 下的配置类源码与 examples/ 中的可运行示例，系统讲解 BasicTS 1.0 的配置类体系：任务配置类的选型与字段分区、类/字典双形态用法、配置对象的两种传参方式，以及配置保存、加载、序列化与执行期的完整调用链。读完后，你可以独立为一个预测、分类或插补任务编写完整配置，并理解每个字段在运行时的真实去向。

1. 设计哲学：从“脚本 + 命令行”到配置类

BasicTS 的设计理念是“配置即一切”（All-in-configuration）：让用户专注于模型和数据，而不被繁琐的流程构建所困扰。从 1.0 版本开始，BasicTS 不再使用.py文件配合命令行指定配置路径的方式，而是升级为使用配置类进行配置。

配置体系由一个基类和若干任务配置类组成（参见 configs/init.py 的导出列表）：

基类BasicTSConfig定义了各任务公用的字段，以及保存（save）、加载（from_json）、打印（__str__）配置的方法；任务特定配置类则包含执行该任务所需的一切配置参数。用户可以在配置类中灵活导入模型、数据集与指标，并设置所有必要选项。

从源码结构看，BasicTSConfig使用@dataclass(init=False)装饰并继承EasyDict（见 base_config.py#L29-L30），这是它“既是类、也是字典”双形态的根基。每个字段都以 dataclass field 形式定义，default/default_factory给出默认值，metadata={"help": ...}给出该字段的默认值说明、详细含义与使用方法——文档中“Config 类字段的 metadata 提供了每个字段的默认值、详细含义及使用方法”正是这一实现的直接体现。

2. 配置分区总览：一个配置类包含哪些字段

一个任务配置类通常按功能划分为如下分区（以预测配置 tsf_config.py 为例，分区注释直接来自源码）：

2.1 常规选项

2.2 环境选项

这些字段由BasicTSRunner.set_env在初始化时消费：调用set_tf32_mode(cfg.tf32)与setup_determinacy(seed + rank, cfg.deterministic, cfg.cudnn_enabled, ...)（见 basicts_runner.py#L838-L868）。因此需要严格复现实验时，建议组合设置deterministic=True、cudnn_benchmark=False、cudnn_determinstic=True。

2.3 数据集选项

dataset_name与model一样是必须显式指定的字段（预测配置中声明于 tsf_config.py#L69-L75）。

2.4 数据缩放器选项

分类任务默认scaler=None，因为“分类任务无需 rescale，数据可在预处理阶段归一化”（见 tsc_config.py#L115-L117 的字段注释）。缩放器实例在运行期由Builder._build_scaler构造，它按scaler.__init__的签名从配置顶层字段中收集参数（见 builder.py#L151-L165）。

2.5 模型选项

compile_model的实现在Builder._build_model中：版本低于 2.0 时会打 warning 并跳过编译（见 builder.py#L50-L59）。

2.6 评估指标选项

Runner 初始化时会做断言：target_metric必须存在于已解析的metrics中或等于"loss"，best_metric必须是"min"/"max"（见 basicts_runner.py#L168-L180）。

2.7 训练选项

常规：

优化器：optimizer默认Adam；optimizer_params默认{"lr": 2e-4, "weight_decay": 5e-4}；lr为顶层快捷字段，会覆盖optimizer_params中的学习率。

调度器：lr_scheduler默认None；lr_scheduler_params默认None。注意LRScheduler的optimizer参数由 builder 在构造时自动传入（builder.py#L147-L149），无需在参数中指定。

数据：batch_size（统一设置）、train_batch_size（默认 64）、train_data_prefetch（默认False）、train_data_shuffle（默认True）、train_data_collate_fn、train_data_num_workers（默认0）、train_data_pin_memory（默认False）。

Checkpoint：

2.8 验证、测试与评估选项

验证与测试的触发点在BasicTSRunner.on_epoch_end：仅当epoch % val_interval == 0时执行验证、epoch % test_interval == 0时执行测试（见 basicts_runner.py#L680-L684）。eval_after_train=True时，训练结束会自动用最佳 checkpoint 在测试集上评估（见 basicts_runner.py#L303-L316）。

3. 构造配置类

3.1 既是类，也是字典

BasicTS 的配置类继承自EasyDict，既可以作为类使用，也可以作为字典使用，方便扩展并且灵活易用。

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

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")

从源码结构看，这一能力的实现分为两处：构造函数中，与 dataclass 字段同名的 kwargs 被逐一setattr，其余 kwargs 会交给EasyDict基类（见 base_config.py#L170-L199）；下标访问则先尝试属性访问，失败后再回退到字典语义（__getitem__，见 base_config.py#L210-L218）。

3.2 配置类中的对象：两种传参方式

配置中存在许多需要进一步构造的对象，例如模型、数据集、优化器、调度器等。BasicTS 在配置中传入对应的类和创建对象所需的参数，而将这些对象的创建延迟到实际执行任务时。对于这些对象，支持两种方式灵活配置：

方式一：将构造对象所需的全部参数以字典形式传入。例如把参数字典传给dataset_params供后续创建数据集实例：

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

方式二：直接将构造对象需要的参数作为字段传入。例如直接配置 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

这两种方式之所以都能工作，源于构造时的“参数打包”与运行期的“签名收集”两个机制：

1. 构造时打包（_pack_params）：BasicTSConfig.__init__会对四组“类 + 参数字典”调用_pack_params，即model/model_config、dataset_type/dataset_params、optimizer/optimizer_params、lr_scheduler/lr_scheduler_params（见 base_config.py#L199-L202）。该方法用inspect.signature检视目标对象__init__的形参，若某个形参名在配置顶层存在且非None，就用顶层字段的值覆盖参数字典中的同名字段——源码注释明确写着 “short cut has higher priority than params in config”（见 base_config.py#L262-L287）。因此顶层快捷字段的优先级高于xxx_params字典。
2. 运行期收集（Builder）：Builder._build_dataset在cfg.dataset_params is not None时直接以该字典构造数据集；当它为None时，则按dataset_type.__init__的签名逐项从配置顶层字段取值，若缺少必填参数会抛出KeyError提示补全（见 builder.py#L114-L141）。_build_optimizer、_build_lr_scheduler、_build_scaler同理（见 builder.py#L143-L165）。

另外，batch_size是一个特殊的“广播”字段：一旦设置，__init__会把它同步写入train_batch_size、val_batch_size、test_batch_size（见 base_config.py#L194-L197），否则三者各自使用默认值 64。

3.3 快捷字段与序列化排除

基类定义了_SHORTCUT_KEYS = ["batch_size", "input_len", "output_len", "use_timestamps", "memmap", "lr"]（见 base_config.py#L147-L148）。这些顶层快捷字段的值经_pack_params已汇入对应的xxx_params字典；在序列化配置时，_serialize会跳过私有属性和这些快捷键，避免cfg.json中出现重复信息（见 base_config.py#L235-L241）。

4. 保存、加载与打印配置

基类提供了保存/加载/打印配置的完整能力，均围绕“序列化”展开：

• 打印：__str__返回json.dumps(self.serialized, ensure_ascii=False, indent=4)（见 base_config.py#L207-L208）。
• 序列化：_serialize_obj将类或函数转成{"name": ..., "module": ...}，functools.partial转成name + params，枚举转成value，slice转成[start:stop:step]字符串，普通对象则只保留其非默认构造参数（见 base_config.py#L296-L352）。这使得包含模型类、优化器类、损失函数的复杂配置也能落盘为纯 JSON。
• 反序列化：类方法from_json读取 JSON 后用_construct_obj递归重建——遇到{"name", "module"}结构时用importlib.import_module还原为真实的类/函数（见 base_config.py#L220-L260）。
• 保存：save()将 JSON 写入{ckpt_save_dir}/{md5}/cfg.json（见 base_config.py#L289-L294）。这里的md5是对训练相关子集配置的哈希：先深拷贝序列化结果，剔除_TRAINING_INDEPENDENT_KEYS（如gpus、各num_workers、pin_memory、save_results等不影响训练结果的字段）后再计算（见 base_config.py#L149-L154 与 #L354-L361）。可以推断，该设计意在让“仅硬件/IO 配置不同但训练设定完全相同”的实验共享同一配置标识，同时保证cfg.json与训练结果一一对应、可复现。
• 触发时机：训练启动时，BasicTSLauncher.launch_training在节点 0 上调用cfg.save()把配置持久化（见 launcher.py#L33-L34）。

5. 配置如何驱动实际执行：从示例到调用链

一个典型的预测任务配置示例来自 examples/forecasting/forecasting_demo.py——训练 iTransformer 于 ETTh1，覆盖 4 种input_len× 4 种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 for input_len in [96, 192, 336, 720]: for output_len in [96, 192, 336, 720]: # 配置模型 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 output_len=output_len, gpus="0", callbacks=[EarlyStopping(), GradientClipping(1.0)], seed=233, num_epochs=100, batch_size=64, # 广播到 train/val/test metrics=["MSE", "MAE"], loss=masked_mse, # 可传可调用对象 optimizer_params={"lr": 5e-4}, lr_scheduler=MultiStepLR, lr_scheduler_params={"milestones": [25, 50], "gamma": 0.5} ))

最小化的三行写法见 examples/simplest_demo.py：

model_config = DLinearConfig(input_len=336, output_len=336) BasicTSLauncher.launch_training(BasicTSForecastingConfig( model=DLinear, model_config=model_config, dataset_name="ETTh1", gpus="0" ))

分类任务则使用BasicTSClassificationConfig，参考 examples/classification/classification_demo.py（默认数据集类为UEADataset，无需output_len，checkpoint 目录模板也不含输入/输出长度）。

配置的运行时调用链为：

1. BasicTSLauncher.launch_training(cfg)：主节点保存cfg.json，根据gpus设置设备类型与可见设备，并用dist_wrap包裹训练函数以支持 DDP（见 launcher.py#L18-L58）；
2. training_func创建BasicTSRunner(cfg)，Runner 初始化时按配置解析 loss（字符串从ALL_METRICS查找，可调用对象直接使用）、解析metrics并断言target_metric、创建模型与缩放器（见 basicts_runner.py#L105-L180）；
3. 训练循环中，Builder依据配置惰性构造模型、数据集、DataLoader、优化器与调度器（见 builder.py），并按val_interval/test_interval周期性验证、测试、保存 checkpoint；最佳模型保存为{model_name}_best_val_{target_metric}.pt；
4. 训练结束后若eval_after_train为True，自动加载最佳 checkpoint 在测试集上评估；若save_results为True，评估结果另存为 numpy 文件与test_metrics.json（见 basicts_runner.py#L634-L644）。

独立评估则通过BasicTSLauncher.launch_evaluation(cfg, ckpt_path, gpus, batch_size)完成，它会覆盖gpus与可选的test_batch_size后调用runner.eval(ckpt_path)（见 launcher.py#L60-L100）。

6. 高频修改字段速查（Hot Fields）

任务配置类的 docstring 明确列出了“虽有默认值但常被修改”的字段，整理如下（以预测配置为准）：

7. 进一步探索

配置类是整个 BasicTS 任务流程的入口，与其配合阅读的配套文档（均位于docs/下）包括：

• 快速上手：安装、数据集下载与三步跑通训练；
• 整体设计理念：Dataset、Scaler、Model、Metrics、Runner、Config 六大组件如何协作；
• 数据集设计：自定义数据集的规范，与dataset_type/dataset_params直接相关；
• 数据缩放器设计：自定义缩放器，对应scaler字段；
• 模型设计：自定义模型与其model_config的约定；
• 评估指标设计：自定义损失与指标，对应loss/metrics字段；
• 执行器与流程设计：taskflow与callbacks的底层机制。

此外，英文版本配置设计文档见 config_design.md，与本文对应的中文版 config_design_cn.md 互为补充；如需核对任意字段的默认值与含义，直接阅读 src/basicts/configs/ 下对应文件的字段定义即可。

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