Shortcuts

hfai.client

任务类

Experiment

任务类

创建任务

create_experiment_v2

根据 v2 配置文件创建任务

get_experiment

通过 name、id 或 chain_id 获取训练任务,不能都为空,只能获取自己的任务

get_experiments

获取自己最近提交的任务

任务管理

set_watchdog_time

设置任务超时时间,规定时间内无 log 该任务会被认为已失败,默认为 1800 秒

set_whole_life_state

设置 whole_life_state

get_whole_life_state

获取当前 chain_id 的上一个 id 任务留下来的 whole_life_state

receive_suspend_command

获取该任务是否即将被打断

go_suspend

通知 server 该任务可以被打断

Resource

用于提交任务时指定所需要的资源

Code

用于提交任务时指定代码

bind_hf_except_hook

该函数用于将 Process 类绑定异常 hook,在子进程发生异常时通知 server 将其强行关闭,并启动自我检查,发现硬件故障重启该任务

EXP_PRIORITY

set_priority

设置当前任务的优先级,注意如果你没有该优先级的权限可能会导致任务被立刻打断

class hfai.client.api.Experiment(**kwargs)[source]

任务类

包含如下属性:

  • id (int): 任务 id

  • nb_name (str): 任务名

  • user_name (str): 用户名

  • code_file (str): 训练任务代码的路径

  • workspace (str): 训练任务代码的 workspace

  • config_json (dict): 任务的配置信息,包括:priority (int),environment (dict[str, str]),whole_life_state (int)

  • group (str): 任务所在组

  • nodes (int): 任务占用节点数量

  • assigned_nodes (list[str]): 分配的节点

  • whole_life_state (int): 当前设置的 whole_life_state

  • star(bool): 是否是星标任务

  • first_id (int): 整个 chain_id 中最小的 id

  • backend (str): 任务所在环境

  • task_type (str): 任务类型

  • queue_status (str): 任务当前运行状态

  • priority (int): 任务当前的优先级

  • chain_id (str): 任务 chain_id

  • stop_code (int): 任务退出情况

  • worker_status (str): 任务结束时的状态

  • begin_at (str): 任务开始时间

  • end_at (str): 任务结束时间

  • created_at (str): 任务创建时间

  • id_list (list[int]): 整个 chain_id 的所有 id

  • begin_at_list (list[str]): 整个 chain_id 所有 id 的启动时间

  • end_at_list (list[str]): 整个 chain_id 所有 id 的结束时间

  • stop_code_list (list[int]): 整个 chain_id 所有 id 的退出情况

  • whole_life_state_list (list[int]): 整个 chain_id 所有 id 的最新 whole_life_state

  • _pods_ (list[Pod]): 该任务每个 pod 的各项参数

Examples:

from hfai.client import get_experiment
import asyncio
experiment: Experiment = asyncio.run(get_experiment(id=1))
log = asyncio.run(experiment.log_ng(rank=0))  # 获取 rank0 的日志
asyncio.run(experiment.stop())  # 结束该任务
async log_ng(rank, last_seen=None)

通过rank获取日志,last_seen用于断点续读

async suspend(restart_delay=0)

打断该任务,restart_delay 暂未实现

async stop()

结束该任务

schema()[source]

获取任务提交时候的 yaml schema :return:

async hfai.client.create_experiment_v2(config, **kwargs)[source]

根据 v2 配置文件创建任务

配置文件示例:

version: 2
name: test_create_experiment
priority: 20 # 内部用户 50 40 30 20, 外部用户 0
spec: # 任务定义,根据定义,将在集群上做下面的运行
  # cd /xxx/xxx; YOUR_ENV_KEY=YOUR_ENV_KEY python xxx.py --config config
  workspace: /xxx/xxx               # 必填
  entrypoint: xxx.py                # 必填, 若 entrypoint_binary 为 False 或者不填,那么支持 .py 或者 .sh, .sh 则使用 bash xxx.sh 运行;
                                    #      若 entrypoint_binary 为 True,那么认为 entrypoint 是可执行文件,直接使用 <entrypoint> 运行
  parameters: --config config       # 可选
  environments:                     # 可选
    YOUR_ENV_KEY: YOUR_ENV_VALUE
  entrypoint_executable: False      # 可选,不填则默认为 False,若为 True,那么认为 entrypoint 是可执行文件
resource:
  image: registry.high-flyer.cn/hfai/docker_ubuntu2004:20220630.2   # 可选,不指定,默认 default,通过 hfai 上传的 image,或者集群内建的 template
  group: jd_a100#heavy                                              # 可选, jd_a100, jd_a100#heavy, jd_a100#light, jd_a100#A, jd_a100#B
  node_count: 1                                                     # 必填
options: # 可选
  whole_life_state: 1   # hfai.get_whole_life_state() => 1
  mount_code: 2         # use 3fs prod mount
  py_venv: py38-202111 # 会在运行脚本前,source 一下 python 环境,根据输入不同选择 hf_env 或 hfai_env。
                       # 分为两类:1. py3-202111 => source hf_env3 202111; 2.1 hfai_env_name[hfai_env_owner] => source hfai_env hfai_env -u hfai_env_owner
                       #                                                 2.2 hfai_env_name => source hfai_env hfai_env_name  # 这个 hfai_env 是你自己的
                       # hf_env 可选: py3-202105, py3-202111, py38-202111, py38-202207
Parameters

config (str, StringIO, munch.Munch) – 配置路径,yaml 的 string,或 Munch

Returns

生成的任务

Return type

Experiment

Examples:

from hfai.client import create_experiment_v2
import asyncio
asyncio.run(create_experiment_v2('config/path'))  # python3.8以下可能不支持asyncio.run的用法,需要用其它异步调用接口

