CLI命令行工具

更新时间：2024-11-20

您可以通过客户端工具管理资源池、队列以及训练任务。

安装

依赖

服务器上已经安装python（版本>=3.8）、pip软件

安装客户端工具

pip install https://bj.bcebos.com/v1/cce-ai-aihc/aihc-cli/aihc-1.3.0-py3-none-any.whl

命令

查看版本信息

用法

aihc version

示例

aihc version

获取帮助信息

用法

aihc help

示例

aihc help

输出：

Aihc provide baige training task management capabilities.

Find more information at https://cloud.baidu.com/doc/AIHC/s/Xm1g74vkc.

Usage:
    aihc [commands] [flags]

Resources Management Commands:
    pool       资源池管理
    queue      队列管理
    job        任务管理
    logs       任务日志管理

Other Commands:
    config     设置配置信息
    version    显示版本信息
    help       输出帮助文档

配置

在使用命令行工具之前，必须配置包含 AK、SK、Region 在内的用户身份凭证。

请确保该用户已经申请百舸使用依赖的必需权限，详情请参考：权限管理

用法

aihc config [flags]

输入参数：

参数	类型	必填	默认值	说明
--access-key/--ak	string	是	-	百度云安全认证Access Key
--secret-key/--sk	string	是	-	百度云安全认证Secret Key
--region	string	否	cn-beijing	地域
--username	string	否	-	私有镜像仓库用户名
--password	string	否	-	私有镜像仓库密码

region 列表如下：

地域	Region	host
北京	cn-beijing	`aihc.bj.baidubce.com`
广州	cn-guangzhou	`aihc.gz.baidubce.com`
苏州	cn-suzhou	`aihc.su.baidubce.com`
保定	cn-baoding	`aihc.bd.baidubce.com`
武汉	cn-wuhan	`aihc.fwh.baidubce.com`
阳泉	cn-yangquan	`aihc.yq.baidubce.com`

示例：

aihc config --access-key <AccessKey> --secret-key <SecretKey> --region cn-beijing --username <Username> --password <Password>
aihc config --ak <AccessKey> --sk <SecretKey>
aihc config --region cn-beijing
aihc config --username <Username> --password <Password>
Configuration saved to: ~/.aihc/config

资源池管理

资源池相关接口

用法

aihc pool [command] [flags]

获取资源池列表

用法

aihc pool list/ls

输入参数

无

输出参数

字段	说明
ID	资源池ID
NAME	资源池名称
STATUS	状态（运行中/创建中/...）
REGION	地域
NODES(READY/TOTAL)	节点数（ready数量/总数量）
GPUS(ALLOCATED/TOTAL)	GPU（已分配数/总卡数）
CREATEDTIME(UTC+8)	资源池创建时间

示例

aihc pool list

获取资源池详情

用法

aihc pool get [flags] POOL_ID

输入参数

无

输出参数

字段	说明
ID	资源池ID
NAME	资源池名称
STATUS	状态（运行中/创建中/...）
REGION	地域
NODES(READY/TOTAL)	节点数（ready数量/总数量）
GPU(ALLOCATED/TOTAL)	GPU（已分配数/总卡数）
CREATOR	资源池创建人
CREATEDTIME(UTC+8)	资源池创建时间
PFS_ID	关联的PFSID
CPROM_ID	关联的CRPOM_ID

队列管理

队列相关接口

用法

aihc queue [command] [flags]

获取队列列表

用法

aihc queue list/ls [flags]

输入参数

参数	类型	必填	默认值	说明
--pool/-p	string	是	-	资源池ID

输出参数

字段	说明
NAME	队列名称
GPU_TYPE	GPU卡类型
GPU(ALLOCATED/TOTAL)	GPU（已分配数/总卡数）
NOTE	用户自定义的备注信息
CREATEDTIME(UTC+8)	资源池创建时间

示例

aihc queue list --pool <PoolId>

