User Guide

本書の目的

本書はKAMONOHASHIを利用したAI開発をスムーズに行う為に各機能や手順を説明する事を目的としている。

前提

読者がLinux、Git、Dockerの基本的な知識を持つことを前提としている。

概要

KAMONOHASHIの利用者は以下の操作を行える。

KAMONOHASHIの利用者の想定操作をまとめた図を以下に示す。 ユーザー手順概要

ログイン

KAMONOHASHIはブラウザ・SDK・コマンドラインツールから使用できる。 ブラウザで開始するには、KAMONOHASHIにログインする。 KAMONOHASHIのURLはシステム管理者に問い合わせること。

ログイン

KAMONOHASHIにログインするにはログイン画面からユーザー名・パスワードを入力する。 ユーザー名・パスワードはシステム管理者から提供される。

ログイン

テナントについて

テナントはKAMONOHASHIの最小の利用単位である。 テナント毎にリソースの使用量などが決められている。 ユーザは複数のテナントに所属することができる。

利用するテナントを切り替えるには、右上のユーザ名が表示されているリンクを押し、切り替えたいテナントを選択する。

テナント切替

ユーザ情報設定

利用者は右上のプルダウンメニューより[ユーザ情報設定]を選択することで、各種ユーザ設定情報の確認・変更が行える。

Gitトークンの設定

KAMONOHASHIでは学習に用いる学習スクリプトなどを、システム管理者によって設定されたGitリポジトリサービスから取得する。

Gitリポジトリサービスへのアクセスに認証が必要な場合、ユーザ情報設定画面にて [Git Token]タブを選択し、認証情報を設定する。

レジストリトークンの設定

KAMONOHASHIでは、学習環境としてDockerコンテナを使用する。 このコンテナはシステム管理者によって設定されたDockerレジストリサービスから取得する。

Dockerレジストリサービスへのアクセスに認証が必要な場合、ユーザ情報設定画面にて [Registry Token]タブを選択し、認証情報を設定する。

レジストリトークンの設定

データ管理

KAMONOHASHIでは Deep Learning等に利用するデータを管理することができる。データは画像やzipファイルなど、データ形式を問わず登録できる。

データを登録するには、[データ管理]を選択し、新規登録ボタンから行う。

データの登録

種類  説明 
データ名 データの名前。
メモ 画像の説明など補足情報。
タグ データの種類や受領日などグルーピングしたい単位に付与し、検索等で利用する。
ファイル 複数のデータを登録できる。jpg/png/csv/zipなど、ファイルのデータ形式は任意。

前処理管理

前処理とは、既存データを元に、より目的に適した新しいデータを新規生成する処理である。例えば画像のトリミング処理などがこれにあたる。 KAMONOHASHIでは、データに対する前処理の実行、およびその履歴の管理を行うことができる。

ワークフロー

KAMONOHASHIで前処理を扱う場合、以下の二つのワークフローがある

  • KAMONOHASHI管理の計算ノード上で前処理を実行する
    • 全てのフローをKAMONOHASHIの管理範囲内で行う。前処理実行の自動化や並列処理、処理履歴のトラッキングを完全に行うことができる。
    • フロー
      1. KAMONOHASHI上での前処理作成
        • 前処理用ソースコードやコンテナなど、実行するための全情報の登録が必要となる。
      2. 登録した前処理の実行
        • 登録済みのデータに対し、KAMONOHASHIの管理リソース上で前処理を実行する。
        • 結果や履歴情報は全て自動で記録される。
  • KAMONOHASHI環境外で前処理を実施し、結果だけをKAMONOHASHIに登録する
    • 前処理の実行自体は、ローカル環境などKAMONOHASHIの外で行い、結果だけをKAMONOHASHIにアップロードする。アップロード時の内容に従い、部分的に履歴管理が可能となる。前処理がKAMONOHASHIの管理リソース上で行えない場合(WindowsやMacOSが必要な場合など)に利用する。
    • この操作は KAMONOHASHI CLI によってのみ実行が可能である。WebUI上では行えない。
    • フロー
      1. KAMONOHASHI上での前処理作成
        • 必須入力は前処理名のみ。その他情報は任意で設定する。
      2. KAMONOHASHI外での前処理実行
        • ローカル環境などで前処理を行う。
      3. 結果と履歴情報の保存
        • 前処理結果ファイルと、その履歴情報(対象データや試用した前処理など)を登録する。

