.torchxconfig¶

状态：测试版

您可以通过将调度器运行配置文件（运行配置）存储在 .torchxconfig 文件中来存储项目的调度器运行配置文件。目前，仅在从 CLI 运行组件时才会读取和使用此文件。

CLI 用法¶

调度器配置

cd 到您希望放置 .torchxconfig 文件的目录。CLI 仅从当前工作目录 (CWD) 中获取 .torchxconfig 文件，因此请选择您通常运行 torchx 的目录。通常，这是项目目录的根目录。

通过运行以下命令生成配置文件

$ torchx configure -s <comma,delimited,scheduler,names>

# -- or for all registered schedulers --
$ torchx configure

如果您指定了 -s local_cwd,kubernetes，您应该会看到一个 .torchxconfig 文件，如下所示

$ cat .torchxconfig
[local_cwd]

[kubernetes]
queue = #FIXME:(str) Volcano queue to schedule job in

.torchxconfig 以 INI 格式显示，节名称映射到调度器名称。每个节包含调度器的运行配置，以 $key = $value 对的形式。您可能会发现某些调度器具有空节，这意味着调度器为所有运行配置定义了合理的默认值，因此在运行时不需要运行配置。如果您想覆盖默认值，可以添加它们。提示：要查看调度器的所有运行选项，请使用 torchx runopts <scheduler_name>。
包含 FIXME 占位符的节是调度器所需的运行配置。将这些替换为适用于您的值。
重要：如果您对调度器为特定运行配置提供的默认值感到满意，则您不应在 .torchxconfig 中使用相同的默认值重复指定它们。这是因为调度器可能会决定在稍后的日期更改默认值，这将导致您使用过时的默认值。
现在，您可以运行组件，而无需每次都指定调度器运行配置。只需确保您运行 torchx cli 的目录实际上包含 .torchxconfig！
```
$ ls .torchxconfig
.torchxconfig

$ torchx run -s local_cwd ./my_component.py:train
```
此外，还可以指定除 .torchxconfig 之外的其他配置以在运行时加载。要求是通过环境变量 TORCHX_CONFIG 指定配置路径。它还禁用了从多个目录加载配置的层次结构，因为其他情况并非如此。
用户级 .torchxconfig 除了项目根目录中的项目级 .torchxconfig 之外，您还可以在 $HOME/.torchxconfig 中创建一个，以覆盖或指定其他默认配置。此配置文件将覆盖在项目根目录中定义的配置文件之上。
配置选项具有以下优先级（从高到低）
1. 直接从 CLI 指定的选项
2. 如果设置了 TORCHXCONFIG 环境变量，则该文件中指定的选项
3. 如果未设置 TORCHXCONFIG 环境变量，则
  
  用户级 .torchxconfig ($HOME/.torchxconfig) 中指定的选项
  
  .torchxconfig 中指定的选项
4. 代码中的任何默认值
请注意，格式错误或无法识别的选项将被简单地跳过，不会应用

组件配置

您可以通过添加以 component: 为前缀的节来指定组件默认值。

[component:dist.ddp]
j=2x8
cpu=4

现在，当您运行 dist.ddp 组件时，这些配置会自动获取。

$ torchx run -s local_cwd dist.ddp
... runs with -j 2x8 --cpu 4

CLI 子命令配置

可以覆盖 torchx 子命令的默认参数。任何 --foo FOO 参数都可以通过相应的 [cli:<cmd>] 设置块进行设置。

对于 run 命令，您还可以设置 component 来设置要运行的默认组件。

[cli:run]
component=dist.ddp
scheduler=local_docker
workspace=file://some_workspace

编程用法¶

与 cli 不同，.torchxconfig 文件不会从 CWD 自动获取，如果您使用 torchx.runner.Runner 以编程方式运行组件。您必须手动指定包含 .torchxconfig 的目录。

以下是一个示例

from torchx.runner import get_runner
from torchx.runner.config import apply
import torchx.specs as specs

def my_component(a: int) -> specs.AppDef:
   # <... component body omitted for brevity ...>
   pass

scheduler = "local_cwd"
cfg = {"log_dir": "/these/take/outmost/precedence"}

apply(scheduler, cfg, dirs=["/home/bob"])  # looks for /home/bob/.torchxconfig
get_runner().run(my_component(1), scheduler, cfg)

您也可以指定多个目录（按优先顺序），这在您希望将个人配置覆盖置于项目定义的默认值之上的时候非常有用。

配置 API 函数¶

torchx.runner.config.apply(scheduler: str, cfg: Dict[str, Optional[Union[str, int, float, bool, List[str], Dict[str, str]]]], dirs: Optional[List[str]] = None) → None[source]¶

从指定的目录中加载 .torchxconfig INI 文件，并按顺序将调度器的运行配置应用于给定的 cfg。