获取队列详情

用法

aihc queue get QUEUE_NAME

输入参数

参数	类型	必填	默认值	说明
--pool/-p	string	是	-	资源池ID

输出参数

字段	说明
NAME	队列名称
TYPE	队列类型
STATE	队列状态
GPU_TYPE	GPU卡类型
GPU(ALLOCATED/TOTAL)	GPU（已分配卡数/总卡数）
DISABLE_OVERSELL	是否支持超发
RECLAIMABLE	是否可被抢占
NOTE	用户自定义的备注信息
CREATEDTIME(UTC+8)	队列创建时间

示例

aihc queue get -p <PoolId> <QueueName>

任务管理

任务相关命令

单任务提交

单个提交任务，只能指定单个数据源

用法

aihc job submit [flags]

输入参数

参数	类型	必填	默认值	说明
--pool/-p	string	是	-	资源池ID
--name/-n	string	是	-	任务名称
--framework/-F	string	否	pytorch	任务框架，支持pytorch/mpi
--queue/-q	string	否	default	资源队列名称
--image/-i	string	是	-	镜像的地址
--username	string	否	-	访问私有镜像仓库的配置，优先使用用户命令行输入，然后使用配置文件中的配置。
--password	string	否	-	访问私有镜像仓库的配置，优先使用用户命令行输入，然后使用配置文件中的配置。
--replicas	int	否	1	训练任务的节点数
--command/-c	string	否		指定训练任务的入口命令,`--command`和`--script-file`参数二选一注意事项： 1. 当命令行参数中的字符串包含空格时，需要使用引号（单引号 ' 或双引号 "）来确保整个字符串被视为一个单独的参数 2. 如果字符串内部同时包含单引号和双引号，则可能需要使用转义字符 \ 来避免解析错误，例如：`"echo \"Hello\""` 3. 转义字符：在命令行中使用路径或包含特殊字符的字符串时，可能需要使用转义字符。例如，Windows 系统中的路径可能需要将反斜杠 (`\`) 作为转义字符。如`C:\\Users\\username\\file.txt` 推荐：如执行命令较长，建议使用`--script-file`参数
--script-file	string	否	-	命令脚本的路径，以脚本的方式指定训练任务的入口命令 `--command`和`--script-file`参数二选一
--env/-e	string	否	-	指定的环境变量，值为KEY=VALUE形式，可以指定多个
--gpu/-g	string	否	-	训练时每个训练节点的GPU型号和数量，值为KEY=VALUE形式，key为GPU的型号，value是卡数
--cpu	float	否	-	cpu配额，单位核
--memory	float	否	-	内存配额，单位GiB
--share-memory	int	否	10	共享内存，单位GiB
--rdma/-r	bool	否	false	是否开启rdma
--hostnetwork	bool	否	false	是否开启宿主机网络
--ds-type	string	否		数据集类型，仅支持pfs、hostpath
--ds-name	string	否	-	数据集名称，类型为pfs时输入pfsid，如是hostpath则自定义名称
--ds-mountpath	string	否	-	容器内挂载路径
--ds-sourcepath	string	否	-	如数据集类型是pfs，这里需要填写pfs实例挂载子路径（请确保该子路径存在；如不填写默认为根路径）如数据集类型是hostpath，填写hostpath本地路径
--ds-readonly	bool	否	false	是否只读
--faulttolerance	bool	否	false	是否开启容错备注：mpijob暂不支持设置容错
--label	string	否		训练任务标签，值为KEY=VALUE形式，可以指定多次
--priority	string	否	normal	任务优先级，支持高（high）、中（normal）、低（low）
--log	bool	否	false	是否支持日志持久化

输出参数

Job <JobName>/<JobId> was created

示例

