Prerequisites

• Data has been prepared. Specifically, you have created an available dataset in ModelArts, or you have uploaded the dataset used for training to the OBS directory.
• If the algorithm source is Custom, create an image and upload the image to SWR. For details, see Creating and Uploading a Custom Image.
• The training script has been uploaded to the OBS directory.
• At least one empty folder has been created on OBS for storing the training output.
• The account is not in arrears because resources are consumed when training jobs are running.
• The OBS directory you use and ModelArts are in the same region.

Precautions

• In the dataset directory specified for a training job, the names of the files (such as the image file, audio file, and label file) containing data used for training contain 0 to 255 characters. If the names of certain files in the dataset directory contain over 255 characters, the training job will ignore these files and use data in the valid files for training. If the names of all files in the dataset directory contain over 255 characters, no data is available for the training job and the training job fails.
• In the training script, the Data Source and Training Output Path parameters must be set to the OBS path. You are advised to use the MoXing interface to perform read and write operations in the path.

Creating a Training Job

1. Log in to the ModelArts management console. In the left navigation pane, choose Training Management > Training Jobs. By default, the system switches to the Training Jobs page.
2. In the upper left corner of the training job list, click Create to switch to the Create Training Job page.
3. Set related parameters and click Next.
   1. Set the basic information, including Billing Mode, Name, Version, and Description. The Version information is automatically generated by the system and named in an ascending order of V001, V002, and so on. You cannot manually modify it.
      Specify Name and Description according to actual requirements.

      Figure 1 Setting basic information about the training job
      
   2. Set job parameters, including the data source, algorithm source, and more. For details, see Table 1.
      Figure 2 Custom as the algorithm source
      

      Table 1 Job parameter description

      Parameter	Sub-Parameter	Description
      One-Click Configuration	-	If you have saved job parameter configurations in ModelArts, click One-Click Configuration and select an existing job parameter configuration as prompted to quickly complete parameter setting for the job.
      Algorithm Source	Custom	For details about custom image specifications, see Specifications for Custom Images Used for Training Jobs. Image Path: SWR URL generated after the image is uploaded to SWR. For details, see 3.b.i. Code Directory: OBS path for storing the training code file. Boot Command: boot command after the image is started. For details, see 3.b.ii.
      Data Source	Dataset	Select an available dataset and its version from the ModelArts Data Management module. Dataset: Select an existing dataset from the drop-down list. If no dataset is available in ModelArts, no result will be displayed in the drop-down list. Version: Select a version according to the Dataset setting.
      	Data path	Select the training data from your OBS bucket. On the right of the Data path text box, click Select. In the dialog box that is displayed, select an OBS folder for storing data.
      Training Output Path	-	Storage path of the training result NOTE: To avoid errors, you are advised to select an empty directory for Training Output Path. Do not select the directory used for storing the dataset for Training Output Path.
      Environment Variable	-	Add environment variables based on your image file. This parameter is optional. You can click Add Environment Variable to add multiple variable parameters. For details about environment variables, see 3.b.iii.
      Job Log Path	-	Select a path for storing log files generated during job running.

      Pay special attention to the settings of the following job parameters:

      1. Image Path
         SWR URL generated after the image is uploaded to SWR.

         Figure 3 SWR image address
         
      2. Boot Command

         Boot command after the image is started. The basic format is as follows:

         bash /home/work/run_train.sh {UserCommand}

         bash /home/work/run_train.sh [python/bash/..] {file_location} {file_parameter}

         run_train.sh is the training boot script. After this script is executed, ModelArts recursively downloads all content in the code directory to the local path of the container. The local path is in the format of /home/work/user-job-dir/${Name of the last level in the code directory}/.

         For example, if the OBS path of the training code file is obs://obs-bucket/new/train.py and the code directory is obs://obs-bucket/new/, the local path of the container is /home/work/user-job-dir/new/. The local training code path of the container is /home/work/user-job-dir/new/train.py. Then, you can set the boot command to the following: bash /home/work/run_train.sh python /home/work/user-job-dir/new/train.py {python_file_parameter}

         For details about the setting example, see Example: Creating a Training Job Using a Custom Image.

         

         If you create a training job using a custom image, ModelArts allows you to customize the boot command. The following are two basic formats for the boot command:

         bash /home/work/run_train.sh {UserCommand}

         bash /home/work/run_train.sh [python/bash/..] {file_location} {file_parameter}

         run_train.sh is the training boot script. When creating a custom image, you can implement the training boot script or place the training code in the custom image environment in advance to customize the boot command (in the basic formats or any other formats).

      3. Environment Variable

         After the container is started, besides the environment variables added by configuring Environment Variable during training job creation, Table 2 lists other environment variables to be loaded. You can determine whether to use these environment variables in your own Python training script, or run the {python_file_parameter} command to pass the required parameters.

         Table 2 Environment variables

         Environment Variable	Description
         DLS_TASK_INDEX	Container index, starting from 0.
         DLS_TASK_NUMBER	Number of containers, corresponding to Compute Nodes
         DLS_APP_URL	Code directory, corresponding to Code Dir with the protocol name added. For example, you can use $DLS_APP_URL/*.py to read files in OBS.
         DLS_DATA_URL	Dataset path, corresponding to Data Source with the protocol name added
         DLS_TRAIN_URL	Training output path, corresponding to Training Output Path with the protocol name added
         BATCH_{jobName}.0_HOSTS (standalone)	For standalone training, that is, when the number of compute nodes is 1, the environment variable is BATCH_{jobName}.0_HOSTS. The format of the HOSTS environment variable is hostname:port. A container can view the HOSTS of all containers in the same job, such as BATCH_CUSTOM0_HOSTS and BATCH_CUSTOM1_HOSTS, varying according to the indexes. If the resource pool is a dedicated resource pool with the 8GPU specifications, the network type of the container is a host network, and the host IB network can be used to accelerate communications. If other resource pools are used, the network is a container network. NOTE: When the host IB network is used for communication acceleration, the ip_mapper.py tool is required to obtain the IP address of the ib0 NIC for using the IPoIB feature.

   3. Select resources for the training job.
      Figure 4 Selecting resources for the training job
      

      Table 3 Resource parameters

      Parameter	Description
      Resource Pool	Select resource pools for the job. For training jobs, Public resource pools and Dedicated resource pools are available. Instances in the public resource pool can be of the CPU or GPU type. Pricing standards for resource pools with different instance types are different. For details, see Product Pricing Details. For details about how to create a dedicated resource pool, see Resource Pools.
      Type	If Resource Pool is set to Public resource pools, select a resource type. Available resource types are CPU and GPU. The GPU resource delivers better performance, and the CPU resource is more cost effective. If the selected algorithm has been defined to use the CPU or GPU, the resource type is automatically displayed on the page. Select the resource type as required. The data disk capacity varies depending on the resource type. For details, see What Are Sizes of the /cache Directories for GPU and CPU Resources in the Training Environment?. NOTE: If GPU resources are used in training code, you must select a GPU cluster when selecting a resource pool. Otherwise, the training job may fail.
      Specifications	Select a resource flavor based on the resource type. If you select an existing or frequently-used algorithm, or a custom image, ModelArts allows you to use Ascend 910 to create training jobs. This resource is available only in the CN North-Beijing4 region. In the resource flavor list, the flavor marked with Limited-time free is a free flavor. You can use the flavor to experience the training job function of ModelArts free of charge. For details about the precautions for using the flavor, see Experiencing AI Development Lifecyle for Free.
      Compute Nodes	Set the number of compute nodes. If you set Compute Nodes to 1, the standalone computing mode is used. If you set Compute Nodes to a value greater than 1, the distributed computing mode is used. Select a computing mode based on the actual requirements.

   4. Configure Notification and select whether to save the parameters of the training job.
      Figure 5 Configuring notifications for the training job
      

      Table 4 Parameters related to notification and parameter configuration saving

      Parameter	Description
      Notification	Select the resource pool status to be monitored from the event list, and SMN sends a notification message when the event occurs. This parameter is optional. You can choose whether to enable subscription based on actual requirements. If you enable subscription, set the following parameters as required: Topic: indicates the topic name. You can create a topic on the SMN console. Event: indicates the event to be subscribed to. The options are OnJobRunning, OnJobSucceeded, and OnJobFailed, indicating that training is in progress, successful, and failed, respectively.
      Saving Training Parameters	If you select this option, the parameter settings of the current job will be saved to facilitate subsequent job creation. Select Save Training Parameters and specify Configuration Name and Description. After a training job is created, you can switch to the Job Parameters tab page to view your saved job parameter settings. For details, see Managing Job Parameters.

   5. After setting the parameters, click Next.
4. Confirm that the information is correct on the Confirm page that is displayed and click Submit. Generally, training jobs run for a period of time, which may be several minutes or tens of minutes depending on the amount of your selected data and resources.

   After a custom image job is created, the system authorizes ModelArts to obtain and run the image by default. When you run a custom image job for the first time, ModelArts checks the custom image. For details about the check, see Specifications for Custom Images Used for Training Jobs. You can view the cause of the check failure in the log and modify the custom image based on the log.

   Figure 6 Failed to check the image
   

   After the image is checked, the background starts the custom image container to run the custom image training job. You can switch to the training job list to view the basic information about training jobs. In the training job list, Status of the newly created training job is Initializing. If the status changes to Successful, the training job ends and the model generated is stored in the location specified by Training Output Path. If the status of a training job changes to Running failed. Click the name of the training job and view the job logs. Troubleshoot the fault based on the logs.

   Figure 7 Run log
   
   

   • After a training job is created, it is started immediately. During the running, you will be charged based on your selected resources.
   • After an image is reviewed, the image does not need to be reviewed again when being used to create training jobs again.