Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

GKE에서 vLLM을 사용하여 DeepSeek-V3.1-Base로 추론 실행

이 튜토리얼에서는 vLLM 프레임워크를 사용하여 DeepSeek-V3.1-Base 언어 모델을 배포하고 서빙하는 방법을 보여줍니다. Google Kubernetes Engine (GKE) Enterprise 버전 Autopilot 클러스터에 이 모델을 배포하고 8개의 B200 GPU가 있는 단일 A4 가상 머신(VM)을 사용합니다.

이 튜토리얼은 추론 워크로드를 처리하기 위해 Kubernetes 컨테이너 조정 기능을 사용하는 데 관심이 있는 머신러닝 (ML) 엔지니어, 플랫폼 관리자 및 운영자, 데이터 및 AI 전문가를 대상으로 합니다.

목표

Hugging Face를 사용하여 DeepSeek-V3.1-Base에 액세스하세요.
환경을 준비합니다.
Autopilot 모드로 GKE 클러스터를 만듭니다.
Hugging Face 사용자 인증 정보용 Kubernetes 보안 비밀을 만듭니다.
Cloud Storage 버킷을 만듭니다.
모델을 Cloud Storage 버킷에 다운로드합니다.
GKE 클러스터에 vLLM 컨테이너를 배포합니다.
curl을 사용하여 DeepSeek-V3.1-Base와 상호작용합니다.
삭제

비용

이 튜토리얼에서는 비용이 청구될 수 있는 Google Cloud구성요소를 사용합니다.

프로젝트 사용량을 기준으로 예상 비용을 산출하려면 가격 계산기를 사용합니다.

시작하기 전에

Google Cloud CLI를 설치합니다.
gcloud CLI에서 제휴 ID를 사용하도록 구성합니다.

자세한 내용은 제휴 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)을 통해 이 권한이 이미 있을 수 있습니다. 그렇지 않으면 서비스 사용량 관리자 역할 (roles/serviceusage.serviceUsageAdmin)을 통해 이 권한을 얻을 수 있습니다. 역할을 부여하는 방법 알아보기
```
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: 사용자 계정 예를 보려면 IAM 정책에서 직원 풀 사용자 표현을 참고하세요.
- ROLE: 사용자 계정에 부여할 IAM 역할입니다.
Hugging Face 계정에 로그인하거나 계정을 만듭니다.

Hugging Face를 사용하여 DeepSeek에 액세스

Hugging Face를 사용하여 DeepSeek에 액세스하려면 다음 단계를 따르세요.

Hugging Face에 로그인하고 DeepSeek-V3.1-Base 모델을 살펴봅니다.
Hugging Face read 액세스 토큰을 만듭니다.
read access 토큰 값을 복사하여 저장합니다. 이 주소는 이 튜토리얼의 뒷부분에서 사용됩니다.

개발 환경 준비

환경을 준비하려면 기본 환경 변수를 설정하세요.

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 클러스터를 만드는 데 사용할 예약의 URL입니다. 예약이 있는 프로젝트에 따라 다음 값 중 하나를 지정합니다.
- 예약이 프로젝트에 있습니다. RESERVATION_NAME
- 예약이 다른 프로젝트에 있고 내 프로젝트에서 예약을 사용할 수 있는 경우: projects/RESERVATION_PROJECT_ID/reservations/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 보안 비밀 만들기

Hugging Face 사용자 인증 정보용 Kubernetes 보안 비밀을 만들려면 다음 단계를 따르세요.

GKE 클러스터와 통신하도록 kubectl을 구성합니다.

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

Hugging Face 토큰을 저장할 Kubernetes 보안 비밀을 만듭니다.

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

Cloud Storage 버킷 만들기

새 버킷을 사용하여 모델을 저장하려면 다음을 실행하세요.

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 버킷을 사용하려면 이 단계를 건너뛰어도 됩니다. 하지만 버킷이 클러스터와 동일한 리전에 있고 서비스 계정에 필요한 write 권한이 있는지 확인해야 합니다.

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-1"
          mkdir -p "$LOCAL_DIR"

          echo "Downloading model from HF to local SSD using parallel workers..."
          hf download deepseek-ai/DeepSeek-V3.1-Base \
            --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-1" --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에서 Google Cloud Storage 버킷으로 DeepSeek-V3.1-Base 모델 가중치를 다운로드합니다. 다운로드를 완료하는 데 약 40분이 걸립니다. 다운로드가 완료되면 다음 섹션으로 진행하여 모델 배포를 시작합니다.
작업을 삭제하려면 다음 명령어를 실행합니다.
```
kubectl delete job deepseek-download-job
```

GKE 클러스터에 vLLM 컨테이너 배포

모델을 Cloud Storage 버킷에 다운로드한 후 다음 단계를 완료하여 vLLM 컨테이너를 GKE 클러스터에 배포합니다.

선택한 vLLM 배포를 사용하여 vllm-deepseek3-1-base.yaml 파일을 만듭니다.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: deepseek3-1-deploy
spec:
  replicas: 1
  selector:
    matchLabels:
      app: deepseek
  template:
    metadata:
      labels:
        app: deepseek
        ai.gke.io/model: deepseek-v3-1-base
        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:20250819_0916_RC01
        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-1
        - --tensor-parallel-size=8
        - --host=0.0.0.0
        - --port=8000
        - --max-model-len=8192
        - --max-num-seqs=4
        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

GKE 클러스터에 vllm-deepseek3-1-base.yaml 파일을 적용합니다.
```
envsubst < vllm-deepseek3-1-base.yaml | kubectl apply -f -
```
완료 상태를 확인하려면 다음 명령어를 실행합니다.
```
kubectl wait \
  --for=condition=Available \
  --timeout=7200s deployment/deepseek3-1-deploy
