配置系统

概述

Pyruns 的配置系统围绕 YAML 文件构建，支持嵌套结构、自动类型推断和批量参数展开。整个配置体系分为三个层次：

层次	文件	说明
参数模板	config_default.yaml	脚本的默认参数基准，由 pyr 自动生成或用户导入
任务快照	config.yaml	每次生成任务时的参数副本，保存在各任务目录下
任务元数据	task_info.json	任务的完整生命周期数据（状态、时间、PID、笔记等）

---

配置文件

config_default.yaml — 参数模板

存放在 _pyruns_/{script}/ 目录下，是 Generator 页面的参数来源。

生成方式（三选一）：

方式	触发条件	行为
Argparse 自动解析	pyr train.py（脚本含 argparse）	AST 静态分析提取所有参数默认值并生成
YAML 导入	pyr train.py my_config.yaml	将 my_config.yaml 复制为 config_default.yaml
pyruns.load() 模式	脚本使用 pyruns.load()	要求 config_default.yaml 已存在，否则报错并引导用户导入

后续运行 pyr train.py（不带 YAML 参数）时，始终自动加载已有的 config_default.yaml。再次传入新 YAML 会覆盖旧模板。

# Auto-generated for train.py

lr: 0.001  # 学习率
epochs: 10  # 训练轮数
batch_size: 32  # 批大小
model: resnet50

在 Generator 中的行为：

• 以只读模板形式加载（左上角 🔒 标记）
• 用户编辑的是内存副本，原始文件不受影响
• 生成任务时，参数写入各任务目录的独立 config.yaml

config.yaml — 任务级快照

每个任务目录包含一个独立的 config.yaml，是生成任务时的参数快照：

lr: 0.01
epochs: 20
batch_size: 64
model: resnet50

• 批量生成时，每个任务的 config.yaml 各自包含该任务的参数组合
• 内部元数据字段（以 _meta 开头的键）会被自动过滤

task_info.json — 任务元数据

记录任务的完整生命周期数据：

{
    "id": "2026-02-13_10-30-45_1707817845123",
    "name": "baseline-[1-of-6]",
    "status": "completed",
    "created_at": "2026-02-13 10:30:45",
    "progress": 1.0,
    "pinned": false,
    "env": {
        "CUDA_VISIBLE_DEVICES": "0"
    },
    "script": "/path/to/train.py",
    "run_at": "2026-02-13 10:31:00",
    "run_pid": null,
    "rerun_at": ["2026-02-13 11:00:00"],
    "rerun_pid": [null],
    "notes": "首次实验，baseline 配置",
    "monitors": [
        {"loss": 0.234, "acc": 95.2, "_ts": "2026-02-13 10:31:05"}
    ]
}

字段说明：

字段	类型	说明
id	string	唯一标识符（时间戳 + 毫秒）
name	string	显示名称（= 目录名）
status	string	pending / queued / running / completed / failed
created_at	string	创建时间
progress	float	进度 0.0 ~ 1.0
pinned	bool	是否置顶
env	dict	环境变量（如 CUDA_VISIBLE_DEVICES）
script	string	用户脚本的绝对路径
run_at	string?	首次运行时间
run_pid	int?	首次运行的进程 PID（结束后为 null）
rerun_at	list[string]	每次重跑的时间
rerun_pid	list[int?]	每次重跑的 PID
notes	string	用户笔记
monitors	list[dict]	监控数据条目列表

ConfigNode — 点号访问配置

pyruns.load() 返回一个 ConfigNode 对象，支持属性风格的点号访问：

config = pyruns.load()

# 基础类型
config.lr          # 0.001
config.epochs      # 10

# 嵌套结构
config.model.name  # "resnet50"
config.model.layers  # [64, 128, 256]

# 转回字典
config.to_dict()   # {"lr": 0.001, "epochs": 10, "model": {"name": "resnet50", ...}}

支持的配置文件格式：

• .yaml / .yml
• .json

类型推断

配置值从字符串输入自动推断类型（由 parse_value() 处理）：

输入	推断类型	结果
42	int	42
3.14	float	3.14
true / True	bool	True
false / False	bool	False
[1, 2, 3]	list	[1, 2, 3]
hello	str	"hello"
None	NoneType	None

嵌套配置

YAML 的嵌套结构在 Pyruns 中完全支持：

# config_default.yaml
model:
  name: resnet50
  hidden_size: 256
  dropout: 0.1

training:
  lr: 0.001
  epochs: 100
  scheduler:
    type: cosine
    warmup: 5

在 Generator 页面中，嵌套字典显示为可折叠的分组。

在脚本中使用（Mode 2）：

config = pyruns.load()
config.model.name          # "resnet50"
config.training.scheduler.type  # "cosine"

环境变量配置（Per-Task）

每个任务可以在 Task Dialog 的 Env Vars 标签页中设置独立的环境变量：

{
    "CUDA_VISIBLE_DEVICES": "0,1",
    "MASTER_PORT": "29500",
    "OMP_NUM_THREADS": "4"
}

这些环境变量在任务执行时通过 executor.py 的 _prepare_env() 注入到子进程环境中。

配置查找优先级

pyruns.read() 按如下顺序查找配置文件：

优先级	来源	说明
1	环境变量 __PYRUNS_CONFIG__	由 pyr executor 自动设置，指向当前任务的 config.yaml
2	显式传入的 file_path	pyruns.read("my_config.yaml")
3	默认路径	_pyruns_/{script}/config_default.yaml

工作流说明：

• 通过 pyr 运行任务时，executor 会自动设置 __PYRUNS_CONFIG__ 指向任务目录的 config.yaml，用户脚本中的 pyruns.read() / pyruns.load() 会自动读取
• 直接 python train.py 运行时，按优先级 2→3 查找

---

全局设置 _pyruns_settings.yaml

Pyruns 的配置层明确分离：

文件	作用	修改方式
_pyruns_settings.yaml	用户可定制的 UI 设置（端口、并发数、列数等）	手动编辑或 UI 内修改
pyruns/_config.py	系统级常量（目录名、环境变量名等）	仅开发者修改
pyruns/ui/theme.py	视觉系统（CSS 类名、颜色映射、图标）	仅开发者修改