前処理の管理と作成

KAMONOHASHIで前処理を管理するためには、まず前処理の登録を行う。実行前に前処理を登録しておくことで、その前処理を多数のデータに任意のタイミングで適用することができる。

前処理を登録するには、[前処理管理]を選択し、右上の新規登録ボタンから行う。 前処理作成

種類 要否 説明
前処理名 必須 前処理の名前。任意の文字列を指定可能。
実行コマンド 任意 前処理として実行するコマンドを指定する。コンテナイメージに設定されたcommand, entrypointは無効になり、このコマンドのみが実行される
メモ 任意 前処理に付与する任意のメモ。
コンテナイメージ 任意 利用するDockerレジストリ、コンテナ、タグを指定する。
モデル 任意 前処理で利用するソースコードを格納しているGitサーバ、リポジトリ、ブランチ、コミットIDを指定する。コミットIDを指定した場合はブランチの入力値は無視される。コミットIDが未指定の場合はブランチのHEADが選択される。ブランチもコミットIDも未指定の場合は、masterブランチのHEADが選択される。
CPU 任意 前処理が使用するCPUコア数のデフォルト値を指定する。実行時に再設定が可能。
メモリ 任意 学習が使用するメモリ量(GB)のデフォルト値を指定する。実行時に再設定が可能。
GPU 任意 学習が使用するGPU枚数のデフォルト値を指定する。実行時に再設定が可能。

KAMONOHASHI上で前処理を実行したい場合は、メモを除くすべての項目が必須入力となる。

前処理実行

KAMONOHASHIで前処理を実行するためは、以下3つのフローのいずれかで前処理実行画面を表示する。

  • 前処理管理画面から前処理を行う場合
    1. 前処理管理画面を表示する
    2. 右上の[前処理実行]ボタンを押す
    3. 登録済みのデータ、リソースを設定し実行する
  •  データ管理画面から1つのデータに前処理を行う場合
    1. データ管理画面を表示する
    2. 前処理の対象データを選択し、データ編集画面を表示する
    3. 右上の[前処理実行]ボタンを押す
    4. 登録済みの前処理を選択、リソースを設定し実行する
  •  データ管理画面から複数のデータに前処理を行う場合
    1. データ管理画面を表示する
    2. 全ての前処理の対象データに対し、データIDの左側に表示されたチェックボックスを選択する
    3. データ管理画面右上の[前処理実行]ボタンを押す
    4. 登録済みの前処理を選択、リソースを設定し実行する

前処理実行

種類 要否 説明
前処理 必須 実行する前処理を選択する。
環境変数 任意 前処理に渡す環境変数を指定する。環境変数はコンテナ内の環境変数へ追加設定される。
パーティション 任意 KAMONOHASHI に設定されているパーティションを設定する。例えばGPUの型番などはここから指定する。
CPU 必須 使用するCPUコア数を指定する。
メモリ 必須 使用するメモリ量(GB)を指定する。
GPU 必須 使用するGPU枚数を指定する。
実行後に履歴を開く 任意 ONにした場合、[実行]ボタンの押下後に当該前処理の履歴画面へ遷移する。OFFの場合は前の画面に戻る。

前処理実行の仕様

