チュートリアル: Hugging Faceからオープンウェイトモデルをデプロイする¶

Workload APIを使用して、Hugging Face Hubから人気のあるオープンウェイトモデルを、マネージドでオートスケーリングするエンドポイントとしてデプロイします。 単一のワークロード仕様にvLLMサーバーを記述し、ワークロードを直接作成します。 プラットフォームはGPUコンピューティングをプロビジョニングし、認証されたOpenAI互換エンドポイントを公開し、実行中のサービスのログ、トレース、および指標を収集します。

この手順では、LLM推論とサービングのためのオープンソースフレームワークであるvLLMライブラリを使用します。 公式のvllm/vllm-openaiイメージは、Hugging Face Hubから直接モデルをダウンロードしてロードするOpenAI互換HTTPサーバーを起動します。 別のモデルをサーブするには、アーティファクトのエントリーポイントにあるモデル識別子を変更します。

このガイドでは、単一の中規模GPUバンドルでopenai/gpt-oss-20bをサーブします。 gpt-oss-20bは、Apache 2.0ライセンスでリリースされたオープンウェイトモデルです（アクセス制限なし）。

前提条件¶

Hugging FaceのLLMをワークロードとしてデプロイする前に、以下を取得してください:

• DataRobot環境に対して認証され、ワークロードコマンドが有効になっているDataRobot CLI (dr):

  export DATAROBOT_CLI_FEATURE_WORKLOAD=true
  dr auth login 
  

  完全なコマンドリファレンスについては、CLIを使用したワークロードの管理を参照してください。 このガイドの後半で使用される生のcurl呼び出しのために、DATAROBOT_ENDPOINT（/api/v2で終わる）とDATAROBOT_API_TOKENも設定する必要があります。

• プラットフォームがプルできるコンテナレジストリ。 パブリックのvllm/vllm-openaiイメージはそのまま動作します。

• クラスターで利用可能な容量があり、選択したモデルに十分な大きさのGPUコンピューティングバンドルへのアクセス。 コンピューティングバンドルの選択を参照してください。

• gpt-ossモデルはオープンライセンス（Apache 2.0）であり、Hugging Faceトークンは必要ありません。 代わりにゲート付きモデルをサーブするには、Hugging Faceアカウントと、READ権限を持つHugging Faceアクセストークン（およびモデル作成者からのモデルアクセス権限）が必要です。 参照によってワークロードに注入できるように、そのトークンを資格情報管理ページにDataRobotのAPIトークン資格情報として保存します。

コンピューティングバンドルの選択¶

ここから始めます。 ワークロードアーティファクトの定義に記述されたアーティファクトは、プラットフォームに実際に存在し、_かつ_モデルに対して十分な大きさを持つGPUコンピューティングバンドルを参照する必要があるため、スペックを書く前にハードウェアを決定してください。

利用可能なコンピューティングバンドルを見つける¶

ワークロードのGPUモデル、VRAM、CPU、メモリは、プラットフォームが公開するコンピューティングバンドルから提供されます。 このクエリーによって返されるバンドルのみが有効な値であり、バンドルIDはプラットフォーム固有であるため、サンプルIDをコピーするのではなく、ご自身の環境から読み取ってください。 まず、それらをリストします:

# List the compute bundles available on the platform
curl -sS "${DATAROBOT_ENDPOINT}/mlops/compute/bundles/?useCases=workload" \
  -H "Authorization: Bearer ${DATAROBOT_API_TOKEN}"

useCases=workload フィルターはそのままにしておきます。これがないと、レスポンスには他のDataRobot製品用に予約されたバンドルも含まれます。各バンドルは、そのGPUタイプ、VRAM、CPU、およびメモリーを報告します。バンドルの id（例えば gpu.medium）に注意し、それを runtime.containerGroups[].resourceBundles に設定します。これはコンテナグループごとに正確に1つのバンドルを取ります。詳細なリファレンスについては、リソース割り当てとバンドルを参照してください。

モデルのメモリーとコンテキスト長の決定¶

GPUメモリーを消費する2つの要素は、モデルの重みと、コンテキスト長 (--max-model-len) に応じて大きくなるKVキャッシュです。検証済みの数値を取得する最も早い方法は、当て推量ではなくvLLM独自のツールを使用することです。