如果未指定 dirs，则会在当前工作目录中查找 .torchxconfig。如果指定的目录中没有 .torchxconfig，则会忽略该目录。

请注意，给定 cfg 中已存在的配置优先于配置文件中的配置，并且只会添加新的配置。列表顺序加载的配置也是如此。

例如，如果 cfg={"foo":"bar"}，而配置文件为

# dir_1/.torchxconfig
[local_cwd]
foo = baz
hello = world

# dir_2/.torchxconfig
[local_cwd]
hello = bob

那么在方法调用之后，cfg={"foo":"bar","hello":"world"}。

torchx.runner.config.load(scheduler: str, f: TextIO, cfg: Dict[str, Optional[Union[str, int, float, bool, List[str], Dict[str, str]]]]) → None[source]¶: 从给定的配置文件 f（.INI 格式）中加载部分 [{scheduler}] 到提供的 runcfg 中，仅添加当前不在给定 runcfg 中的配置（例如，不覆盖 runcfg 中的现有值）。如果未找到部分，则不执行任何操作。

torchx.runner.config.dump(f: TextIO, schedulers: Optional[List[str]] = None, required_only: bool = False) → None[source]¶

将包含给定调度器名称的 :py:class:torchx.specs.runopts 的默认 INI 样式配置文件模板转储到 f 指定的文件类对象中。如果未指定 schedulers，则转储所有已知的注册调度器。

可选 runopts предварительно заполнены значениями по умолчанию. Необходимые runopts задаются с помощью заполнитель FIXME: .... Чтобы转储仅必需的 runopts，请传递 required_only=True.

每个调度器的 runopts 都写入名为 [{scheduler_name}] 的部分中。

例如

[kubernetes]
namespace = default
queue = #FIXME (str)Volcano queue to schedule job in

引发:: ValueError – 如果给定一个未知的调度器名称

torchx.runner.config.find_configs(dirs: Optional[Iterable[str]] = None) → List[str][source]¶

根据以下逻辑查找并返回指向 .torchxconfig 文件的文件路径

如果环境变量 TORCHXCONFIG 存在，则其值将以单元素列表的形式返回，并且不会搜索通过 dirs 参数指定的目录。
否则，将在 dirs 中查找 .torchxconfig 文件，并返回指向现有配置文件的文件路径。如果未指定 dirs 或为空，则 dirs 默认值为 [$HOME, $CWD]，其中 CWD 是当前工作目录。

torchx.runner.config.get_configs(prefix: str, name: str, dirs: Optional[List[str]] = None) → Dict[str, str][source]¶

获取 ["{prefix}:{name}"] 部分中的所有配置值。如果该部分不存在，则返回一个空映射。

示例

# for config file:
# [foo:bar]
# baz = 1

get_configs(prefix="foo", name="bar") # returns {"baz": "1"}
get_config(prefix="foo", name="barr") # returns {}

torchx.runner.config.get_config(prefix: str, name: str, key: str, dirs: Optional[List[str]] = None) → Optional[str][source]¶

获取 ["{prefix}:{name}"] 部分中 key 的配置值。如果不存在部分或键，则返回 None

示例

# for config file:
# [foo:bar]
# baz = 1

get_config(prefix="foo", name="bar", key="baz") == 1
get_config(prefix="foo", name="bar", key="bazz") == None
get_config(prefix="foo", name="barr", key="baz") == None
get_config(prefix="fooo", name="bar", key="baz") == None

torchx.runner.config.load_sections(prefix: str, dirs: Optional[List[str]] = None) → Dict[str, Dict[str, str]][source]¶

加载给定 .torchxconfig 文件中以指定前缀开头的部分的内容。返回一个包含部分名称的映射，其中不包含前缀，并将部分内容加载到一个映射中。 ":" 用作前缀分隔符。

以下是指定内置组件 dist.ddp 的默认值的示例配置格式

[component:dist.ddp]
j = 1x2
image = ghcr.io/foo:1

# calling `load_sections(prefix="component")` returns
#  {
#    "dist.ddp": {
#       "j":"1x2",
#       "image":"ghcr.io/foo:1",
#     },
#  }

部分中的键必须与组件函数的参数名称匹配。下面的示例显示了如何表示允许作为组件参数类型的各种类型。

[component:foo.bar]
int = 1
float = 1.2
bool = True # or False
str = foobar
list = a,b,c
map = A=B,C=D
vararg = -a b --c=d e

# to call the component as:
foo.bar(
   "-a", "b", "--c=d", "e",
   int=1,
   float=1.2,
   bool=True,
   str="foobar",
   list=["a", "b", "c"],
   map={"A":"B", "C": "D"})

.torchxconfig¶

CLI 用法¶

编程用法¶

配置 API 函数¶

文档

Tutorials

Resources