Cloud Run'da vLLM ile Gemma 3'ü sunma

1. Giriş

Büyük dil modelleri (LLM'ler), akıllı uygulamaları oluşturma şeklimizi değiştiriyor. Ancak bu güçlü modelleri gerçek dünyada kullanıma hazırlamak zor olabilir. Bu modellerin çalışması için çok fazla işlem gücü (özellikle grafik kartları) ve aynı anda birçok isteği işlemek için akıllı yöntemler gerekir. Ayrıca, maliyetleri düşük tutmak ve uygulamanızın sorunsuz bir şekilde, gecikmeden çalışmasını sağlamak istiyorsunuz.

Bu Codelab'de bu zorlukların üstesinden nasıl geleceğiniz gösterilecektir. İki temel araç kullanacağız:

1. vLLM: Bunu LLM'ler için süper hızlı bir motor olarak düşünebilirsiniz. Bu sayede modelleriniz çok daha verimli çalışır, aynı anda daha fazla isteği işler ve bellek kullanımı azalır.
2. Google Cloud Run: Google'ın sunucusuz platformudur. Kullanıcı sayısı sıfırdan binlere çıkıp tekrar düşse bile tüm ölçeklendirme işlemlerini sizin için yaptığından uygulamaları dağıtmak için mükemmeldir. En önemlisi, Cloud Run artık GPU'ları destekliyor. Bu da LLM'leri barındırmak için çok önemli.

vLLM ve Cloud Run birlikte çalışarak LLM'lerinizi sunmak için güçlü, esnek ve uygun maliyetli bir yol sunar. Bu kılavuzda, standart bir web API'si olarak kullanılabilen açık bir model dağıtacaksınız.

Neler öğreneceksiniz?

• Yayın için doğru model boyutu ve varyantı nasıl seçilir?
• OpenAI ile uyumlu API uç noktalarına hizmet vermek için vLLM'yi ayarlama
• vLLM sunucusunu Docker ile kapsama alma
• Container görüntünüzü Google Artifact Registry'ye nasıl göndereceğinizi öğrenin.
• Container'ı GPU hızlandırmasıyla Cloud Run'a dağıtma
• Dağıtılan modelinizi test etme

Gerekenler

• Google Cloud Console'a erişmek için Chrome gibi bir tarayıcı
• Güvenilir bir internet bağlantısı
• Faturalandırmanın etkin olduğu bir Google Cloud projesi
• Hugging Face erişim jetonu (Henüz yoksa buradan oluşturabilirsiniz)
• Python, Docker ve komut satırı arayüzü hakkında temel düzeyde bilgi
• Meraklı bir zihin ve öğrenme isteği

2. Başlamadan Önce

Google Cloud projesi oluşturma

Bu codelab için etkin bir faturalandırma hesabına sahip bir Google Cloud projesi gerekir.

• Eğitmen tarafından yönetilen oturumlar için: Bir sınıftaysanız eğitmeniniz size gerekli proje ve fatura bilgilerini sağlar. Kurulumu tamamlamak için eğitmeninizin talimatlarını uygulayın.
• Bağımsız öğrenenler için: Bu işlemi kendi başınıza yapıyorsanız ve mevcut etkin bir faturalandırma hesabınız yoksa kendi ödeme bilgilerinizi kullanarak bir faturalandırma hesabı oluşturmanız gerekir. Yeni bir faturalandırma hesabı oluşturmak ve projeniz için etkinleştirmek üzere Google Cloud Billing belgelerine bakın.

Google Cloud projesi oluşturun

Bu codelab'deki tüm çalışmalarınızı düzenli tutmak ve diğer projelerden ayırmak için yeni bir Google Cloud projesi oluşturarak başlayacaksınız.

Proje oluşturma sayfasını açmak için Yeni Proje Oluştur'u tıklayın.

Proje oluşturma sayfasında gerekli bilgileri girin:

• Proje adı: İstediğiniz adı girebilirsiniz (ör.genai-workshop).
• Konum: Kuruluş Yok olarak bırakın.
• Faturalandırma hesabı: Bu seçenek görünürse "Google Cloud Platform Deneme Sürümü Faturalandırma Hesabı"nı veya isterseniz kendi faturalandırma hesabınızı seçin. Bu seçeneği görmüyorsanız bir sonraki adıma geçebilirsiniz.

Oluşturulan proje kimliğini kopyalayın. Daha sonra bu kimliğe ihtiyacınız olacak.

Her şey doğruysa Oluştur düğmesini tıklayın.

Cloud Shell'i yapılandırma

Cloud Shell, bu codelab için ihtiyacınız olan tüm araçların bulunduğu önceden yapılandırılmış bir ortamdır. Projeniz başarıyla oluşturulduktan sonra Cloud Shell'i ayarlamak için aşağıdaki adımları uygulayın.

Cloud Shell'i başlatma

Cloud Shell'i başlatmak için Cloud Shell'i başlat'ı tıklayın.

Yetkilendirme isteyen bir pop-up gösterilirse Yetkilendir'i tıklayın.

Proje kimliğini ayarlama

replace-with-your-project-id yerine yukarıdaki proje oluşturma adımındaki gerçek proje kimliğinizi yazın. Doğru Proje Kimliği'ni ayarlamak için Cloud Shell terminalinde aşağıdaki komutu çalıştırın.

gcloud config set project replace-with-your-project-id

Artık Cloud Shell terminalinde doğru projenin seçildiğini görebilirsiniz. Seçilen proje kimliği sarı renkle vurgulanır.

Gerekli API'leri etkinleştirme

Cloud Run gibi Google Cloud hizmetlerini kullanmak için öncelikle projenizde ilgili API'leri etkinleştirmeniz gerekir. Bu Codelab için gerekli hizmetleri etkinleştirmek üzere Cloud Shell'de aşağıdaki komutları çalıştırın:

gcloud services enable run.googleapis.com
gcloud services enable cloudbuild.googleapis.com
gcloud services enable secretmanager.googleapis.com
gcloud services enable artifactregistry.googleapis.com

3. Doğru modeli seçme

Hugging Face Hub ve Kaggle gibi web sitelerinde birçok açık model bulabilirsiniz. Bu modellerden birini Google Cloud Run gibi bir hizmette kullanmak istediğinizde, sahip olduğunuz kaynaklara (ör. NVIDIA L4 GPU) uygun olanı seçmeniz gerekir.

Modelin boyutunun yanı sıra neler yapabileceğini de göz önünde bulundurmanız gerektiğini unutmayın. Modellerin hepsi aynı değildir. Her birinin kendine özgü avantajları ve dezavantajları vardır. Örneğin, bazı modeller farklı giriş türlerini (görüntü ve metin gibi; çok formatlı özellikler olarak bilinir) işleyebilirken bazıları aynı anda daha fazla bilgiyi hatırlayıp işleyebilir (daha büyük bağlam pencereleri vardır). Genellikle daha büyük modellerde işlev çağırma ve düşünme gibi daha gelişmiş özellikler bulunur.

İstediğiniz modelin, yayınlama aracı (bu durumda vLLM) tarafından desteklenip desteklenmediğini de kontrol etmeniz önemlidir. vLLM tarafından desteklenen tüm modelleri burada inceleyebilirsiniz.

Şimdi de Google'ın herkese açık en yeni Büyük Dil Modeli (LLM) ailesi olan Gemma 3'ü inceleyelim. Gemma 3, karmaşıklığına göre dört farklı ölçekte sunulur. Bu ölçekler, parametreler ile ölçülür: 1 milyar, 4 milyar, 12 milyar ve 27 milyar.

Bu boyutların her biri için iki ana tür bulunur:

• Temel (önceden eğitilmiş) sürüm: Bu, çok büyük miktarda veriden öğrenmiş olan temel modeldir.
• Talimatlara göre ayarlanmış sürüm: Bu sürüm, belirli talimatları veya komutları daha iyi anlayıp uygulamak için daha da geliştirilmiştir.

Daha büyük modeller (4 milyar, 12 milyar ve 27 milyar parametre) çok formatlıdır. Bu nedenle hem görselleri hem de metinleri anlayıp işleyebilirler. Ancak en küçük 1 milyar parametreli varyant yalnızca metne odaklanır.

Bu Codelab'de 1 milyar parametreli Gemma 3: gemma-3-1b-it modelini kullanacağız. Daha küçük bir model kullanmak, sınırlı kaynaklarla nasıl çalışacağınızı öğrenmenize de yardımcı olur. Bu, maliyetleri düşük tutmak ve uygulamanızın bulutta sorunsuz çalışmasını sağlamak için önemlidir.

4. Ortam Değişkenleri ve Gizli Anahtarlar

Ortam dosyası oluşturma

Devam etmeden önce, bu Codelab boyunca kullanacağınız tüm yapılandırmaları tek bir yerde toplamanız iyi bir uygulama olacaktır. Başlamak için terminalinizi açın ve şu adımları uygulayın:

1. Bu proje için yeni bir klasör oluşturun.
2. Yeni oluşturulan klasöre gidin.
3. Bu klasörde boş bir .env dosyası oluşturun (bu dosya daha sonra ortam değişkenlerinizi içerecektir).

Bu adımları gerçekleştirmek için gereken komut aşağıda verilmiştir:

mkdir vllm-gemma3 && cd vllm-gemma3 && cloudshell edit .env

Not: vim veya nano gibi komut satırı araçlarını kullanmakta zorlanıyorsanız Open Editor (Düzenleyiciyi Aç) düğmesini tıklayarak Cloud Code Düzenleyici'yi kullanabilirsiniz.

.env dosyasını bulamıyorsanız Düzenleyici > Görünüm > Gizli Dosyaları Aç/Kapat seçeneğini etkinleştirmeyi deneyin.

Ardından, aşağıda listelenen değişkenleri kopyalayıp yeni oluşturduğunuz .env dosyasına yapıştırın.

PROJECT_ID=your_project_id
REGION=your_region

MODEL_PROVIDER=google
MODEL_VARIANT=gemma-3-1b-it
MODEL_NAME=${MODEL_PROVIDER}/${MODEL_VARIANT}

AR_REPO_NAME=vllm-gemma3-repo
SERVICE_NAME=${MODEL_VARIANT}-service
IMAGE_NAME=${REGION}-docker.pkg.dev/${PROJECT_ID}/${AR_REPO_NAME}/${SERVICE_NAME}

SERVICE_ACC_NAME=${SERVICE_NAME}-sa
SERVICE_ACC_EMAIL=${SERVICE_ACC_NAME}@${PROJECT_ID}.iam.gserviceaccount.com

Yer tutucu değerleri (your_project_id ve your_region) kendi proje bilgilerinizle değiştirmeyi unutmayın. Örneğin (PROJECT_ID=unique-ai-project ve REGION=us-central1). Cloud Run'da GPU'ları destekleyen bölgelerin listesini buradan inceleyebilirsiniz.

.env dosyası düzenlenip kaydedildikten sonra bu ortam değişkenlerini terminal oturumuna yüklemek için şu komutu yazın:

source .env

Değişkenlerden birini yansıtarak değişkenlerin başarıyla yüklenip yüklenmediğini test edebilirsiniz. Örneğin:

echo $SERVICE_NAME

.env dosyasında atadığınız değerle aynı değeri alırsanız değişkenler başarıyla yüklenir.

Secret Manager'da gizli anahtar depolama

Erişim kodları, kimlik bilgileri ve şifreler gibi hassas veriler için Secret Manager kullanılması önerilir.

Gemma 3 modellerini kullanmadan önce, erişim kısıtlaması olduğu için hükümler ve koşulları onaylamanız gerekir. Şartlar ve koşulları Gamma 3 Model Card On Hugging Face Hub üzerinden onaylayabilirsiniz.

Not: Henüz bir Hugging Face erişim jetonunuz yoksa buradan oluşturabilirsiniz. Bu bilgiye sonraki adımlarda ihtiyacınız olacak.

Hugging Face erişim jetonunu aldıktan sonra Secret Manager sayfasına gidip aşağıdaki talimatları uygulayarak bir gizli anahtar oluşturun.

• Google Cloud Console'a gidin.
• Sol üstteki açılır menü çubuğundan projeyi seçin.
• Arama çubuğunda Secret Manager'ı arayın ve seçenek göründüğünde bu seçeneği tıklayın.

Secret Manager sayfasında:

• +Create Secret (Gizli Anahtar Oluştur) düğmesini tıklayın.
• Aşağıdaki bilgileri doldurun:
• Name (Ad): HF_TOKEN
• Gizli Anahtar Değeri: <your_hf_access_token>
• İşlemi tamamladığınızda Gizli Oluştur düğmesini tıklayın.

Hugging Face erişim jetonunuz artık Google Cloud Secret Manager'da gizli anahtar olarak bulunuyor.

Aşağıdaki komutu terminalde çalıştırarak gizli veriye erişiminizi test edebilirsiniz. Bu komut, gizli veriyi Secret Manager'dan alır:

gcloud secrets versions access latest --secret=HF_TOKEN

Erişim jetonunuzun alınıp terminal penceresinde gösterildiğini görürsünüz.

Cloud Build hizmet hesabına gizli erişim izni verme

Gizli anahtar artık Secret Manager'da güvenli bir şekilde saklandığı için

Bunun için terminalde şu komutları çalıştırın:

# Get the project number
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')

# Grant Cloud Build access to the Hugging Face Token secret
gcloud secrets add-iam-policy-binding HF_TOKEN \
  --member="serviceAccount:${PROJECT_NUMBER}@cloudbuild.gserviceaccount.com" \
  --role="roles/secretmanager.secretAccessor"

5. Hizmet hesabı oluşturma

Üretim ortamında güvenliği artırmak ve erişimi etkili bir şekilde yönetmek için hizmetler, yalnızca belirli görevleri için gerekli izinlerle kesin olarak sınırlandırılmış özel hizmet hesapları altında çalışmalıdır.

Hizmet hesabı oluşturmak için bu komutu çalıştırın

gcloud iam service-accounts create $SERVICE_ACC_NAME --display-name='Cloud Run vLLM Model Serving SA'

Aşağıdaki komut, gerekli izni ekler.

gcloud secrets add-iam-policy-binding HF_TOKEN \
  --member="serviceAccount:${SERVICE_ACC_EMAIL}" \
  --role="roles/secretmanager.secretAccessor"

6. Artifact Registry'de görüntü oluşturma

Bu adımda, model ağırlıklarını ve önceden yüklenmiş bir vLLM'yi içeren bir Docker görüntüsü oluşturulur.

1. Artifact Registry'de Docker deposu oluşturma

Oluşturulan görüntülerinizi göndermek için Artifact Registry'de bir Docker deposu oluşturalım. Terminalde aşağıdaki komutu çalıştırın:

gcloud artifacts repositories create ${AR_REPO_NAME} \
  --repository-format docker \
  --location ${REGION}

2. Modeli saklama

GPU ile ilgili en iyi uygulamalar dokümanına göre, makine öğrenimi modellerini container resimlerinin içinde depolayabilir veya Cloud Storage'dan yüklemeyi optimize edebilirsiniz.

Elbette her yaklaşımın kendine özgü avantajları ve dezavantajları vardır. Bu özellikler hakkında daha fazla bilgi edinmek için dokümanları okuyabilirsiniz. Basitlik için modeli yalnızca container görüntüsünde depolayacağız. Bu işlemi bir sonraki oturumda yapacaksınız.

3. Docker dosyası oluşturma

Dockerfile adlı bir dosya oluşturun ve aşağıdaki içeriği bu dosyaya kopyalayın:

FROM vllm/vllm-openai:v0.16.0

ARG MODEL_NAME
ARG HF_TOKEN

ENV HF_HOME=/model-cache
ENV MODEL_NAME=${MODEL_NAME}

# Use the HF_TOKEN argument to log in and download the model
RUN huggingface-cli login --token ${HF_TOKEN} && \
    huggingface-cli download ${MODEL_NAME}

# Prevent vLLM from trying to download the model again at runtime
ENV HF_HUB_OFFLINE=1

EXPOSE 8080

ENTRYPOINT python3 -m vllm.entrypoints.openai.api_server \
    --port ${PORT:-8080} \
    --model ${MODEL_NAME} \
    --gpu-memory-utilization 0.90 \
    ${MAX_MODEL_LEN:+--max-model-len "$MAX_MODEL_LEN"}

4. Dağıtım için bir YAML dosyası oluşturma

Ardından, aynı dizinde cloudbuild.yaml adlı bir dosya oluşturun. Bu dosya, Cloud Build'in izleyeceği adımları tanımlar. Aşağıdaki içeriği kopyalayıp cloudbuild.yaml dosyasına yapıştırın:

steps:
- name: 'gcr.io/cloud-builders/docker'
  entrypoint: 'bash'
  args:
  - '-c'
  - |
    docker build \
      --build-arg MODEL_NAME=${_MODEL_NAME} \
      --build-arg HF_TOKEN=$$HF_TOKEN_SECRET \
      -t ${_IMAGE_NAME} .
  secretEnv: ['HF_TOKEN_SECRET']

images:
- '${_IMAGE_NAME}'

availableSecrets:
  secretManager:
  - versionName: projects/${PROJECT_ID}/secrets/HF_TOKEN/versions/latest
    env: 'HF_TOKEN_SECRET'

5. Derlemeyi Cloud Build'e gönderme

Aşağıdaki kodu kopyalayıp yapıştırın ve terminalde çalıştırın:

gcloud builds submit . \
    --config=cloudbuild.yaml \
    --region=${REGION} \
    --substitutions=_MODEL_NAME=${MODEL_NAME},_IMAGE_NAME=${IMAGE_NAME}

Bu komut, kodunuzu (Dockerfile ve cloudbuild.yaml) yükler, kabuk değişkenlerinizi yerine koyma olarak iletir (_MODEL_NAME ve _IMAGE_NAME) ve derlemeyi başlatır.

Cloud Build artık cloudbuild.yaml içinde tanımlanan adımları yürütecek. Günlükleri terminalinizde veya Cloud Console'da derleme ayrıntılarının bağlantısını tıklayarak takip edebilirsiniz. İşlem tamamlandığında, container görüntüsü Artifact Registry deponuzda dağıtıma hazır şekilde bulunur.

6. Cloud Run'a dağıtma

Artık hizmeti Cloud Run'a dağıtmaya hazırsınız. Terminalde şu komutu çalıştırın:

gcloud run deploy ${SERVICE_NAME} \
  --image ${IMAGE_NAME} \
  --region ${REGION} \
  --service-account ${SERVICE_ACC_EMAIL} \
  --gpu 1 \
  --gpu-type nvidia-l4 \
  --cpu 4 \
  --memory 16Gi \
  --max-instances 3 \
  --concurrency 80 \
  --no-allow-unauthenticated

Not: Model ağırlıkları doğrudan kapsayıcıya entegre edildiğinden, görüntünün oluşturulup gönderilmesi yaklaşık 30 dakika sürer. Ağırlıkları bu şekilde yerleştirerek, genellikle Cloud Run hizmetlerini başlatmayla ilişkili olan uzun soğuk başlatma sürelerini önleyebiliriz.

7. Hizmeti test etme

Hizmete localhost'ta çalışırken erişebilmek için terminalde aşağıdaki komutu çalıştırarak bir proxy oluşturun:

gcloud run services proxy ${SERVICE_NAME} --region ${REGION}

Bağlantıyı test etmek için yeni bir terminal penceresinde terminalde şu curl komutunu çalıştırın:

curl -X POST http://localhost:8080/v1/completions \
-H "Authorization: Bearer $(gcloud auth print-identity-token)" \
-H "Content-Type: application/json" \
-d '{
  "model": "google/gemma-3-1b-it",
  "prompt": "Cloud Run is a ",
  "max_tokens": 128,
  "temperature": 0.90
}'

