モデルデプロイ管理

GPUStack の Models - Deployments ページで、モデルのデプロイを管理できます。GPUStack のモデルデプロイには、1 つ以上のモデルインスタンスのレプリカが含まれます。デプロイ時には、GPUStack がモデルのメタデータからモデルインスタンスのリソース要件を自動計算し、それに基づいて利用可能なワーカーにスケジュールします。

モデルのデプロイ

現在、Hugging Face、ModelScope、ローカルパスのモデルをサポートしています。

Hugging Face モデルのデプロイ

Deploy Model ボタンをクリックし、ドロップダウンから Hugging Face を選択します。
左上の検索バーを使って、Hugging Face からモデル名で検索します。例: Qwen/Qwen3-0.6B。
必要に応じて Name、Cluster、Backend、Backend Version、Replicas を調整します。
性能を設定する場合は Performance セクションを展開します。詳細は性能に関する設定を参照してください。
スケジューリングを設定する場合は Scheduling セクションを展開します。詳細はスケジューリング設定を参照してください。
詳細設定を行う場合は Advanced セクションを展開します。詳細は詳細設定を参照してください。
Save ボタンをクリックします。

ModelScope モデルのデプロイ

Deploy Model ボタンをクリックし、ドロップダウンから ModelScope を選択します。
左上の検索バーを使って、ModelScope からモデル名で検索します。例: Qwen/Qwen3-0.6B。
必要に応じて Name、Cluster、Backend、Backend Version、Replicas を調整します。
性能を設定する場合は Performance セクションを展開します。詳細は性能に関する設定を参照してください。
スケジューリングを設定する場合は Scheduling セクションを展開します。詳細はスケジューリング設定を参照してください。
詳細設定を行う場合は Advanced セクションを展開します。詳細は詳細設定を参照してください。
Save ボタンをクリックします。

ローカルパスのモデルのデプロイ

ローカルパスからモデルをデプロイできます。モデルパスには、ワーカー上のディレクトリー（ダウンロード済みの Hugging Face モデルディレクトリーなど）またはファイル（GGUF モデルファイルなど）を指定できます。エアギャップ環境での運用に役立ちます。

注記

GPUStack はモデルファイルを使ってリソース要件を推定します。サーバーからモデルパスにアクセスできない場合、ワーカーからのアクセスを試みます。
GPUStack はモデルファイルを自動同期しません。対象のワーカーからモデルパスにアクセスできるようにする必要があります（NFS、rsync などを使用）。ワーカーセレクターの設定で、特定のワーカーにモデルをデプロイすることもできます。

ローカルパスのモデルをデプロイする手順は次のとおりです。

Deploy Model ボタンをクリックし、ドロップダウンから Local Path を選択します。
デプロイの Name を入力します。
Model Path を入力します。
必要に応じて Cluster、Backend、Backend Version、Replicas を調整します。
性能を設定する場合は Performance セクションを展開します。詳細は性能に関する設定を参照してください。
スケジューリングを設定する場合は Scheduling セクションを展開します。詳細はスケジューリング設定を参照してください。
詳細設定を行う場合は Advanced セクションを展開します。詳細は詳細設定を参照してください。
Save ボタンをクリックします。

バックエンド

現在、GPUStack は組み込みバックエンドとして vLLM、SGLang、MindIE、VoxBox をサポートしています。

詳細は推論バックエンドを参照してください。

バックエンドのバージョン

バックエンドのバージョンを選択します。選択可能なバージョンは、選択したバックエンドによって異なります。互換性を確保したり、特定のバージョンで導入された機能を利用したりする際に役立ちます。

組み込みの vLLM または SGLang バックエンドで runner カタログにないコンテナーイメージを使うには、デプロイ設定で image_name を設定します。カスタムイメージとバックエンドのバージョンは同時に選択できないため、backend_version は未設定のままにしてください。vLLM のデプロイでカスタムイメージを使う場合、分散実行のデフォルトは mp です。イメージに Ray が含まれていて、それを使用する場合は、backend_parameters で --distributed-executor-backend=ray を設定します。

