チュートリアル:Python API を使用して Azure Batch で並列ワークロードを実行するTutorial: Run a parallel workload with Azure Batch using the Python API

Azure Batch を使用すると、大規模な並列コンピューティングやハイパフォーマンス コンピューティング (HPC) のバッチ ジョブを Azure で効率的に実行することができます。Use Azure Batch to run large-scale parallel and high-performance computing (HPC) batch jobs efficiently in Azure. このチュートリアルでは、Batch を使用して並列ワークロードを実行する Python の例を紹介します。This tutorial walks through a Python example of running a parallel workload using Batch. 一般的な Batch アプリケーション ワークフローのほか、Batch および Storage のリソースをプログラムで操作する方法を学習します。You learn a common Batch application workflow and how to interact programmatically with Batch and Storage resources. 学習内容は次のとおりです。You learn how to:

  • Batch アカウントおよびストレージ アカウントで認証するAuthenticate with Batch and Storage accounts
  • Storage に入力ファイルをアップロードするUpload input files to Storage
  • アプリケーションを実行するコンピューティング ノードのプールを作成するCreate a pool of compute nodes to run an application
  • 入力ファイルを処理するジョブとタスクを作成するCreate a job and tasks to process input files
  • タスクの実行を監視するMonitor task execution
  • 出力ファイルを取得するRetrieve output files

このチュートリアルでは、ffmpeg オープンソース ツールを使用して複数の MP4 メディア ファイルを並行して MP3 形式に変換します。In this tutorial, you convert MP4 media files in parallel to MP3 format using the ffmpeg open-source tool.

Azure サブスクリプションをお持ちでない場合は、開始する前に無料アカウントを作成してください。If you don't have an Azure subscription, create a free account before you begin.

前提条件Prerequisites

Azure へのサインインSign in to Azure

