⚠️ 通知：已停止维护

该项目已不再维护，并且存在安全漏洞。将不会提供进一步的更新或安全补丁。请自行承担使用风险。

runx - 一个实验管理工具

runx 帮助自动化研究中的常见任务：

• 超参数扫描
• 日志记录、TensorBoard、检查点管理
• 实验总结
• 代码检查点
• 为每次运行创建唯一的目录

目录

• 快速入门安装
• 简介：一个简单示例
• runx 架构
• 创建项目特定的配置文件
• 运行目录、日志文件
• 实验 YAML 详细信息
  • 布尔值
  • 列表、继承
• logx - 日志记录、TensorBoard、检查点
• sumx - 总结你的运行
• NGC 支持

快速入门安装

使用 pip 安装：

> pip install runx

从源码安装：

> git clone https://github.com/NVIDIA/runx
> cd runx
> python setup.py .

简介示例

假设你有一个现有的项目，你可以通过以下方式运行：

> python train.py --lr 0.01 --solver sgd

通常情况下，要进行超参数扫描，你需要编写一个一次性脚本生成扫描任务。但使用 runx，你只需定义一个 YAML 文件，列出你想要使用的超参数列表即可。

首先创建一个名为 sweep.yml 的 YAML 文件：

CMD: 'python train.py'

HPARAMS:
  lr: [0.01, 0.02]
  solver: ['sgd', 'adam']

现在你可以使用 runx 运行扫描：

 > python -m runx.runx sweep.yml -i

python train.py --lr 0.01 --solver sgd
python train.py --lr 0.01 --solver adam
python train.py --lr 0.02 --solver sgd
python train.py --lr 0.02 --solver adam 

可以看到，runx 自动计算了所有超参数的笛卡尔积，在这个例子中产生了 4 次运行。然后它通过将超参数与训练命令拼接来构建命令行。

一些有用的 runx 选项：

-n     不执行，只打印命令
-i     交互模式（而不是提交作业到集群）

runx 特别适合向集群提交批量作业。

集群支持非常简单。首先创建一个 .runx 文件来配置集群：

LOGROOT: /home/logs
FARM: bigfarm

bigfarm:
  SUBMIT_CMD: 'submit_job'
  RESOURCES:
     gpu: 2
     cpu: 16
     mem: 128

LOGROOT：这是运行输出应该存放的地方 FARM：你可以定义多个集群目标。这里选择使用哪一个 SUBMIT_CMD：用于向集群提交作业的脚本 RESOURCES：传递给 SUBMIT_CMD 的参数

现在当你运行 runx 时，它会生成尝试使用你的 SUBMIT_CMD 向集群提交作业的命令。注意我们省略了 -i 命令行参数，因为现在我们是要提交作业，而不是交互式地运行它们。

> python -m runx.runx sweep.yml

submit_job --gpu 2 --cpu 16 --mem 128 -c "python train.py --lr 0.01 --solver sgd"
submit_job --gpu 2 --cpu 16 --mem 128 -c "python train.py --lr 0.01 --solver adam"
submit_job --gpu 2 --cpu 16 --mem 128 -c "python train.py --lr 0.02 --solver sgd"
submit_job --gpu 2 --cpu 16 --mem 128 -c "python train.py --lr 0.02 --solver adam"

唯一的运行目录

我们希望每次训练的结果都保存到一个唯一的输出/日志目录中。我们不希望 TensorBoard 文件或日志文件相互覆盖。runx 通过自动为每次运行生成唯一的输出目录来解决这个问题。

你可以在实验 YAML 中通过特殊变量 LOGDIR 访问这个唯一目录名。你的训练脚本可以使用该路径并将输出写入其中。

CMD: 'python train.py'

HPARAMS:
  lr: [0.01, 0.02]
  solver: ['sgd', 'adam']
  logdir: LOGDIR

在上面的实验 YAML 中，我们将 LOGDIR 作为参数传递给了你的训练脚本。当我们启动作业时，runx 会自动生成唯一的输出目录，并将路径传递给你的训练脚本：

> python -m runx.runx sweep.yml