組み込みの vLLM または SGLang バックエンドでは、run_command に実行ファイルを含めず、初期起動引数を指定します。GPUStack は、サービスのホストやポートなど、自身が管理する引数を引き続き追加します。カスタムバックエンドの場合、run_command には実行ファイルを含む完全なコマンドを指定します。例はカスタム推論バックエンドの使用を参照してください。

モデルデプロイの編集

デプロイ一覧ページで、編集するモデルデプロイを探します。
Operations 列の Edit ボタンをクリックします。
必要に応じて属性を更新します。たとえば、Replicas を変更してスケールアップまたはスケールダウンします。
Save ボタンをクリックします。

注記

モデルデプロイを編集しても、既存のモデルインスタンスには設定が適用されません。既存のモデルインスタンスを削除する必要があります。GPUStack が、更新されたモデル設定に基づいて新しいインスタンスを再作成します。

モデルデプロイの停止

モデルデプロイを停止すると、目標レプリカ数をゼロに設定し、インスタンスを削除してリソースを解放します。スケジュールに基づくスケーリングが有効なデプロイでは、scaling_schedule.paused も設定してスケジュールの実行を一時停止します。有効化の設定、ベースライン、ルールは保持されます。スケジュールを有効のままにする編集やロールバックでは、一時停止状態も保持されます。通常のデプロイは、一時停止状態を持たないレプリカスケーリングを使用します。

デプロイ一覧ページで、停止するモデルデプロイを探します。
Operations 列の省略記号ボタンをクリックし、Stop を選択します。
操作を確認します。

モデルデプロイの開始

スケジュールに基づくスケーリングが有効な場合、開始すると scaling_schedule.paused が解除され、GPUStack が現在時刻でスケジュールを評価します。過去に実行できなかった時間帯を再実行することはありません。ベースラインがゼロの場合、有効な時間帯の外では目標レプリカ数がゼロのままになることがあります。このとき、デプロイは一時停止ではなく、スケジュールの時刻を待っている状態です。これらのデプロイでは、操作のラベルは Resume Schedule になります。

有効なスケジュールがない場合、開始すると目標レプリカ数を 1 に設定します。スケジュールに基づくスケーリングの無効化は、別の設定操作です。一覧でレプリカ数を直接編集すると、確認後に手動スケーリングに切り替わります。

デプロイ一覧ページで、開始するモデルデプロイを探します。
Operations 列の省略記号ボタンをクリックし、Start を選択します。

モデルデプロイの削除

デプロイ一覧ページで、削除するモデルデプロイを探します。
Operations 列の省略記号ボタンをクリックし、Delete を選択します。
削除を確認します。

デプロイのエクスポートとインポート

デプロイの完全な設定を YAML ファイルにエクスポートし、ファイルをインポートして再作成できます。主な用途は、アップグレードや移行の前のバックアップ、GPUStack 再インストール後の復元、デプロイ設定のバージョン管理、チームとのデプロイテンプレートの共有、別のクラスターでの同じデプロイの再現などです。

デプロイのエクスポート

デプロイ一覧ページで、エクスポートするモデルデプロイを探します。
Operations 列の省略記号ボタンをクリックし、Export YAML を選択します。
複数のデプロイをまとめてエクスポートするには、先に対象を選択し、一覧の上にある一括操作のドロップダウンから Export YAML を選択します。

ブラウザーが YAML ファイルをダウンロードします。ファイル名は、単一のデプロイの場合は <deployment-name>.yaml、複数の場合は gpustack-deployments-<timestamp>.yaml です。

ファイルには YAML ドキュメントごとに 1 つのデプロイが含まれ、--- で区切られます。各ドキュメントは、デプロイ作成時のリクエストボディーに所属クラスターを加え、サーバーが生成するフィールドを除いたものです。

# Exported from GPUStack v2.3.0 at 2026-09-07T10:00:00Z
name: qwen3-8b
cluster_name: production
source: huggingface
huggingface_repo_id: Qwen/Qwen3-8B
replicas: 2
placement_strategy: binpack
worker_selector:
  zone: a
gpu_selector:
  gpu_ids:
  - worker-1:cuda:0
  gpus_per_replica: 1
backend: vLLM
backend_version: 0.11.0
backend_parameters:
- --max-model-len=32768
env:
  HF_TOKEN: hf_xxx
enable_model_route: true
---
name: bge-m3
cluster_name: staging
source: huggingface
huggingface_repo_id: BAAI/bge-m3
replicas: 1