aihc job submit --pool cce-**** \
                --name test-pytorch \
                --priority high \
                --script-file /root/file.txt \
                --image registry.baidubce.com/aihc-aiak/aiak-megatron:ubuntu20.04-cu11.8-torch1.14.0-py38_v1.2.7.12_release \
                --label key=value \
                --gpu baidu.com/a100_80g_cgpu=8 \
                --env CUDA_DEVICE_MAX_CONNECTIONS=1 \
                --ds-type pfs \
                --ds-name pfs-**** \
                --ds-mountpath /mnt/cluster
                
aihc job submit --pool cce-**** \
                --name test-pytorch \
                --priority high \
                --command "sleep 10" \
                --image registry.baidubce.com/aihc-aiak/aiak-megatron:ubuntu20.04-cu11.8-torch1.14.0-py38_v1.2.7.12_release \
                --label key=value \
                --gpu baidu.com/a100_80g_cgpu=8 \
                --env CUDA_DEVICE_MAX_CONNECTIONS=1 \
                --ds-type pfs \
                --ds-name pfs-**** \
                --ds-mountpath /mnt/cluster

批量任务提交

批量提交任务，指定任务串行/并行执行。

用法

aihc job batch [flags]

输入参数

参数	类型	必填	默认值	说明
--pool/-p	string	是	-	资源池ID
--job-file/-f	string	是	-	脚本路径，内容是yaml格式，定义多个任务的配置
--username	string	否	-	访问私有镜像仓库的配置，优先使用用户命令行输入，然后使用配置文件中的配置。
--password	string	否	-	访问私有镜像仓库的配置，优先使用用户命令行输入，然后使用配置文件中的配置。
--parallel	bool	否	false	--parallel 为false：串行创建任务：前序任务执行状态为Succeeded才继续执行后续任务；如前序任务状态为Failed或者被删除，后续未执行的任务终止提交执行。 --parallel=true、--parallel为 true则并行创建任务。备注: 1. 串行执行任务时，请勿退出执行流程，否则后续任务无法执行 2. 如资源内有任务名称和批量执行的任务名称重复：对于串行执行的任务，整个串行任务会直接退出不进行创建；对于并行执行任务，非重名任务正常创建，重名任务不创建

Job-file内容参数（yaml格式）

参数	类型	必填	默认值	说明
name	string	是	-	任务名称，支持小写字母、数字以及 - 且开头必须是小写字母，结尾必须是小写字母或数字，长度1-50
queue	string	否	default	资源队列名称
jobFramework	string	否	pytorch	任务框架，pytorch/mpi
priority	string	否	normal	调度优先级，支持高（high）、中（normal）、低（low），默认值：normal
scriptFile	string	否	-	脚本文件的路径，以文件方式指定训练任务的入口命令 `command`和`scriptFile`参数二选一
command	string	否	-	指定训练任务的入口命令,`command`和`scriptFile`参数二选一
image	string	是	-	镜像的URL
replicas	int	否	1	分布式训练任务的节点数
envs	string	否	-	训练任务的环境变量，值为：KEY=VALUE形式，可以指定多个
labels	string	否		训练任务标签，值为：KEY=VALUE形式，可以指定多个
hostNetwork	bool	否	false	是否开启宿主机网络
faultTolerance	bool	否	false	是否开启容错，mpijob不支持开启训练容错
resources	object	否	false	任务资源申请配置，配置详见下方字段描述
datasources	object	否	false	数据集挂载配置，配置详见下方字段描述

resources

参数	必填	默认值	说明
gpu	否	0（不申请GPU资源）	训练时每个训练节点的GPU型号和数量，值为：KEY=VALUE形式，key为GPU的型号，value是卡数
cpu	否	-	cpu配额，单位核，不填写默认使用整机资源
memory	否	-	内存配额，单位GiB，不填写默认使用整机资源
sharedMemory	否	10	共享内存，单位GiB
rdma	否	false	是否开始 rdma

datasources

