skypilot

SkyPilot スキル

SkyPilot は、あらゆるクラウド、Slurm、Kubernetes で AI ワークロードを実行するための統合フレームワークです。25 以上のクラウド（AWS、GCP、Azure、Coreweave、Nebius、Lambda、Together AI、RunPod など）、Kubernetes クラスター、Slurm クラスターで、クラスターの起動、ジョブの実行、モデルの提供を行うための単一のインターフェースを提供します。

SkyPilot を使用する場面

次のような場合に SkyPilot を使用してください：

• あらゆるクラウド、Slurm、Kubernetes クラスター上のコンピューティングリソースを管理する
• あらゆるクラウド、Kubernetes、Slurm で CPU/GPU/TPU（GB300、GB200、B200、H200、H100 など）を起動する
• トレーニング、ファインチューニング、バッチ推論のジョブを実行する
• 自動スケーリングとマルチクラウドレプリカ（SkyServe）でモデルを提供する
• 自動ライフサイクル管理と復旧機能を使って長時間実行されるジョブを実行する（マネージドジョブ）
• クラウド全体から最も安価、または最も利用しやすい GPU を見つける

次の用途には SkyPilot を使用しないでください：

• ローカルのみのワークロード（Docker/conda を直接使用してください）

機能：用途に応じた使い分け

SkyPilot には 3 つのコア抽象化があります。ワークフローの各段階に適したものを使用してください：

1. SkyPilot クラスター（sky launch / sky exec）— 対話的な開発とデバッグ

• 初期開発、デバッグ、実験に使用します
• クラスターを起動し、SSH で接続するか、VSCode/Cursor に接続して（code --remote ssh-remote+CLUSTER）、素早く反復します
• 停止／削除するか、自動停止がトリガーされるまでクラスターは稼働し続けます
• 最適な用途：プロトタイプ作成、デバッグ、短時間の実験

2. マネージドジョブ（sky jobs launch）— 長時間実行されるトレーニングジョブとバッチジョブ

• 無人で実行すべき長時間実行ジョブを送信するときに使用します
• プロビジョニング、実行、復旧、終了までのライフサイクル全体を管理します
• スポットインスタンスのプリエンプション、クォータ制限、一時的な障害から自動的に復旧します
• クラウド、Kubernetes、Slurm で動作します（プリエンプションとクォータに対応）
• 最適な用途：トレーニング実行、ファインチューニング、ハイパーパラメーター探索、バッチ推論

3. SkyServe（sky serve up）— 本番環境でのモデル提供

• 自動スケーリングで大規模にモデルを提供するときに使用します
• まず sky launch とポートの公開でモデル提供の構成をテストし、その後 sky serve up を使ってスケールします
• ロードバランシング、自動スケーリング、マルチクラウドレプリカを提供します
• 最適な用途：モデル提供エンドポイント、API サービス

開始前の準備（エージェントの初期設定）

SkyPilot がインストールされ、API サーバーに接続され、クラウドの認証情報が設定されていることを確認するため、初期設定を行います。確認後は、ユーザーのタスクに進んでください。

ステップ 1：インストールと API サーバーへの接続を確認する

sky api info

出力に含まれる内容	意味	次の操作
サーバーのバージョンとステータス	サーバーが稼働し、接続されています	初期設定完了です。 ユーザーのタスクに進んでください。
No SkyPilot API server is connected	サーバーが接続されていません	下記の「サーバーを起動または接続する」に進んでください。
Could not connect to SkyPilot API server	リモートサーバーに到達できないか、認証の有効期限が切れています	ユーザーに伝え、再接続するために sky api login --relogin -e <endpoint> を提案してください。
command not found: sky	SkyPilot がインストールされていません	下記の「SkyPilot をインストールする」に進んでください。

SkyPilot をインストールする（sky コマンドが見つからない場合のみ）：

pip install "skypilot[aws,gcp,kubernetes]"  # Pick clouds the user needs

不明な場合は、ユーザーに必要なクラウドを尋ねてから、sky api info を再実行してください。

サーバーを起動または接続する（「稼働していない」場合のみ）：

ユーザーに尋ねてください：

接続先となる既存の SkyPilot API サーバーはありますか？ それともローカルで起動しますか？

• 既存のサーバーに接続する： sky api login -e <API_SERVER_URL> — URL をユーザーに尋ねてください。
• ローカルで起動する： sky api start

どちらの方法でも、サーバーに到達できることを確認するため、sky api info を再実行してください。

ステップ 2：クラウドの認証情報を確認する（新規セットアップの場合のみ — サーバーがすでに稼働している場合は省略）

