Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

GKE で vLLM を使用して DeepSeek-V3.2-Speciale で推論を実行する

このチュートリアルでは、vLLM フレームワークを使用して DeepSeek-V3.2-Speciale 言語モデルをデプロイしてサービングする方法について説明します。このモデルを Google Kubernetes Engine（GKE）Enterprise エディションの Autopilot クラスタにデプロイし、8 個の B200 GPU を搭載した単一の A4 仮想マシン（VM）を使用します。

このチュートリアルでは、DeepSeek-V3.2-Speciale 言語モデルを確認し、その機能がユースケースの要件を満たしていることを確認済みであることを前提としています。

このチュートリアルは、Kubernetes コンテナオーケストレーション機能を使用して推論ワークロードを処理することに関心のある ML エンジニア、プラットフォーム管理者、オペレーター、データと AI のスペシャリストを対象としています。

目標

Hugging Face を使用して DeepSeek-V3.2-Speciale にアクセスします。
環境を準備します。
Autopilot モードで GKE クラスタを作成する。
Hugging Face の認証情報用の Kubernetes Secret を作成します。
Cloud Storage バケットを作成する。
モデルを Cloud Storage バケットにダウンロードします。
vLLM コンテナを GKE クラスタにデプロイする。
curl を使用して DeepSeek-V3.2-Speciale を操作します。
クリーンアップする。

費用

このチュートリアルでは、以下を含む、 Google Cloudの課金対象となるコンポーネントを使用します。

料金計算ツールを使うと、予想使用量に基づいて費用の見積もりを生成できます。

始める前に

Google Cloud アカウントにログインします。 Google Cloudを初めて使用する場合は、アカウントを作成して、実際のシナリオでの Google プロダクトのパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。

Google Cloud CLI をインストールします。

外部 ID プロバイダ（IdP）を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。

gcloud CLI を初期化するには、次のコマンドを実行します。

gcloud init

Google Cloud プロジェクトを作成または選択します。

プロジェクトの選択または作成に必要なロール

プロジェクトを選択する: プロジェクトの選択に特定の IAM ロールは必要ありません。ロールが付与されているプロジェクトであれば、どのプロジェクトでも選択できます。
プロジェクトを作成する: プロジェクトを作成するには、resourcemanager.projects.create 権限を含むプロジェクト作成者ロール（roles/resourcemanager.projectCreator）が必要です。詳しくは、ロールを付与する方法をご覧ください。

Google Cloud プロジェクトを作成します。
```
gcloud projects create PROJECT_ID
```
PROJECT_ID は、作成する Google Cloud プロジェクトの名前に置き換えます。
作成した Google Cloud プロジェクトを選択します。
```
gcloud config set project PROJECT_ID
```
PROJECT_ID は、 Google Cloud プロジェクトの名前に置き換えます。

Google Cloud プロジェクトに対して課金が有効になっていることを確認します。

必要な API が有効になっていない場合は、有効にします。

API を有効にするために必要なロール

API を有効にするには、serviceusage.services.enable 権限が必要です。プロジェクトを作成した場合は、オーナーロール（roles/owner）を介してこの権限がすでに付与されている可能性があります。それ以外の場合は、Service Usage 管理者ロール（roles/serviceusage.serviceUsageAdmin）を介してこの権限を取得できます。ロールを付与する方法をご覧ください。

gcloud services enable container.googleapis.com

Google Cloud CLI をインストールします。

外部 ID プロバイダ（IdP）を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。

gcloud CLI を初期化するには、次のコマンドを実行します。

gcloud init

Google Cloud プロジェクトを作成または選択します。

プロジェクトの選択または作成に必要なロール

プロジェクトを選択する: プロジェクトの選択に特定の IAM ロールは必要ありません。ロールが付与されているプロジェクトであれば、どのプロジェクトでも選択できます。
プロジェクトを作成する: プロジェクトを作成するには、resourcemanager.projects.create 権限を含むプロジェクト作成者ロール（roles/resourcemanager.projectCreator）が必要です。詳しくは、ロールを付与する方法をご覧ください。