• vLLM recipes：recipes.vllm.ai では、モデルおよびGPUごとに検証済みの vllm serve コマンドを公開しており、これには量子化、コンテキスト長、テンソル並列サイズ、メモリーフラグが含まれます。ターゲットモデルと最も近いGPUに一致するレシピを見つけ、そのフラグとハードウェアサイジングを再利用します。
• コンテキスト長：KVキャッシュは --max-model-len に比例してスケーリングされるため、これを減らす（例えば 8192 にする）ことで、実質的なVRAMが解放され、モデルをより小さなバンドルに収めることができます。--max-model-len、--gpu-memory-utilization、--kv-cache-dtype fp8、および複数のGPUに分割するための --tensor-parallel-size などのレバーについては、vLLMのメモリーの節約ガイドを参照してください。

参考までに、gpt-oss-20b を --max-model-len 8192 で実行すると、24GBのGPU上で約15GBを占有し、KVキャッシュ用に約5GB（およそ148,000トークン）が残ります。

より大きなモデルのサービング¶

gpt-oss-120b は4ビット（MXFP4）でロードされます：重みは約60GBであり、実際にはKVキャッシュとアクティベーションが含まれると80～96GBが必要になります。単一の80GB GPUバンドル（例えばNVIDIA H100 80GB）は、--max-model-len 8192 などの短いコンテキスト長でモデルに適合します；より長いコンテキストは、KVキャッシュをその範囲の上限に押し上げます。長いコンテキストの場合は、マルチGPUバンドルを選択し、vLLMエントリーポイントに --tensor-parallel-size <N> を追加します。ここで N はバンドルのGPU数と一致します。

ワークロードアーティファクトの定義¶

単一のスペックでワークロード全体を記述します。artifact ブロックは、イメージ、ポート、エントリーポイント、環境変数、ヘルスプローブなど、実行されるものの不変の定義です（アーティファクトの概念を参照）。runtime ブロックは、実行するリソースとレプリカを定義します。このスペックからワークロードを作成すると、1回の呼び出しで両方が作成されます。

スペックでは status: locked が設定されており、これによりアーティファクトは不変になり、ワークロードに有効期限がなくなります。設定を反復処理している間はその行を省略して編集可能な draft を維持し、確定したらロックします。ロックは一方向であるため、設定する前に本番環境への昇格を確認してください。

# spec.yaml
name: gpt-oss-20b-vllm
importance: moderate
artifact:
  name: gpt-oss-20b-vllm-artifact
  description: Serve openai/gpt-oss-20b via vLLM's OpenAI-compatible HTTP server.
  status: locked
  spec:
    type: service
    containerGroups:
      - name: default
        containers:
          - name: vllm-server
            imageUri: vllm/vllm-openai:v0.26.0
            primary: true
            port: 8000
            entrypoint:
              - /bin/sh
              - -c
              - >
                exec vllm serve openai/gpt-oss-20b
                --host 0.0.0.0 --port 8000
                --max-model-len 8192
                --otlp-traces-endpoint ${OTEL_EXPORTER_OTLP_ENDPOINT}/v1/traces
            environmentVars:
              - name: USER
                value: vllm
              - name: HOME
                value: /tmp
              - name: HF_HOME
                value: /tmp/hf
              - name: TRANSFORMERS_CACHE
                value: /tmp/hf
              # OTEL_EXPORTER_OTLP_ENDPOINT is injected by the platform; do not set it here.
            startupProbe:
              path: /health
              port: 8000
              periodSeconds: 15
              failureThreshold: 60
            readinessProbe:
              path: /health
              port: 8000
              periodSeconds: 10
              failureThreshold: 3
            livenessProbe:
              path: /health
              port: 8000
              periodSeconds: 20
              failureThreshold: 3
              timeoutSeconds: 5
runtime:
  containerGroups:
    - name: default          # Must match artifact.spec.containerGroups[].name.
      replicaCount: 1
      resourceBundles:
        - gpu.medium           # Replace with a bundle ID from your platform; see "Choose a compute bundle." 

ヘルスプローブの構成¶

大規模なモデルのロードには数分かかり、3つのプローブは異なる目的を果たします（コンテナの正常性と準備状況を参照）：

