get-available-resources

利用可能なリソースの取得

現在のプロセスで利用可能なリソースについて、保守的な状況を把握します。 ホストのインベントリ、プロセスのアフィニティ、cgroup／コンテナーの制限、スケジューラーの割り当て、アクセラレーターのランタイム利用可能性は、それぞれ分けて扱います。

安全性の方針

以下のルールに従ってください。

• ユーザーから要求された場合、または特定のワークロードでリソース計画が必要な場合に検出を実行します。科学技術タスクのたびにフィンガープリントを保存しないでください。
• デフォルトでは stdout を使用します。ユーザーが明示的な汎用ローカルファイル名を選んだ場合に限り、保存します。
• 負荷テスト、ベンチマーク、大規模なメモリ確保、書き込みプローブ、デバイスのリセット、ドライバーのインストール、クロックや電力の変更は実行しないでください。
• 環境変数を一括出力しないでください。検出器が実装している、名前が明示された Slurm およびアクセラレーターの環境変数のみを読み取ります。
• ホスト名、絶対パス、cgroup のパス、ジョブ ID、デバイス UUID、PCI アドレス、生の可視性環境変数の値は報告しないでください。
• 観測できなかった情報は不明として扱います。不明を無制限に置き換えないでください。
• ホスト上で確認できる CPU、メモリプール、GPU が、スケジューラーの割り当てやコンテナー内で利用できると推定しないでください。

同梱の検出器は、固定された実行ファイルと引数の組み合わせのみを使用し、シェルを介さず、タイムアウトを短く設定し、stdout／stderr の出力を制限し、部分的な失敗について警告します。

クイックスタート

このスキルのディレクトリから実行します。

一時的な stdout スナップショット

python scripts/detect_resources.py

このコマンドは stdout に JSON のみを出力します。通常のシェル権限で問題ない場合に限り、出力をリダイレクトしてください。

明示的なプライベートファイル

python scripts/detect_resources.py --output resource-snapshot.json

明示的な出力先には、カレントディレクトリ内の .json ファイル名を1つだけ指定できます。プライベートな権限を適用し、シンボリックリンクとパストラバーサルを拒否します。また、--force が指定されていない場合は上書きしません。

オプションの psutil 機能拡張

標準ライブラリを使用する検出器は、インストールなしで動作します。物理コア、アフィニティ、利用可能なメモリ、スワップ、ディスクをより幅広くクロスプラットフォームで検出するには、次を実行します。

uv pip install "psutil==7.2.2"

インポートは遅延実行されます。psutil のインポートに失敗しても、致命的なエラーではなく警告になります。

管理ツールのプローブをスキップする

python scripts/detect_resources.py --skip-accelerators

アクセラレーターの検出に時間がかかる場合に使用します。検出器は、許可リストにある可視性環境変数の値を返さずに、その存在と状態を要約します。

必須の解釈

CPU

以下はそれぞれ異なる情報として読み取ってください。

• cpu.host.logical：システムから見えるスケジューリング単位。
• cpu.host.physical：物理トポロジー。不明の場合は null。論理 CPU 数から推定しないでください。
• cpu.process.affinity_logical：対応している場合の現在のアフィニティセットのサイズ。
• cpu.cgroup_v2.cpuset_logical：有効な cgroup cpuset のサイズ。
• cpu.cgroup_v2.quota_cores：有限の cpu.max 容量。小数になる場合があります。
• scheduler.allocation.cpu_per_process：スコープが明確な場合における、タスクごとの Slurm 割り当ての限定的な解釈。
• cpu.effective.capacity_cores：観測された正の制約の最小値。
• cpu.effective.worker_ceiling：CPU プロセスワーカー数の保守的な上限。

1.5 のクォータは CPU 時間の容量であり、物理コア 1.5 個を意味するものではありません。アフィニティと cpuset は CPU の配置を制約し、クォータは帯域幅を制約します。

メモリ

以下はそれぞれ別に扱ってください。

• ホストの総メモリ／利用可能メモリ。
• 現在の cgroup 使用量、ハード上限である memory.max、階層全体での残り容量。
• 圧力やスロットリングの境界であり、ハード上限ではない memory.high。
• スケジューラーによるメモリ割り当てと、そのスコープ。
• 保守的に見積もった実効ハード上限と利用可能量。