各デプロイは行頭から始まるため、インデントを変更せずにファイルから 1 つをコピーしたり、手作業で作成したりできます。以前の GPUStack リリースのエクスポート形式である、単一の YAML リスト形式のファイルもインポートできます。

フィールドリファレンス

ファイル内の各フィールドは、デプロイフォームで設定する項目に対応します。以下に、エクスポートファイルの出力順に、両者の名称を示します。各フィールドの意味は、右列からリンクされた設定の説明に記載されています。

フィールド	デプロイフォームの項目
`name`	`Name`
`cluster_name`	`Cluster`。クラスター ID ではなく名前で記録します
`source`	`Source`
`huggingface_repo_id`, `huggingface_filename`	Hugging Face モデルの `Repo ID` と `File Name`
`model_scope_model_id`, `model_scope_file_path`	ModelScope モデルの `Repo ID` と `File Name`
`local_path`	ローカルパスのモデルの `Model Path`
`replicas`	`Replicas`
`categories`	`Model Category`
`placement_strategy`	`Scheduling` → `Auto`、配置戦略
`cpu_offloading`	`Allow CPU Offloading`
`distributed_inference_across_workers`	`Allow Distributed Inference Across Workers`
`worker_selector`	`Scheduling` → `Manual` → `Selector`
`gpu_selector`	`Scheduling` → `Specify GPU`
`gpu_type_selector`	`Scheduling` → `Specify GPU Type`
`backend`	`Backend`
`backend_version`	`Backend Version`
`backend_parameters`	`Backend Parameters`
`image_name`	組み込みまたはカスタムバックエンドのコンテナーイメージ。組み込みバックエンドでは `backend_version` と排他的です
`run_command`	組み込みの vLLM/SGLang では初期引数、カスタムバックエンドでは完全なコマンド
`native_anthropic_api`	`Native Anthropic API`
`env`	`Environment Variables`
`restart_on_error`	`Auto-Restart On Error`
`extended_kv_cache`	`Extended KV Cache`
`speculative_config`	`Performance` → 投機的デコード
`scaling_schedule`	`Scheduled Scaling`
`generic_proxy`	`Enable Generic Proxy`
`lora_list`	`LoRA Adapters`
`enable_model_route`	`Enable Model Route`。フォームではデプロイ作成時にのみ設定できます

最後のグループのフィールド、gpu_selector、gpu_type_selector、extended_kv_cache、speculative_config、scaling_schedule、lora_list は、単一の値ではなくブロックを保持します。その構造はここには記載していません。デプロイで設定してエクスポートし、ファイルからブロックをコピーしてください。書き写すより速く、構造を確実に把握できます。

description と distributable はファイルに保持されますが、フォームには対応する入力項目がありません。

ファイルに含まれないものは、ID、タイムスタンプ、準備完了レプリカ数や一時停止状態などの実行時状態、スケジューラーから導出されるメタデータ、所属組織、アクセスポリシー、LoRA の実行時パスです。スケジュールに基づくスケーリングが有効な場合、エクスポートされるレプリカ数は現在の時間帯の目標値ではなく、設定したベースラインです。実行時状態は、インポート時にサーバーが再生成します。有効かつ一時停止中のスケジュールを持つ既存デプロイを上書きする場合、その一時停止状態は保持されます。

複数のクラスターからデプロイをまとめて選択しても問題ありません。各エントリーが自身の cluster_name を記録するため、1 つのファイルにすべてを記述し、そのまま一括でインポートできます。クラスターは ID ではなく名前で記録されるため、再インストール後のようにクラスターの採番が変わった GPUStack でも正しく復元できます。

ただし、1 つのファイルで扱えるのは、クラスター数にかかわらず 1 つの組織です。デプロイ名は組織内で一意であり、組織をまたいで一意ではありません。そのため、All を表示するプラットフォーム管理者だけが可能な、組織をまたぐ選択は拒否されます。組織ごとにエクスポートしてください。

デプロイが実行された場所はエクスポートされません。自動スケジューリングのデプロイでは、ファイルに gpu_selector 自体が含まれず、インポート時に対象クラスターで利用可能なリソースに対して再スケジュールされます。自分で選んだ GPU はスケジューリングの結果ではなくユーザーの意図なので、指定したとおりにエクスポートされます。別のクラスターへのインポートに関する以下の注意を参照してください。