sky check -o json

有効または無効になっているクラウドが表示されます。ユーザーが使用するクラウドが有効でない場合は、認証情報の設定を案内してください（トラブルシューティングを参照）。

基本的なコマンド

ステータスやクエリのコマンドでは、-o json を使うと、テーブルではなく構造化された JSON 出力を取得できます。

クラスター — 対話型の開発とデバッグ：

コマンド	説明
sky launch -c NAME task.yaml	クラスターを起動するか、タスクを実行します
sky exec NAME task.yaml	既存のクラスターでタスクを実行します（プロビジョニングを省略）。毎回 workdir を同期します
sky exec NAME task.yaml -d	同じ処理を行いますが、すぐにデタッチします（ログをストリーミングしません）
sky status -o json	すべてのクラスターを表示します
sky logs NAME	クラスターからジョブのログをストリーミングします
sky logs NAME --no-follow	既存のログを出力して、すぐに終了します
sky logs NAME --tail 50	ログの末尾 50 行を出力して終了します
sky logs NAME --status	終了コード 0=成功、100=失敗、101=未完了、102=見つからない、103=キャンセル済みで終了します
sky queue NAME -o json	クラスター上のジョブをステータス付きで一覧表示します（構造化 JSON）
sky stop NAME / sky start NAME	コストを節約するために停止／再起動します（ディスクは保持されます）
sky down NAME	クラスターを完全に破棄します
sky gpus list -o json	各クラウドで利用可能な GPU の種類を一覧表示します

マネージドジョブ — 長時間実行される無人ワークロード：

コマンド	説明
sky jobs launch task.yaml	マネージドジョブを起動します（ライフサイクル管理と復旧を自動化）
sky jobs queue -o json	すべてのマネージドジョブとそのステータスを表示します
sky jobs logs JOB_ID	マネージドジョブのログをストリーミングします
sky jobs cancel JOB_ID	マネージドジョブをキャンセルします

SkyServe — オートスケーリングによるモデルサービング：

コマンド	説明
sky serve up serve.yaml -n NAME	モデルサービングサービスを開始します
sky serve status NAME	サービスのステータスとエンドポイント URL を表示します
sky serve update NAME new.yaml	実行中のサービスを更新します（ローリング更新）
sky serve down NAME	サービスを破棄します

CLI の詳細については、CLI リファレンスを参照してください。

クイックスタート

# Launch a GPU cluster
sky launch -c mycluster --gpus H100 -- nvidia-smi

# Run a task from YAML
sky launch -c mycluster task.yaml

# SSH into cluster
ssh mycluster

# Connect VSCode or Cursor to the cluster for interactive development
code --remote ssh-remote+mycluster /home/user/sky_workdir
# or: cursor --remote ssh-remote+mycluster /home/user/sky_workdir

# Tear down
sky down mycluster

タスク YAML の構造

タスク YAML は SkyPilot の主要なインターフェースです。すべてのフィールドは省略可能です。

# task.yaml
name: my-training-job

# Local directory to sync to remote ~/sky_workdir
workdir: .

# Number of nodes (for distributed training)
num_nodes: 1

resources:
  # GPU/TPU accelerators (SkyPilot auto-selects the cheapest cloud/region)
  accelerators: H200:8
  # Optional: pin to a specific cloud/region/infra
  # infra: aws  # or aws/us-east-1, k8s, ssh/my-pool
  # If infra is left out, SkyPilot automatically fails over across all
  # enabled clouds/regions to find the cheapest available option.
  # Use spot instances for cost savings
  use_spot: false
  # Disk size in GB
  disk_size: 256
  # Open ports for serving
  ports: 8080

# Environment variables (accessible in file_mounts, setup, and run)
envs:
  MODEL_NAME: my-model
  BATCH_SIZE: 32

# Setup: runs once on cluster creation, cached on reuse
setup: |
  pip install torch transformers

# Run: the main command
run: |
  python train.py --model $MODEL_NAME --batch-size $BATCH_SIZE

ファイルマウント、SkyPilot が設定する環境変数、詳細フィールドを含む YAML スキーマ全体については、YAML 仕様を参照してください。

GPU とクラウドの選択

重要：クラウドとリージョンの選択は SkyPilot に任せてください。 sky gpus list の出力を解析して、クラウド／リージョン／インスタンスを手動で選ばないでください。SkyPilot のオプティマイザーは、有効になっているすべてのクラウドから、利用可能な最も安価なオプションを自動的に選択します。ユーザーが特定のクラウドまたはリージョンを明示的に指定した場合にのみ、infra: を指定してください。

