Table of Contents
  • Docs >
  • 命令行工具 (CLI)
Shortcuts

命令行工具 (CLI)

命令行工具（hai-cli）是用户访问 HAI Platform 进行操作的终端工具，其中包括便捷的调试接口、提交/查看任务的接口、任务操作/查看任务输出的接口等。在网络可访问的条件下，命令行工具可以在集群外的用户终端使用，同步用户指定环境及工作区。

键入 hai-cli --help 即可查看所有支持的功能。

Usage: hai-cli COMMAND <argument>... [OPTIONS]

Options:
  --version   Show the version and exit.
  -h, --help  Show this message and exit.

Exec Commands:
  bash    在集群上运行 bash 脚本
  exec    在集群上运行 二进制 文件
  python  在集群上运行 bash 脚本
  run     根据 yaml 文件来运行一个任务，可以通过参数来覆盖配置;...

Task Manage Cmds:
  describe  打印任务的 schema yaml，可以在下次创建任务的时候使用
  list      列出用户任务列表, 用户要查看第几页的任务列表
  logs      查看任务日志
  ssh       登录到哪台机器，只能在开发容器内使用
  status    查询任务状态
  stop      关闭任务状态

Cluster Commands:
  nodes     查看节点信息

User Commands:
  init    初始化用户账户
  whoami  显示用户的个人信息, 包括集群用量、quota 等

UGC Commands:
  images     用户自定义镜像的管理接口
  workspace  haiworkspace

Other Commands:
  env     haienv

本文给出常见场景下的用法示例。

用例1： 使用客户端工具的基本流程

场景

用户开始使用 HAI Platform 平台，需要搭建个人运行环境、准备实验代码、数据等。通过HAI Platform启动的开发容器默认安装并配置了客户端，用户也可以在个人本地安装。

说明

使用 hai-cli 需要按用户信息初始化本地配置，支持用户创建个人虚拟环境，并且支持环境上传，确保本地和集群上环境一致。

注意：目前仅支持 bash, 如果要使用其它 shell，需要手动修改 venv 环境下的 activate 脚本。

步骤

  1. 在本地首次安装使用，执行 hai-cli init <token> --url <address-to-hai-server> 命令初始化 hai 客户端配置。初始化过程会生成配置文件 ~/.hai/conf.yaml。HAI Platform开发容器中使用则无需重复初始化。

  2. 使用 hai-cli whoami 查看用户个人信息，包括集群用量、配额等。

  3. 使用 haienv 工具创建及管理个人环境：

    haienv create <env_name>  # 创建虚拟环境
source haienv <env_name>  # 进入此虚拟环境
pip install <your_package>  # 在此虚拟环境下安装依赖包
conda install <your_package> # 在此虚拟环境下安装依赖包

    注意：在集群开发容器创建虚拟环境，可以选择继承集群基础环境，只做增量安装

示例

# 创建个人虚拟环境
haienv create extenv  ## 在基础环境上扩展，相同包可以覆盖基础环境里的版本
# 输出
#确认您要构建的虚拟环境版本为：3.8.10；扩展py38-202111环境
#Y/N: Y
#Collecting package metadata (current_repodata.json): ...working... done
#Solving environment: ...working... failed with repodata from current_repodata.json, will retry #with next repodata source.
#Collecting package metadata (repodata.json): ...working... done
#Solving environment: ...working... done
#......
#...
#...
#...
#Preparing transaction: ...working... done
#Verifying transaction: ...working... done
#Executing transaction: ...working... done
#创建虚拟环境成功，使用 source haienv extenv 进入

haienv list ## 列表查看虚拟环境
# 输出
"
当前虚拟环境目录为/root，如需更改请设置环境变量HAIENV_PATH
请在bash中使用以下命令加载env：source haienv <haienv_name>
其他环境
+------+-------------+------+--------+------------+----+
| user | haienv_name | path | extend | extend_env | py |
+------+-------------+------+--------+------------+----+
+------+-------------+------+--------+------------+----+
自己创建的环境
+---------+-------------+--------------------------------------+--------+-------------+--------+
| user    | haienv_name | path                                 | extend | extend_env  | py     |
+---------+-------------+--------------------------------------+--------+-------------+--------+
| hfadmin | extenv      | /hf_shared/hfai_envs/user/extenv_0   | True   | py38-202111 | 3.8.10 |
+---------+-------------+--------------------------------------+--------+-------------+--------+
...
"

haienv remove extenv ## 删除虚拟环境

用例2： 训练任务管理

场景

用户提交、查看、管理个人在集群上的任务。

说明

由于集群以分时调度的方式分配资源，每个任务实际上都是一个任务链(chain)。任务的 chain_status 有如下可能：

  1. waiting_init: 该任务处于排队状态，尚未被调度到；

  2. running: 该任务处于运行状态；

  3. suspended: 该任务被调度器打断了，处于挂起状态；

  4. finished: 该任务执行结束了。

