.torchxconfig

状态：测试版

你可以通过将调度器运行配置（运行配置）存储在.torchxconfig文件中来为项目保存这些配置。 目前，此文件仅在从CLI运行组件时被读取和使用。

命令行接口使用方法

调度器配置

1. cd 文件放入您希望 .torchxconfig 文件被放置的目录中。 命令行界面只会从当前工作目录 (CWD) 中获取 .torchxconfig 文件， 因此请选择一个您通常运行 torchx 的目录。通常这是您的项目根目录。

2. 通过运行生成配置文件

   $ torchx configure -s <comma,delimited,scheduler,names>
   
   # -- or for all registered schedulers --
   $ torchx configure
   

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

   $ cat .torchxconfig
   [local_cwd]
   
   [kubernetes]
   queue = #FIXME:(str) Volcano queue to schedule job in
   

4. .torchxconfig 在INI格式中，且部分名称映射到调度器名称。 每个部分包含调度器的运行配置为 $key = $value 对。 您可能会发现某些调度器的部分为空，这意味着 调度器为其所有运行配置定义了合理的默认值，因此在运行时不需要指定运行配置。如果您想覆盖默认值，可以添加它们。 提示： 要查看调度器的所有运行选项，请使用 torchx runopts <scheduler_name>。

5. 带有FIXME占位符的部分是调度器所需的运行配置。请用适用于您的值进行替换。

6. 重要: 如果您对特定运行配置提供的调度器默认值感到满意，您 不应 在.torchxconfig中冗余地指定它们，因为调度器可能会在稍后决定更改默认值，这会使您留下过时的默认值。

7. 现在你可以运行你的组件而无需每次都指定调度器的运行配置。只需确保你运行 torchx cli 的目录实际上 包含 .torchxconfig!

   $ ls .torchxconfig
   .torchxconfig
   
   $ torchx run -s local_cwd ./my_component.py:train
   

8. 此外，还可以指定不同于.torchxconfig的其他配置文件在运行时加载。要求是通过环境变量TORCHX_CONFIG指定配置文件路径。它还禁用了从多个目录加载层次结构配置文件的功能，与其它情况不同。

9. 用户级别 .torchxconfig 除了在项目目录根部的项目级别的 .torchxconfig 文件外， 你还可以在 $HOME/.torchxconfig 中创建一个以覆盖或指定额外的默认配置。 此配置文件将覆盖项目根部定义的文件。

10. Config options take the following precedence (high to low):

    1. 从命令行接口直接指定的选项

    2. 如果设置了 TORCHXCONFIG 环境变量，则使用该文件中指定的选项

    3. If TORCHXCONFIG env variable is not set,

       1. 用户级别中指定的选项 .torchxconfig ($HOME/.torchxconfig)

       2. 在 .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

命令行子命令配置

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

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

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

程序化用法

与命令行界面不同，.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]]]], dirs: Optional[List[str]] = None) → None

从指定目录按顺序加载一个 .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]]]]) → None

加载配置文件 [{scheduler}] 中的节 f（.INI 格式）到提供的 runcfg 中，只添加当前不在给定 runcfg 中的配置（例如不会覆盖 runcfg 中现有的值）。如果未找到节，则不执行任何操作。

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

将包含给定调度器名称的 :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]

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

1. 如果环境变量 TORCHXCONFIG 存在，则返回其值在一个单元素列表中，并且不会搜索通过 dirs 参数指定的目录。

2. 否则，查找 .torchxconfig 文件在 dirs 中，并返回现有配置文件的路径。如果未指定或为空，则此方法将在当前工作目录 (CWD) 中查找 .torchxconfig 文件并返回其路径。

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

获取配置值中的所有内容 ["{prefix}:{name}"]。 或者如果不存在该部分，则为空映射。

Example:

# 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]

获取配置值，对于 key 在 ["{prefix}:{name}"] 部分。 或者 None 如果没有部分或键存在

Example:

# 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]]

加载给定的.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"})