Apple シリコンでは、memory.model は unified_cpu_gpu です。統合 GPU のメモリを RAM に加算したり、独立した VRAM と説明したりしないでください。

アクセラレーター

各デバイスは、バックエンドの候補です。

• NVIDIA GPU → CUDA 候補。
• AMD GPU → ROCm 候補。
• Apple 統合 GPU → Metal 候補。

管理クエリで可視性を確認できても、以下は保証されません。

1. スケジューラー／コンテナーによる使用許可。
2. デバイスノードへのアクセス。
3. ドライバー／ランタイムの互換性。
4. フレームワークパッケージとの互換性。
5. オペレーター／データ型のサポート。

そのため、runtime_usable_devices は null のままとし、各デバイスの runtime_compatibility は not_tested とします。可視性や割り当ての数は上限であり、利用が保証される数ではありません。

ディスク

capacity_bytes、ファイルシステムの free_bytes、ユーザーが利用可能なブロック数、書き込みを伴わない権限チェックは、それぞれ異なる情報です。ファイルシステムやプロジェクトのクォータのほうが厳しい場合もあります。絶対作業パスは常に秘匿されます。

スケジューラーとコンテナー

Slurm の変数は割り当ての範囲を示しますが、適用される制限は、タスクのアフィニティや cgroups など、サイトの設定によって異なります。制限が適用されていることの証拠としては、アフィニティと cgroup の観測結果を優先してください。

コンテナーマーカーはコンテナーのコンテキストを識別し、cgroup の制御情報は制限を識別します。有限の cgroup 値が設定されていないコンテナーでも、ホストのリソース情報が見える場合があります。また、非ルートの cgroup が自動的にコンテナーとしてラベル付けされるわけではありません。

詳細なプラットフォームルールについては、references/resource_semantics.md を参照してください。

ワークロードを計画する

プランナーは検証済みのスナップショットを受け取り、処理は実行しません。

python scripts/plan_workload.py resource-snapshot.json \
  --workload cpu \
  --tasks 100 \
  --memory-per-worker-mib 2048

任意の制御オプション：

• --workers N：明示的な上限。
• --reserve-memory-mib N：ワーカーの予算から除外するメモリ。
• --workload cpu|mixed|io：上限付きのワーカー推定方法を選択します。
• --accelerator none|any|cuda|rocm|metal：利用可能性を断定せず、候補となるバックエンドの判定を要求します。
• --output plan.json：ローカルの非公開出力先を明示します。既定では標準出力に出力します。

CPU または混合ワークロードでは、suggested_workers と threads_per_worker を併用してください。プロセスワーカー数に BLAS/OpenMP のネイティブスレッド数を掛けると、割り当てられたリソースを超過する場合があります。

I/O プランでは上限付きのオーバーサブスクリプション（最大 32）が許可されますが、これはあくまでヒューリスティックとして示されます。実際の代表的なワークロードのみをベンチマークし、スケジューラーやコンテナーの制限内に収めてください。

スナップショットを検証または差分比較する

検証：

python scripts/snapshot_tools.py validate resource-snapshot.json

observed_at を無視してリソース状態を差分比較します：

python scripts/snapshot_tools.py diff before.json after.json

タイムスタンプを含めるには --include-volatile を使用してください。入力は、1 MiB 以下の通常の非シンボリックリンク JSON ファイルでなければなりません。差分の出力には上限があります。

スキーマと null／ゼロの意味については、references/snapshot_schema.md に記載されています。

オプションのアクセラレーター診断プラン

診断を実行せずにプランを生成します：

python scripts/accelerator_diagnostics.py resource-snapshot.json \
  --backend auto

結果には、固定された読み取り専用の管理クエリ引数リストと、可視性、権限、ランタイム互換性を個別に確認するゲートが含まれます。フレームワーク公式の利用可能性チェックは、ワークロードを実行する環境とまったく同じ環境でのみ実行してください。ドライバーを自動的にインストールしたり変更したりしないでください。

部分的な失敗と来歴

1 つのプローブに失敗しても、正常に取得できた観測結果を失ってはなりません。次を確認してください：

