環境準備

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()

上述運行命令的參數說明如下：