submit_job --gpu 2 --cpu 16 --mem 128 -c "python train.py --lr 0.01 --solver sgd  --logdir /home/logs/athletic-wallaby_2020.02.06_14.19"
submit_job --gpu 2 --cpu 16 --mem 128 -c "python train.py --lr 0.01 --solver adam  --logdir /home/logs/industrious-chicken_2020.02.06_14.19"
submit_job --gpu 2 --cpu 16 --mem 128 -c "python train.py --lr 0.02 --solver sgd  --logdir /home/logs/arrogant-buffalo_2020.02.06_14.19"
submit_job --gpu 2 --cpu 16 --mem 128 -c "python train.py --lr 0.02 --solver adam  --logdir /home/logs/vengeful-jaguar_2020.02.06_14.19"

使用 sumx 进行总结

在运行完实验后，你可能希望对结果进行总结。你可能会想知道：

• 哪次训练效果最好？
• 每个 epoch 花了多长时间？
• 其他指标如何？

你可以使用命令行工具 sumx 来总结你的运行。你只需要告诉 sumx 要总结哪个实验。sumx 知道你的 LOGROOT（它会从 .runx 文件中获取），因此它会在该目录下查找你的实验目录。

在下面的例子中，我们要求 sumx 总结 sweep 实验。

> python -m runx.sumx sweep --sortwith acc

        lr    solver  acc   epoch  epoch_time
------	----  ------  ----  -----  ----------
run4    0.02  adam    99.1   10     5:11
run3    0.02  sgd     99.0   10     5:05
run1    0.01  sgd     98.2   10     5:15
run2    0.01  adam    98.1   10     5:12

sumx 是 runx 套件的一部分，能够总结所使用的不同超参数以及你的运行指标和结果。请注意，我们使用了 sumx 的 --sortwith 功能，它可以对结果进行排序，以便你轻松找到最佳的运行。

这就是基本思路。 接下来的部分将更详细地介绍所有功能。

runx 架构

runx 由三个主要模块组成：

• runx
  • 使用简洁的 YAML 格式启动训练运行的扫描，允许每个超参数有多个值
  • 特别是，当你调用 runx 时：
    • 计算所有超参数的笛卡尔积 -> 运行次数
    • 对于每次运行，创建一个输出目录，将你的代码复制到那里，然后启动训练命令
• logx
  • 记录指标、消息、检查点、TensorBoard
• sumx
  • 总结训练运行的结果，显示结果和独特的超参数

这些模块旨在一起使用，但如果你只想使用 runx，也是可以的。 不过，使用 sumx 需要你先使用 logx 记录指标。

创建项目专用配置文件

为了使用 runx，您需要在将要调用 runx CLI 的目录中创建一个配置文件。

.runx 文件定义了若干关键字段：

• LOGROOT - 您希望日志存放的根目录。这是一个任何农场作业都可以写入的路径。
• FARM - 如果已定义，则作业应提交到该农场；否则以交互方式运行。
• 对于给定的农场，以下字段是必需的：
  • SUBMIT_CMD - 农场提交命令
  • RESOURCES - 传递给 SUBMIT_CMD 的超参数。您可以列出任意数量的条目，下面显示的只是示例。
• CODE_IGNORE_PATTERNS - 在将代码复制到输出目录时忽略这些文件模式。

以下是此类文件的示例：

LOGROOT: /home/logs
CODE_IGNORE_PATTERNS: '.git,*.pyc,docs*,test*'
FARM: bigfarm

# 农场资源需求
bigfarm:
    SUBMIT_CMD: 'submit_job'
    RESOURCES:
        image: mydocker-image-big:1.0
        gpu: 8
        cpu: 64
        mem: 450

smallfarm:
    SUBMIT_CMD: 'submit_small'
    RESOURCES:
        image: mydocker-image-small:1.2
        gpu: 4
        cpu: 32
        mem: 256

运行目录、日志文件

runx 具有两级实验层次结构：实验和运行。一个 实验 对应于一个单独的 YAML 文件，其中可能包含多个 运行。

runx 会为每个实验创建一个父级实验目录，并为每次运行创建一个唯一的子目录。实验目录的名称为 LOGROOT/<实验名称>，因此在 sweep.yml 的示例中，实验名称为 sweep，源自 YAML 文件名。

例如，这可能是 sweep 研究的目录结构：