Google Cloud プロジェクトを作成します。
```
gcloud projects create PROJECT_ID
```
PROJECT_ID は、作成する Google Cloud プロジェクトの名前に置き換えます。
作成した Google Cloud プロジェクトを選択します。
```
gcloud config set project PROJECT_ID
```
PROJECT_ID は、 Google Cloud プロジェクトの名前に置き換えます。

Google Cloud プロジェクトに対して課金が有効になっていることを確認します。

必要な API が有効になっていない場合は、有効にします。

API を有効にするために必要なロール

gcloud services enable container.googleapis.com

ユーザーアカウントにロールを付与します。次の IAM ロールごとに次のコマンドを 1 回実行します。 roles/container.admin
```
gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE
```
次のように置き換えます。
- PROJECT_ID: プロジェクト ID。
- USER_IDENTIFIER: ユーザーアカウントの識別子。例: myemail@example.com
- ROLE: ユーザーアカウントに付与する IAM ロール。
Hugging Face アカウントにログインするか、アカウントを作成します。

Hugging Face を使用して DeepSeek-V3.2-Speciale にアクセスする

Hugging Face を使用して DeepSeek-V3.2-Speciale モデルにアクセスする手順は次のとおりです。

Hugging Face にログインします。
Hugging Face read アクセストークンを作成します。
read アクセストークンの値をコピーして保存します。これは、このチュートリアルの後半で使用します。

環境を準備する

環境を準備するには、デフォルトの環境変数を設定します。

export PROJECT_ID="YOUR_PROJECT_ID"
export RESERVATION_URL="YOUR_RESERVATION_NAME"
export REGION="YOUR_REGION"
export CLUSTER_NAME="YOUR_CLUSTER_NAME"
export GCS_BUCKET="YOUR_GCS_BUCKET"
export HUGGING_FACE_TOKEN="YOUR_HF_TOKEN"
export NETWORK="YOUR_NETWORK_NAME"
export SUBNETWORK="YOUR_SUBNETWORK_NAME"
export PROJECT_NUMBER=$(gcloud projects describe "${PROJECT_ID}" --format="value(projectNumber)")

gcloud config set project "${PROJECT_ID}"
gcloud config set billing/quota_project "${PROJECT_ID}"

次のように置き換えます。

YOUR_PROJECT_ID: GKE クラスタを作成する Google Cloud プロジェクトの ID。
YOUR_RESERVATION_NAME: GKE クラスタの作成に使用する予約の名前。予約が存在するプロジェクトに基づいて、次のいずれかの値を指定します。
- 予約がプロジェクトに存在する場合: YOUR_RESERVATION_NAME
- 予約が別のプロジェクトにあり、プロジェクトで予約を使用できる場合: projects/RESERVATION_PROJECT_ID/reservations/YOUR_RESERVATION_NAME
YOUR_REGION: GKE クラスタを作成するリージョン。クラスタは、予約が存在するリージョンでのみ作成できます。
YOUR_CLUSTER_NAME: 作成する GKE クラスタの名前。
YOUR_GCS_BUCKET: モデルをダウンロードする Cloud Storage バケットの名前。
YOUR_HF_TOKEN: 前のセクションで作成した Hugging Face アクセストークン。
YOUR_NETWORK_NAME: GKE クラスタが使用するネットワーク。次のいずれかの値を指定します。
- カスタムネットワークを作成した場合は、ネットワークの名前を指定します。
- それ以外の場合は、default を指定します。
YOUR_SUBNETWORK_NAME: GKE クラスタが使用するサブネットワーク。次のいずれかの値を指定します。
- カスタムサブネットワークを作成した場合は、サブネットワークの名前を指定します。指定できるのは、予約と同じリージョンにあるサブネットワークのみです。
- それ以外の場合は、default を指定します。

Autopilot モードの GKE クラスタを作成する

Autopilot モードで GKE クラスタを作成するには、次のコマンドを実行します。

gcloud container clusters create-auto "$CLUSTER_NAME" \
    --project="$PROJECT_ID" \
    --region="$REGION" \
    --release-channel=rapid \
    --network="$NETWORK" \
    --subnetwork="$SUBNETWORK"

GKE クラスタの作成には時間がかかることがあります。 Google Cloud がクラスタの作成を完了したことを確認するには、 Google Cloud コンソールの [Kubernetes クラスタ] に移動します。

Hugging Face の認証情報用の Kubernetes Secret を作成する