警告

環境変数は入力した値のままエクスポートされ、HF_TOKEN などの認証情報を含む場合があります。エクスポートしたファイルを公開リポジトリーにコミットしないでください。共有する前に機密値を削除または置換してください。

デプロイのインポート

Deploy Model ボタンをクリックし、ドロップダウンから YAML File を選択します。
.yaml ファイルを選択します。最初にクラスターから読み込むことはなく、ファイルが出発点となります。ファイル内のデプロイを検索し、差分の読み取り専用側に表示します。2 つ目のファイルを選ぶと、編集内容も含めて 1 つ目を完全に置き換えます。
デプロイ先を決めます。ドロワーの初期設定である Follow the file では、各エントリーは自身の cluster_name が示すクラスターに配置されます。これにより、複数クラスターにまたがるバックアップを一度に復元できます。クラスター名のないエントリーは、そのデプロイがすでに所属するクラスターにフォールバックします。代わりに特定のクラスターを選択すると、ファイルの指定にかかわらずすべてのエントリーをそこに配置します。
差分を確認します。左側が GPUStack に保存されているデプロイ、右側がインポート予定の内容です。横の一覧はドキュメント全体から始まり、各デプロイが続きます。各項目に Create、Update、Unchanged のマークが付き、Update には変更するフィールド数が表示されます。各項目を選択するとそのデプロイだけを編集でき、先頭行を選ぶとすべてをまとめて編集できます。
一覧に赤色で示された問題を修正します。理由は差分の上に表示され、編集時には入力を止めてしばらくした後、またはエディターからフォーカスを外した直後に、ドキュメントが再検証されます。
Import をクリックします。既存のデプロイを置き換える計画がある場合は、一度確認します。ダイアログには置き換え対象のすべてのデプロイ名が表示されます。すべての書き込みは一括で実行され、1 つでも失敗すると、ファイルの内容は一切書き込まれません。

ドキュメントから書き込むものがない間は、Import は無効のままです。編集していないエクスポートファイルを再インポートすると、すべてのエントリーが Unchanged になり、何も書き込みません。そこから変更した内容だけがインポートの対象です。

ファイル自体はアップロードされません。インポートリクエストで送信されるのは、エディター内のテキストだけです。

インポート時には、次のルールが適用されます。

上書きには明示的な操作が必要で、対象も限定されます。 既存のデプロイと名前が一致するエントリーを置き換えるのは、インポート時に置き換えを確認し、かつそのデプロイが停止済みの場合だけです。停止済みとは、レプリカ数がゼロで、実行中のインスタンスも残っていない状態です。スケールダウンはすぐに戻りますが、インスタンスの終了には少し時間がかかるため、直後のインポートでは待機を求められる場合があります。デプロイ名は組織全体で一意なので、エントリーの名前は、所属クラスターにかかわらず必ず 1 つのデプロイを特定します。
クラスターは、エントリーの通常のフィールドです。 エディターで cluster_name を変更するか、インポート先として別のクラスターを選ぶと、上書きによってデプロイがそこに移動します。上書きできるのは停止済みのデプロイだけなので、移行するインスタンスはありません。次に作成するインスタンスは、その時点で指定されたクラスターに配置されます。gpu_selector と worker_selector を新しいクラスターに合わせて更新するか、削除してください。
上書きはデプロイ全体の置き換えであり、マージではありません。 ファイルが望ましい状態を表すため、ファイルから削除したフィールドはデフォルト値に戻ります。デプロイを自動スケジューリングに戻すには、gpu_selector ブロックを削除します。計画上 Unchanged のエントリーには、何も書き込みません。
モデルルートは enable_model_route に従います。 上書き時に false に設定すると、そのデプロイが作成したルートと LoRA の子ルートを削除します。ファイルから LoRA アダプターを削除すると、そのアダプターのルートだけを削除し、ほかは保持します。いずれの場合も、削除対象のルートが別のデプロイにも使われていると、エントリーは拒否されます。先にほかのターゲットを切り離してください。
レプリカ数はファイルから取得します。 対象環境の規模がエクスポート元と異なる場合は、エディターで replicas を編集します。GPU を手動選択している場合は、デプロイ編集時と同じように、gpu_selector に新しいレプリカ数を満たす GPU が含まれているか確認してください。スケジュールに基づくスケーリングが有効な場合、レプリカ数はスケジュールが管理するため、この値は scaling_schedule.baseline_replicas に設定されます。
GPUStack が認識しないフィールドは、黙って破棄されるのではなく拒否されます。通常、より新しい GPUStack リリースからのファイルであることを意味します。エラーで示されたフィールドを削除して再試行してください。
この GPUStack に存在しないクラスターは、推測せずに問題として表示します。 クラスター名の異なる別の環境からファイルをインポートすると、不明な cluster_name を持つ各エントリーが指摘されます。ここに存在するクラスター名に変更するか、全エントリーの配置先として特定のクラスターを選択してください。まだ存在しないデプロイでクラスター名も指定されていない場合は、配置先がないため同じように指摘されます。
配置先の組織は、ファイルの指定から決まります。 All を表示するプラットフォーム管理者は組織を選択していないため、Follow the file はファイルが指定するクラスターから組織を取得します。2 つの組織のクラスターを指定したファイルや、この GPUStack にあるクラスターを 1 つも指定していないファイルは、任意の組織にフォールバックせずに拒否されます。インポート先として特定のクラスターを選択するか、先に組織を切り替えてください。
エクスポート元と異なるクラスターにエントリーを配置する場合、gpu_selector 配下の gpu_ids と worker_selector は、引き続き元のクラスターの GPU とワーカーを参照しています。新しいクラスターの値に変更するか、削除してスケジューラーに配置を任せてください。そうしないと GPU が見つからず、インポートが失敗します。