/home/logs
  sweep/
     curious-rattlesnake_2020.02.06_14.19/
     ambitious-lobster_2020.02.06_14.19/
     ...

各个运行目录的命名结合了 coolname 和日期。使用 coolname 比仅用日期代码更容易引用特定的运行。

如果您在实验 YAML 中包含 RUNX.TAG 字段，或者向 runx CLI 提供 --tag 参数，则名称中会包含该标签。

代码暂存

runx 实际上会在每个运行的日志目录中复制一份您的代码。这样做有几个原因：

• 如果您希望在训练运行进行时继续修改代码，可以放心地进行，而不必担心会影响正在运行的作业。
• 如果您的作业失败并需要重新启动，代码和训练环境都自包含在运行的日志目录中。
• 这也有助于文档记录：如果您想了解某个运行时代码的确切状态，这也是一个有用的方法。

实验 YAML 详细信息

特殊变量

CMD - 您的基础训练命令。通常这里不包含任何参数。 HPARAMS - 所有超参数。这是一个数据结构，可以是简单的参数字典，也可以是字典列表。此外，每个超参数可以是标量、列表或布尔值。 PYTHONPATH - 此字段为可选。用于修改默认的 PYTHONPATH，即 LOGDIR/code。可以是冒号分隔的路径列表，也可以包含 LOGDIR 特殊变量。

HPARAMS

HPARAMS 的一个简单示例如下：

CMD: "python train.py"

HPARAMS:
  logdir: LOGDIR
  adam: true
  arch: alexnet
  lr: [0.01, 0.02]
  epochs: 10
  RUNX.TAG: 'alexnet'

在此例中，将创建 2 个运行。

布尔值

如果您想指定某个布尔标志应开启或关闭，可以使用 true 和 false 关键字：

some_flag: [true, false]

这将导致一个运行带有 --some_flag，而另一个运行则没有该标志。

如果您想传递实际的字符串，可以这样做：

  some_arg: ['True', 'False']

这将导致一个运行带有 --some_arg True，另一个运行带有 --some_arg False。

如果您希望某个参数根本不传递到脚本中，可以将其设置为 None：

  some_arg: None

列表、继承

通常，您可能希望在实验中定义不同的超参数列表。例如：

1. 架构 = alexnet，学习率 = [0.01, 0.02]
2. 架构 = resnet50，学习率 = [0.002, 0.005]

您可以通过如下方式定义超参数：

PYTHONPATH: LOGDIR/code:LOGDIR/code/lib
CMD: "python train.py"

HPARAMS: [
  {
   logdir: LOGDIR,
   adam: true,
   arch: alexnet,
   lr: [0.01, 0.02],
   epochs: 10,
   RUNX.TAG: 'alexnet',
  },
  {
   arch: resnet50，
   lr: [0.002, 0.005],
   RUNX.TAG: 'resnet50',
  },
  {
   RUNX.SKIP: true，
   arch: resnet50，
   lr: [0.002, 0.005],
   RUNX.TAG: 'resnet50',
  }
]

您可能会注意到，HPARAMS 现在是一个包含两个字典的列表。好处是 runx 会假定从列表中的第一项继承到所有剩余的字典，这样您就不必重复输入所有冗余的超参数。

当您将此 YAML 文件传递给 runx 时，您将得到以下输出：

submit_job ... --name alexnet_2020.02.06_6.32  -c "python train.py --logdir ... --lr 0.01 --adam --arch alexnet --epochs 10
submit_job ... --name alexnet_2020.02.06_6.40  -c "python train.py --logdir ... --lr 0.02 --adam --arch alexnet --epochs 10
submit_job ... --name resnet50_2020.02.06_6.45 -c "python train.py --logdir ... --lr 0.002 --adam --arch resnet50 --epochs 10
submit_job ... --name resnet50_2020.02.06_6.50 -c "python train.py --logdir ... --lr 0.005 --adam --arch resnet50 --epochs 10

由于继承机制，adam、arch 和 epochs 参数在每个运行中都相同。

这也展示了魔术变量 RUNX.TAG 的使用，它允许您为实验的一部分添加标签。这与使用 runx.py 的 --tag <tagname> 选项效果相同，不同之处在于您可以直接在 HPARAMS 数据结构中指定标签。RUNX.TAG 的值不会传递到您的训练脚本中。

