貸してください、RunPod を Kaggle でこう使うのはどうですか

この記事は、私の作成した pxq というジョブ管理 CLI の紹介です。

この記事を読んでほしい人

• クラウド GPU を使いたいけどイマイチ使えてない人
• お家に GPU は買えないけど、Kaggle でゴリゴリ GPU 使いたい人
• RunPod やクラウド GPU の仕組みに詳しくない人

多くの Kaggler が抱えている課題

Kaggle でクラウド GPU って便利そうだけど…

• 使い方がよくわからん
• できるだけ安く GPU を使い倒したい
• 実験のたびにポチポチ設定するのが面倒
• 複数の実験を並列に回したい

そんな悩みを解決するのが、私が開発した pxq です。

pxq を使うのはどうでしょう？

pxq は、クラウド GPU を「もっと簡単に便利に」使うためのツールです。

• GitHub リポジトリ: https://github.com/takeru1205/pxq
• PyPI プロジェクト: https://pypi.org/project/pxq

pxq でできること

1. シンプルな CLI でジョブを管理: pxq add "コマンド" だけで GPU ジョブを実行
2. 自動 Pod 管理: ジョブ完了後、自動的に Pod を停止して課金を抑制（managed モード）
3. Web ダッシュボード: 進捗をリアルタイムで監視
4. Network Volume 活用: 一度ダウンロードしたデータを複数 Pod で使い回せる
5. SSH 接続: 実行中の Pod に簡単 SSH デバッグ

RunPod とは？初心者向け解説

pxq を使う前に、RunPod の基本を知っておきましょう。

RunPod の主要コンセプト

料金の目安（2026 年現在）

使い方のイメージ

このサンプルでは、次の 2 段階のワークロードを実施します。

1. CPU Pod で Kaggle データセットを Network Volume にダウンロード
   • CPU なら安い！データダウンロード専用
2. ダウンロードしたデータセットを GPU Pod にアタッチして学習
   • 同じ Volume をマウントするだけ。再ダウンロード不要

RunPod にジョブを発行してみよう

まずは RunPod 側の準備をしましょう

RunPod（リファラルリンク）にアクセスして、アカウントを作成します。

Step 1: API キーを取得する

1. RunPod 画面右上のアカウントアイコン →「Settings」
2. 「API Keys」タブを選択
3. 「New API Key」をクリック
4. 表示されたキーをコピーして控える

Step 2: Kaggle API トークンを Secrets に登録する

Kaggle のデータセットをダウンロードするには、Kaggle API トークンが必要です。

1. Kaggle 設定ページ にアクセス
2. 「API」セクションで「Generate New Token」をクリック
3. Tokenをコピー
4. RunPod の「Secrets」に以下として登録：
   • KAGGLE_USERNAME: あなたの Kaggle ユーザー名
   • KAGGLE_API_TOKEN: API キー

Step 3: Network Volume を作成する

RunPod では、Network Volume を作成して各 Pod に紐づけることで、共通のデータにアクセスできます。

1. Storage タブ →「New Network Volume」をクリック
2. 以下の設定を入力：
   • リージョン: GPU を使いたいリージョンと同じにする（重要！）
   • サイズ: 10GB 以上推奨
3. 「Create」をクリック
4. 表示された Volume ID をコピー

注意: Network Volume と Pod のリージョンは必ず同一にしてください。異なるリージョンではマウントできません。

pxq をインストールしよう

uv を使う方法（推奨）

# uv tool として pxq をインストール
$ uv tool install pxq

# バージョン確認
$ pxq --version

PyPI からインストール

$ pip install pxq

最新開発版をインストール

$ uv tool install git+https://github.com/takeru1205/pxq.git

pxq のセットアップ

Step 1: RunPod API キーを設定する

環境変数として API キーを設定します。

export PXQ_RUNPOD_API_KEY="your_runpod_api_key"

ヒント: ~/.bashrc や ~/.zshrc に追加すると、ターミナル起動時に自動で設定されます。

Step 2: pxq サーバーを起動する

pxq はサーバー・クライアントアーキテクチャで動作します。

$ pxq server

サーバーは http://127.0.0.1:8765 で起動し、バックグラウンドでジョブを管理します。