KAMONOHASHIによる前処理の実行フロー

  1. クラスタからリソースを確保する
    • リソースに十分な空きがなかった場合は待機する
  2. リソース上にコンテナがデプロイされる
    • コンテナ内に環境変数が設定される。
  3. 学習結果ファイル保存用ディレクトリ /kqi/output を作成する
  4. kamonohashiの学習制御に必要なツールをインストールする
    • git, python, pip, kamonohashi-cli がコンテナにインストールされる
    • コンテナに既にこれらのツールがインストール済みだった場合はスキップされる
  5. 前処理スクリプトを /kqi/git/ に git clone する
  6. データセットを /kqi/input/{データID}/データファイル にダウンロードする
  7. 指定された「実行コマンド」が実行される
    • /kqi/git/ がカレントディレクトリになる
    • 実行ユーザはコンテナのrootユーザとなる
    • 学習中、結果ファイルが /kqi/output/{前処理後結果として作成されるデータの名前}/ に書き出されるように「実行コマンド」または前処理スクリプトの記述が必要である
      • /kqi/output/{前処理後結果として作成されるデータの名前}/ 以下のファイルは全て新規データに追加される。サブディレクトリ内のファイルも再帰的に新規データに追加される。
      • /kqi/output/ 直下のファイルは新規データに追加されない。
      • 出力ファイルはzip圧縮されない。
      • 結果のリアルタイム確認はできない。
  8. 実行ログを確認する
    • このファイルは前処理履歴画面の添付ファイル「stdout_stderr_.log」からダウンロードできる。
  9. 実行結果のステータスが更新される
    • KAMONOHASHIの実行成否は、実行後の “$?” コマンドの結果で判断される
    • そのため、実行コマンド自体は改行して複数記述可能だが、結果の成否判定が難しくなるため、単一コマンドを推奨する。
  10. コンテナが停止し、リソースが開放される

フォルダ構造

前処理ディレクトリ

注意事項

前処理は、同じデータに対して1度しか実行できない。 スクリプトのエラー等で再度実行したい場合、前処理履歴を削除する必要がある。削除時は生成された前処理結果データも同時に削除されるので注意が必要である。

データセット管理

データセットとは、データを Training/Validation/Test などのグループに分割し、機械学習などで処理するために利用する。 KAMONOHASHIでは後述する学習を実行する際の入力ファイルは、データセット単位となる。 学習実行時に使用するデータセットを指定すると、training 等の分類に応じてデータが異なるディレクトリにダウンロードされる。 KAMONOHASHIではトレーサビリティを重視しているため、一度学習と関連付けられたデータセットは変更できない。

データセットを作成するには、[データセット管理]を選択し、右上の新規登録ボタンから行う。

データセットの作成

種類  説明 
データセット名 データセットの名前。
メモ データセットを説明するメモ。
データ allに表示されるデータ一覧からそれぞれのエリアにドラッグで移動させることでデータを分割していく。

データセットのコピー

KAMONOHASHI では1度学習に利用したデータセットは編集できなくなる。このため、過去に利用したデータセットから派生して処理を行い たい場合には、データセットをコピーして利用する。データセットをコピーするには、一覧からコピーしたいデータセットを選択し、 右上のコピーボタンから行う。

学習管理

学習は KAMONOHASHI が管理するクラスタで計算を実行するための最小単位を表す。 学習を開始すると KAMONOHASHI はクラスタから指定されたCPU、メモリ、GPUリソースを確保し、Dockerコンテナを起動して計算環境を用意する。ユーザはこの環境を利用し、任意の計算を行うことができる。

学習の開始

学習を開始するには[学習管理]を選択し、右上の新規登録ボタンから行う。実行コマンドやモデルの仕様については後述

学習の実行は4ステップにて行う。

ステップ1

新規ジョブ実行画面 ステップ1

種類 要否 説明
学習名 必須 学習の名前。
半角英数小文字、または記号(“-”(ハイフン)、”.”(ドット)) 30 文字以下で指定可能。
任意 既に実行した学習との関連付ける場合に指定する。指定時に親学習の設定がコピーされるので、変更したい箇所を指定後に変更する。また、親に指定した学習の出力結果が、コンテナにマウントされる。
データセット 必須 学習の入力ファイルとなるデータセットを指定する。

ステップ2

新規ジョブ実行画面 ステップ2

種類 要否 説明
コンテナイメージ 必須 利用するDockerレジストリ、コンテナ、タグを指定する。
モデル 必須 学習で利用するソースコードを格納しているGitサーバ、リポジトリ、ブランチ、コミットIDを指定する。コミットIDを指定した場合はブランチの入力値は無視される。コミットIDが未指定の場合はブランチのHEADが選択される。ブランチもコミットIDも未指定の場合は、masterブランチのHEADが選択される。
実行コマンド 必須 学習で実行するコマンドを指定する。コンテナイメージに設定されたcommand, entrypointは無効になり、このコマンドのみが実行される