デフォルトの動作（推奨）： GPU の種類だけを指定します。SkyPilot が最も安価なクラウド／リージョンを自動的に探します。

resources:
  accelerators: H200:8  # SkyPilot picks the cheapest cloud/region with H200:8

ユーザーが GPU の種類を指定していない場合は、必要な GPU、または実行するモデル／ワークロードを尋ねて、適切なものを提案してください。sky gpus list を実行して代わりに選ばないでください。選択肢を提示してユーザーに決めてもらうか、any_of を使って SkyPilot に可用性を最大化させてください。

# Let SkyPilot choose from multiple acceptable GPU types (cheapest wins)
resources:
  any_of:
    - accelerators: H100:8
    - accelerators: A100-80GB:8
    - accelerators: A100:8

ユーザーに厳密な希望がある場合にのみ、ordered を使ってください。

# Try H100 first on AWS, fall back to GCP, then A100
resources:
  ordered:
    - infra: aws/us-east-1
      accelerators: H100:8
    - infra: gcp/us-central1
      accelerators: H100:8
    - infra: aws/us-west-2
      accelerators: A100-80GB:8

ユーザーが「AWS を使って」や「GCP us-central1 で実行して」のように明示した場合にのみ、infra: を設定してください。

resources:
  infra: aws             # User asked for AWS specifically
  accelerators: H100:8

クラスターのライフサイクル

# Launch and run a task
sky launch -c mycluster task.yaml

# Launch with autostop at launch time (preferred: saves cost, no follow-up command needed)
sky launch -c mycluster task.yaml -i 30        # stop after 30 min idle
sky launch -c mycluster task.yaml -i 30 --down # tear down after 30 min idle

# Override or pass environment variables via CLI
sky launch -c mycluster task.yaml --env MODEL_NAME=llama3 --env BATCH_SIZE=64

# Re-run a different task on the same cluster (fast, skips provisioning)
sky exec mycluster another_task.yaml

# Run an inline command
sky exec mycluster -- python train.py --epochs 10

# Set autostop after launch (use if you forgot to set -i at launch time)
sky autostop mycluster -i 30        # stop after 30 min idle, preserving disk (can restart with sky start)
sky autostop mycluster -i 30 --down # tear down after 30 min idle (disk is deleted, cannot restart)

# Stop to save costs, restart later
sky stop mycluster
sky start mycluster

# Tear down completely
sky down mycluster

workdir の同期動作

workdir: は、各 sky exec の前に rsync を使ってリモートの ~/sky_workdir に同期されます。rsync は追加同期であり、ローカルで削除されたファイルはリモートから削除されません。 そのため、古いビルド成果物や設定ファイルを使って実験が実行されることがあります。

まっさらな状態にするには、SSH 接続してから sky exec の前にファイルを削除してください。

ssh mycluster "rm -rf ~/sky_workdir"
sky exec mycluster task.yaml

特定の成果物だけを削除すればよい場合は、run: の中でクリーンアップしてください。

run: |
  find ~/sky_workdir/build -name '*.o' -delete 2>/dev/null || true
  cd ~/sky_workdir && make

マネージドジョブ

バックグラウンドで実行し続ける必要があるジョブには、sky jobs launch を使用します。SkyPilot が、プロビジョニング、実行、プリエンプション・クォータ・障害からの復旧、ティアダウンまで、ライフサイクル全体を管理します。

# managed-job.yaml
name: training-job

resources:
  accelerators: A100:8

run: |
  python train.py --resume-from-checkpoint

# Launch as managed job
sky jobs launch managed-job.yaml

# Check status
sky jobs queue -o json

# Stream logs
sky jobs logs <job_id>

# Cancel
sky jobs cancel <job_id>

チェックポイントのパターン：トレーニングスクリプトでは、チェックポイントを永続ストレージ（クラウドバケットまたはボリューム）に保存し、再起動時に最新のチェックポイントから再開するようにします。SkyPilot がクラスターの復旧を担当し、スクリプトが状態の復旧を担当します。

SkyServe：モデルサービング

# serve.yaml
resources:
  accelerators: A100:1
  ports: 8080

run: |
  python -m vllm.entrypoints.openai.api_server \
    --model meta-llama/Llama-3.1-8B-Instruct \
    --port 8080

service:
  readiness_probe: /v1/models
  replica_policy:
    min_replicas: 1
    max_replicas: 3
    target_qps_per_replica: 5

# Start service
sky serve up serve.yaml -n my-llm

# Check status / get endpoint
sky serve status my-llm
sky serve status my-llm --endpoint

# Update (rolling)
sky serve update my-llm new-serve.yaml