RUNX.TAG 的一个非常有用的功能是，您可以引用其他超参数，例如：

   arch: resnet50，
   RUNX.TAG: '{arch}-lrstudy'

这将使标签变为 resnet50-lrstudy。runx 在遇到花括号时会进行简单的字符串匹配和替换。

logx - 日志记录、TensorBoard 可视化、检查点保存

为了使用 sumx，你需要使用 logx 导出指标。

logx 帮助以标准方式记录指标，从而使 sumx 能够汇总结果。

logx 还可以方便地将日志信息输出到文件（以及标准输出）。

此外，logx 还能自动管理检查点的保存，其优势在于只会保留最新的和最优的检查点，从而节省大量磁盘空间。

使用 logx 的基本方法是按照以下方式修改你的训练代码：

在训练脚本的顶部（或任何调用 logx 函数的模块中）：

from runx.logx import logx

在使用 logx 之前，必须按如下方式初始化它：

   logx.initialize(logdir=args.logdir, coolname=True, tensorboard=True)

确保在使用分布式数据并行时，仅从 rank=0 节点调用 logx。

然后，将以下 logx 调用替换到你的代码中：

从	到	作用
print()	logx.msg()	标准输出消息
writer.add_scalar()	logx.add_scalar()	TensorBoard 标量写
writer.add_image()	logx.add_image()	TensorBoard 图像写
	logx.save_model()	保存最新/最佳模型

最后，为了让 sumx 能够读取你运行的结果，你必须将指标推送到 logx。务必推送验证集指标，但也可以选择推送训练集指标（目前 sumx 尚未使用这些指标）。

# 定义要记录的指标
metrics = {'loss': test_loss, 'accuracy': accuracy}
# 将指标推送到日志文件
logx.metric(phase='val', metrics=metrics, epoch=epoch)

logx.metric 的一些重要注意事项：

• phase 参数用于指定该指标是训练指标还是验证指标。
• 对于验证指标，应将 idx 设置为当前 epoch；而对于训练指标，idx 通常为迭代次数。

logx 的最后一个功能是模型保存。此功能不仅能够保存最新模型，还能保存最优模型。

save_dict = {'epoch': epoch + 1,
             'arch': args.arch,
             'state_dict': model.state_dict(),
             'best_acc1': best_acc1,
             'optimizer' : optimizer.state_dict()}
logx.save_model(save_dict, metric=accuracy, epoch=epoch, higher_better=True)

在调用 save_model 时，需要明确指标是越高越好还是越低越好。

sumx - 汇总你的运行结果

sumx 会汇总你的运行结果。它要求你已使用 logx.metric 记录了指标。

我们选择这种方式而不是直接读取 TensorBoard 文件，是因为后者速度会慢很多。

> python -m runx.sumx sweep
        lr    solver  acc   epoch  epoch_time
run4    0.02  adam    99.1  10     5:21
run3    0.02  sgd     99.0  10     5:02
run1    0.01  sgd     98.2  10     5:40
run2    0.01  adam    98.1  10     5:25

几个值得注意的功能：

• 使用 --sortwith 参数可以根据你最关心的字段（如准确率）对输出进行排序。
• sumx 会显示当前运行正在进行的 epoch。
• sumx 还会显示平均每个 epoch 的耗时，这对于监控训练速度非常有帮助。
• 可以使用可选的 --ignore 标志来限制 sumx 输出的字段。

NGC 支持

NGC 支持现已成为标配。你的 .runx 文件应如下所示。

LOGROOT: /path/to/logroot

FARM: ngc

ngc:
    NGC_LOGROOT: /path/to/ngc_logroot
    WORKSPACE: <your ngc workspace>
    SUBMIT_CMD: 'ngc batch run'
    RESOURCES:
       image: nvidian/pytorch:19.10-py3
       instance: dgx1v.16g.1.norm
       ace: nv-us-west-2
       result: /result

必要的步骤：

