はじめに
近年ではHPCクラスタ利用においても、VSCode の AI Agent、Claude Code、OpenAI Codex などのエージェント型開発ツールを利用する機会が増えていると思います。
これらのAIエージェントをHPCクラスタ環境で直接起動・実行することには、いくつかの課題や不便な点があります。
本ガイドでは、AIエージェントをローカルPC上で実行してコード開発などを行い、GPUジョブをさくらONEへ投入する方法について紹介します。
背景と課題
さくらONE のインタラクティブノードは複数ユーザーが共有する環境です。そのため、AI エージェントを直接実行すると次のような問題が顕在化します。また、さくらONEのアクセスサーバを経由してのログインが必要なため、二要素認証回数の削減のための設定も必要となります。
問題 | 影響 |
高負荷が集中 | 利用中ユーザーの処理が遅くなる |
大量のファイル検索 | 並列ファイルシステムのメタデータ参照が多数発生し、 ファイルアクセス処理に影響が発生する |
二要素認証の毎回入力 | 手動で 6 桁コードを入力しなければならず、スクリプト化が阻害される |
このような問題点を回避しつつ、ローカルマシンでAIエージェントを利用して快適にコードを書き、さくらONEのGPUリソースを活用したい、というニーズに対応する環境構成を説明します。
想定利用ケース
- ローカルで AI エージェントを動かす
- 開発したコードや必要データをさくらONEに転送する
- GPU ジョブを投入して実行
という利用が想定されます。
アプリケーション | 目的 |
VS Code (Remote SSH) | ローカルでコードを編集し、リモートの環境で実行 |
Claude Code / Codex | ローカルPC上でAIエージェントを実行し、生成したコードをリモート環境へ転送 |
任意のスクリプト | データ前処理やモデル学習の設定ファイル作成、GPUノードでのジョブ実行 |
HPC環境でAIエージェントを直接実行する問題点
- インタラクティブノードへの負荷
AIエージェントは大量のファイルを探索します。例えば、
- VSCode Agent
- Claude Code
- OpenAI Codex
などはリポジトリ全体や、設定によってはホームディレクトリ内のファイルを頻繁にスキャンします。
AIエージェントが不要なファイルや大容量データ、機密情報を参照しないよう、.rgignore や .ignore を設定しておくことを推奨します。特に学習データ、モデルファイル、チェックポイント、秘密鍵などは除外対象に含めると効率的です。記載例はページ最後の「付録」を参照してください。そのため共有インタラクティブノード上で実行すると、
- CPU使用率上昇
- メモリ消費増加
- コマンド応答の遅延
- 他利用者への影響
が発生し、開発効率にも影響を生じます。
- Lustreストレージへの負荷
AIエージェントが大量のファイルを参照・読み込みを行うと、特に以下のような処理が頻繁に発生します。
- grep / ripgrep(rg)
- git status
- ソースコードインデックス作成
- ベクトル検索用スキャン
これらがLustreストレージに対して大量に実行されると、
- Metadata Server(MDS)負荷増加
- メタデータアクセス性能低下
- ファイル操作遅延
に繋がり、学習ジョブや大規模並列ジョブと競合すると、演算性能にも影響する可能性があります。
- 機密情報漏洩のリスク
AIエージェントはコード補完だけではなく、プロジェクト全体の理解を目的として大量のファイルを参照します。例えば、
- ソースコード
- 設定ファイル
- ログファイル
- ドキュメントファイル
- Git履歴
- APIトークン
- クラウドサービス認証情報
- 共有ストレージの利用者データ
などを自動的に探索する場合があります。
AIエージェントの設定や利用方法によっては、プロンプト生成のためにファイル内容を外部AIサービスへ送信する可能性があります。そのため、
- どのファイルを参照するか
- どの情報を外部送信するか
- 利用するAIサービスのデータ保持ポリシー
を十分に確認する必要があります。
想定する開発・実行環境の構成
AIエージェントはローカルPCで動作させます。AIエージェントをローカルPCで実行することで、利用するAI基盤を柔軟に選択できます。例えば、
- ローカルLLM
- オンプレミスLLM
- 組織内で運用するクローズドなAIサービス
- データ利用ポリシーを確認済みの商用AIサービス
など、組織のセキュリティポリシーに応じた構成を選択できます。
ローカル環境でAIエージェント実行、コード編集、ファイル転送を行い、ジョブ実行は srun / sbatch でGPUジョブを実行します。
なお、srun でのジョブ実行の場合は、SSH接続が切断された場合や、srunを実行しているシェルが終了した場合は GPUノードジョブも終了しますので、長時間のジョブ実行は sbatch での投入をお勧めします。
アクセスノードへの認証済みSSHセッションを再利用する方法
この構成でさくらONEに接続する場合、認証済みSSHセッションを再利用して認証回数を削減する手順が必要となります。通常の場合、ssh や scp、rsync の度に二要素認証の6桁数字の入力が必要となってしまいます。SSH Connection Multiplexing を利用すると、一度認証したセッションを再利用できます。以下の設定の ControlMaster、ControlPath、ControlPersist を ~/.ssh/config に追記してください。
Host access # アクセスノードのニックネーム
HostName <FQDN> # アクセスノードのFQDN
Port <Port> # 接続ポート
User <Access ID> # 会員ID
IdentityFile <Identity File> # 秘密鍵のファイル名を指定
ControlMaster auto # ControlMaster方式を使う
ControlPath ~/.ssh/cm-%C # ソケットファイルの保存先
ControlPersist 5m # 全ての子接続が切断された後の保持時間
Host interactive #インタラクティブノードのニックネーム
HostName <Host Name> #インタラクティブノードのホスト名
user <User ID> #ユーザID
ProxyJump access #アクセスノードを踏み台サーバに利用する設定上記の設定で、インタラクティブノードに以下のコマンドで接続できることを確認してください。接続に成功すると、インタラクティブノードのホスト名が表示されます。
ssh interactive "hostname"ファイルの同期方法
SSHセッションを再利用することで、scp や rsync コマンドでのファイル転送時に6桁数字の入力が必要なく、スクリプトファイル内やAIエージェントによるファイル転送もスムーズに行われます。
ファイルを同期する場合の注意点
ローカル環境とクラスタ環境でソースコードを同期する場合、両環境でディレクトリ構成を可能な限り統一することを推奨します。例えば、ローカル環境では動作していたコードでも、
- データファイルの配置場所が異なる
- 設定ファイルの配置場所が異なる
- 相対パスの起点が異なる
といった理由で、クラスタ環境では正常に動作しない場合があります。
特にAI・機械学習系のプログラムでは、
data/
models/
configs/
outputs/のようなディレクトリ構成を前提としていることが多く、環境ごとに配置場所が異なると、検証時にエラーの原因となります。ローカル環境とクラスタ環境で、
- ディレクトリ構成
- ファイル配置
- 実行ディレクトリ
をできるだけ統一し、コード内で絶対パスをハードコードしないようにします。また、設定ファイルや環境変数を利用してデータパスを切り替えられる設計にしておくと、ローカル環境とクラスタ環境の両方で同じコードを利用しやすくなります。
さくらONEではグループディスクのような、 $HOME 以外のディレクトリパスを使用することがあるので、両環境でのディレクトリ構造に注意する必要があります。
データの生成時間と転送時間
学習データや評価データをどこで生成するかも重要な検討事項です。一般的には、
- ローカルPCで生成してインタラクティブノードへ転送する
- インタラクティブノード上（またはGPUノード上）で生成する
の2つの方法があります。
ローカル生成のメリットは、インタラクティブノードの応答状況、Lustreストレージの応答状況に影響されない安定性です。また、近年の開発用PCは性能が高く、データ生成処理や結果評価処理を高速に実行できる場合があります。また、
- AIエージェントとの連携が容易
- 開発中の動作確認がしやすい
といった利点もあります。
一方で、ローカル生成のデメリットは、転送時間が必要となることです。rsync コマンドで転送途中に中断されたファイルの転送し直しには対応（rsyncコマンドの -P オプション）できますが、
rsync -aP ~/datasets/dataset.tar interactive:~/datasets/数GBサイズのファイル転送や、ファイル数が数千〜数万となる場合には、想定よりも転送時間が長時間となることがあります。このようなことから、データ生成場所については以下を推奨します。
- ソースコード開発や小規模データ生成はローカル
- 数十GB〜数百GB規模のデータ生成はGPUノード
- データはGPUノードのローカル NVMe に書き出し、可能であれば tar shard で1つの WebDataset ファイルとした後、$HOME 領域に mv すると Lustre アクセスが抑えられる
- 生成時間と転送時間 を比較してデータ生成場所を判断
- ただし開発が進むにつれて、両者の時間バランスは変わる可能性がある
GPUジョブの実行
通常はインタラクティブノード上で、GPUジョブは srun / sbatch コマンドで投入しますが、ローカルPCからSSH コマンドを利用してジョブの投入も可能です。
短時間のテストや評価には srun コマンドを利用したインタラクティブ実行、長時間の実行には sbatch でのバッチジョブ投入を推奨します。
インタラクティブジョブ
ssh -t interactive "srun --partition=p001-b200 --gres=gpu:1 --pty bash"バッチジョブ投入
ssh interactive "sbatch train.sh"ジョブ状態の確認
投入したジョブはローカルPCからも確認できます。
ssh interactive "squeue -u \$USER"このように、ローカルPCで SSH コマンドを実行することで GPU リソースを利用することもでき、スクリプトファイルからの反復的なテスト実行もスムーズに行えます。
まとめ
本ガイドでは、AIエージェントをローカルPC上で実行してコード開発を行い、さくらONEではGPU計算ジョブのみを実行するための構成を紹介しました。
この構成により、インタラクティブノードや共有ストレージへの負荷を抑えながら、AIエージェントを活用した効率的な開発が可能になります。また、ローカルLLMやクローズドなAIサービスを利用しやすくなるため、情報管理の面でもメリットがあります。
本ガイドが、AIエージェントとHPCクラスタを組み合わせた効率的な開発・運用環境を構築する際の参考になれば幸いです。
付録
最近の AI Agent（Codex、Claude Code、OpenCode、Aider など）は .gitignore を参照するものも多いですが、ツールによっては .ignore や .rgignore を独自に参照するため、使用するAIエージェントに応じて使い分けてください。
.rgignore または .ignore の記載例
# Git
.git/
.gitignore
# Python
__pycache__/
*.pyc
*.pyo
*.pyd
.venv/
venv/
# Build
build/
dist/
*.egg-info/
# Node.js
node_modules/
# Logs
*.log
logs/
# Temporary files
tmp/
temp/
# IDE
.vscode/
.idea/
# macOS
.DS_Store
# Large datasets
data/
datasets/
# Model files
models/
checkpoints/
*.ckpt
*.pt
*.pth
*.safetensors
# Generated outputs
outputs/
results/
# Secrets
.env
.env.*
*.pem
*.key
*.crt
# Jupyter
.ipynb_checkpoints/