Aşağıdakine benzer bir çıkış görürseniz:

{"id":"cmpl-e96d05d2893d42939c1780d44233defa","object":"text_completion","created":1746870778,"model":"google/gemma-3-1b-it","choices":[{"index":0,"text":"100% managed Kubernetes service. It's a great option for many use cases.\n\nHere's a breakdown of key features and considerations:\n\n* **Managed Kubernetes:**  This means Google handles the underlying infrastructure, including scaling, patching, and maintenance.  You don't need to worry about managing Kubernetes clusters.\n* **Serverless:**  You only pay for the compute time your application actually uses.  No charges when your code isn't running.\n* **Scalability:**  Cloud Run automatically scales your application based on demand. You can easily scale up or down to handle fluctuating traffic.\n*","logprobs":null,"finish_reason":"length","stop_reason":null,"prompt_logprobs":null}],"usage":{"prompt_tokens":6,"total_tokens":134,"completion_tokens":128,"prompt_tokens_details":null}}

8. Sonuç

Tebrikler! Bu Codelab'i başarıyla tamamladınız. Öğrendikleriniz:

• Hedef dağıtım için uygun bir model boyutu seçin.
• OpenAI ile uyumlu bir API sunmak için vLLM'yi ayarlayın.
• Docker ile vLLM sunucusunu ve model ağırlıklarını güvenli bir şekilde kapsülleyin.
• Google Artifact Registry'ye bir container görüntüsü aktarın.
• GPU hızlandırmalı bir hizmeti Cloud Run'a dağıtın.
• Kimliği doğrulanmış, dağıtılmış bir modeli test etme

Öğrenme yolculuğunuza devam etmek için Llama, Mistral veya Qwen gibi diğer heyecan verici modelleri dağıtmayı deneyebilirsiniz.

9. Temizleme

Gelecekte ücretlendirilmemek için oluşturduğunuz kaynakları silmeniz önemlidir. Projenizi temizlemek için aşağıdaki komutları çalıştırın.

1. Cloud Run hizmetini silin:

gcloud run services delete ${SERVICE_NAME} --region=${REGION} --quiet

2. Artifact Registry deposunu silin:

gcloud artifacts repositories delete ${AR_REPO_NAME} --location=${REGION} --quiet

3. Hizmet hesabını silin:

gcloud iam service-accounts delete ${SERVICE_ACC_EMAIL} --quiet

4. Gizli anahtarı Secret Manager'dan silin:

gcloud secrets delete HF_TOKEN --quiet