CommandBuilder

CommandBuilderは、ZenithTuneでコマンドラインオプションを動的に操作するための強力なユーティリティクラスです。 既存のコマンドを解析し、オプションの追加・更新・削除を簡単に行えるため、ハイパーパラメータチューニングで複雑なコマンドラインを扱う際に特に有用です。

概要

CommandBuilderは以下のような場面で活用できます：

• 既存のトレーニングスクリプトのコマンドラインオプションを動的に変更
• 複数の形式のオプションを統一的に扱う
• KubernetesのPyTorchJobなどでコマンドを動的に構築

サポートするオプション形式

CommandBuilderは4つの主要なオプション形式を自動的に認識し、適切に処理します：

1. EQUALS形式

--key=value
--nproc_per_node=4
--config=/path/to/config.yaml

2. SPACE形式

--key value
--batch-size 32
--learning-rate 0.001

3. KEYVALUE形式

--env KEY1=value1 KEY2=value2
--define batch_size=32 learning_rate=0.001

4. FLAG形式

--verbose
--use-amp
--debug

基本的な使い方

コマンドの初期化と操作

from zenith_tune.command import CommandBuilder

# 既存のコマンドから初期化
builder = CommandBuilder("python train.py --epochs 10 --batch-size 32")

# オプションの追加（既存のオプションがあっても追加される）
builder.append("--learning-rate 0.001")

# オプションの更新（既存のオプションを置き換える）
builder.update("--epochs 20")  # 10から20に更新

# オプションの削除
builder.remove("--batch-size")

# 最終的なコマンドの取得
command = builder.get_command()
print(command)  # "python train.py --epochs 20 --learning-rate 0.001"

メソッドチェーン

すべての操作メソッドは自身を返すため、メソッドチェーンが可能です：

command = (CommandBuilder("python train.py")
    .append("--epochs 10")
    .append("--batch-size 32")
    .update("--learning-rate 0.001")
    .remove("--debug")
    .get_command())

実践的な使用例

ZenithTuneでのハイパーパラメータチューニング

from optuna.trial import Trial
from zenith_tune.command import CommandBuilder

def command_generator(trial: Trial, **kwargs):
    # 既存のコマンドをベースに開始
    base_command = "torchrun --nproc_per_node=8 --master_port=29500 train.py --epochs 100"
    builder = CommandBuilder(base_command)

    # ハイパーパラメータのサンプリング
    batch_size = trial.suggest_int("batch_size", 16, 128)
    lr = trial.suggest_float("learning_rate", 1e-5, 1e-3, log=True)
    dropout = trial.suggest_float("dropout", 0.1, 0.5)

    # 既存のオプションを更新
    builder.update(f"--batch-size {batch_size}")
    builder.update(f"--lr {lr}")

    # 新しいオプションを追加
    builder.append(f"--dropout {dropout}")

    # 条件付きでフラグを追加
    if trial.suggest_categorical("use_amp", [True, False]):
        builder.append("--use-amp")

    return builder.get_command()

KubernetesのPyTorchJobでの使用

from zenith_tune.integration.kubernetes import PyTorchJob

def job_converter(trial: Trial, job: PyTorchJob) -> PyTorchJob:
    # 現在のコマンドを取得（例えば ["sh", "-c", "actual command"]）
    current_command = job.get_command()
    actual_command = current_command[2]

    # CommandBuilderで操作
    builder = CommandBuilder(actual_command)

    # パラメータの更新
    num_workers = trial.suggest_int("num_workers", 0, 8)
    builder.update(f"--num-workers {num_workers}")

    # GPUメモリ設定の追加
    if trial.suggest_categorical("gradient_checkpointing", [True, False]):
        builder.append("--gradient-checkpointing")

    # コマンドを設定
    new_command = current_command.copy()
    new_command[2] = builder.get_command()
    job.set_command(new_command)

    return job