ray-llm

Ray LLM

オープンソースの Ray で LLM ワークロードを扱うためのライブラリリファレンススキルです。ray.serve.llm（OpenAI 互換、vLLM ベースのサービング）と ray.data.llm（バッチ推論）を対象に、5 つのカテゴリにわたる 13 のルールをまとめています。この領域は Ray の他のどの部分よりも変更が速く、独立したリポジトリが取り込まれてアーカイブされ、エントリーポイントが改名され、設定の構造も再編されました。そのため、モデルが学習した例の大半は、もはや動作しません。各ルールでは、修正対象となる誤ったデフォルトを示しています。有能なモデルがすでに正しく扱えることについてのルールはありません。

対象は LLM 固有のレイヤーです。一般的な Serve／Data／クラスターに関する判断（デプロイのライフサイクル、自動スケーリングのセマンティクス、KubeRay）は、姉妹スキルの ray が担当します。2 つのスキルは組み合わせて使えます。

ray 2.57.0（対応する vLLM を固定する ray[llm] エクストラ）を対象としています。API に関する記述は、展開した 2.57.0 の wheel とインストール済みパッケージのソースで検証しました。また、ルール内の設定例はすべて CPU のみの pydantic 検証で作成しており、トラップとなる例も説明どおりに失敗することを確認しています。エンジン／GPU の実行時の挙動はソースでのみ検証しており、モデルを実際にサービングしたわけではありません。

適用する場面

• Ray 上で OpenAI 互換の LLM サービングデプロイを立ち上げる、またはレビューする場合
• データセットに対するバッチ LLM 推論（要約、埋め込み、スコアリングなどの大規模処理）を記述する場合
• マルチ GPU モデルのサイズ設定や配置を行う場合（テンソル並列化／パイプライン並列化、アクセラレーターの選択）
• LLM デプロイをスケーリングする場合（レプリカの自動スケーリング、イングレスのサイズ設定、リクエストのルーティング）
• 共有ベースモデルを使った LoRA ファインチューニングモデル群をサービングする場合
• アーカイブ済みの ray-llm リポジトリ、独自実装の vLLM エンジン、または 2.5x より前の ray.data.llm 名を使用するコードを移行する場合

ルールのカテゴリ

#	カテゴリ	プレフィックス	対象
1	サービングの設定	serve-	独自実装のエンジンやアーカイブ済みリポジトリではなく、LLMConfig と build_openai_app を使用する方法、model_id と model_source の違い、ray[llm] と vLLM のバージョン固定、移動した LLMServer／OpenAiIngress のインポート
2	バッチ推論	batch-	旧名が削除された build_processor、ブール値フラグではなくステージ設定を使う方法、CPU がデフォルトとなる accelerator_type と自動スケーリングの concurrency、HTTP／Serve プロセッサーの代替手段
3	配置とアクセラレーター	place-	エンジン独自の TP×PP 配置グループ（およびストラテジーを上書きする場合）、検証済みの accelerator_type 名
4	自動スケーリングとルーティング	scale-	エンジンのサイズに合わせたレプリカ設定を行う deployment_config.autoscaling_config、イングレスのレプリカ数の設定、プレフィックスキャッシュのアフィニティに基づくルーティング
5	LoRA と API サーフェス	api-	アダプターごとのデプロイではなく、動的な LoRA 多重化を使う方法、OpenAI エンドポイントの全サーフェス、GPU を使わない設定検証

クイックリファレンス

1. サービングの設定

• serve-builtin-not-handrolled — LLMConfig と build_openai_app を使用します。ray-llm リポジトリはアーカイブ済みで、独自実装のエンジンよりも再実装する範囲を減らせます
• serve-model-id-vs-source — model_id はクライアント向けの名前で、model_source は重みの保存場所です
• serve-ray-llm-extra-pins-vllm — ray[llm] は vLLM のバージョンを正確に固定します。それぞれ独立して選んだバージョンを混在させないでください
• serve-deprecated-server-router — LLMServer／LLMRouter は移動しました。イングレスクラスは OpenAiIngress です（大文字・小文字もこのとおりです）

2. バッチ推論

• batch-build-processor-renamed — build_llm_processor は削除されました。build_processor と vLLMEngineProcessorConfig を使用します
• batch-stage-configs-not-flags — ブール値の apply_chat_template／tokenize／detokenize は、ステージ設定に置き換えられました
• batch-concurrency-and-alternatives — accelerator_type=None は CPU を意味します。並行数は (min, max) で指定します。HTTP／Serve プロセッサーも使用できます

3. 配置とアクセラレーター

• place-engine-builds-pg — エンジンが TP×PP 配置グループを構築します。戦略をオーバーライドし、手動で構築しないでください
• place-accelerator-type-validated — 標準のアクセラレーター定数です。"A10" は正規化され、ほとんどのタイプミスはエラーになります

4. オートスケーリングとルーティング

• scale-autoscaling-deployment-config — 標準の Serve オートスケーリングは deployment_config にネストされ、レプリカはエンジン全体です
• scale-prefix-cache-routing — PrefixCacheAffinityRouter は、同じプレフィックスのリクエストをウォーム状態の KV キャッシュにルーティングします

5. LoRA と API サーフェス

• api-lora-dynamic-multiplexing — アダプターごとにデプロイするのではなく、クラウドストレージからアダプターを動的に読み込みます
• api-endpoint-surface-cpu-validation — 埋め込み、文字起こし、スコア、トークナイズも提供されます。GPU なしで設定を検証できます

使用方法

該当する判断が必要になったときに、リファレンスファイルを参照してください。各ルールでは、修正対象となる誤った既定の方法を示したうえで、標準的な方法を紹介します（誤った方法が実際に陥りやすい落とし穴である場合に限り、誤りと正解を対比します）。

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

関連スキル

• ray — 従来の ML 向け Ray の関連ルールパックです（Train、Tune、Data、Serve、Core、KubeRay の本番環境トポロジー）。汎用的な Serve とクラスターに関する判断は、こちらに記載されています

リファレンスファイル

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