# Tear down
sky serve down my-llm

よくあるワークフロー

ファインチューニングのワークフロー

1. setup（依存関係のインストール）と run（トレーニングコマンド）を含むタスク YAML を作成します
2. file_mounts または workdir を使用してコードを同期します
3. sky launch -c train task.yaml で起動します
4. sky logs train で監視します
5. sky exec train -- python eval.py で同じクラスター上で評価します
6. 完了したら sky down train を実行します

ハイパーパラメーターのスイープ

1. envs を含むパラメーター化された YAML を作成します
2. 複数のマネージドジョブを起動します：

   for lr in 1e-4 1e-5 1e-6; do
     sky jobs launch sweep.yaml --env LR=$lr --name sweep-lr-$lr
   done
   

3. sky jobs queue -o json で監視します

モデルサービングのデプロイ

1. service: セクションを含むサーブ YAML を作成します
2. sky serve up serve.yaml -n my-service を実行します
3. エンドポイントを取得します：sky serve status my-service --endpoint
4. モデルを更新します：sky serve update my-service updated.yaml

並列実験の送信

sky exec -d を使用して、ブロックせずに複数の VM へジョブを送信し、その後結果を収集します。

# Submit all experiments (detached, returns after job is queued)
for i in 1 2 3 4; do
  sky exec exp-vm-0$i task.yaml --env LR=1e-$i -d
done

# Get the latest job ID from a cluster
job_id=$(sky queue exp-vm-01 -o json \
  | python3 -c "import sys, json; jobs = json.load(sys.stdin).get('exp-vm-01', []); print(max(j['job_id'] for j in jobs) if jobs else '')")

# Wait for a specific job and fetch last 50 lines
sky logs exp-vm-01 $job_id --status && sky logs exp-vm-01 $job_id --tail 50

# Check all jobs across a cluster at once
sky queue exp-vm-01 -o json

Slurm ワークロードの変換

ユーザーが既存の sbatch スクリプトや salloc ワークフローを使用している場合、または Slurm コマンドと SkyPilot の対応について尋ねている場合は、YAML を作成する前に**Slurm からの移行を読んでください。**対応関係には、間違えやすい、直感的でない部分があります。

• --time は autostop に対応しません。Slurm では autostop はサポートされていません。config.slurm.sbatch_options.time を使用してください。
• 単独の srun <cmd> は、通常、変換せずに削除します。run はすでにすべてのノードで実行されます。srun を維持するのは MPI/PMIx ランチャーの場合のみで、その場合は --overlap と rank 0 のガードが必要です。
• --account／--qos／--exclusive や、ほかのモデル化されていないディレクティブは config.slurm.sbatch_options を通じて指定します。これは値をそのまま sbatch に渡します。
• sbatch --array は $SKYPILOT_JOB_RANK を使う sky jobs launch --num-jobs に対応し、シェルループには対応しません。

sky launch --dryrun <yaml> で結果を検証してください。sky jobs launch には --dryrun がないため、最終的なコマンドが sky jobs launch の場合でも、sky launch 経由でドライランを実行してください。

ユーザーが Slurm を離れたいと決めつけないでください。SkyPilot はログインノードを通じて既存の Slurm クラスターにジョブを送信します。Kubernetes への移行は別の問題であり、制約も異なります。

エージェントのフィードバックループ

SkyPilot をプログラムから使用する場合は、次のループに従ってください。

1. 検証：sky launch --dryrun task.yaml（リソースの利用可能性とコストを確認）
2. 起動：sky launch -c mycluster task.yaml
3. 監視：sky status -o json と sky queue mycluster -o json
4. 完了を待機：sky logs mycluster <JOB_ID>（ログをストリーミングして進捗を確認し、停滞に対応できるようにします。ジョブが終了するまでブロックします。sky queue mycluster -o json から JOB_ID を取得してください）。中間出力が不要な長時間実行ジョブでは、代わりに sky logs mycluster <JOB_ID> --status を使用します（出力せずにブロックし、成功時に 0 で終了します）。
5. 出力を確認：sky logs mycluster <JOB_ID> --no-follow または sky logs mycluster <JOB_ID> --tail 100
6. デバッグ：ssh mycluster（対話型）
7. 反復：sky exec mycluster updated_task.yaml（既存のクラスター上で実行）
8. クリーンアップ：sky down mycluster

sleep と sky queue を組み合わせてポーリングしないでください。sky logs CLUSTER JOB_ID を使用してログをストリーミングし、完了まで待機してください。終了コードだけが必要な場合は --status を使用し、完了後に直近の出力を取得する場合は --tail N を使用します。