デプロイのリビジョン履歴

GPUStack は、モデルデプロイを作成したとき、またはデプロイ設定を変更したときに、設定のリビジョンを記録します。YAML からの更新のインポートも含まれます。同じ設定の保存、スケジュールに基づくスケーリングの一時停止や再開、インスタンスの再起動、スケジュールによるスケーリングなどの自動変更では、リビジョンを作成しません。既存のデプロイでは、初めて履歴を開いたとき、または初めて設定を更新したときに、初期スナップショットが作成されます。それ以前の設定は復元できません。

モデルデプロイ一覧で対象のデプロイを探します。
Operations メニューを開き、Revision history を選択します。
リビジョンを選択し、読み取り専用の YAML 差分で直前のリビジョンと比較します。たとえば、v2 を選択すると、左に v1、右に v2 を表示します。最新のリビジョンも確認できます。初期リビジョン、または直前のリビジョンが削除や自動整理で失われたものは、設定全体を表示します。
過去のリビジョンの行にある Roll back to this revision をクリックします。同じドロワーが、現在のデプロイ設定とそのリビジョンを比較する Roll back <name> to vN というプレビューに切り替わります。ロールバックの確認中は、リビジョン一覧が非表示になります。Back to history をクリックすると、それまでの選択とページに戻ります。設定を適用するには、プレビューで Roll back を直接クリックします。追加の確認ダイアログは表示されません。最新のリビジョンには、ロールバック操作はありません。設定が一致する場合もロールバックは無効です。サーバーは通常の編集と同じルールで設定を検証します。設定が変わるロールバックが成功すると、新しいリビジョンが作成されます。

ロールバックは、バックエンド設定、環境変数、配置、レプリカ数、スケジュールに基づくスケーリング、LoRA アダプターなどのデプロイ設定を復元します。デプロイの名前、説明、組織、クラスター、アクセスポリシー、リビジョンの保持設定は保持されます。独立したモデルルートの設定は復元されません。導出される LoRA ルートは、復元されたアダプターに従います。

保存済みスナップショットにフィールドがない場合、ロールバックはそのフィールドの現在値を保持します。ロールバックのプレビューにも保持される値を含めるため、送信される設定と一致します。保存済みスナップショットに明示的な null がある場合は、そのフィールドを引き続きクリアします。互換性のない設定スキーマの変更には、履歴の移行が必要です。