另外，任务信息还包含运行节点信息，节点的状态有如下可能：

  1. created: 该任务节点处于创建过程中；

  2. building: 该任务节点处于初始化过程中；

  3. unschedulable: 该任务节点在等待资源施放；

  4. running: 该任务节点处于运行状态；

  5. succeeded_terminating / failed_terminating / stopped_terminating: 该任务节点处于结束态（正在退出过程中），_ 之前的描述词为其终态；

  6. succeeded / failed / stopped: 该任务节点已经完全退出。

步骤

  1. 执行 hai-cli run 通过提交yaml文件来运行一个任务，支持运行python文件或shell脚本。yaml格式参考API说明。

    hai-cli run /path/to/yaml_file

    另外也可使用 hai-cli python, hai-cli bash 或 hai-cli exec 提交任务执行。

    hai-cli python <experiment.py> # 本地运行，等同于运行 python xxx
hai-cli python <experiment.py> -- [CLUSTER_OPTIONS]  # 提交到集群作为新建任务运行，提交前请先检查工作区是否同步；集群任务参数详见api文档
hai-cli python <experiment.py> ++ [SIMULATE_OPTIONS] # 在本地运行，模拟集群任务响应

  2. 使用 hai-cli list, hai-cli status, hai-cli logs 等查看任务状态、日志等。

  3. 对于运行中或者等待中的任务，可以执行 hai-cli stop 发起停止。用户停止的任务不再进入调度。

示例

通过 hai-cli status <experiment> 查看任务的状态

# 未特殊指明，<experiment> 均使用 experiment_name
hai-cli status sample_exp
# 输出
"
==================== experiment ====================
+--------+------------+-------+--------------+------------+---------------+---------------------+
| id     | nb_name    | nodes | chain_status | task_type  | suspend_count | updated_at          |
+========+============+=======+==============+============+===============+=====================+
| 397246 | sample_exp | 1     | finished     | training   | 0             | 2021-09-23 11:04:20 |
+--------+------------+-------+--------------+------------|---------------+---------------------+
==================== jobs ====================
+------+---------+-------------+---------------------+
| rank | status  | node        | started_at          |
+======+=========+=============+=====================+
| 0    | stopped | hfai-rank-0 | 2021-09-23T10:25:26 |
+------+---------+-------------+---------------------+
...
"
# 加 --json 参数可以将任务转换成 json 格式输出
hai-cli status sample_exp --json

通过 hai-cli list 功能查看个人历史任务。该接口带有分页功能，其中页大小（page_size）不能超过50。

hai-cli list [--page=<page>] [--page_size=<page_size>]
# 可以通过 --page 和 --page_size 参数来拿到指定范围的任务
# 获取第7-8个任务
hai-cli list --page 4 --page_size 2
# 输出
"
现在查看的是第 4 页任务，共 5 页, 每页 2 个任务, 共 9 个任务
+--------+------------+-------+--------------+------------+---------------+---------------------+
| id     | nb_name    | nodes | chain_status | task_type  | suspend_count | updated_at          |
+========+============+=======+==============+============+===============+=====================+
| 396391 | sample_exp | 2     | finished     | training   | 0             | 2021-09-22 15:29:13 |
| 396388 | sample_exp | 1     | finished     | training   | 0             | 2021-09-22 14:31:16 |
+--------+------------+-------+--------------+------------+---------------+---------------------+
...
"

通过 hai-cli logs 查看任务日志。输出由“任务信息 + 任务日志”两部分构成。前半部分与 hai-cli status 相同，后半部分为用户任务输出的日志，在每条日志之前，会打印这条日志的时间戳。

# 持续打印 sample_exp rank 1 的日志：（rank 从 0 开始）
hai-cli logs -f sample_exp --rank 0
# 加上 -f 参数后，会持续追加打印日志，并且 tab 的自动补全只会补全运行中的任务
# 另外，大部分 hai-cli 命令均有 tab 自动补全的功能
# <experiment> 为 experiment_name 时，会选择同名任务中最后一个，如果想查看历史任务的 log，需要使用 experiment_id
# 输出
"
==================== experiment ====================
+---------+----- ------+-------+--------------+------------+---------------+---------------------+
| id      | nb_name    | nodes | chain_status | task_type  | suspend_count | created_at          |
+=========+============+=======+==============+============+===============+=====================+
| 396391  | sample_exp | 2     | finished     | training   | 0             | 2021-09-22 15:34:45 |
+---------+-------- ---+-------+--------------+------------+---------------+---------------------+
==================== jobs ====================
+------+---------+-------------+---------------------+
| rank | status  | node        | begin_at          |
+======+=========+=============+=====================+
| 0    | failed  | hfai-rank-0 | 2021-09-22T15:34:45 |
| 1    | stopped | hfai-rank-1 | 2021-09-22T15:34:45 |
+------+---------+-------------+---------------------+
====================  fetching  log on rank 0... ====================
[2021-09-22 15:34:53.282729] [训练前检查] 检查[MARSV2] cpu memory 24.0 < 100G and total gpu memory 0 < 100M 通过
...
"