torchx.specs 的

应用定义

class torchx.specs 中。AppDef（名称： str， 角色： List[torchx.specs.api.Role] = <factory>， 元数据： Dict[str， str] = <factory>）

表示由多个元数据组成的分布式应用程序。包含驱动程序的必要信息 将此应用提交到调度程序。Roles

参数

• name – 应用程序名称

• roles – 角色列表

• metadata – 特定于 AppDef 的配置，相比之下是特定于运行时的配置。RunConfig

角色

class torchx.specs 中。角色（名称： str， 图像： str， base_image： 可选[str] = 无， 入口点： str = '<MISSING>'， args： List[str] = <factory>， env： Dict[str， str] = <factory>， num_replicas： int = 1， max_retries： int = 0， retry_policy： torchx.specs.api.RetryPolicy = <RetryPolicy.APPLICATION： 'APPLICATION'>， 资源： torchx.specs.api.Resource = 资源（cpu=-1，gpu=-1，memMB=-1，capabilities={}），port_map：Dict[str， int] = <factory>）

在 . 例子：AppDef

1. 分布式数据并行应用 - 由单个角色 （trainer） 组成。

2. 具有参数服务器的应用程序 - 由多个角色（trainer、ps）组成。

注意

An 是安装在容器上的软件包 由调度程序调度。调度器上的容器指示 图像实际上是什么。图像可以像焦油球一样简单 或映射到 Docker 镜像。调度器通常知道如何 “拉” 为图像提供图像名称 （STR），该名称可以是简单名称 （例如 docker image） 或 URL （例如 ）。images3://path/my_image.tar

注意

如果调度程序支持 基础映像的概念。对于运行 Docker 容器的计划程序， 基础映像没有用，因为应用程序映像本身可以是 从基础镜像构建（使用 Dockerfile 的 Dockerfile）。但是，基础镜像对于满足以下条件的调度程序非常有用 使用没有内置 基础映像的概念。对于这些调度程序，指定一个基础镜像 包含依赖项，而主映像是实际的应用程序代码 可以更改应用程序代码，而不会产生 重建 Uber 神器的成本。base_imageFROM base/image:latest*.tar.gz

用法：

trainer = Role(name="trainer",
               image = "pytorch/torch:1",
               entrypoint = "my_trainer.py"
               args = ["--arg", "foo", ENV_VAR="FOOBAR"],
               num_replicas = 4,
               resource = Resource(cpu=1, gpu=1, memMB=500),
               port_map={"tcp_store":8080, "tensorboard": 8081})


# for schedulers that support base_images
trainer = Role(name="trainer", image="pytorch/torch:1", base_image="common/ml-tools:latest")...

参数

• name （名称） – 角色的名称

• image （映像） – 安装在容器上的软件包。

• base_image – 可选基础映像（如果调度程序支持映像叠加）

• entryPoint – 用于调用角色的命令（在容器内）

• args – 入口点 cmd 的命令行参数

• env – 环境变量映射

• replicas （副本） – 要运行的容器副本数

• max_retries – 放弃前的最大重试次数

• retry_policy – 副本失败时的重试行为

• resource （资源） – 角色的资源要求。应安排角色 通过容器上的调度器，它们中的每一个都应该有 at 最少的保证。num_replicasresource

• port_map – 角色的端口映射。key 是端口的唯一标识符 例如，“TensorBoard”：9090

pre_proc（调度器：str，dryrun_info：torchx.specs.api.AppDryRunInfo）→ torchx.specs.api.AppDryRunInfo

根据特定于角色的配置修改调度程序请求。 在 scheduler 期间为每个角色调用该方法 。 如果有多个角色，则为 Order 的 Order 的 Sequence 的 Zip 的 S Lam Ssubmit_dryrunAppDef.roles

class torchx.specs 中。RetryPolicy（value）

定义 中的 的重试策略。 该策略定义角色副本遇到故障时的行为：RolesAppDef

1. unsuccessful （non zero） 退出代码

2. 硬件/主机崩溃