ジョブを発行してみよう

ローカルジョブ（動作確認用）

まずは簡単なコマンドで試してみましょう。

$ pxq add "echo Hello pxq"

ジョブが追加され、ローカルで実行されます。

ジョブの状態を確認する

$ pxq status

以下のような出力が得られます：

{
  "jobs": [
    {
      "id": 61,
      "command": "echo Hello pxq",
      "status": "queued",
      "provider": "local",
      "managed": false,
      "created_at": "2026-03-22T12:39:34.078141Z",
      "updated_at": "2026-03-22T12:39:34.078141Z",
      "started_at": null,
      "finished_at": null,
      "exit_code": null,
      "pod_id": null,
      "workdir": "/Users/take/pxq",
      "gpu_type": null,
      "cpu_count": null,
      "volume_id": null,
      "volume_mount_path": null,
      "region": null,
      "secure_cloud": false,
      "cpu_flavor_ids": null,
      "env": null,
      "template_id": null,
      "image_name": null,
      "error_message": null,
      "local_pid": null
    }
  ],
  "count": 1
}

ジョブのステータス遷移

ジョブは以下のステータスを遷移します：

CPU Pod でネットワークボリュームにデータセットをダウンロード

config/dataset-download.yaml ファイルを作成して、次のように設定します。

# config/dataset-download.yaml
provider: runpod
managed: true
secure_cloud: true
region: EU-RO-1
volume: {作成した VolumeID}
volume_path: /kaggle/input
cpu_count: 1
cpu_flavor_ids:
  - cpu3c
env:
  KAGGLE_USERNAME: "{{ RUNPOD_SECRET_KAGGLE_USERNAME }}"
  KAGGLE_API_TOKEN: "{{ RUNPOD_SECRET_KAGGLE_API_TOKEN }}"

ポイント: {{ RUNPOD_SECRET_* }} プレースホルダーを使うと、RunPod Secrets に登録した値が自動的に展開されます。

この設定ファイルを使って、データセットをダウンロードします。

$ COMPETITION_NAME="spaceship-titanic"
$ pxq add "pip install kaggle && mkdir -p ${COMPETITION_NAME} && kaggle competitions download -c ${COMPETITION_NAME} -p ${COMPETITION_NAME} && unzip ${COMPETITION_NAME}/*.zip -d /kaggle/input/${COMPETITION_NAME}" --config config/dataset-download.yaml

実行しているコマンドの内訳：