Azure Portal (https://portal.azure.com) にサインインします。Sign in to the Azure portal at https://portal.azure.com.

アカウントの資格情報を取得するGet account credentials

この例では、Batch アカウントと Storage アカウントの資格情報を指定する必要があります。For this example, you need to provide credentials for your Batch and Storage accounts. Azure Portal を使用すると、必要な資格情報を簡単に取得できますA straightforward way to get the necessary credentials is in the Azure portal. (Azure API やコマンドライン ツールを使用してこれらの資格情報を取得することもできます)。(You can also get these credentials using the Azure APIs or command-line tools.)

  1. [すべてのサービス] > [Batch アカウント] の順に選択し、Batch アカウントの名前を選択します。Select All services > Batch accounts, and then select the name of your Batch account.

  2. Batch 資格情報を表示するには、 [キー] を選択します。To see the Batch credentials, select Keys. [Batch アカウント][URL][プライマリ アクセス キー] の値をテキスト エディターにコピーします。Copy the values of Batch account, URL, and Primary access key to a text editor.

  3. Storage アカウント名とキーを表示するには、 [ストレージ アカウント] を選択します。To see the Storage account name and keys, select Storage account. [ストレージ アカウント名][Key1] の値をテキスト エディターにコピーします。Copy the values of Storage account name and Key1 to a text editor.

サンプルのダウンロードと実行Download and run the sample

サンプルのダウンロードDownload the sample

GitHub からサンプル アプリをダウンロードまたは複製します。Download or clone the sample app from GitHub. Git クライアントを使用してサンプル アプリ リポジトリを複製するには、次のコマンドを使用します。To clone the sample app repo with a Git client, use the following command:

git clone https://github.com/Azure-Samples/batch-python-ffmpeg-tutorial.git

batch_python_tutorial_ffmpeg.py ファイルが含まれているディレクトリに移動します。Navigate to the directory that contains the file batch_python_tutorial_ffmpeg.py.

ご利用の Python 環境で、pip を使用して必要なパッケージをインストールします。In your Python environment, install the required packages using pip.

pip install -r requirements.txt

ファイル config.pyを開きます。Open the file config.py. Batch アカウントとストレージ アカウントの資格情報文字列を、アカウントに固有の値で更新します。Update the Batch and storage account credential strings with the values unique to your accounts. 例:For example:

_BATCH_ACCOUNT_NAME = 'mybatchaccount'
_BATCH_ACCOUNT_KEY = 'xxxxxxxxxxxxxxxxE+yXrRvJAqT9BlXwwo1CwF+SwAYOxxxxxxxxxxxxxxxx43pXi/gdiATkvbpLRl3x14pcEQ=='
_BATCH_ACCOUNT_URL = 'https://mybatchaccount.mybatchregion.batch.azure.com'
_STORAGE_ACCOUNT_NAME = 'mystorageaccount'
_STORAGE_ACCOUNT_KEY = 'xxxxxxxxxxxxxxxxy4/xxxxxxxxxxxxxxxxfwpbIC5aAWA8wDu+AFXZB827Mt9lybZB1nUcQbQiUrkPtilK5BQ=='

アプリの実行Run the app

スクリプトを実行するには、次の手順を実行します。To run the script:

python batch_python_tutorial_ffmpeg.py

サンプル アプリケーションを実行すると、コンソールの出力は次のようになります。When you run the sample application, the console output is similar to the following. 実行中、プールのコンピューティング ノードを開始する際に、Monitoring all tasks for 'Completed' state, timeout in 00:30:00... で一時停止が発生します。During execution, you experience a pause at Monitoring all tasks for 'Completed' state, timeout in 00:30:00... while the pool's compute nodes are started.

Sample start: 11/28/2018 3:20:21 PM

Container [input] created.
Container [output] created.
Uploading file LowPriVMs-1.mp4 to container [input]...
Uploading file LowPriVMs-2.mp4 to container [input]...
Uploading file LowPriVMs-3.mp4 to container [input]...
Uploading file LowPriVMs-4.mp4 to container [input]...
Uploading file LowPriVMs-5.mp4 to container [input]...
Creating pool [LinuxFFmpegPool]...
Creating job [LinuxFFmpegJob]...
Adding 5 tasks to job [LinuxFFmpegJob]...
Monitoring all tasks for 'Completed' state, timeout in 00:30:00...
Success! All tasks completed successfully within the specified timeout period.
Deleting container [input]....

Sample end: 11/28/2018 3:29:36 PM
Elapsed time: 00:09:14.3418742

プール、コンピューティング ノード、ジョブ、タスクを監視するには、Azure Portal で Batch アカウントに移動します。Go to your Batch account in the Azure portal to monitor the pool, compute nodes, job, and tasks. たとえば、プール内のコンピューティング ノードのヒート マップを確認するには、 [プール] > LinuxFFmpegPool の順にクリックします。For example, to see a heat map of the compute nodes in your pool, click Pools > LinuxFFmpegPool.

タスクが実行されていると、ヒート マップは次のようになります。When tasks are running, the heat map is similar to the following:

プールのヒート マップ

既定の構成でアプリケーションを実行する場合、通常の実行時間は約 5 分間です。Typical execution time is approximately 5 minutes when you run the application in its default configuration. プールの作成に最も時間がかかります。Pool creation takes the most time.

出力ファイルを取得するRetrieve output files

Azure Portal を使用して、ffmpeg タスクによって生成された出力 MP3 ファイルをダウンロードすることができます。You can use the Azure portal to download the output MP3 files generated by the ffmpeg tasks.

  1. [すべてのサービス] > [ストレージ アカウント] の順にクリックし、ストレージ アカウントの名前をクリックします。Click All services > Storage accounts, and then click the name of your storage account.
  2. [BLOB] > [出力] の順にクリックします。Click Blobs > output.
  3. 出力 MP3 ファイルの 1 つを右クリックして、 [ダウンロード] をクリックします。Right-click one of the output MP3 files and then click Download. ブラウザーのメッセージに従って、ファイルを開くか保存します。Follow the prompts in your browser to open or save the file.

出力ファイルをダウンロードする

このサンプルには示されていませんが、コンピューティング ノードまたはストレージ コンテナーからプログラムでファイルをダウンロードすることもできます。Although not shown in this sample, you can also download the files programmatically from the compute nodes or from the storage container.

コードの確認Review the code

以降のセクションでは、サンプル アプリケーションを、Batch サービスでワークロードを処理するために実行する複数の手順に分けます。The following sections break down the sample application into the steps that it performs to process a workload in the Batch service. サンプルのすべてのコード行について説明しているわけではないので、この記事の残りの部分を読む際は Python コードを参照してください。Refer to the Python code while you read the rest of this article, since not every line of code in the sample is discussed.

BLOB クライアントと Batch クライアントの認証Authenticate Blob and Batch clients

ストレージ アカウントを操作するには、アプリで azure-storage-blob パッケージを使用して BlockBlobService オブジェクトを作成します。To interact with a storage account, the app uses the azure-storage-blob package to create a BlockBlobService object.

blob_client = azureblob.BlockBlobService(
    account_name=_STORAGE_ACCOUNT_NAME,
    account_key=_STORAGE_ACCOUNT_KEY)

このアプリは BatchServiceClient オブジェクトを作成して、Batch サービスでプール、ジョブ、タスクを作成および管理します。The app creates a BatchServiceClient object to create and manage pools, jobs, and tasks in the Batch service. このサンプルの Batch クライアントでは共有キー認証を使用します。The Batch client in the sample uses shared key authentication. Batch は、個々のユーザーまたは自動アプリケーションを認証するために、Azure Active Directory による認証もサポートしています。Batch also supports authentication through Azure Active Directory, to authenticate individual users or an unattended application.

credentials = batchauth.SharedKeyCredentials(_BATCH_ACCOUNT_NAME,
                                             _BATCH_ACCOUNT_KEY)

batch_client = batch.BatchServiceClient(
    credentials,
    base_url=_BATCH_ACCOUNT_URL)

入力ファイルのアップロードUpload input files

アプリは、blob_client 参照を使用して、入力 MP4 ファイル用のストレージ コンテナーとタスク出力用のコンテナーを作成します。The app uses the blob_client reference create a storage container for the input MP4 files and a container for the task output. 次に、upload_file_to_container 関数を呼び出し、ローカルの InputFiles ディレクトリ内の MP4 ファイルをコンテナーにアップロードします。Then, it calls the upload_file_to_container function to upload MP4 files in the local InputFiles directory to the container. ストレージ内のファイルは、Batch の ResourceFile オブジェクトとして定義されており、Batch が後でコンピューティング ノードにダウンロードできます。The files in storage are defined as Batch ResourceFile objects that Batch can later download to compute nodes.

blob_client.create_container(input_container_name, fail_on_exist=False)
blob_client.create_container(output_container_name, fail_on_exist=False)
input_file_paths = []

for folder, subs, files in os.walk(os.path.join(sys.path[0], './InputFiles/')):
    for filename in files:
        if filename.endswith(".mp4"):
            input_file_paths.append(os.path.abspath(
                os.path.join(folder, filename)))

# Upload the input files. This is the collection of files that are to be processed by the tasks.
input_files = [
    upload_file_to_container(blob_client, input_container_name, file_path)
    for file_path in input_file_paths]

コンピューティング ノードのプールの作成Create a pool of compute nodes

次に、create_pool が呼び出されて、コンピューティング ノードのプールが Batch アカウントに作成されます。Next, the sample creates a pool of compute nodes in the Batch account with a call to create_pool. この定義済みの関数は、Batch の PoolAddParameter クラスを使用して、ノードの数、VM のサイズ、プールの構成を設定します。This defined function uses the Batch PoolAddParameter class to set the number of nodes, VM size, and a pool configuration. ここでは、VirtualMachineConfiguration オブジェクトで ImageReference に、Azure Marketplace で公開されている Ubuntu Server 18.04 LTS イメージを指定します。Here, a VirtualMachineConfiguration object specifies an ImageReference to an Ubuntu Server 18.04 LTS image published in the Azure Marketplace. Batch は、Azure Marketplace のさまざまな VM イメージだけでなく、カスタム VM イメージもサポートしています。Batch supports a wide range of VM images in the Azure Marketplace, as well as custom VM images.

ノードの数と VM のサイズは、定義済みの定数を使用して設定されます。The number of nodes and VM size are set using defined constants. Batch では専用ノードと低優先度ノードがサポートされているため、ご利用のプールではそのいずれかまたは両方を使用できます。Batch supports dedicated nodes and low-priority nodes, and you can use either or both in your pools. 専用ノードは、プール用に予約されています。Dedicated nodes are reserved for your pool. 低優先度ノードは、Azure の VM の余剰容量から割引価格で提供されます。Low-priority nodes are offered at a reduced price from surplus VM capacity in Azure. 低優先度ノードは、Azure に十分な容量がない場合に使用できなくなります。Low-priority nodes become unavailable if Azure does not have enough capacity. このサンプルは、既定で、サイズ Standard_A1_v2 の低優先度ノードが 5 つだけ含まれているプールを作成します。The sample by default creates a pool containing only 5 low-priority nodes in size Standard_A1_v2.

このプールの構成には、物理ノードのプロパティだけでなく、StartTask オブジェクトも含まれています。In addition to physical node properties, this pool configuration includes a StartTask object. 各ノードがプールに参加するときと、ノードの再起動のたびに、各ノードで StartTask が実行されます。The StartTask executes on each node as that node joins the pool, and each time a node is restarted. この例では、StartTask は Bash シェル コマンドを実行して、ffmpeg パッケージと依存関係をノードにインストールします。In this example, the StartTask runs Bash shell commands to install the ffmpeg package and dependencies on the nodes.

pool.add メソッドは、プールを Batch サービスを送信します。The pool.add method submits the pool to the Batch service.

new_pool = batch.models.PoolAddParameter(
    id=pool_id,
    virtual_machine_configuration=batchmodels.VirtualMachineConfiguration(
        image_reference=batchmodels.ImageReference(
            publisher="Canonical",
            offer="UbuntuServer",
            sku="18.04-LTS",
            version="latest"
        ),
        node_agent_sku_id="batch.node.ubuntu 18.04"),
    vm_size=_POOL_VM_SIZE,
    target_dedicated_nodes=_DEDICATED_POOL_NODE_COUNT,
    target_low_priority_nodes=_LOW_PRIORITY_POOL_NODE_COUNT,
    start_task=batchmodels.StartTask(
        command_line="/bin/bash -c \"apt-get update && apt-get install -y ffmpeg\"",
        wait_for_success=True,
        user_identity=batchmodels.UserIdentity(
            auto_user=batchmodels.AutoUserSpecification(
                scope=batchmodels.AutoUserScope.pool,
                elevation_level=batchmodels.ElevationLevel.admin)),
    )
)
batch_service_client.pool.add(new_pool)

ジョブを作成するCreate a job

Batch ジョブでは、タスクの実行対象となるプールと、作業の優先順位やスケジュールなどのオプションの設定を指定します。A Batch job specifies a pool to run tasks on and optional settings such as a priority and schedule for the work. このサンプルでは、create_job の呼び出しを使用してジョブを作成します。The sample creates a job with a call to create_job. この定義済みの関数は、JobAddParameter クラスを使用して、プールにジョブを作成します。This defined function uses the JobAddParameter class to create a job on your pool. job.add メソッドは、プールを Batch サービスに送信します。The job.add method submits the pool to the Batch service. 最初、ジョブにはタスクがありません。Initially the job has no tasks.

job = batch.models.JobAddParameter(
    id=job_id,
    pool_info=batch.models.PoolInformation(pool_id=pool_id))

batch_service_client.job.add(job)

タスクの作成Create tasks

アプリは、add_tasks の呼び出しを使用してジョブにタスクを作成します。The app creates tasks in the job with a call to add_tasks. この定義済みの関数は、TaskAddParameter クラスを使用して、タスク オブジェクトの一覧を作成します。This defined function creates a list of task objects using the TaskAddParameter class. 各タスクは、ffmpeg を実行して、command_line パラメーターを使用して入力の resource_files オブジェクトを処理します。Each task runs ffmpeg to process an input resource_files object using a command_line parameter. ffmpeg は、以前にプールが作成されたときに各ノードにインストールされています。ffmpeg was previously installed on each node when the pool was created. ここでは、コマンド ラインで ffmpeg を実行して、各入力 MP4 (ビデオ) ファイルを MP3 (オーディオ) ファイルに変換します。Here, the command line runs ffmpeg to convert each input MP4 (video) file to an MP3 (audio) file.

このサンプルでは、コマンド ラインの実行後に MP3 ファイルの OutputFile オブジェクトを作成します。The sample creates an OutputFile object for the MP3 file after running the command line. 各タスクの出力ファイル (この場合は 1 つ) は、タスクの output_files プロパティを使用して、リンクされているストレージ アカウントのコンテナーにアップロードされます。Each task's output files (one, in this case) are uploaded to a container in the linked storage account, using the task's output_files property.

その後、アプリは、task.add_collection メソッドを使用してジョブにタスクを追加します。これにより、タスクは、コンピューティング ノードで実行するためにキューに登録されます。Then, the app adds tasks to the job with the task.add_collection method, which queues them to run on the compute nodes.

tasks = list()

for idx, input_file in enumerate(input_files):
    input_file_path = input_file.file_path
    output_file_path = "".join((input_file_path).split('.')[:-1]) + '.mp3'
    command = "/bin/bash -c \"ffmpeg -i {} {} \"".format(
        input_file_path, output_file_path)
    tasks.append(batch.models.TaskAddParameter(
        id='Task{}'.format(idx),
        command_line=command,
        resource_files=[input_file],
        output_files=[batchmodels.OutputFile(
            file_pattern=output_file_path,
            destination=batchmodels.OutputFileDestination(
                container=batchmodels.OutputFileBlobContainerDestination(
                    container_url=output_container_sas_url)),
            upload_options=batchmodels.OutputFileUploadOptions(
                upload_condition=batchmodels.OutputFileUploadCondition.task_success))]
    )
    )
batch_service_client.task.add_collection(job_id, tasks)

タスクの監視Monitor tasks

タスクは、ジョブに追加されると、関連付けられたプール内のコンピューティング ノードで実行するために、Batch によって自動的にキューに登録され、スケジュールが設定されます。When tasks are added to a job, Batch automatically queues and schedules them for execution on compute nodes in the associated pool. 指定した設定に基づいて、Batch は、タスクのキューへの登録、スケジュール設定、再試行など、タスク管理作業すべてを処理します。Based on the settings you specify, Batch handles all task queuing, scheduling, retrying, and other task administration duties.

タスクの実行を監視する方法は多数ありますが、There are many approaches to monitoring task execution. この例の wait_for_tasks_to_complete 関数は、TaskState オブジェクトを使用して、制限時間内で特定の状態 (この場合は完了した状態) についてタスクを監視します。The wait_for_tasks_to_complete function in this example uses the TaskState object to monitor tasks for a certain state, in this case the completed state, within a time limit.

while datetime.datetime.now() < timeout_expiration:
    print('.', end='')
    sys.stdout.flush()
    tasks = batch_service_client.task.list(job_id)

    incomplete_tasks = [task for task in tasks if
                        task.state != batchmodels.TaskState.completed]
    if not incomplete_tasks:
        print()
        return True
    else:
        time.sleep(1)
...

リソースのクリーンアップClean up resources

タスクの実行後、自動的に、作成された入力用ストレージ コンテナーが削除され、Batch プールとジョブを削除するためのオプションが表示されます。After it runs the tasks, the app automatically deletes the input storage container it created, and gives you the option to delete the Batch pool and job. BatchClient の JobOperations クラスと PoolOperations クラスの両方に削除メソッドがあります。このメソッドは、削除を確定すると呼び出されます。The BatchClient's JobOperations and PoolOperations classes both have delete methods, which are called if you confirm deletion. ジョブとタスク自体は課金対象ではありませんが、コンピューティング ノードは課金対象です。Although you're not charged for jobs and tasks themselves, you are charged for compute nodes. そのため、必要な場合にのみプールを割り当てることをお勧めします。Thus, we recommend that you allocate pools only as needed. プールを削除すると、ノード上のタスク出力はすべて削除されます。When you delete the pool, all task output on the nodes is deleted. ただし、入力ファイルと出力ファイルはストレージ アカウントに残ります。However, the input and output files remain in the storage account.

リソース グループ、Batch アカウント、ストレージ アカウントは、不要になったら削除します。When no longer needed, delete the resource group, Batch account, and storage account. Azure Portal でこれを行うには、Batch アカウントのリソース グループを選択し、 [リソース グループの削除] をクリックしてください。To do so in the Azure portal, select the resource group for the Batch account and click Delete resource group.

次の手順Next steps

このチュートリアルで学習した内容は次のとおりです。In this tutorial, you learned about how to:

  • Batch アカウントおよびストレージ アカウントで認証するAuthenticate with Batch and Storage accounts
  • Storage に入力ファイルをアップロードするUpload input files to Storage
  • アプリケーションを実行するコンピューティング ノードのプールを作成するCreate a pool of compute nodes to run an application
  • 入力ファイルを処理するジョブとタスクを作成するCreate a job and tasks to process input files
  • タスクの実行を監視するMonitor task execution
  • 出力ファイルを取得するRetrieve output files

Python API を使用して Batch ワークロードのスケジュール設定と処理を行う他の例については、GitHub のサンプルを参照してください。For more examples of using the Python API to schedule and process Batch workloads, see the samples on GitHub.