ステップ3

新規ジョブ実行画面 ステップ3

種類 要否 説明
CPU 必須 学習が利用するCPUコア数を指定する。
メモリ 必須 学習が利用するメモリ量(GB)を指定する。
GPU 必須 学習が利用するGPU枚数を指定する。

ステップ4

新規ジョブ実行画面 ステップ4

種類 要否 説明
環境変数 任意 学習に渡す環境変数を指定する。環境変数はコンテナ内の環境変数へ追加設定される。
パーティション 任意 KAMONOHASHI に設定されているパーティションを設定する。例えばGPUの型番などはここから指定する。
メモ 任意 学習に付与する任意のメモ。

学習の確認

過去に実行した学習の情報・状態・結果などを確認したい場合、[学習管理]の画面で該当学習を選択し、学習履歴画面を表示する。

ジョブ詳細画面

学習履歴画面では、各種情報が項目毎に一覧化されており、以下のことなどが行える。

TensorBoard の起動

学習を実行しているコンテナの TensorBoard を表示したい場合、[学習管理]の画面で該当学習を選択する。 Tensorbardの項目からTensorboadが起動できる。 ただし、TensorBoard に読み込ませるログデータが、学習の結果ファイルとして出力されている必要がある。

学習の停止

学習を停止したい場合、[学習管理]の画面で該当学習を選択する。操作の項目にある学習停止ボタンから学習を停止することができる。 ※この操作は学習のステータスがRunning時のみ実行可能である。

学習コンテナへの接続

学習を実行しているコンテナに接続したい場合、[学習管理]の画面で該当学習を選択し、[Shell起動]ボタンを押下する。 コンテナ内のrootユーザとしてシェルが立ち上がり、コンテナ内で任意のコマンドを実行できる。 ※この操作は学習のステータスがRunning時のみ実行可能である。

コピー実行

類似の学習を投入したい場合は、過去の該当学習を選択し右上のコピー実行ボタンから行える。コピー実行を選択すると、 過去の学習を投入した情報が初期値として設定され、必要な個所を変更して実行できる。

学習の仕様

KAMONOHASHIによる学習の実行フロー

  1. クラスタからリソースを確保する
    • リソースに十分な空きがなかった場合は待機する
  2. リソース上にコンテナがデプロイされる
    • コンテナ内に環境変数が設定される。
  3. 親学習の指定があった場合、/kqi/parent に親学習の出力結果を読み取り専用でマウントする
  4. 学習結果ファイル保存用ディレクトリ /kqi/output を作成する
  5. kamonohashiの学習制御に必要なツールをインストールする
    • git, zip, python, pip, kamonohashi-cli がコンテナにインストールされる
    • コンテナに既にこれらのツールがインストール済みだった場合はスキップされる
  6. モデルを /kqi/git/ に git clone する
  7. データセットを /kqi/input にダウンロードする
  8. 指定された「実行コマンド」が実行される
    • /kqi/git/ がカレントディレクトリになる
    • 実行ユーザはコンテナのrootユーザとなる
    • 学習中、結果ファイルが /kqi/output に書き出されるように「実行コマンド」またはモデルの記述が必要
  9. 結果ファイルを保存する
    • /kqi/output をzip圧縮する。このファイルは学習履歴画面の添付ファイル「output.zip」からダウンロードできる。
  10. 実行結果のステータスが更新される
    • KAMONOHASHIの実効成否は、実行後の “$?” コマンドの結果で判断される
    • そのため、実行コマンド自体は改行して複数記述可能だが、結果の成否判定が難しくなるため、単一コマンドを推奨する。
    • e.g. 評価スクリプトを裏で実行するなど、複数操作が必要な場合は modelリポジトリにその処理を行うスクリプトを置く。
  11. コンテナが停止し、リソースが開放される

フォルダ構造

ジョブディレクトリ

/kqi/input/ 入力ファイル

  • 実行時に指定したデータセットは /kqi/input/ にダウンロードされる
  • ファイルは /kqi/input/{データ種別名}/{データID}/データファイル という構造で配備される