• completeness；
• 安定したコードが付いたソート済みの warnings；
• ソースとステータスの記録が含まれるソート済みの provenance；および
• null のフィールド。

サブプロセスの標準エラー出力と未加工の例外テキストは、識別子やパスを含む可能性があるため、スナップショットにはコピーされません。

プラットフォームに関する注意事項

• Linux： 上限付きの /proc および cgroup v2 ファイルのみを読み取ります。祖先の CPU およびメモリ制限も考慮されます。
• macOS： 固定の sysctl キーと、上限付きの system_profiler SPDisplaysDataType -json クエリを使用します。Apple シリコンではメモリが統合されています。
• Windows： オプションの psutil により、物理コア、アフィニティ、利用可能メモリ、スワップの観測精度が向上します。プロセッサグループの範囲によって、ホストとプロセスのカウントが異なる場合があります。
• Slurm： 許可リストに含まれる割り当て変数を読み取ります。ジョブ、ノード、送信元ホスト、GPU ID、パスの値は出力しません。
• NVIDIA/AMD： 管理 CLI はオプションです。存在しないのは通常の状態です。タイムアウト、出力の切り詰め、解析失敗、ランタイムの不確実性は、明示的に示されます。

同梱ファイル

• scripts/detect_resources.py — 機密情報を除去したスナップショット収集ツール。
• scripts/plan_workload.py — 決定論的なワーカー／メモリプランナー。
• scripts/snapshot_tools.py — スキーマバリデーターおよび制限付き構造差分ツール。
• scripts/accelerator_diagnostics.py — 実行を伴わない読み取り専用の診断 プラン。
• リポジトリのルートにある tests/get-available-resources/ — ネットワーク接続なしで実行できる Linux、macOS、Windows、cgroup、Slurm、アクセラレーターのケース。
• references/resource_semantics.md — 解釈およびプラットフォームの詳細。
• references/snapshot_schema.md — スキーマ 1.1 の仕様。
• references/sources.md — 日付付きの公式ソース一覧。

公式ドキュメントは 2026-07-23 に更新されています。セマンティクスや依存関係のピン留めを変更する前に、 references/sources.md を参照してください。

エージェントの作業手順

1. 環境を確認します。 Python 環境とライブラリのバージョン（python -c "import pkg; print(pkg.__version__)"）を確認し、データの形状、型、欠損値を調べます。
2. 入力を明確にします。 データまたはユーザーから形式、識別子、パラメーターを確認します。結果に影響する値を推測せず、質問してください。
3. まず小規模なバージョンを実行します。 まずサンプルまたは単一のフォールドで実行し、実行時間とメモリを確認します。
4. 上記の手順とリファレンスを使用して、タスク全体を実行します。
5. 結果を検証します。 ホールドアウトデータ、固定した乱数シード、適切な指標を使用し、リークがないか確認して、不確実性（信頼区間、シード間の標準偏差）を報告します。
6. 報告します。 実行内容（バージョン、コマンド、パラメーター）、確認した内容、未確定な点を示します。

このような場合	次のように対応します
メモリ不足、または実行が非常に遅い	サブサンプリング、チャンク処理や遅延計算の使用、またはモデルサイズの縮小を行い、変更内容をユーザーに伝えます。
これらの手順に記載された関数、フラグ、エンドポイントがインストール済みバージョンに存在しない	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認して適応し、その旨をユーザーに伝えます。API を決して捏造しないでください。
必須の入力、識別子、パラメーターが曖昧	ユーザーに質問するか、実行前に仮定を明示します。

完全性に関するルール

• 結果、パラメーター、識別子、引用、統計値を決して捏造しないでください。実行または検証できないことがあれば、明確に伝えてください。
• このセッションで計算していない指標を報告しないでください。すべての数値について、その算出に使用したコードパスを示してください。
• ここに記載されたバージョン固有の詳細は古くなっている可能性があるものとして扱い、インストール済みバージョンの公式ドキュメントで確認してください。
• 費用が発生する、共有 GPU やクラウドのクォータを消費する、個人データや患者データに触れる、または取り消せない操作を行う前に、ユーザーに確認してください。