ノーコードチューニングの使用方法
ノーコードチューニングはPythonスクリプトを記述することなくコマンドラインだけでハイパーパラメータチューニングを実行するためのツールです。
概要
ノーコードチューニングは、Preset, Strategy, Evaluatorの3つのコンポーネントで構成されています。 チューニングしたい目的に応じて、Preset, Strategy, Evaluatorを組み合わせて選択することで簡単にチューニングを実行することができます。
| コンポーネント | 役割 |
|---|---|
| Preset | パラメータ探索空間の定義とコマンドへの適用 |
| Strategy | 探索空間の探索方法 |
| Evaluator | コマンド出力からの目的関数値の抽出 |
Strategy, Evaluatorを指定しない場合、Presetに依存して推奨のコンポーネントが自動的に選択されます。 どのStategy, Evaluatorが適しているかわからない場合はPresetのみを指定することでチューニングを即座に開始することができます。
Presetとは
Presetとは、特定のフレームワーク向けのチューニング設定をまとめたテンプレートです。 Presetには以下に示すフレームワークごとに異なる固有の知識が定義されており、ユーザはPresetを指定するだけでフレームワークを全く意識せずにチューニングを実行することができます。
- チューニングの対象: そのフレームワークでチューニング対象とするハイパーパラメータとその探索範囲
- パラメータの適用方法: 探索されたパラメータをフレームワーク固有の引数形式でコマンドに渡す方法
現状提供されているPresetは以下の通りです。
| Preset | 説明 | デフォルトStrategy | デフォルトEvaluator |
|---|---|---|---|
megatron | Megatronファミリーのフレームワークでチューニングすべきパラメータのセット | megatron-heuristic | megatron |
Strategyとは
Strategyとは、パラメータ探索空間をどのように探索するかを決定するコンポーネントです。 Presetが定義した探索空間に対して、次に試すべきパラメータの組み合わせを提案します。 Strategyには特定のPresetでのみ使用できるPreset専用Strategyと、任意のPresetで使用できる汎用Strategyの2種類があります。
現状提供されているPreset専用Strategyは以下の通りです:
| Strategy | 説明 |
|---|---|
megatron-heuristic | megatron Presetに対して並列化戦略の知識に基づいて効率よくパラメータを探索する |
megatron-staged-blackbox | megatron Presetに対してパラメータを段階的にBlackBox探索する |
現状提供されている汎用Strategyは以下の通りです（詳細は汎用Strategyを参照）:
| Strategy | 説明 |
|---|---|
random | パラメータをランダムにサンプリング |
grid | パラメータの全組み合わせを網羅的に探索 |
optuna | OptunaのSamplerに従ってサンプリング |
Evaluatorとは
Evaluatorとは、コマンドの実行結果から最適化の目的関数値を抽出するコンポーネントです。 コマンドの標準出力や実行時間などから数値を取り出し、その値を最小化（または最大化）するようにチューニングが進行します。 EvaluatorもStrategyと同様、Preset専用Evaluatorと汎用Evaluatorが存在します。
現状提供されているPreset専用Evaluatorは以下の通りです:
| Evaluator | 説明 |
|---|---|
megatron | megatron Presetに対して学習スループットTFLOP/s/GPUの値を最大化 |
現状提供されている汎用Evaluatorは以下の通りです:
| Evaluator | 説明 |
|---|---|
duration | コマンドの実行時間を最小化 |
CLI
ノーコードチューニングはzenithtuneコマンドで実行します。3つのサブコマンドがあります。
| サブコマンド | 説明 |
|---|---|
optimize | チューニングの実行 |
apply | チューニング結果の最良パラメータを適用してコマンドを実行 |
analyze | チューニング結果の分析・可視化 |
optimize: チューニングの実行
zenithtune optimize --preset <Preset名> [オプション] -- <チューニング対象コマンド>
引数:
| 引数 | 説明 | デフォルト |
|---|---|---|
--preset | Presetの名前（必須） | - |
--strategy | Strategyの名前 | Presetの推奨Strategy |
--evaluator | Evaluatorの名前 | Presetの推奨Evaluator |
--n-trials | 試行回数 | 10 |
--output-dir | 結果出力ディレクトリ | outputs |
--study-name | Optunaスタディ名 | study_YYYYMMDD_HHMMSS |
--db-path | 既存DBからの再開時のパス | - |
--skip-default | ベースライン試行をスキップ | False |
--timeout | 静的タイムアウト秒数（後述） | なし |
--timeout-dynamic | 動的タイムアウト係数（後述） | なし（指定時: 1.5） |
--args | Presetに渡すカンマ区切りのkey=value | - |
--skip-duplicate | 同一パラメータセットの再実行をスキップ | True |
--list | 登録済みのPreset/Strategy/Evaluatorを一覧表示 | - |
--dev | デモ用コンポーネント（dev:プレフィックス付き）を有効化 | False |
使用例:
# dev:demo Presetで10回のチューニング
zenithtune optimize --preset dev:demo --dev --n-trials 10 -- python train.py --epochs 3
# 既存のスタディから20回追加でチューニングを再開
zenithtune optimize --preset dev:demo --dev --n-trials 20 --db-path outputs/my_study/study.db -- python train.py --epochs 3
# 登録済みのPreset/Strategy/Evaluatorを確認
zenithtune optimize --list --dev
zenithtuneコマンドとチューニング対象コマンドの間にはセパレータ--を記述してください。
apply: 最良パラメータの適用
チューニング結果（DBファイル）から最良のパラメータを取得し、コマンドに適用して実行します。
zenithtune apply --db-path <DBファイルパス> --preset <Preset名> [--args <key=value,...>] -- <実行コマンド>
使用例:
# チューニング結果を適用してコマンドを実行
zenithtune apply --db-path outputs/my_study/study.db --preset dev:demo --dev -- python train.py --epochs 100
applyサブコマンドは--db-pathで指定したチューニング結果の最良パラメータでコマンドを1回実行します。
チューニング時より長い--epochsを指定するなど、本番実行用にコマンドを変更して実行できます。
optimize時に指定した--presetや--argsはapply時にも同じものを指定する必要があります。
analyze: チューニング結果の分析
既存のスタディDBから結果を分析したい場合に使用します。
analyzeサブコマンドと同一の結果分析はoptimizeの終了時に自動的に実行されるため、分析結果を削除してしまった場合や、optimizeコマンドを途中で中断した場合に有用です。
zenithtune analyze <DBファイルパス>
使用例:
zenithtune analyze outputs/my_study/study.db
分析結果として、DBファイルと同じディレクトリに以下のファイルが生成されます:
history.png: 試行過程におけるチューニング対象（目的関数値）の推移timeline.png: 各試行のタイムラインimportances.png: パラメータ重要度contour.html: パラメータ間の等高線プロット
ワークフロー例
以下は、dev:demoプリセットを使ったチューニングの一連の流れです。
dev:demoはGPUや学習フレームワークなしで操作を試せるデモ用プリセットです。
実際のチューニングではmegatronなどのプリセットを使用してください（Megatronプリセットを参照）。
# 1. 利用可能なプリセットを確認
zenithtune optimize --list --dev
# 2. 10回のチューニングを実行
zenithtune optimize --preset dev:demo --dev --n-trials 10 -- python train.py --epochs 3
# 3. 結果を分析
zenithtune analyze outputs/study_20260305_120000/study.db
# 4. 最適パラメータで本番実行
zenithtune apply --db-path outputs/study_20260305_120000/study.db --preset dev:demo --dev -- python train.py --epochs 100
便利機能
チューニング効果を高めるためのいくつかの便利機能を紹介します。
タイムアウト
タイムアウトを超えた試行は失敗（FAIL）として記録され、次の試行に進みます。 高速化のためのチューニングにおいて、著しく遅い試行を制限することで総チューニング時間を削減することができます。 タイムアウトには静的タイムアウトと動的タイムアウトの2種類が存在します。
静的タイムアウト
--timeoutで秒数を直接指定します。すべての試行に同じタイムアウトが適用されます。
# 各試行を1200秒（20分）でタイムアウト
zenithtune optimize --preset <Preset名> --timeout 1200 -- python train.py
動的タイムアウト
--timeout-dynamicを指定すると、これまでの最良試行の実行時間に基づいてタイムアウトが自動調整されます。
最良試行の実行時間 × 係数（デフォルト: 1.5）がタイムアウトとして設定されます。
また、まだ完了した試行がない場合（初期の試行）はタイムアウトなしで実行されます。
# 動的タイムアウト（デフォルト係数: 1.5）
zenithtune optimize --preset <Preset名> --timeout-dynamic -- python train.py
# 係数を指定（最良試行の3倍まで許容）
zenithtune optimize --preset <Preset名> --timeout-dynamic 3.0 -- python train.py
動的タイムアウトは、パラメータの組み合わせによって実行時間が大きく変動する場合に有効です。 明らかに遅い試行を早期に打ち切ることで、チューニング全体の時間を短縮できます。
静的タイムアウトと動的タイムアウトの併用
--timeoutと--timeout-dynamicは同時に指定できます。
両方指定した場合、各試行のタイムアウトは静的タイムアウトと動的タイムアウトの短い方が適用されます。
# 静的1200秒（20分）を上限に、動的タイムアウト（係数2.0）で早期打ち切り
zenithtune optimize --preset <Preset名> --timeout 1200 --timeout-dynamic 2.0 -- python train.py
これにより、動的タイムアウトで普段は効率的に打ち切りつつ、最初の試行が極端に遅い場合でも静的タイムアウトが絶対上限として機能します。
ベースライン試行
optimize実行時、デフォルトではチューニングパラメータを適用しない元のコマンドが最初に実行されます（ベースライン試行）。
これにより、チューニングによる改善率をanalyzeで確認できます。
ベースライン試行が不要な場合は--skip-defaultを指定してスキップできます。
zenithtune optimize --preset dev:demo --dev --skip-default -- python train.py
Python APIでの使用
CLIの代わりにPythonコードからPresetTuner APIを使用してチューニングすることもできます。
from aibooster.intelligence.zenith_tune.tuners.preset import PresetTuner
# チューニングの実行
tuner = PresetTuner(
command="python train.py --epochs 3",
preset="dev:demo",
)
best_value, best_params = tuner.optimize(n_trials=10, dynamic_timeout=1.5)
# 分析
tuner.analyze()
# 最適パラメータの適用と実行
returncode = PresetTuner.apply_from_db(
db_path="outputs/my_study/study.db",
preset="dev:demo",
command="python train.py --epochs 100",
)
カスタマイズ
独自のPresetやEvaluatorの作成方法についてはカスタマイズを参照してく ださい。