Python SDK使用说明

环境准备

1. 执行以下命令，安装FastGPU软件包。

   pip3 install --force-reinstall https://ali-perseus-release.oss-cn-huhehaote.aliyuncs.com/fastgpu/fastgpu-1.1.5-py3-none-any.whl

2. 执行以下命令，配置环境变量。

   配置环境变量时，需要您提前在您的ECS实例、本地机器或阿里云Cloud Shell工具上，获取阿里云账号AccessKey（AccessKey ID和AccessKey Secret）、默认地域以及默认可用区等信息。更多信息，请参见地域和可用区。

   export ALIYUN_ACCESS_KEY_ID=****          # 填入您的AccessKey ID
   export ALIYUN_ACCESS_KEY_SECRET=****      # 填入您的AccessKey Secret
   export ALIYUN_DEFAULT_REGION=cn-hangzhou  # 填入您希望使用的地域（Region）
   export ALIYUN_DEFAULT_ZONE=cn-hangzhou-i  # （选填）填入您希望使用的地域的可用区

3. 执行以下命令，在Python代码中导入FastGPU模块。

   import fastgpu

创建或获取实例

fastgpu.make_job方法会自动按规则创建实例集合。如果实例集合已存在，则返回实例集合。

job = fastgpu.make_job(
    name: str="",             # （必填）设置实例集群名称 
    instance_type: str="",    # （必填）设置实例类型 
    num_tasks: int=0,         # 设置创建实例个数
    install_script: str="",   # 设置初始化命令
    image_name: str="",       # 设置镜像名称
    image_type: str="",       # 设置镜像类型
    disk_size: int=500,       # 设置数据盘大小
    spot: bool=False,         # 设置是否抢占式实例
    confirm_cost: bool=False, # 设置是否跳过消费警告
    install_cuda: bool=False, # 设置是否自动安装GPU驱动
    mount_nas: bool=False     # 设置是否挂载NAS盘
)

上述示例涉及的参数说明如下：

返回值：返回一个Job对象，代表一个实例集群，实例集群可以通过访问Tasks成员访问到具体单个实例。job可以包含若干Task，关系如下图所示：

job = fastgpu.make_job(...) # 创建Job
job.run("ls -l")            # 集群执行ls -l命令
job.tasks[0].run("ls -l")   # 单个实例（task0）执行命令

代码示例：创建一个名称为fastgpu_test的job，该Job是包含2个实例（task）的对象，您可以通过访问Job对象的Tasks来访问创建出的实例列表。具体示例代码如下：

job = fastgpu.make_job(
    name="fastgpu_test",                   # 实例集群名称
    num_tasks=2,                           # 实例数量，创建2个实例
    instance_type="ecs.gn6v-c8g1.2xlarge", # 实例类型
    image_type="ubuntu_18_04",             # 实例镜像类型，比如为Ubuntu 18.04
    disk_size=500,                         # 数据盘大小为500 GB
    confirm_cost=True,                     # 是否确认消费警告
    spot=True,                             # 是否抢占型实例
    install_cuda=True,                     # 是否自动安装GPU驱动
    mount_nas=True                         # 是否自动挂载NAS盘
)
task1 = job.tasks[0]
task2 = job.tasks[1]

运行命令

集群或实例运行指定命令，运行完成后会将输出保存到指定目录下。

# 支持整个集群运行命令
job.run(cmd,                        # 运行的命令
         sudo=False,                # 是否以管理员权限运行
         non_blocking=False,        # 是否以非阻塞运行任务
         ignore_errors=False,       # 是否忽略错误，默认如果执行报错，则抛出一个异常
         max_wait_sec=365*24*3600,  # 最大超时时间
         show=False,                # 运行结束后是否输出结果
         show_realtime=False        # 是否实时打印输出
       )

# 同理也支持单实例运行命令
job.tasks[i].run(cmd, ...)

上述运行命令的参数说明如下：

代码示例：

# 集群运行 "ls"，列出每个实例工作目录下的文件和文件夹
job.run("ls")
# 单实例运行 "ls", 列出第i个实例工作目录下的文件和文件夹
job.tasks[i].run("ls")

文件传输

• 上传文件到集群或单个实例

  # 上传文件到集群
  job.upload(local_fn: str, remote_fn: str="", dont_overwrite: bool=False)
  # 上传文件到集群中第i个实例
  job.tasks[i].upload(local_fn: str, remote_fn: str="", dont_overwrite: bool=False)

  上述运行命令的参数说明如下：

  参数名称	是否必填	参数说明	参数示例
  Iocal_fn	是	本地文件路径。	设置需要上传到实例的文件路径，即 local_fn="/root/test_download.fn"。
  remote_fn	否	上传目标路径。 默认值：空。表示上传到和local_fn相同的路径下。	设置实例内文件路径，即 remote_fn="/root/test.txt"
  dont_overwrite	否	是否覆盖原有文件。 默认值为False，表示自动覆盖已存在的文件。	设置为不覆盖原有文件，即 dont_overwrite=True。

• 从集群或单个实例下载文件到本地

  # 集群下载文件
  job.download(remote_fn, local_fn: str="")
  # 集群中第i个实例下载文件
  job.tasks[i].download(remote_fn, local_fn: str="")

  重要

  当机器数量大于2台时，集群下载文件会引入文件冲突，不建议使用。

  上述运行命令的参数说明如下：

  参数名称	是否必填	参数说明	参数示例
  remote_fn	是	远程文件路径。	设置第i个实例中的文件路径，即 remote_fn="/root/test.txt"。
  local_fn	否	本地文件路径。 默认值：空。表示下载到和remote_fn相同的本地路径下。	设置下载到本地的文件路径，即 local_fn="/root/test_download.fn"。

代码示例：为集群中所有实例上传文件，并通过某一个实例下载到本地。

# 上传/root/test.txt到集群中所有实例的/root/下
job.upload("/root/test.txt")
# 从task[0]实例中下载txt文件到当前路径下
job.tasks[0].download("/root/test.txt", "./test.txt")

停止实例

停止集群或单个实例。

# 停止整个集群的实例。
job.stop(
    keep=False, # 停止集群后，是否仍然计费
    force=False # 是否强制停止
)

# 停止集群中第i个实例
job.tasks[i].stop(
    keep=False, # 停止实例后，是否仍然计费
    force=False # 是否强制停止
)

代码示例：

job.stop(force=True, keep=True) # 强制停止整个集群，并保持收费

上述运行命令的参数说明如下：

释放实例

永久删除集群或实例，释放实例占用的资源。

job.kill()          # 释放整个集群
job.tasks[i].kill() # 释放单个实例

代码示例：强制停止并释放一个正在运行的实例。

# 强制释放集群以及集群中的实例，即使实例处于Running状态
job.kill(force=True)
# 释放单个实例，此实例应处于停机状态
job.tasks[i].kill()

上述运行命令的参数说明如下：