ray

Ray

本番環境で使用できるオープンソースの Ray を対象とした、ライブラリ参照用スキルです。トレーニングからサービングまでを網羅する、6 つのカテゴリにわたる 26 のルールを収録しています。Ray の API は 2.x 系を通じて大きく変化しました（Train V2 がデフォルトになり、Serve ではパラメーターやハンドルクラスが完全に削除され、Ray Data では非推奨化が撤回されました）。そのため、旧バージョンの情報に精通したモデルが生成したコードは、警告やエラーを出したり、気付かないうちに別の意味になったりします。各ルールでは、修正対象となる誤ったデフォルトを明示しています。十分な能力を持つモデルがすでに正しく扱えることについては、ルールを設けていません。

対象範囲は、セルフホストの KubeRay クラスター上で動作する従来型の機械学習向け Ray です。LLM サービングとバッチ推論（ray.serve.llm、ray.data.llm）は、兄弟スキルである ray-llm の対象です。

ray 2.57.0（Python ≥ 3.10）に固定しています。API に関する記述は、展開した 2.57.0 の wheel に照らして検証済みです。従来型の機械学習の例は、稼働中のローカル Ray 2.57.0 ランタイムで実行して検証しました。

適用する場面

• 分散トレーニングコードの作成やレビュー — TorchTrainer、ScalingConfig、チェックポイント、フォールトトレランス
• Ray Data によるデータパイプラインの構築 — 読み込み、map_batches、GPU 推論プール、トレーニング用データ取り込み
• Ray Tune によるハイパーパラメーターの探索 — 特に Ray Train と組み合わせる場合
• Ray Serve デプロイメントの作成やレビュー — スケーリング、ハンドル、構成、本番環境向け設定
• Ray Core のプリミティブの直接使用 — タスク、アクター、オブジェクトストア、再試行
• 本番環境向け Ray インフラストラクチャの構築やレビュー — KubeRay CRD、ジョブの送信、フォールトトレランス、可観測性

ルールカテゴリ

#	カテゴリ	プレフィックス	対象
1	Ray Train	train-	デフォルトの Train V2（非推奨の設定フィールド）、ray.air session よりも ray.train.report を使う方法、設定のインポートとエラスティックスケーリング、prepare_model／prepare_data_loader ラッパー
2	Ray Serve	serve-	max_ongoing_requests（旧名称は削除済み）、現在の自動スケーリング用フィールド、DeploymentResponse ハンドル、serve.run／build／deploy のライフサイクル、レプリカ配置オプション
3	Ray Data	data-	compute= の戦略（concurrency の変更）、override_num_blocks、パイプラインに代わるストリーミング実行、PyTorch のデータ取り込み、ゼロコピーの読み取り専用バッチ
4	Ray Core	core-	従来のアンチパターンに残る見落としやすい影響、再試行／再起動のデフォルト、オブジェクトストアと /dev/shm のサイズ設定、ray.util.state
5	Ray Tune	tune-	正式な方法としての Tuner（tune.run の実際の位置付けも含む）、ray.tune.RunConfig のインポート、ドライバー関数による Train との連携
6	本番環境とクラスター	prod-	KubeRay CRD の選択、Jobs API による送信、Redis を使った GCS のフォールトトレランス、ビルド済みイメージと runtime_env の比較、Prometheus／Grafana の接続

クイックリファレンス

1. Ray Train

• train-v2-default-changed-semantics — 2.51 以降は V2 がデフォルトです。sync_config／verbose／fail_fast は削除されています
• train-report-not-air-session — ray.train.report(metrics, checkpoint=) を使用します。ray.air はレガシー向けの互換レイヤーです
• train-configs-from-ray-train-elastic — V2 設定のインポート、エラスティックな num_workers=(min, max)、大文字と小文字を区別するリソースキー
• train-prepare-model-and-loader — prepare_model／prepare_data_loader を使わない場合、N 個のワーカーが同期されないコピーをそれぞれトレーニングします