await create_experiment_v2('''
        version: 2
        name: test_create_experiment
        priority: 20
        ... yaml file
''')
async hfai.client.get_experiment(name=None, id=None, chain_id=None, **kwargs)[source]

通过 name、id 或 chain_id 获取训练任务,不能都为空,只能获取自己的任务

Parameters
  • name (str) – 任务名

  • id (int) – 任务 id

  • chain_id (str) – 任务 chain_id

Returns

返回的任务

Return type

Experiment

Examples

>>> from hfai.client import get_experiment
>>> import asyncio
>>> asyncio.run(get_experiment(id=1))  # python3.8以下可能不支持asyncio.run的用法,需要用其它异步调用接口
async hfai.client.get_experiments(page, page_size, only_star=False, select_pods=True, nb_name_pattern=None, task_type_list=['training', 'virtual'], worker_status_list=[], queue_status_list=[], tag_list=[], **kwargs)[source]

获取自己最近提交的任务

Parameters
  • page (int) – 第几页

  • page_size (int) – 每一页的任务个数

  • only_star (bool) – 只考虑 star 的任务(默认为 False

  • select_pods (bool) – 是否查询 pod

  • nb_name_pattern (str) – 查询 nb_name 带有这个字符串的任务

  • task_type_list (list[str]) – 查询 task_type,默认拿 training 和 validation

  • worker_status_list (list[str]) – 查询 worker_status

  • queue_status_list (list[str]) – 查询 queue_status

  • tag_list – 查询 tag

Returns

符合条件的任务总数,返回的任务列表

Return type

int, list[Experiment]

Examples

>>> from hfai.client import get_experiments
>>> import asyncio
>>> asyncio.run(get_experiments(page=1, page_size=10))  # python3.8以下可能不支持asyncio.run的用法,需要用其它异步调用接口
hfai.client.set_watchdog_time(seconds)[source]

设置任务超时时间,规定时间内无 log 该任务会被认为已失败,默认为 1800 秒

Parameters

seconds (int) – 超时时间,单位为秒

Examples

>>> from hfai.client import set_watchdog_time
>>> set_watchdog_time(1800)
hfai.client.set_whole_life_state(state, timeout=500, raise_exception=True)[source]

设置 whole_life_state

Parameters
  • state (int) – 想要设置的 whole_life_state

  • timeout (int) – 设置请求超时时间,默认为 500 秒

  • raise_exception (bool) – 调用runtime接口时发生异常是否需要抛出,默认为抛出

Examples

>>> from hfai.client import set_whole_life_state
>>> set_whole_life_state(100)
hfai.client.get_whole_life_state()[source]

获取当前 chain_id 的上一个 id 任务留下来的 whole_life_state

Returns

whole_life_state

Return type

int

Examples

>>> from hfai.client import get_whole_life_state
>>> get_whole_life_state()
hfai.client.receive_suspend_command(timeout=500, raise_exception=False)[source]

获取该任务是否即将被打断

Parameters
  • timeout (int) – 设置请求超时时间,默认为 500 秒

  • raise_exception (bool) – 调用runtime接口时发生异常是否需要抛出,默认为不抛出

Returns

表示是否即将被打断

Return type

bool

Examples

>>> from hfai.client import receive_suspend_command
>>> receive_suspend_command()
hfai.client.go_suspend(timeout=500, raise_exception=False)[source]

通知 server 该任务可以被打断

Parameters
  • timeout (int) – 设置请求超时时间,默认为 500 秒

  • raise_exception (bool) – 调用runtime接口时发生异常是否需要抛出,默认为不抛出

Examples

>>> from hfai.client import go_suspend
>>> go_suspend()
class hfai.client.Resource(async_init=False)[source]

用于提交任务时指定所需要的资源

Parameters

async_init (bool) – 是否异步初始化(默认为 False

Examples:

from hfai.client import Resource

resource = Resource()
resource.set_container('cuda_11')  # 使用 cuda_11 这个环境
resource.acquire(node_count=1)  # 申请1个节点

# 接下来将 resource 用于生成 experiment,详见 create_experiment
class hfai.client.Code(directory, entrypoint, parameters='')[source]

用于提交任务时指定代码

Parameters
  • directory (str) – 代码所在的 workspace 目录

  • entrypoint (str) – 代码入口,可以是 .py 或者 .sh 文件

  • parameters (str) – 代码参数,默认为空

Examples:

from hfai.client import Code

code = Code(directory='your/workspace/path', entrypoint='test.py')

# 接下来将 code 用于生成 experiment,详见 create_experiment
hfai.client.bind_hf_except_hook(f)[source]

该函数用于将 Process 类绑定异常 hook,在子进程发生异常时通知 server 将其强行关闭,并启动自我检查,发现硬件故障重启该任务

Parameters

f (class) – 传进来的 Process 类

Examples

>>> from hfai.client import bind_hf_except_hook
>>> from torch.multiprocessing import Process
>>> bind_hf_except_hook(Process)
class hfai.client.EXP_PRIORITY[source]
AUTO = -1
classmethod get_name_by_value(value)[source]
hfai.client.set_priority(priority, timeout=500, raise_exception=False)[source]

设置当前任务的优先级,注意如果你没有该优先级的权限可能会导致任务被立刻打断

Parameters
  • priority (int) – 设置的任务优先级

  • timeout (int) – 设置请求超时时间,默认为 500 秒

  • raise_exception (bool) – 调用runtime接口时发生异常是否需要抛出,默认为不抛出

Returns

是否设置成功

Return type

bool

Examples

>>> from hfai.client import set_priority, EXP_PRIORITY
>>> set_priority(EXP_PRIORITY.LOW)