マネージドジョブの調査

ユーザーから「自分のジョブは何をしていますか？」や「なぜ保留中／失敗になっていますか？」と聞かれた場合は、以下を順番に実行し、質問に答えられた時点で終了します。

1. sky jobs queue -v -o json — status、details、failure_reason（detailsを含めるには-vが必要です）。開始していないジョブの場合、答えはdetailsにあります。キューに入っているパーティションとともに、クラスターが待機している理由（例：SlurmのQOSGrpGRESやDependency）が示されます。
2. sky jobs logs JOB_ID --tail 100 --no-follow — タスクの最近の出力です。プロビジョニング／復旧ログには--controllerを指定します。

detailsとSlurmの保留理由の読み方については、ジョブの調査をご覧ください。

エージェントによくある間違い

間違い	なぜ間違いなのか	代わりに行うこと
sky gpus listの出力をもとにクラウド／リージョンを手動で選ぶ	SkyPilotのオプティマイザーが自動で、より適切に選択します	accelerators:だけを設定し、SkyPilotに選択させます
長時間実行する無人ジョブにsky launchを使う	プリエンプトや中断が発生しても復旧できません	無人ジョブにはsky jobs launchを使います
作業終了後にsky downまたは自動停止を忘れる	アイドル状態のクラスターに料金がかかり続けます	必ずクリーンアップするか、起動時に-i <minutes> --downを使います
ユーザーからの依頼がないのにinfra: awsをハードコードする	利用可能性が低下し、コストが増加します	ユーザーがクラウドを明示的に指定した場合にのみinfra:を設定します
設定可能な値にenvs:を使わない	再利用やCLIからの上書きが困難になります	YAMLではenvs:を使い、パラメーター化には--env KEY=VALを使います
-c <name>を指定せずにsky launchを実行する	ランダムな名前のクラスターが作成され、参照しにくくなります	クラスターには必ず-cで名前を付けます
ステータスコマンドのテーブル出力を解析する	テーブル形式は人間向けで、解析に適していません	構造化出力には-o jsonを使います
非推奨のcloud:／region:／zone:フィールドを使う	infra:に置き換えられています	代わりにinfra: aws/us-east-1を使います
sleepとsky queueでジョブのステータスをポーリングする	トークンを浪費し、タイミングの問題が発生しやすく、不安定です	完了まで待つにはsky logs CLUSTER JOB_ID --statusを使います
workdirの同期でリモートのファイルが削除されると思い込む	rsyncは追加同期のため、古いリモートファイルはsky execの呼び出し後も残ります	SSHで接続して~/sky_workdirを手動でクリーンアップするか、run:スクリプト内でクリーンアップします
最後の出力だけが必要なのに--tailを使わない	長時間のジョブでは、ログ全体をストリーミングするとトークンを浪費します	直近N行を取得するにはsky logs CLUSTER JOB_ID --tail 50を使います

よくある問題のクイックリファレンス

問題	解決策
GPUを利用できない	フォールバックにはany_ofを使うか、別のリージョン／クラウドを試します
セットアップに時間がかかりすぎる	SkyPilotはセットアップをキャッシュします。再実行時はsky execを使ってセットアップを省略します
タスクが何も出力せずに失敗する	デバッグにはsky logs <cluster>またはssh <cluster>を確認します
クラスターがINITのまま動かない	sky down <cluster>を実行して再起動します
プリエンプション／クォータ	自動復旧とライフサイクル管理にはsky jobs launchを使います
ポートにアクセスできない	リソースでports:が設定され、セキュリティグループでトラフィックが許可されていることを確認します
ファイル同期が遅い	大規模なデータセットでは、workdirの代わりにクラウドバケットマウントを使います
認証情報エラー	sky check -o jsonを実行し、無効になっているクラウドを確認します

参考資料

詳しいリファレンスドキュメントについては、以下をご覧ください。

• CLI リファレンス — すべてのコマンドとフラグ
• YAML 仕様 — タスク YAML の完全なスキーマ、ファイルマウント、環境変数
• Python SDK — プログラム API と SDK の使用方法
• 高度なパターン — マルチクラウド、分散トレーニング、本番環境向けパターン
• Slurm からの移行 — sbatch スクリプトをタスク YAML に変換する方法、Slurm コマンドと環境変数の対応、Slurm 固有の制約
• ジョブの調査 — 「自分のジョブは何をしていて、なぜなのか」という疑問に答えるコマンド、details、イベント、Slurm の保留理由の読み方
• トラブルシューティング — エラーの診断と解決策
• 例 — コピーしてそのまま使えるタスク YAML の例