参数	必填	默认值	说明
type	否		可选值：pfs、hostpath
name	否	-	如type为pfs，此值为pfsid；如type为hostpath，则自定义存储卷名称；
mountPath	否	-	容器内挂载路径
sourcePath	否	/ (根路径)	如type为pfs，此值为pfs的子路径，请确保该路径提前存在；如type为hostpath，此值为主机路径

job-file示例

JobFile:
  - name: llama2
    queue: default
    jobFramework: # 可选值：pytorch/mpi
    priority: normal
    scriptFile: # 训练执行命令，可以以文档的形式给出，scriptFile、command二选一填写
    command: |-
      #!/bin/bash
      sleep 10
    image: registry.baidubce.com/cce-ai-native/aiak-megatron:0703
    replicas: 2
    hostNetwork: true
    faultTolerance: true
    resources:
      gpu: "baidu.com/a100_80g_cgpu=8"# 单实例的GPU数量
      cpu: 90 # cpu
      memory:1000
      sharedMemory: 10
      rdma: true 
    datasources: 
      - type: pfs
        name: pfs-****  # pfsid
        mountPath: /mnt/cluster # 容器挂载路径
        sourcePath: /

输出

Job <JobName>/<JobId> was created

示例

jobfile示例：

JobFile:
  - name: test-mpi-1
    queue: default
    jobFramework: pytorch
    command: |-
      #!/bin/bash
      sleep 10
    image: registry.baidubce.com/cce-ai-native/aiak-megatron:0703
    replicas: 1
    envs: ["a=b","c=d","e=2"]
    labels: ["key=value"]
    hostNetwork: false
    faultTolerance: false
    resources:
      rdma: false
    datasources:
      - type: pfs
        name: pfs-****
        sourcePath: /mnt/a
        mountPath: /mnt/PFS
      - type: pfs
        name: pfs-****
        sourcePath: /mnt/b
        mountPath: /mnt/PFS2
  - name: test-mpi-2
    queue: default
    jobFramework: pytorch
    command: |-
      #!/bin/bash
      sleep 10
    image: registry.baidubce.com/cce-ai-native/aiak-megatron:0703
    replicas: 1
    envs: ["a=b","c=d","e=2"]
    labels: ["key=value"]
    hostNetwork: false
    faultTolerance: false
    resources:
      rdma: false
    datasources:
      - type: pfs
        name: pfs-****
        sourcePath: /mnt/a
        mountPath: /mnt/PFS
      - type: pfs
        name: pfs-****
        sourcePath: /mnt/b
        mountPath: /mnt/PFS2
  - name: test-mpi-3
    queue: default
    jobFramework: pytorch
    command: |-
      #!/bin/bash
      sleep 30
    image: registry.baidubce.com/cce-ai-native/aiak-megatron:0703
    replicas: 1
    envs: ["a=b","c=d","e=2"]
    labels: ["key=value"]
    hostNetwork: false
    faultTolerance: false
    resources:
      rdma: false
    datasources:
      - type: pfs
        name: pfs-****
        sourcePath: /mnt/a
        mountPath: /mnt/PFS
      - type: pfs
        name: pfs-****
        sourcePath: /mnt/b
        mountPath: /mnt/PFS2

提交示例

aihc job batch -f ./job.yaml -p cce-****

获取任务列表

用法

aihc job list/ls [flags]

输入参数

参数	类型	必填	默认值	说明
--pool/-p	string	是	-	资源池ID
--queue/-q	string	否	-	队列名称
--framework/-F	string	否	-	任务类型
--name	string	否	-	jobname，支持模糊匹配
--start-time	string	否	-	查询区间的起始时间，使用任务的创建时间来过滤，例如：YYYY-MM-DDTHH:MM:SS+08:00或YYYY-MM-DDTHH:MM:SSZ
--end-time	string	否	-	查询区间的截止时间，使用任务的创建时间来过滤，例如：YYYY-MM-DDTHH:MM:SS+08:00或YYYY-MM-DDTHH:MM:SSZ