リビジョンの表示は、YAML のインポート/エクスポートと同じ設定形式を使用します。未設定のモデルフィールドは省略し、フィールドはスキーマの順序に従います。false、0、空の上書き値など、明示的な値は表示されます。設定をクリアすると、差分ではその行の削除として表示します。この形式は表示する設定だけに影響し、ロールバックは保存された完全なスナップショットを使用します。

プレビューのフッター左側には、操作ボタンと並んで Restart on rollback チェックボックスがあり、デフォルトで選択されています。復元した設定を保存した後、UI はデプロイの再起動を要求し、インスタンスを再作成します。再起動せずに保存する場合はチェックを外してください。設定の変更を反映するためにインスタンスの再作成が必要な場合は、黄色の通知が表示されます。ロールバックと、要求した再起動が成功すると、ドロワーが閉じてデプロイ一覧が更新されます。設定の保存は成功して再起動が失敗した場合、ドロワーは開いたまま両方の結果を示し、Retry restart を表示します。この操作はロールバックを繰り返しません。再試行が成功した場合も、ドロワーが閉じて一覧が更新されます。ロールバック API を直接呼び出した場合は、設定だけを復元します。

最新のリビジョンは、保存された最新の設定を示すものであり、実行中の全インスタンスがその設定を使っていることを保証するものではありません。再起動は非同期であり、無停止での切り替えは提供しません。設定の有効性はロールバック送信時に検証されるため、参照先のリソースやサポート対象の設定が変わっていると、プレビューできても適用が失敗する場合があります。

リビジョンの保持

デフォルトでは、デプロイは最新のリビジョンに加えて 10 個の過去のリビジョンを保持します。デプロイフォームにはこの設定は表示されません。上級ユーザーは API で revision_history_limit を調整できます。最新のリビジョンだけを保持するには 0 に設定します。上限を下げると、設定のリビジョンを作成することなく、超過分の履歴を古いものから即座に削除します。

履歴ドロワーには個別のリビジョン削除機能はありません。自動クリーンアップはデプロイの保持上限に従います。API では古いリビジョンを削除できますが、最新のリビジョンは削除できません。デプロイを削除すると、すべてのリビジョンも削除されます。削除されたリビジョンは復元できません。

履歴には、デプロイの編集と同じ組織およびアクセスの制限が適用され、ワーカーとクラスターの SYSTEM プリンシパルは利用できません。環境変数は元の値で保存されるため、過去のリビジョンが削除または自動整理されるまで、認証情報が保持される場合があります。

モデルインスタンスの表示

デプロイ一覧ページで、確認するモデルデプロイを探します。
> 記号をクリックし、デプロイのインスタンス一覧を表示します。

モデルインスタンスの削除

デプロイ一覧ページで、確認するモデルデプロイを探します。
> 記号をクリックし、デプロイのインスタンス一覧を表示します。
削除するモデルインスタンスを探します。
モデルインスタンスの Operations 列にある省略記号ボタンをクリックし、Delete を選択します。
削除を確認します。

注記

モデルインスタンスを削除した後、必要に応じて GPUStack が新しいインスタンスを再作成し、デプロイの期待レプリカ数を満たします。

モデルインスタンスのログの表示

デプロイ一覧ページで、確認するモデルデプロイを探します。
> 記号をクリックし、デプロイのインスタンス一覧を表示します。
確認するモデルインスタンスを探します。
モデルインスタンスの Operations 列にある View Logs ボタンをクリックします。

GPUStack は、モデルの推論性能を最適化するために、次の設定を提供しています。

拡張 KV キャッシュ

拡張 KV キャッシュを有効にすると、KV キャッシュを CPU メモリまたはリモートストレージにオフロードできます。GPU メモリが限られており、長いコンテキストが必要な構成で特に役立ちます。内部では GPUStack が、選択したバックエンドとフレームワークがサポートする KV キャッシュのオフロードを設定します。LMCache や HiCache などが該当します。

利用可能なオプションは次のとおりです。

RAM と VRAM の比率: KV キャッシュに使用する、GPU VRAM に対するシステム RAM の比率です。たとえば、2.0 は RAM 内のキャッシュサイズを GPU VRAM の 2 倍にできることを意味します。
最大 RAM サイズ: システムメモリに保存する KV キャッシュの最大サイズ（GiB）です。設定すると、RAM-to-VRAM Ratio より優先されます。
キャッシュチャンクのサイズ: KV キャッシュのチャンクあたりのトークン数です。CANN 上の vLLM には適用されません。そのコネクターは KV ブロック全体をオフロードし、エンジンのブロックサイズで再利用するためです。