1. pip install kaggle - Kaggle CLI をインストール
2. mkdir -p spaceship-titanic - ディレクトリ作成
3. kaggle competitions download -c spaceship-titanic -p spaceship-titanic - データセットダウンロード
4. unzip spaceship-titanic/*.zip -d /kaggle/input/spaceship-titanic - 解凍

これで、Network Volume の /kaggle/input/spaceship-titanic/ にデータセットが保存されました。

ダウンロードしたデータを GPU Pod で学習してみる

次に、GPU Pod で学習ジョブを実行します。

学習ジョブ用の config を作成

config/torch-cuda-with-volume.yaml を作成：

# config/torch-cuda-with-volume.yaml
provider: runpod
managed: true
secure_cloud: true
gpu_type: RTX4090:1
region: EU-RO-1
volume: {ダウンロードに使った Volume ID}
volume_path: /kaggle/input
image_name: runpod/pytorch:2.1.0-py3.10-cuda11.8.0-devel-ubuntu22.04
workdir: .
env:
  KAGGLE_USERNAME: "{{ RUNPOD_SECRET_KAGGLE_USERNAME }}"
  KAGGLE_API_TOKEN: "{{ RUNPOD_SECRET_KAGGLE_API_TOKEN }}"

学習コードを準備

$ curl https://raw.githubusercontent.com/takeru1205/pxq/main/examples/runpod/train_model.py > train_model.py
$ curl https://raw.githubusercontent.com/takeru1205/pxq/main/examples/runpod/requirements.txt > requirements.txt

ジョブを実行

$ pxq add "nvidia-smi && pwd && ls && pip install -r requirements.txt && python train_model.py" --config config/torch-cuda-with-volume.yaml

workdir: . を指定すると、カレントディレクトリのファイルが Pod にコピーされます。

結果を確認

ダッシュボード（http://127.0.0.1:8765）でジョブの状態を確認しましょう。

• nvidia-smi が GPU を認識していることを確認
• 学習ログがリアルタイムで表示される

効果的な使い方

pxq のメリットは以下の 3 つです：

1. シンプル: 1 コマンドで GPU ジョブを実行
2. マネージド: ジョブ完了後、自動で Pod 停止 → 無駄な課金なし
3. 再現性: config ファイルで実験設定を管理

実験ディレクトリごとのジョブ管理

Kaggle では、1 実験 1 ディレクトリで管理している人も多いでしょう。pxq なら簡単に実現できます。

# kaggle_exp.yaml
provider: runpod
managed: true
secure_cloud: true
gpu_type: RTX4090:1
region: EU-RO-1
volume: {Volume ID}
volume_path: /kaggle/input
image_name: runpod/pytorch:2.1.0-py3.10-cuda11.8.0-devel-ubuntu22.04
env:
  KAGGLE_USERNAME: "{{ RUNPOD_SECRET_KAGGLE_USERNAME }}"
  KAGGLE_API_TOKEN: "{{ RUNPOD_SECRET_KAGGLE_API_TOKEN }}"
  WANDB_API_KEY: "{{ RUNPOD_SECRET_WANDB_API_KEY }}"
  WANDB_EXP_NAME: "sample_kaggle_exp"

# 実験 1 を実行
$ pxq add "python exp.py" --config kaggle_exp.yaml --dir exp100

# 実験 2 を実行
$ pxq add "python exp.py" --config kaggle_exp.yaml --dir exp101

--dir オプションを使うと、指定したディレクトリに移動してジョブを実行できます。

WandB 連携で実験ログを管理

Secrets に WandB API キーを登録しておけば、実行中の実験ログを自動的に WandB に送信できます。

# RunPod Secrets に登録
WANDB_API_KEY=your_wandb_key

その他の機能

非 managed な Pod を使う

--managed を付けないと、ジョブ完了後も Pod が稼働し続けます。

$ pxq add "python train.py" --provider runpod --gpu RTX4090:1

こんな時に便利:

• Pod に SSH してデバッグしたい
• 複数のコマンドを続けて実行したい
• 学習結果を直接確認したい

SSH 接続

実行中の Pod に SSH 接続できます：

$ pxq ssh {job id}

ジョブのキャンセル

QUEUED 状態のジョブはキャンセル可能です：

$ pxq cancel {job id}

実行中のジョブを停止するには：

$ pxq stop {job id}

よくあるトラブルと対処法

「GPU が利用できません」エラー

原因: RunPod Community Cloud は容量が限られています。

解決策:

1. 別の GPU タイプを試す
2. リージョンを変える
3. 時間を置いて再試行

「Volume がマウントできません」エラー

原因: Volume と Pod のリージョンが異なります。

解決策: 両方が同じリージョン（例：EU-RO-1）にあるか確認してください。

ダウンロードジョブが失敗する

原因: Kaggle API トークンが正しく設定されていません。

解決策:

1. RunPod Secrets の名前が KAGGLE_USERNAME と KAGGLE_API_TOKEN か確認
2. トークンが有効か再確認

コスト最適化のヒント

1. データダウンロードは CPU で: 割高な GPU を使う必要はありません
2. managed モードを常時使用: 停止し忘れ防止
3. Network Volume を活用: 再ダウンロードの時間と通信コストを節約
4. 空き時間を狙う: 深夜帯は Community Cloud が空いていることが多い

最後に

もしよければ、私のRunPodのリファラルリンクを登録していただけるととってもハッピーです。

pxq はまだ開発中のツールです。今後は以下のような機能を検討しています：

• LAN 内の別のマシンへのジョブ発行
• 他のクラウドプロバイダー対応
• Coding Agent 向け Skills 作成

Issue や PR も大歓迎です！使ってみて「イマイチだな」と思ったら感想を、「良かった！」と思ったらシェアをお願いします。

関連リンク

• pxq GitHub リポジトリ
• pxq PyPI
• RunPod 公式サイト
• Kaggle