3. 先买权

4. 驱逐

注意

并非所有计划程序都支持所有重试策略。 但是，所有计划程序都必须支持 。 有关更多信息，请参阅调度程序的文档 关于他们支持的重试策略和行为注意事项（如果有）。RetryPolicy.APPLICATION

1. REPLICA：替换 replica 实例。幸存的副本保持不变。

   用于重新启动手电筒坐标 和成员变更。否则，由应用程序 处理失败的副本离开和替换副本准入。torch_dist_role

2. APPLICATION：重新启动整个应用程序。

资源

class torchx.specs 中。资源（cpu： int， gpu： int， memMB： int， capabilities： Dict[str， Any] = <factory>）

表示 的资源要求 。Role

参数

• cpu – CPU 内核数（注意：不是超线程）

• gpu – GPU 数量

• memMB – 内存的 MB

• capabilities （功能） – 其他硬件规格（由调度程序解释）

static copy（原始：torchx.specs.api.Resource，**capabilities：Any）→ torchx.specs.api.Resource

复制资源并应用新功能。如果相同的功能 存在于原始资源中，并且作为参数，则 from 参数 将被使用。

torchx.specs 的get_named_resources（res： str） → torchx.specs.api.Resource

根据通过 entrypoints.txt 注册的字符串定义获取资源对象。

Torchx 实现了注册机制，包括 以下步骤：named_resource

1. 创建模块并定义资源检索函数：

# my_module.resources
from typing import Dict
from torchx.specs import Resource

def gpu_x_1() -> Dict[str, Resource]:
    return Resource(cpu=2, memMB=64 * 1024, gpu = 2)

2. 在 entrypoints 部分中注册资源检索：

[torchx.named_resources]
gpu_x_1 = my_module.resources:gpu_x_1

可以用作此函数的字符串参数：gpu_x_1

from torchx.specs import named_resources
resource = named_resources["gpu_x_1"]

宏

class torchx.specs 中。宏

定义可与 和 一起使用的宏。 宏将在运行时替换为其实际值。Role.entrypointRole.args

可用的宏：

1. img_root- 拉取的 container.image 的根目录

2. base_img_root- 拉取role.base_image的根目录

   （如果未设置base_image，则解析为 “<NONE>”）

3. app_id- 调度程序分配的应用程序 ID

4. replica_id- Role 副本的每个实例的唯一 ID，

   例如，具有 3 个副本的角色可以具有 0、1、2 作为副本 ID 来获取。请注意，当容器发生故障并且 replaced，则新容器将与它所替换的容器相同。例如，如果节点 1 失败且 被调度器替换，则替换节点也将 有。replica_idreplica_id=1

例：

# runs: hello_world.py --app_id ${app_id}
trainer = Role(name="trainer", entrypoint="hello_world.py", args=["--app_id", macros.app_id])
app = AppDef("train_app", roles=[trainer])
app_handle = session.run(app, scheduler="local", cfg=RunConfig())

类值（img_root： str， app_id： str， replica_id： str， base_img_root： str = '<NONE>'）

apply（role： torchx.specs.api.Role） → torchx.specs.api.Role

apply 将值应用于指定角色的副本并返回该副本。

substitute（arg： str） → str

substitute 将值应用于模板 arg。

运行配置

class torchx.specs 中。RunConfig（cfgs： Dict[str， Optional[Union[str， int， float， bool， List[str]]]] = <factory>）

应用程序的其他运行配置。这些通常是 未绑定的调度程序运行时配置/参数 到 也不是 .例如 应用程序的特定集群（在调度程序中） 应该提交给。由于可以启动相同的应用程序 转换为多种类型的集群（dev、prod） cluster id config 未绑定到 app。也不 这是否绑定到调度器，因为集群可以 按实例大小 （S、M、L） 或 抢占设置（例如，按需与 Spot）。AppDefScheduler

由于允许提交申请 发送给多个调度程序，希望提交相同的 app 添加到多个调度程序中，就可以 将所有 union 合并到一个 object 中。这 scheduler 实现将选择性地读取 它需要。SessionRunConfigs