この機能が利用できるのは、特定のバックエンドとフレームワークだけです。

互換性マトリクス

バックエンド	フレームワーク
vLLM	CUDA, ROCm, CANN
SGLang	CUDA, ROCm, CANN

CANN 上の vLLM では、拡張 KV キャッシュに vLLM Ascend v0.21.0 以降が必要です。Atlas 300I Duo (310P) では利用できません。

スケジューリング設定

スケジュールモード

自動

GPUStack は、現在利用可能なリソースに基づいて、適切な GPU/ワーカーにモデルインスタンスを自動スケジュールします。

配置戦略

Spread: クラスター全体のリソースを、すべてのワーカーに比較的均等に分散させます。1 台のワーカー内では、リソースの断片化が増える場合があります。

Binpack: クラスター全体のリソース利用率を優先し、ワーカー/GPU のリソースの断片化を減らします。

ワーカーセレクター

設定すると、スケジューラーは指定したラベルを持つワーカーにモデルインスタンスをデプロイします。

Workers ページに移動し、対象のワーカーを編集します。ラベルセクションにカスタムラベルを追加して、ワーカーに割り当てます。
Deployments ページに移動し、Deploy Model ボタンをクリックします。Scheduling セクションを展開し、Worker Selector 設定に、先ほど割り当てたワーカーのラベルを入力します。デプロイ時に、これらのラベルに基づいて対応するワーカーへモデルインスタンスを割り当てます。

手動

このスケジュールタイプでは、モデルインスタンスをデプロイする GPU をユーザーが指定できます。

GPU セレクター

一覧から 1 つ以上の GPU を選択します。リソースが許す場合、モデルインスタンスを選択した GPU にデプロイしようとします。

レプリカあたりの GPU 数

Auto: システムが、レプリカあたりの GPU 数を自動計算します。デフォルトでは 2 の累乗を使用し、選択した GPU 数を上限とします。

Manual: 各レプリカで使用する GPU 数をドロップダウンから選択します。

詳細設定

GPUStack は、モデルデプロイに合わせた設定をサポートしています。

モデルカテゴリー

モデルカテゴリーを使うと、モデルを整理したり絞り込んだりできます。デフォルトでは、GPUStack がモデルのメタデータに基づいてカテゴリーを自動検出します。ドロップダウンから選択して、カテゴリーを変更することもできます。

バックエンドパラメーター

モデルの実行時にカスタマイズするバックエンドのパラメーターを入力します。次のパラメーター形式をサポートしています。

方法	例	備考
等号で区切る	`--hf-overrides={"architectures": ["NewModel"]}`	-
スペースで区切る	`--hf-overrides '{"architectures": ["NewModel"]}'`	`shell-like` 形式の分割をサポートします（スペースを含む値など）。
別の項目にする	`--max-model-length`, `8192`	パラメーター名と値を、2 つの別々の項目として入力します。

サポート対象パラメーターの全一覧は、推論バックエンドを参照してください。

環境変数

モデルの実行時に使用する環境変数です。起動時にバックエンドプロセスに渡されます。

LoRA アダプター

LoRA（Low-Rank Adaptation）は、重み全体を再学習する代わりに、小さなアダプターファイルを読み込んで、ベースモデルを特定のドメインに適応させる、パラメーター効率の高いファインチューニング手法です。GPUStack では、デプロイ済みの 1 つのベース LLM に複数の LoRA アダプターをマウントでき、アダプターごとにモデルルートを自動作成します。

注記

LoRA は vLLM、SGLang、Ascend MindIE バックエンドでのみサポートしています。それ以外のバックエンドでは、LoRA Adapters 設定は無視されます。

デプロイフォームの Advanced セクションを展開し、LoRA Adapters でアダプターを 1 つずつ追加します。

ドロップダウンからアダプターを選択します。一覧は検索に対応しています。目的のアダプターが表示されない場合、まず Hugging Face または ModelScope で、そのモデルが実際にアダプターを提供しているか確認してください。その後、リポジトリー ID を検索欄に貼り付けて選択します。
LoRA name: alpaca など、アダプター名だけを入力します。