Hugging Face の認証情報用の Kubernetes Secret を作成する手順は次のとおりです。

GKE クラスタと通信するように kubectl を構成します。

gcloud container clusters get-credentials "$CLUSTER_NAME" \
    --location="$REGION"

Hugging Face トークンを保存する Kubernetes Secret を作成します。

kubectl create secret generic hf-secret \
    --from-literal=hf_token="${HUGGING_FACE_TOKEN}" \
    --dry-run=client -o yaml | kubectl apply -f -

Cloud Storage バケットを作成する

既存の Cloud Storage バケットを使用する場合は、この手順をスキップできます。ただし、バケットがクラスタと同じリージョンにあり、サービスアカウントにバケットに対する必要な write 権限が付与されていることを確認する必要があります。

新しいバケットを使用してモデルを保存する場合は、次のコマンドを実行します。

gcloud storage buckets create gs://"$GCS_BUCKET" --location="$REGION" --uniform-bucket-level-access

Cloud Storage バケットに対する write 権限をデフォルトのサービスアカウントに付与します。

gcloud storage buckets add-iam-policy-binding gs://"$GCS_BUCKET" \
    --member="principal://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$PROJECT_ID.svc.id.goog/subject/ns/default/sa/default" \
    --role="roles/storage.objectAdmin"

モデルを Cloud Storage バケットにダウンロードする

deepseek-download-job.yaml ファイルを作成します。

apiVersion: batch/v1
kind: Job
metadata:
  name: deepseek-download-job
  namespace: default
spec:
  template:
    metadata:
      labels:
        app: deepseek-oss-downloader
    spec:
      restartPolicy: OnFailure
      containers:
      - name: downloader
        image: google/cloud-sdk:slim
        resources:
          requests:
            cpu: "8"
            memory: "32Gi"
          limits:
            cpu: "8"
            memory: "32Gi"
        env:
        - name: HUGGING_FACE_HUB_TOKEN
          valueFrom:
            secretKeyRef:
              name: hf-secret
              key: hf_token
        - name: HF_XET_HIGH_PERFORMANCE
          value: "0"
        - name: PIP_BREAK_SYSTEM_PACKAGES
          value: "1"
        command: ["/bin/sh", "-c"]
        args:
        - |
          set -e
          echo "Installing Hugging Face Hub CLI..."
          pip install -U "huggingface_hub[cli]"

          LOCAL_DIR="/mnt/model-download/deepseek-v3-2"
          mkdir -p "$LOCAL_DIR"

          echo "Downloading model from HF to local SSD using parallel workers..."
          hf download deepseek-ai/DeepSeek-V3.2-Speciale \
            --token "$HUGGING_FACE_HUB_TOKEN" \
            --local-dir "$LOCAL_DIR" \
            --max-workers 8

          DOWNLOAD_STATUS=$?

          if [ $DOWNLOAD_STATUS -ne 0 ]; then
            echo "ERROR: Model download failed with exit code $DOWNLOAD_STATUS"
            exit $DOWNLOAD_STATUS
          fi

          echo "Download to SSD complete. Syncing to GCS..."
          gcloud storage rsync "$LOCAL_DIR" "gs://$GCS_BUCKET/deepseek-v3-2" --recursive

          echo "Process successfully completed!"
        volumeMounts:
        - mountPath: /mnt/model-download
          name: download-storage
      volumes:
      - name: download-storage
        ephemeral:
          volumeClaimTemplate:
            spec:
              accessModes: [ "ReadWriteOnce" ]
              storageClassName: premium-rwo
              resources:
                requests:
                  storage: 800Gi

deepseek-download-job.yaml マニフェストを適用して、ダウンロードジョブを初期化します。
```
envsubst '$GCS_BUCKET' < deepseek-download-job.yaml | kubectl apply -f -
```
完了ステータスを表示するには、次のコマンドを実行します。
```
kubectl wait \
    --for=condition=Complete \
    --timeout=7200s job/deepseek-download-job
```
--timeout フラグは、コマンドがタイムアウトする前にジョブをモニタリングする時間を指定します。

