vLLM Cloud Run 프로젝트

이 프로젝트는 Google Cloud Run의 GPU 기능을 사용하여 vLLM 기반의 LLM 추론 서비스를 배포하는 것을 목표로 합니다.

📋 프로젝트 개요

• 목적: Cloud Run GPU에서 vLLM을 사용하여 LLM 추론 서비스 실행
• 모델: Google의 Gemma 2 2B (기본값, 변경 가능)
• API: OpenAI 호환 API 제공
• 참고 자료: Google Codelabs - vLLM 및 Cloud Run GPU

🏗️ 프로젝트 구조

vLLM-cloud-run/
├── main.py              # vLLM 서버 애플리케이션 코드
├── requirements.txt     # Python 의존성 패키지
├── Dockerfile           # Docker 이미지 빌드 설정
├── cloudbuild.yaml      # Cloud Build 설정 파일
├── setup.sh             # 초기 설정 스크립트
├── deploy.sh            # 배포 스크립트
├── test-local.sh        # 로컬 테스트 스크립트
└── README.md            # 프로젝트 문서

🚀 시작하기

사전 요구사항

1. Google Cloud 계정 및 프로젝트

   • GCP 프로젝트가 생성되어 있어야 합니다
   • Cloud Run, Cloud Build, Secret Manager, Artifact Registry API가 활성화되어 있어야 합니다

2. Hugging Face 계정 및 토큰

   • Hugging Face 계정 생성
   • Gemma 2 모델 라이선스 동의: https://huggingface.co/google/gemma-2-2b-it
   • Access Token 생성: https://huggingface.co/settings/tokens

3. 로컬 환경

   • gcloud CLI 설치 및 인증 완료
   • docker 설치 (로컬 테스트용)

단계별 가이드

1단계: 환경 변수 설정

터미널에서 다음 환경 변수를 설정합니다:

export PROJECT_ID=your-gcp-project-id
export HF_TOKEN=your-huggingface-token
export REGION=europe-west1  # 선택사항, 기본값: europe-west1
export SERVICE_NAME=vllm-gemma-2-2b-it  # 선택사항

2단계: 초기 설정 실행

프로젝트를 처음 설정할 때 한 번만 실행합니다:

chmod +x setup.sh
./setup.sh

이 스크립트는 다음 작업을 수행합니다:

• 필요한 Google Cloud API 활성화
• 서비스 계정 생성 및 권한 부여
• Secret Manager에 Hugging Face 토큰 저장
• Artifact Registry 리포지토리 생성

3단계: 서비스 배포

Cloud Run에 서비스를 배포합니다:

chmod +x deploy.sh
./deploy.sh

이 스크립트는 다음 작업을 수행합니다:

• Docker 이미지 빌드 (Cloud Build 사용)
• Artifact Registry에 이미지 푸시
• Cloud Run에 서비스 배포 (GPU 포함)

4단계: 서비스 테스트

배포가 완료되면 서비스를 테스트할 수 있습니다:

# 서비스 URL 가져오기
SERVICE_URL=$(gcloud run services describe vllm-gemma-2-2b-it \
    --region europe-west1 \
    --format 'value(status.url)')

# API 호출 테스트
curl -X POST $SERVICE_URL/v1/completions \
  -H "Authorization: bearer $(gcloud auth print-identity-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemma-2-2b-it",
    "prompt": "Cloud Run is a",
    "max_tokens": 128,
    "temperature": 0.90
  }'

🧪 로컬 테스트

로컬에서 Docker를 사용하여 테스트할 수 있습니다 (GPU가 있는 경우):

chmod +x test-local.sh
./test-local.sh

주의: 로컬 테스트는 GPU가 필요하며, CPU 모드는 매우 느립니다.

📁 파일 설명

main.py

vLLM 서버의 메인 애플리케이션 코드입니다. OpenAI 호환 API를 제공하는 FastAPI 서버를 실행합니다.

주요 기능:

• vLLM 엔진 초기화
• OpenAI 호환 API 엔드포인트 제공
• 환경 변수를 통한 설정 관리

Dockerfile

Docker 이미지를 빌드하기 위한 설정 파일입니다.

주요 내용:

• Python 3.10 베이스 이미지 사용
• 필요한 시스템 패키지 설치
• Python 의존성 설치
• 애플리케이션 코드 복사 및 실행 설정

cloudbuild.yaml

Cloud Build를 사용한 자동 빌드 및 배포 설정 파일입니다.

주요 단계:

1. Docker 이미지 빌드
2. Artifact Registry에 이미지 푸시
3. Cloud Run에 서비스 배포

setup.sh

프로젝트 초기 설정을 자동화하는 스크립트입니다.

수행 작업:

• API 활성화
• 서비스 계정 생성 및 권한 부여
• Secret Manager 설정
• Artifact Registry 리포지토리 생성

deploy.sh

서비스를 Cloud Run에 배포하는 스크립트입니다.

수행 작업:

• Cloud Build를 통한 이미지 빌드 및 배포
• 서비스 URL 확인 및 테스트 명령어 제공

⚙️ 환경 변수

필수 환경 변수

• PROJECT_ID: Google Cloud 프로젝트 ID
• HF_TOKEN: Hugging Face 액세스 토큰

선택적 환경 변수

• REGION: Cloud Run 리전 (기본값: europe-west1)
• SERVICE_NAME: 서비스 이름 (기본값: vllm-gemma-2-2b-it)
• MODEL_NAME: 사용할 모델 이름 (기본값: google/gemma-2-2b-it)
• AR_REPO_NAME: Artifact Registry 리포지토리 이름 (기본값: vllm-gemma-2-2b-it-repo)

🔧 문제 해결

모델 다운로드 실패

• Hugging Face 토큰이 올바르게 설정되었는지 확인
• 모델 라이선스에 동의했는지 확인
• Secret Manager에 토큰이 올바르게 저장되었는지 확인

GPU 할당 실패

• Cloud Run GPU 할당량이 있는지 확인
• 리전에 GPU가 사용 가능한지 확인
• 서비스 계정에 필요한 권한이 있는지 확인

빌드 실패

• Cloud Build API가 활성화되었는지 확인
• Artifact Registry 리포지토리가 생성되었는지 확인
• Dockerfile의 문법이 올바른지 확인

📚 참고 자료

• Google Codelabs - vLLM 및 Cloud Run GPU
• vLLM 문서
• Cloud Run 문서
• Gemma 2 모델

🗑️ 리소스 정리

프로젝트를 삭제하려면:

# Cloud Run 서비스 삭제
gcloud run services delete vllm-gemma-2-2b-it --region europe-west1

# 서비스 계정 삭제
gcloud iam service-accounts delete vllm-gemma-2-2b-it@$PROJECT_ID.iam.gserviceaccount.com

# Secret 삭제
gcloud secrets delete HF_TOKEN

# Artifact Registry 리포지토리 삭제
gcloud artifacts repositories delete vllm-gemma-2-2b-it-repo \
    --location=europe-west1

📝 라이선스

이 프로젝트는 Google Codelabs의 튜토리얼을 기반으로 합니다.