```
--timeout 플래그를 사용하면 명령어가 지정된 기간 동안 배포를 모니터링할 수 있습니다.

curl을 사용하여 DeepSeek-V3.1-Base와 상호작용

배포한 DeepSeek-V3.1-Base 모델을 확인하려면 다음 단계를 따르세요.

DeepSeek-V3.1-Base로의 포트 전달을 설정합니다.

kubectl port-forward service/deepseek-service 8000:8000

새 터미널 창을 엽니다. 그런 다음 curl을 사용하여 모델과 채팅할 수 있습니다.

curl http://127.0.0.1:8000/v1/chat/completions \
-X POST \
-H "Content-Type: application/json" \
-d '{
  "model": "deepseek-ai/DeepSeek-V3.1-Base",
  "messages": [
    {
      "role": "user",
      "content": "Describe how generative AI works in one short and easy to understand sentence"
    }
  ],
"stream":false
}' | jq .

표시되는 출력은 다음과 비슷합니다.

{
  "id": "chatcmpl-1a47172070544a5d83199ed5548befca",
  "object": "chat.completion",
  "created": 1755891024,
  "model": "deepseek-ai/DeepSeek-V3.1-Base",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "\nGenerative AI uses patterns from existing data to create new, similar content, like text, images, or music.\n",
        "refusal": null,
        "annotations": null,
        "audio": null,
        "function_call": null,
        "tool_calls": [],
        "reasoning_content": null
      },
      "logprobs": null,
      "finish_reason": "stop",
      "stop_reason": null
    }
  ],
  "service_tier": null,
  "system_fingerprint": null,
  "usage": {
    "prompt_tokens": 17,
    "total_tokens": 42,
    "completion_tokens": 25,
    "prompt_tokens_details": null
  },
  "prompt_logprobs": null,
  "kv_transfer_params": null
}

모델의 성능 관찰

모델의 성능을 모니터링하려면 Cloud Monitoring에 통합된 vLLM 대시보드를 사용하면 됩니다. 이 대시보드를 사용하면 토큰 처리량, 네트워크 지연 시간, 오류율과 같은 모델의 중요한 성능 측정항목을 확인할 수 있습니다. 자세한 내용은 Monitoring 문서의 vLLM을 참고하세요.

삭제

이 튜토리얼에서 사용된 리소스 비용이 Google Cloud 계정에 청구되지 않도록 하려면 리소스가 포함된 프로젝트를 삭제하거나 프로젝트를 유지하고 개별 리소스를 삭제하세요.

리소스 삭제

튜토리얼을 완료한 후에는 더 이상 필요하지 않은 리소스를 삭제합니다.

vllm-deepseek3-1-base.yaml 파일에 정의된 배포 및 서비스와 Kubernetes 보안 비밀을 GKE 클러스터에서 삭제하려면 다음 명령어를 실행합니다.
```
envsubst < vllm-deepseek3-1-base.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를 만들었을 수 있습니다. appspot.com URL과 같이 프로젝트 ID를 사용하는 URL을 보존하려면 전체 프로젝트를 삭제하는 대신 프로젝트 내에서 선택한 리소스만 삭제합니다.

여러 아키텍처, 튜토리얼 또는 빠른 시작을 살펴보려는 경우 프로젝트를 재사용하면 프로젝트 할당량 한도 초과를 방지할 수 있습니다.

Google Cloud 프로젝트를 삭제합니다.

gcloud projects delete PROJECT_ID

다음 단계

AI에 최적화된 GKE 클러스터 관리