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

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

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

목표

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

비용

이 가이드에서는 비용이 청구될 수 있는 다음과 같은 Google Cloud 구성요소를 사용합니다.

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

시작하기 전에

계정에 로그인합니다. Google Cloud 를 처음 사용하는 경우 Google Cloud 계정을 만들어 실제 시나리오에서 제품이 어떻게 작동하는지 평가하세요. 신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $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를 사용 설정하려면 역할 (roles/serviceusage.serviceUsageAdmin)이 포함된 서비스 사용량 관리자 IAM serviceusage.services.enable 권한이 필요합니다. 역할 부여 방법 알아보기.

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에 액세스

Hugging Face를 사용하여 DeepSeek에 액세스하려면 다음을 수행합니다.

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

개발 환경 준비

개발 환경을 준비하려면 기본 환경 변수를 설정합니다.

gcloud config set project PROJECT_ID
gcloud config set billing/quota_project PROJECT_ID
export PROJECT_ID=$(gcloud config get project)
export RESERVATION_URL=RESERVATION_URL
export REGION=REGION
export CLUSTER_NAME=CLUSTER_NAME
export HUGGING_FACE_TOKEN=HUGGING_FACE_TOKEN
export NETWORK=NETWORK_NAME
export SUBNETWORK=SUBNETWORK_NAME

다음을 바꿉니다.

PROJECT_ID: GKE 클러스터를 만들려는 프로젝트의 ID입니다. Google Cloud
RESERVATION_URL: GKE 클러스터를 만드는 데 사용할 예약의 URL입니다. 예약이 있는 프로젝트를 기반으로 다음 값 중 하나를 지정합니다.
- 예약이 프로젝트에 있습니다. RESERVATION_NAME
- 예약이 다른 프로젝트에 있고 프로젝트에서 예약을 사용할 수 있습니다. 예약: projects/RESERVATION_PROJECT_ID/reservations/RESERVATION_NAME
REGION: GKE 클러스터를 만들려는 리전입니다. 예약이 있는 리전에서만 클러스터를 만들 수 있습니다.
CLUSTER_NAME: 만들 GKE 클러스터의 이름입니다.
HUGGING_FACE_TOKEN: 이전 섹션에서 만든 Hugging Face 액세스 토큰입니다.
NETWORK_NAME: GKE 클러스터에서 사용하는 네트워크입니다. 다음 값 중 하나를 지정합니다.
- 커스텀 네트워크를 만든 경우 네트워크 이름을 지정합니다.
- 그렇지 않은 경우 default를 지정합니다.
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 클러스터를 만드는 데 시간이 걸릴 수 있습니다. 클러스터 생성을 완료했는지 확인하려면 콘솔에서 Kubernetes 클러스터 로 이동합니다. Google Cloud Google Cloud

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 -

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
    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=$(MODEL_ID)
        - --tensor-parallel-size=8
        - --host=0.0.0.0
        - --port=8000
        - --max-model-len=8192
        - --max-num-seqs=4
        env:
        - name: MODEL_ID
          value: deepseek-ai/DeepSeek-V3.1-Base
        - name: HUGGING_FACE_HUB_TOKEN
          valueFrom:
            secretKeyRef:
              name: hf-secret
              key: hf_token
        volumeMounts:
        - mountPath: /dev/shm
          name: dshm
        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
      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-1-base.yaml 파일을 GKE 클러스터에 적용합니다.
```
kubectl apply -f vllm-deepseek3-1-base.yaml
```
배포 프로세스 중에 컨테이너는 Hugging Face에서 deepseek-ai/DeepSeek-V3.1-Base 모델을 다운로드해야 합니다. 따라서 컨테이너 배포를 완료하는 데 최대 30분이 걸릴 수 있습니다.
완료 상태를 보려면 다음 명령어를 실행합니다.
```
kubectl wait \
--for=condition=Available \
--timeout=1800s deployment/deepseek3-1-deploy
```
--timeout=1800s 플래그를 사용하면 명령어가 최대 30분 동안 배포를 모니터링할 수 있습니다.

curl을 사용하여 DeepSeek V3.1과 상호작용

배포한 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
}'

표시되는 출력은 다음과 유사합니다.

{
  "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 대시보드를 사용하면 됩니다. 이 대시보드를 사용하면 토큰 처리량, 네트워크 지연 시간, 오류율과 같은 모델의 주요 성능 측정항목을 확인할 수 있습니다. 자세한 내용은 vLLM 문서의 vLLM을 참고하세요.

삭제

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

프로젝트 삭제

주의: 프로젝트를 삭제하면 다음과 같은 효과가 발생합니다:

프로젝트의 모든 항목이 삭제됩니다. 이 문서의 태스크에 기존 프로젝트를 사용한 경우 프로젝트를 삭제하면 프로젝트에서 수행한 다른 작업도 삭제됩니다.
커스텀 프로젝트 ID가 손실됩니다. 이 프로젝트를 만들 때 앞으로 사용할 커스텀 프로젝트 ID를 만들었을 수 있습니다. appspot.com URL과 같이 프로젝트 ID를 사용하는 URL을 보존하려면 전체 프로젝트를 삭제하는 대신 프로젝트 내에서 선택한 리소스만 삭제합니다.

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

프로젝트 삭제: Google Cloud

gcloud projects delete PROJECT_ID

리소스 삭제

vllm-deepseek3-1-base.yaml 파일의 배포 및 서비스와 GKE 클러스터의 Kubernetes 보안 비밀을 삭제하려면 다음을 실행합니다.
```
kubectl delete -f vllm-deepseek3-1-base.yaml
kubectl delete secret hf-secret
```

GKE 클러스터를 삭제하려면 다음을 수행합니다.

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

다음 단계

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