• startupProbe は他の2つのプローブをゲートし、再起動せずに長いモデルのロードを可能にします。最悪の起動時間を超えるように failureThreshold × periodSeconds を設定します：60 × 15秒で15分の予算になります。
• readinessProbe はレプリカがトラフィックを受信するかどうかを制御します。ウェッジしたレプリカが遅延なくローテーションから外れるように、タイトに保ちます。
• livenessProbe は動作を停止したコンテナを再起動します。vLLMはHTTPサーバーとは別のプロセスでエンジンを実行するため、ポートが引き続き接続を受け入れている間でもエンジンが失敗する可能性があります。その場合、Readinessだけではコンテナは再起動しません。

エントリーポイントに関する注意事項¶

• 量子化は自動的に検出されます。 vLLMはチェックポイントから量子化方法を読み取るため、gpt-oss モデルに --quantization フラグは必要ありません。
• シェル形式により変数展開が有効になります。 エントリーポイントは /bin/sh -c … exec … を通じて実行されるため、${OTEL_EXPORTER_OTLP_ENDPOINT} は実行時に展開されます。exec形式のエントリーポイント配列は、展開されていないリテラル文字列を渡します。トレースがない場合は、よりシンプルなexec形式 entrypoint: ["vllm", "serve", "openai/gpt-oss-20b", "--host", "0.0.0.0", "--port", "8000"] を使用します。
• トレース転送は事前設定されています。 プラットフォームはOTLPエンドポイントとその認証ヘッダーを注入します；これらを上書きしないでください。プラットフォームのコレクターはHTTP経由のOTLPのみを受け入れますが、vLLM（およびOTel SDK）はデフォルトでgRPCを使用するため、エントリーポイントの --otlp-traces-endpoint フラグでHTTPを選択します。

environmentVars:
  - name: USER
    value: vllm
  - name: HOME
    value: /tmp
  - name: HF_HOME
    value: /tmp/hf
  - name: TRANSFORMERS_CACHE
    value: /tmp/hf
  - source: dr-credential
    name: HUGGING_FACE_HUB_TOKEN
    drCredentialId: <huggingface-credential-id>
    key: apiToken 

ワークロードの作成と実行¶

スペックからワークロードを作成し、running になるまでポーリングします。dr workload create は、後続のコマンドで必要となるワークロードIDを出力します：

# Create the Workload; note the Workload ID it returns
dr workload create --spec-file spec.yaml

# Poll status until "running"
dr workload status <workload_id> 

ステータスは submitted → provisioning → launching → running と進行します（ライフサイクルステータスを参照）。最初の起動には数分かかると予想してください：イメージがプルされ、Hugging Face Hubから重みがダウンロードされ、モデルがGPUにロードされます。ワークロードが存在すると、ライフサイクルコマンド（stop、start、delete、endpoint、list）を利用できます。CLIによるワークロードの管理を参照してください。

ワークロードが起動しない場合¶

まずコンテナのログを確認します：

dr workload logs <workload_id> --level error --limit 100 

errored が一時的な異常ではなく最終的なステータスである理由を含め、より完全な症状から原因へのリファレンスについては、ベストプラクティスとトラブルシューティングを参照してください。

OpenAI互換エンドポイントの呼び出し¶

ワークロードのエンドポイントURLを取得し、任意のOpenAI互換クライアントで呼び出します。エンドポイントはDataRobot認証の背後で提供されるため、DataRobot APIトークンをAPIキーとして渡します；これがないリクエストは 401 で拒否されます。

# Get the Workload endpoint URL
dr workload endpoint <workload_id> 

# Call the vLLM OpenAI-compatible endpoint
from openai import OpenAI
import os

# The base URL is the workload endpoint retrieved in the previous step, with the vLLM /v1 suffix.
client = OpenAI(
    base_url="<workload-endpoint>/v1",
    api_key=os.environ["DATAROBOT_API_TOKEN"],
)

completion = client.chat.completions.create(
    model="openai/gpt-oss-20b",   # The model identifier served by vLLM.
    messages=[
        {"role": "system", "content": "You are a helpful assistant"},
        {"role": "user", "content": "Where is DataRobot headquartered?"},
    ],
    stream=False,
)

print(completion.to_json(indent=2)) 

ワークロードの監視¶