2. Ray Serve

• serve-max-ongoing-requests — max_concurrent_queries は削除されています。max_ongoing_requests（デフォルトは 5）と max_queued_requests を使用します
• serve-autoscaling-current-fields — target_ongoing_requests、*_factor フィールド、num_replicas="auto"、ゼロへのスケール
• serve-deployment-response-handles — DeploymentResponse.result()／await を使用し、ray.get は決して使用しません。.bind() による合成
• serve-run-build-deploy — serve.run と serve build／deploy を使用します。Deployment.deploy() の時代は終わりました
• serve-placement-controls — max_replicas_per_node、レプリカごとの配置グループ、ギャングスケジューリング、リクエストルーター

3. Ray Data

• data-compute-not-concurrency — concurrency= は（再び）非推奨です。compute=ActorPoolStrategy/TaskPoolStrategy を使用します
• data-override-num-blocks — 読み取り API では parallelism は非推奨です
• data-streaming-replaced-pipelines — DatasetPipeline／window／repeat は削除されました。実行は消費時にストリームとして行われます
• data-iter-torch-batches-not-to-torch — to_torch は廃止されました。iter_torch_batches と Train のデータセットシャードを使用します
• data-zero-copy-read-only-batches — バッチはデフォルトで読み取り専用ビューです。batch_size を明示的に設定してください

4. Ray Core

• core-classic-traps-residue — 古典的なアンチパターンに残る、見落としやすい問題：ray.wait による排出、クロージャー／グローバル変数のコピー、タスク実行時間の数ミリ秒単位の下限
• core-retries-system-failures-only — retry_exceptions はオプトインです。アクターはデフォルトでは再起動しません
• core-object-store-sizing — デフォルトは 30％、コンテナでは /dev/shm、ローカルディスクへのスピル
• core-state-api-not-ray-state — ray.state は廃止されました。イントロスペクション API には ray.util.state を使用します

5. Ray Tune

• tune-tuner-canonical — API は Tuner です。tune.run はレガシーですが、削除されてはいません
• tune-runconfig-from-ray-tune — Tuner が受け取るのは ray.tune.RunConfig であり、ray.train や ray.air のものではありません
• tune-driver-function-not-trainer — Trainer を Tuner 内で使う方法は非推奨です。ドライバー関数と with_resources を使用します

6. 本番環境とクラスター

• prod-kuberay-crd-choice — RayCluster と RayJob（shutdownAfterJobFinishes のデフォルトは false）と RayService
• prod-jobs-api-not-head-driver — 長時間稼働するクラスターでは ray job submit を使用します。Ray Client は開発用ツールです
• prod-gcs-ft-redis — RayService でヘッドノードのクラッシュ後も稼働を維持するには、外部 Redis GCS が必要です
• prod-baked-images-not-runtime-env — 本番環境の依存関係はイメージに含めます。runtime_env（現在は uv、image_uri も含む）は反復開発用です
• prod-metrics-wiring — ダッシュボードで時系列を表示するには、外部の Prometheus／Grafana が必要です

使い方

該当する判断が必要になったら、リファレンスファイルを読んでください。各ルールでは、修正対象となる誤ったデフォルトを示したうえで、正規の方法を説明します（誤った方法と正しい方法の対比は、誤った方法が実際に問題となる場合にのみ示します）。

• セクションの定義 — カテゴリー構成
• ルールのテンプレート — ルールの追加用
• AGENTS.md — すべてのルールを含む目次を自動生成します

関連するスキル

• ray-llm — Ray 上での LLM サービング（ray.serve.llm）とバッチ推論（ray.data.llm）用の姉妹ルールパックです
• mlflow-3 — 実験トラッキングとモデルレジストリです。MLOps サイクルのトラッキング側で Ray Train と組み合わせて使用します

参照ファイル

ファイル	説明
references/_sections.md	カテゴリーの定義と順序
assets/templates/_template.md	新しいルール用のテンプレート
metadata.json	バージョンとソースの参照