/kqi/output/ 出力ファイル

  • /kqi/outputに結果ファイルを書き出すようにする
  • /kqi/output/配下のファイル名・ディレクトリ名は次の文字だけ使用可
    • -_1-9a-zA-Z/
  • /kqi/output に書き込まれたファイルは 学習履歴画面の「ファイル一覧」ボタンからリアルタイムに閲覧・ダウンロードできる

/kqi/git/ 学習モデル

  • 実行時に指定したモデルは /kqi/git/ に git clone される
  • モデルに限らず、コンテナ内で実行したいコマンドがあれば、スクリプトで記述してモデルと共にリポジトリに入れておく
  • 実行時のカレントディレクトリはこの /kqi/git/ になる。 
    • 例:リポジトリのトップに「entrypoint.py」を置いた場合、 学習実行の「実行コマンド」には「python entrypoint.py」を記述すればよい

/kqi/attach 添付ファイル

  • 学習履歴画面にて、添付ファイルとしてアップロードされたファイルが格納される

/kqi/parent 親学習の結果ファイル

  • 親学習を指定した場合、指定した学習の出力結果(当該学習の /kqi/output に出力されたファイル)が読み取り専用で格納される

学習実行環境で設定される環境変数

  • 下記環境変数がkamonohashiによって設定される
    • 上書き可の環境変数は学習新規登録時に環境変数入力フォームから上書き可能
環境変数名 上書き可否 説明
LC_ALL C.UTF-8 不可 システムの文字化け回避のため設定される
LANG C.UTF-8 不可 システムの文字化け回避のため設定される
HTTP_PROXY <デプロイ環境ごと> プロキシ設定。システム管理者が指定したデフォルト値が設定される
HTTPS_PROXY <デプロイ環境ごと> プロキシ設定。システム管理者が指定したデフォルト値が設定される
NO_PROXY <デプロイ環境ごと> プロキシ設定。システム管理者が指定したデフォルト値が設定される
http_proxy <デプロイ環境ごと> プロキシ設定。システム管理者が指定したデフォルト値が設定される
https_proxy <デプロイ環境ごと> プロキシ設定。システム管理者が指定したデフォルト値が設定される
no_proxy <デプロイ環境ごと> プロキシ設定。システム管理者が指定したデフォルト値が設定される
COLUMNS <学習ごと> ターミナルの列数設定。システム管理者が指定したデフォルト値が設定される
TRAINING_ID <学習ごと> 不可 kamonohashiが学習の制御に使用
DATASET_ID <学習ごと> 不可 kamonohashiが学習の制御に使用
PARENT_ID <学習ごと> 不可 kamonohashiが学習の制御に使用
MODEL_REPOSITORY <学習ごと> 不可 kamonohashiが学習の制御に使用
MODEL_REPOSITORY_TOKEN <学習ごと> 不可 kamonohashiが学習の制御に使用
COMMIT_ID <学習ごと> 不可 kamonohashiが学習の制御に使用
KQI_SERVER <学習ごと> 不可 kamonohashiが学習の制御に使用
KQI_TOKEN <学習ごと> 不可 kamonohashiが学習の制御に使用
ENTRY_POINT <学習ごと> 不可 kamonohashiが学習の制御に使用

注意事項

  • ログファイルの書き出しにはteeコマンドが使われている。 pythonを使用する場合は 「-u」オプションでバッファリングを無効にしないと正しく標準出力結果がログに書き出されない。

推論管理

推論の概要

推論は、上述の学習での結果を用いて推論処理を行うための学習であり、[推論管理]画面で管理される。 推論の起動は[推論管理]の新規登録ボタンおよび、[学習履歴]画面の推論実行ボタンより可能である。

基本的には学習と同一の仕様であるため、ここでは相違点のみ記載する。

学習との相違点

  • マウントする学習で親を指定した場合、指定した学習の出力結果(当該学習の /kqi/output に出力されたファイル)が/kqi/parentに読み取り専用でマウントされる。
  • /kqi/output/value.txtに出力された値(1行の数値を想定)が、出力値の列に表示される
  • コンテナ名は”inference-推論名-推論ID”となる
  • Tensorboardの起動は出来ない