プラットフォームは起動時に、すべてのコンテナにOTLPエンドポイントとその認証ヘッダーを注入します；これらはプラットフォームで管理されるため、上書きしないでください。

インストルメンテーションを必要とせずに自動的にキャプチャされます：ログ（コンテナのstdout/stderr）、サービス統計（リクエスト数、エラー率、応答時間、同時実行性）、リクエストトレース（リクエストごとに1つのスパン）、およびリソース指標（レプリカ数、CPU、メモリー、GPU使用率）。

このスペックで --otlp-traces-endpoint を設定しているためキャプチャされます：vLLMエンジンスパン。リクエストごとに1つ、/v1/chat/completions のプロンプト、完了、およびトークン数に加えて、最初のトークンまでの時間、キュー時間、事前入力とデコード時間、サンプリングパラメーター、そして遅いコールドスタートの診断に役立つ詳細なスタートアップトレースが含まれます。

追加のセットアップが必要です：KVキャッシュ使用率やキュー深度などのvLLMエンジン指標。vLLMエンジン指標の収集を参照してください。

実行中のワークロードは、コンソールのhttps://app.datarobot.com/console-nextgen/workloads/<workload_id>/overviewで表示できます。

トレースは 監視 > データ探索 タブに表示されます。詳細については、データ探索のドキュメントを参照してください。

vLLMエンジン指標の収集¶

このセクションはオプションです。ログ、サービス統計、リクエストトレース、リソース指標（GPU使用率を含む）は、これなしでもすでに収集されています。監視 > OTel指標 サーフェスで、KVキャッシュ使用率やキュー深度など、vLLMのエンジン内部指標の場合にのみ追加します。

vLLMはこれらの指標をPrometheusの /metrics エンドポイント（プルベース）でのみ公開しますが、プラットフォームのOTel指標サーフェスはOTLP（プッシュ）を取り込みます。これらを収集するには、サイドカーとしてブリッジを追加します：localhost 経由でvLLMの /metrics をスクレイプし、OpenTelemetry SDKを使用してOTLP経由で値を再エクスポートする、プライマリ以外の2番目のコンテナです（OpenTelemetryによるワークロードのインストルメント化を参照）。イメージURIの検証に記載されているように、プラットフォームがプルできるレジストリにブリッジイメージをプッシュします。

# Sidecar: scrape vLLM's Prometheus /metrics and re-export as OTLP metrics via the OTel SDK.
- name: vllm-metrics-bridge
  imageUri: <your-registry>/vllm-metrics-bridge:latest
  environmentVars:
    - name: USER
      value: bridge
    - name: HOME
      value: /tmp
    # OTEL_EXPORTER_OTLP_ENDPOINT and its auth headers are injected by the platform. 

グループ内のすべてのコンテナに resourceAllocation エントリーを指定し、バンドルの容量をコンテナ間で分割して、合計がバンドルのCPUとRAMの範囲内に収まるようにします。memory は1000ベースの単位（B、KB、MB、GB）または生のバイト整数を受け入れます。Kubernetesスタイルのバイナリサフィックス（Mi、Gi）は検証エラーを返します。gpu はGPU数のみを設定します：

runtime:
  containerGroups:
    - name: default
      replicaCount: 1
      resourceBundles:
        - gpu.medium
      containers:
        - name: vllm-server
          resourceAllocation: {cpu: 3, memory: "22GB", gpu: 1}
        - name: vllm-metrics-bridge
          resourceAllocation: {cpu: 0.5, memory: "2GB"} 

ワークロードのスケーリング¶

PATCH /workloads/{workload_id}/settings 経由でレプリカまたはオートスケーリングを更新します。フィールドリファレンスとスケーリング指標についてはランタイム設定を参照してください。

このサイズのモデルには2つの考慮事項が適用されます。HF_HOME はコンテナ独自のエフェメラルファイルシステムを指しており、ゼロからスケーリングされたレプリカはトラフィックを提供できるようになる前にイメージのプルと重みの完全なダウンロードの両方を繰り返すため、minReplicaCount を 1 以上に維持します。同時実行ワークロードとレプリカには組織レベルの上限も適用されます。どちらかの上限を超える PATCH は 403 を返すため、積極的にスケーリングする前に現在の使用量を確認してください。