.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 。
带有FIXME占位符的部分是调度程序所需的运行配置。请将这些替换为适用于您的值。
重要提示： 如果您对调度程序为特定运行配置提供的默认值感到满意，您不应在.torchxconfig中冗余地指定相同的默认值。这是因为调度程序可能会在以后决定更改默认值，这将使您保留一个过时的默认值。
现在你可以运行你的组件，而不必每次都指定调度器运行配置。只需确保你运行torchx cli的目录中确实有.torchxconfig！
```
$ ls .torchxconfig
.torchxconfig

$ torchx run -s local_cwd ./my_component.py:train
```
此外，可以在运行时指定不同于.torchxconfig的配置文件。要求是配置路径由环境变量TORCHX_CONFIG指定。它还禁用了从多个目录层次加载配置文件的情况，否则会出现这种情况。
用户级别的 .torchxconfig 除了项目目录根目录下的项目级 .torchxconfig 外，你还可以在 $HOME/.torchxconfig 中创建一个来覆盖或指定额外的默认配置。此配置文件将覆盖项目根目录中定义的配置文件。
Config options take the following precedence (high to low):
1. 直接从CLI指定的选项
2. 如果设置了TORCHXCONFIG环境变量，则使用该文件中指定的选项
3. If TORCHXCONFIG env variable is not set,
  
  在用户级别的 .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:] 设置块来设置。

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

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

编程使用¶

与命令行界面不同，如果你使用torchx.runner.Runner以编程方式运行你的组件，.torchxconfig文件不会自动从CWD中获取。你需要手动指定包含.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，则转储所有已知的已注册调度程序。

可选的运行选项已预先填充其默认值。必需的运行选项使用FIXME: ...占位符设置。要仅转储必需的运行选项，请传递required_only=True。

每个调度器的运行选项写在名为 [{scheduler_name}]的部分。

例如：

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

Raises:: 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"})