这个类旨在简单序列化，并且 传递或保存，因此只允许基元 作为 config 值。如果调度程序需要的 简单原语（例如 str 列表）则取决于 scheduler 记录一种将此值编码为 str 并解析它（例如，将 str 列表表示为 逗号分隔的 str）。

用法：

# write
config = RunConfig()
config.set("run_as_user", "prod")
config.set("priority", 10)

# read
config.get("run_as_user") # "prod"
config.get("priority") # 10
config.get("never_set") # None

class torchx.specs 中。runopts

保存接受的调度程序运行配置 键、默认值（如果有）和帮助消息字符串。 这些选项由 提供并验证 in 反对用户提供。 允许默认值。必需的 opt 不能具有 非 None 默认值。SchedulerSession.runRunConfigNone

重要

此类没有访问器，因为它旨在 由 “help” 工具或作为异常 msg 的一部分构建和返回并打印出来。Scheduler.run_config_options

用法：

opts = runopts()

opts.add("run_as_user", type_=str, help="user to run the job as")
opts.add("cluster_id", type_=int, help="cluster to submit the job", required=True)
opts.add("priority", type_=float, default=0.5, help="job priority")
opts.add("preemptible", type_=bool, default=False, help="is the job preemptible")

# invalid
opts.add("illegal", default=10, required=True)
opts.add("bad_type", type=str, default=10)

opts.check(RunConfig)
print(opts)

add（cfg_key： str， type_： type[Optional[Union[str， int， float、 bool， List[str]]]]， help： str， default： Optional[Union[str， int， float， bool， List[str]]] = 无， 必需：bool = False）→ None

添加具有给定帮助字符串和值（如果有）的选项。如果未指定 ，则此选项 为必需选项。configdefaultdefault

static is_type（obj： 可选[Union[str， int， float， bool， List[str]]]]， tp： Type[Optional[Union[str， int， float， 布尔， List[str]]]]） → bool

如果类型为 ，则返回 True。类似于 isinstance（），但支持 tp = List[str] 因此可以用来验证 ConfigValue。objtp

resolve（config： torchx.specs.api.RunConfig） → torchx.specs.api.RunConfig

根据此检查给定的配置并设置默认配置 如果未设置。runopts

警告

此方法会更改提供的配置！

运行状态

class torchx.specs 中。AppStatus（state： torchx.specs.api.AppState， num_restarts： int = 0， msg： str = ''， structured_error_msg： str = '<NONE>'， ui_url： Optional[str] = None， roles： 列表[torchx.specs.api.RoleStatus] = <factory>）

的运行时状态。调度程序可以 返回任意文本消息（msg 字段）。 如果发生任何错误，调度程序可以填充 json 响应。AppDefstructured_error_msg

replicas表示任务中副本的状态。如果作业 运行多次重试时，该参数将包含 最近的重试。注意：如果之前的重试失败，但最近的重试失败 Retry Succeeded 或 In Progress，将不包含发生的错误。replicas

class torchx.specs 中。AppState（value）

应用程序的状态。应用程序从初始状态开始，经过 、 、 状态，最后到达最终状态：，''FAILED''， .UNSUBMITTEDSUBMITTEDPENDINGRUNNINGSUCCEEDEDCANCELLED

如果调度程序支持抢占，则应用程序将从 state 移动到 upon preempation。RUNNINGPENDING

如果用户停止应用程序，则应用程序状态会移动 to ，然后 to 实际取消作业的时间 由调度程序。STOPPEDCANCELLED

1. UNSUBMITTED - 应用程序尚未提交到调度程序

2. SUBMITTED - 应用程序已成功提交到调度程序

3. PENDING - 应用程序已提交到调度程序待分配

4. RUNNING - 应用程序正在运行

5. 成功 - 应用已成功完成

6. FAILED - 应用未成功完成

7. CANCELLED - 应用程序在完成之前已取消

torchx.specs 的复制状态

别名为torchx.specs.api.AppState