ジョブリソースは、SSD ボリュームを使用して、Hugging Face から DeepSeek-V3.2-Speciale モデルの重みを Google Cloud Storage バケットにダウンロードします。ダウンロードには 40 分ほどかかります。ダウンロードが完了したら、次のセクションに進んでモデルのデプロイを開始します。
ジョブを削除するには、次のコマンドを実行します。
```
kubectl delete job deepseek-download-job
```

vLLM コンテナを GKE クラスタにデプロイする

モデルを Cloud Storage バケットにダウンロードしたら、次の手順で vLLM コンテナを GKE クラスタにデプロイします。

選択した vLLM デプロイを含む vllm-deepseek3-2.yaml ファイルを作成します。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: deepseek3-2-deploy
spec:
  replicas: 1
  selector:
    matchLabels:
      app: deepseek
  template:
    metadata:
      labels:
        app: deepseek
        ai.gke.io/model: deepseek-v3-2
        ai.gke.io/inference-server: vllm
        examples.ai.gke.io/source: user-guide
      annotations:
        gke-gcsfuse/volumes: "true"
    spec:
      containers:
      - name: vllm-inference
        image: us-docker.pkg.dev/vertex-ai/vertex-vision-model-garden-dockers/pytorch-vllm-serve:model-garden.pytorch-vllm-serve-release_20251126.00_p0
        resources:
          requests:
            cpu: "10"
            memory: "1000Gi"
            ephemeral-storage: "1Ti"
            nvidia.com/gpu: "8"
          limits:
            cpu: "10"
            memory: "1000Gi"
            ephemeral-storage: "1Ti"
            nvidia.com/gpu: "8"
        command: ["python3", "-m", "vllm.entrypoints.openai.api_server"]
        args:
        - --model=/mnt/gcs/deepseek-v3-2
        - --tensor-parallel-size=8
        - --host=0.0.0.0
        - --port=8000
        - --max-model-len=131072
        - --max-num-seqs=16
        - --enable-chunked-prefill
        - --gpu-memory-utilization=0.90
        - --enforce-eager
        - --trust-remote-code
        volumeMounts:
        - mountPath: /dev/shm
          name: dshm
        - mountPath: /mnt/gcs
          name: gcs-bucket-volume
          readOnly: true
        livenessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 1800
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 1800
          periodSeconds: 5
      volumes:
      - name: dshm
        emptyDir:
          medium: Memory
      - name: gcs-bucket-volume
        csi:
          driver: gcsfuse.csi.storage.gke.io
          volumeAttributes:
            bucketName: $GCS_BUCKET
            mountOptions: "implicit-dirs,file-cache:max-size-mb:-1,file-cache:enable-parallel-downloads:true,file-cache:max-parallel-downloads:32,file-cache:parallel-downloads-per-file:8,file-cache:download-chunk-size-mb:16"
      nodeSelector:
        cloud.google.com/gke-accelerator: nvidia-b200
        cloud.google.com/reservation-name: $RESERVATION_URL
        cloud.google.com/reservation-affinity: "specific"
        cloud.google.com/gke-gpu-driver-version: latest

---
apiVersion: v1
kind: Service
metadata:
  name: deepseek-service
spec:
  selector:
    app: deepseek
  type: ClusterIP
  ports:
    - protocol: TCP
      port: 8000
      targetPort: 8000
---
apiVersion: monitoring.googleapis.com/v1
kind: PodMonitoring
metadata:
  name: deepseek-monitoring
spec:
  selector:
    matchLabels:
      app: deepseek
  endpoints:
  - port: 8000
    path: /metrics
    interval: 30s

vllm-deepseek3-2.yaml ファイルは GKE クラスタに適用します。
```
envsubst < vllm-deepseek3-2.yaml | kubectl apply -f -
```
完了ステータスを表示するには、次のコマンドを実行します。
```
kubectl wait \
  --for=condition=Available \
  --timeout=7200s deployment/deepseek3-2-deploy
```
--timeout フラグを使用すると、コマンドは指定された期間、デプロイをモニタリングできます。

curl を使用して DeepSeek-V3.2-Speciale を操作する

デプロイした DeepSeek-V3.2-Speciale モデルを確認するには、次の操作を行います。

DeepSeek-V3.2-Speciale へのポート転送を設定します。
```
kubectl port-forward service/deepseek-service 8000:8000
```