デプロイ後、GPUStack は LoRA アダプターごとに <base-model-name>:<adapter-name> という名前のモデルルートを自動作成します。アダプターを切り替えるには、OpenAI 互換 API の model フィールドに対応するルート名を設定します。すべてのアダプターは同じ GPU インスタンスを共有します。GPUStack が --enable-lora などのバックエンド起動引数を自動で注入するため、通常は Backend Parameters に重複して指定する必要はありません。

注記

デプロイ済みモデルの LoRA 設定を変更した場合、新しい設定を有効にするには、対応するインスタンスを再起動する必要があります。

呼び出し例やバックエンドごとの互換性の詳細を含む一連の手順は、LoRA アダプターによるモデルの提供チュートリアルを参照してください。

CPU オフロードの許可

注記

カスタムバックエンドでのみ利用できます。

CPU オフロードを有効にすると、GPU リソースが不足した場合に GPUStack が CPU メモリを割り当てます。CPU+GPU の混合推論または CPU のみの推論を使うには、推論バックエンドを正しく設定する必要があります。

ワーカー間の分散推論の許可

注記

vLLM、SGLang、MindIE バックエンドで利用できます。

複数のワーカー間で分散推論を有効にします。プライマリーのモデルインスタンスは、1 台以上の別ワーカー上のバックエンドインスタンスと通信し、それらに計算タスクをオフロードします。

エラー時の自動再起動

モデルインスタンスでエラーが発生した場合の自動再起動を有効にします。この機能は、モデルインスタンスの高可用性と信頼性を確保します。エラーが発生すると、GPUStack は指数バックオフ戦略でモデルインスタンスの再起動を自動的に試みます。試行間隔は指数的に増え、最大 5 分になります。継続的なエラーの際に、頻繁な再起動によってシステムに過大な負荷がかかるのを防ぎます。

汎用プロキシの有効化

OpenAI 互換 API との統合は一般的ですが、用途によっては別の要件があります。GPUStack は OpenAI 互換以外の任意の推論 API をサポートし、AI アプリケーション開発の柔軟性を高めます。

汎用プロキシを有効にすると、GPUStack では 2 つの方法で対象モデルを指定できます。パスベースの形式を推奨します。ヘッダーベースの形式は後方互換性のために残されており、非推奨です。

パスベースの形式（推奨）

プロキシの接頭辞にモデルルートの数値 ID を追加します。/model/proxy/<model_route_id>/<upstream-path> とすると、GPUStack がそのルートのターゲットにリクエストを振り分けます。追加のヘッダーは不要です。

# Assume the model route id is 42.
curl http://<server-url>/model/proxy/42/embed \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <GPUSTACK_API_KEY>" \
  -d '{"inputs":["What is Deep Learning?", "Deep Learning is not..."]}'

ゲートウェイは転送前に /model/proxy/<id> を除去するため、上流の推論サーバーには次のように届きます。

curl http://<inference-server-url>/embed \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"inputs":["What is Deep Learning?", "Deep Learning is not..."]}'

モデルルートの ID は名前を変更しても変わりません。モデルの詳細ページで確認するか、GET /v2/model-routes で取得できます。

ヘッダーベースの形式（非推奨）

非推奨

/model/proxy と X-GPUStack-Model の形式は、後方互換性のために残されていますが、将来のリリースで削除される予定です。上記のパスベースの形式に移行してください。

curl http://<server-url>/model/proxy/embed \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <GPUSTACK_API_KEY>" \
  -H "X-GPUStack-Model: bge-m3" \
  -d '{"inputs":["What is Deep Learning?", "Deep Learning is not..."]}'

転送前にパスの接頭辞 /model/proxy が除去されます。ゲートウェイが対象モデルを解決できるよう、X-GPUStack-Model ヘッダーまたは JSON ボディーの model 属性のいずれかを指定する必要があります。上流の推論サーバーには、次のようなリクエストが届きます。

curl http://<inference-server-url>/embed \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-GPUStack-Model: bge-m3" \
  -d '{"inputs":["What is Deep Learning?", "Deep Learning is not..."]}'