• 填写 LOGROOT 路径，这是客户端侧的日志目录暂存目录。
• 创建一个 RW 权限的 NGC 工作区，并将其填写到 WORKSPACE 中。
• 在本地机器上挂载该工作区，并将挂载路径填写到 NGC_LOGROOT 中。当作业启动时，这也是用于在运行实例上挂载工作区的路径。
• 填写 RESOURCES 下的必要字段。请注意，这些参数会被传递给 SUBMIT_CMD，而 SUBMIT_CMD 必须设置为 ngc batch run。

使用此配置你应该能够成功提交作业到 NGC。当作业写入结果时，你也应该能够在挂载的工作区内看到这些结果，随后就可以运行 runx.sumx 来汇总这些运行的结果。

runx 快速上手指南

⚠️ 重要提示：项目已停止维护 本项目不再维护，且存在已知安全漏洞。官方不再提供更新或安全补丁。请仅在了解风险的前提下谨慎使用，或仅用于学习其设计思路。

runx 是一个实验管理工具，旨在自动化科研中的常见任务，包括超参数搜索、日志记录、TensorBoard 管理、检查点管理以及为每次运行创建唯一的输出目录。

环境准备

• 系统要求：Linux / macOS (Windows 需通过 WSL 或类似环境)
• 前置依赖：
  • Python 3.x
  • pip 包管理器
  • (可选) 集群作业提交脚本（如 SLURM, LSF 等），若需在农场/集群上运行任务。

安装步骤

方式一：通过 pip 安装（推荐）

pip install runx

方式二：从源码安装

git clone https://github.com/NVIDIA/runx
cd runx
python setup.py .

基本使用

1. 创建项目配置文件 (.runx)

在项目根目录下创建名为 .runx 的配置文件，用于定义日志根目录和运行环境。

创建文件 .runx：

LOGROOT: ./logs
FARM: local

local:
  SUBMIT_CMD: ''
  RESOURCES: {}

• LOGROOT: 实验日志和结果的存储根目录。
• FARM: 定义运行目标。此处设为 local 表示在本地交互式运行。

2. 定义实验超参数 (YAML)

创建一个 YAML 文件（例如 sweep.yml）来定义训练命令和需要搜索的超参数列表。runx 会自动计算所有参数的笛卡尔积。

创建文件 sweep.yml：

CMD: 'python train.py'

HPARAMS:
  lr: [0.01, 0.02]
  solver: ['sgd', 'adam']
  logdir: LOGDIR

• CMD: 基础训练命令。
• HPARAMS: 超参数字典。列表类型的值（如 [0.01, 0.02]）将触发自动遍历。
• LOGDIR: 特殊变量，runx 会自动将其替换为本次运行唯一的输出目录路径，防止文件覆盖。

3. 运行实验

本地交互式运行

使用 -i 标志在本地直接运行所有组合：

python -m runx.runx sweep.yml -i

执行后，runx 将依次执行以下命令（示例）：

python train.py --lr 0.01 --solver sgd --logdir ./logs/sweep/athletic-wallaby_2023.10.27_10.00
python train.py --lr 0.01 --solver adam --logdir ./logs/sweep/industrious-chicken_2023.10.27_10.01
python train.py --lr 0.02 --solver sgd --logdir ./logs/sweep/arrogant-buffalo_2023.10.27_10.02
python train.py --lr 0.02 --solver adam --logdir ./logs/sweep/vengeful-jaguar_2023.10.27_10.03

注意：每次运行都会生成一个包含“形容词 - 名词_时间戳”的唯一目录名。

预览命令（不执行）

如果只想查看生成的命令而不实际运行，使用 -n 标志：

python -m runx.runx sweep.yml -n

4. 结果汇总 (sumx)

实验完成后，使用 sumx 工具汇总结果。它会自动读取 LOGROOT 下的实验数据。

假设你的训练脚本在日志中记录了 acc (准确率) 指标：

python -m runx.sumx sweep --sortwith acc

输出示例：

        lr    solver  acc   epoch  epoch_time
------	----  ------  ----  -----  ----------
run4    0.02  adam    99.1   10     5:11
run3    0.02  sgd     99.0   10     5:05
run1    0.01  sgd     98.2   10     5:15
run2    0.01  adam    98.1   10     5:12

进阶提示：代码快照

runx 在每次运行时，会自动将当前代码复制到对应的唯一日志目录中。这确保了即使后续修改了代码，已运行的实验环境依然保持不变，便于复现和追溯。