输出参数

字段	说明
NAME	任务名称
ID	任务ID
POOL_ID	资源池ID
QUEUE	队列名称
FRAMEWORK	任务框架类型
STATUS	运行状态
WORKERS（READY/TOTAL）	任务节点数量
GPU	分配的GPU数量
CREATOR	创建人
CREATEDTIME（UTC+8）	资源池创建时间

示例

aihc job list --pool <PoolID>
aihc job list --pool <PoolID> --queue default   
aihc job list --pool <PoolID> --framework pytorch    
aihc job list --pool <PoolID> --queue default --framework pytorch

获取任务详情

用法

aihc job get [flags] Job_ID

输入参数

参数	类型	必填	默认值	说明
--pool/-p	string	是	-	资源池id
--pods	bool	否	false	首是否展示作业的实例信息

输出

--pods=false时的数据：

字段	说明
NAME	任务名称
POOL_ID	资源池ID/名称
QUEUE	队列名称
FRAMEWORK	任务框架类型
PRIORITY	优先级
IMAGE	镜像
TOLERANCE	是否开启容错
HOSTNETWORK	是否开启 hostnetwork
RDMA	是否开启 rdma
ENV	环境变量
LABEL	标签
STATUS	运行状态
WORKERS（READY/TOTAL）	任务节点数量
GPU	分配的GPU数量
CPU	分配的CPU数量
MEMORY	分配的内存容量
SHARE_MEMORY	分配的共享内存容量
PFS_TYPE	pfs类型
PFS_ID	pfsid
MOUNTPATH	挂载路径
SOURCEPATH	源路径
CREATOR	任务创建人
CREATEDTIME（UTC+8）	任务创建时间

--pods=true时的输出：

字段	说明
PODNAME	pod名称
WORKERTYPE	worker的类型master/worker
IP	POD IP
STATUS	运行状态
GPU	分配的GPU数量
STARTTIME	POD启动时间
FINISHTIME	POD结束时间

示例

aihc job get -p cce-**** <JobName>

停止训练任务

用法

aihc job stop [flags] Job_ID

输入参数

参数	类型	必填	默认值	说明
--pool/-p	string	是	-	资源池名称

示例

aihc job stop <JobId> --pool <PoolId>
Job <JobId> in <PoolId> was stopping

删除训练任务

用法

aihc job delete [flags] Job_ID

输入参数

参数	类型	默认值	说明	必填
--pool/-p	string	-	资源池id	是

输出

Job <JobId>/<JobName> in <PoolId> was deleted

示例

aihc job delete -p <PoolId> <JobId> 
Job <JobId>/<JobName> in <PoolId> was deleted

查询任务日志

用法

aihc logs [flags] Job_ID

输入参数

参数	类型	必填	默认值	说明
--pool/-p	string	是	-	资源池id
--tail/-t	int	否	-	输出日志行数，不填写默认全部日志
--podname	string	是	-	pod名称
--start-time	string	否	-	日志查询的起始时间，例如：YYYY-MM-DDTHH:MM:SS+08:00或YYYY-MM-DDTHH:MM:SSZ

示例

aihc logs -p <PoolId> <JobId> 
iteration    77889/  100000 | consumed samples:       623112 | elapsed time per iteration (ms): 853.1 | learning rate: 2.999E-04 | global batch size:     8 | loss scale: 1.0 | number of skipped iterations:   1 | number of nan iterations:   1 |

SDK参考

常见问题

百度智能云

百舸异构计算平台 AIHC

百舸异构计算平台 AIHC

CLI命令行工具

安装

依赖

安装客户端工具

命令

查看版本信息

获取帮助信息

配置

资源池管理

获取资源池列表

获取资源池详情

队列管理

获取队列列表

获取队列详情

任务管理

单任务提交

批量任务提交

获取任务列表

获取任务详情

停止训练任务

删除训练任务

查询任务日志