新しいターミナルウィンドウを開きます。その後、curl を使用してモデルとチャットできます。

time curl http://127.0.0.1:8000/v1/completions \
   -X POST \
   -H "Content-Type: application/json" \
   -d '{
     "model": "deepseek-ai/DeepSeek-V3.2-Speciale",
     "prompt": "<|im_start|>user\nExplain the ReAct (Reasoning + Acting) pattern in Agentic AI. Provide a concise Python pseudocode example showing the loop. Keep the explanation under 300 words.<|im_end|>\n<|im_start|>assistant\n",
     "max_tokens": 1024,
     "temperature": 0.7,
     "stream": false,
     "stop": ["<|im_end|>"]
   }' | jq .

出力は次のようになります。

{
  "id": "cmpl-be345f0499e949ed8500e533be2cfe3f",
  "object": "text_completion",
  "created": 1764803171,
  "model": "deepseek-ai/DeepSeek-V3.2-Speciale",
  "choices": [
    {
      "index": 0,
      "text": "The ReAct pattern integrates reasoning (thoughts) and actions (tool calls) within an agentic loop... [TRUNCATED FOR BREVITY] ...ReAct improves transparency and reliability by explicit reasoning steps.",
      "logprobs": null,
      "finish_reason": "stop",
      "stop_reason": "<|im_end|>",
      "token_ids": null,
      "prompt_logprobs": null,
      "prompt_token_ids": null
    }
  ],
  "service_tier": null,
  "system_fingerprint": null,
  "usage": {
    "prompt_tokens": 57,
    "total_tokens": 317,
    "completion_tokens": 260,
    "prompt_tokens_details": null
  },
  "kv_transfer_params": null
}

モデルのパフォーマンスをモニタリングする

モデルのパフォーマンスをモニタリングするには、Cloud Monitoring で vLLM ダッシュボードの統合を使用します。このダッシュボードを使用して、トークンのスループット、リクエストレイテンシ、エラー率などの重要なパフォーマンス指標を確認します。

Google Cloud Managed Service for Prometheus を使用してモデルから指標を収集する方法については、Monitoring のドキュメントで vLLM のオブザーバビリティガイダンスをご覧ください。

クリーンアップ

このチュートリアルで使用したリソースについて、Google Cloud アカウントに課金されないようにするには、リソースを含むプロジェクトを削除するか、プロジェクトを維持して個々のリソースを削除します。

このチュートリアルで使用したリソースについて、Cloud 請求先アカウントに課金されないようにするには、リソースを含むプロジェクトを削除するか、プロジェクトを維持して個々のリソースを削除します。

リソースの削除

チュートリアルを完了したら、不要になったリソースを削除します。

vllm-deepseek3-2.yaml ファイルで定義されたデプロイとサービス、および Kubernetes Secret を GKE クラスタから削除するには、次のコマンドを実行します。
```
envsubst < vllm-deepseek3-2.yaml | kubectl delete -f -
kubectl delete secret hf-secret
```
Cloud Storage バケットを削除するには、次のコマンドを実行します。
```
gcloud storage rm --recursive gs://"$GCS_BUCKET"
```

GKE クラスタを削除する手順は次のとおりです。

gcloud container clusters delete "$CLUSTER_NAME" \
    --region="$REGION" \
    --quiet

プロジェクトの削除

注意: プロジェクトを削除すると、次のような影響があります。

プロジェクト内のすべてのものが削除されます。既存のプロジェクトを使用してこのドキュメントのタスクを行った場合、そのプロジェクトを削除すると、プロジェクト内で行った他の作業もすべて削除されます。
カスタムプロジェクト ID が失われます。このプロジェクトを作成したときに、将来使用するカスタムプロジェクト ID を作成した可能性があります。そのプロジェクト ID を使用した URL（例: appspot.com）を保持するには、プロジェクト全体ではなく、プロジェクト内の選択したリソースだけを削除します。

複数のアーキテクチャ、チュートリアル、クイックスタートを実施する予定がある場合は、プロジェクトを再利用すると、プロジェクトの割り当て上限を超えないようにすることができます。

Google Cloud プロジェクトを削除する:

gcloud projects delete PROJECT_ID

次のステップ

AI 最適化 GKE クラスタを管理する