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 çok fazla işlem gücüne (özellikle grafik kartları) ve aynı anda birçok isteği işlemek için akıllı yöntemlere ihtiyacı vardır. 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:
- 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.
- Google Cloud Run: Google'ın sunucusuz platformudur. Sıfır kullanıcıdan binlerce kullanıcıya ve tekrar sıfır kullanıcıya kadar 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 bir özellik.
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.
Öğrenecekleriniz**:**
- Yayın için doğru model boyutu ve çeşidi nasıl seçilir?
- OpenAI ile uyumlu API uç noktalarına hizmet vermek için vLLM'yi ayarlama
- vLLM sunucusunu Docker ile kapsülleme
- Container görüntünüzü Google Artifact Registry'ye nasıl göndereceğinizi öğrenin.
- GPU hızlandırma ile container'ı Cloud Run'a dağıtma
- Dağıtılan modelinizi test etme
İhtiyacınız olanlar**:**
- 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 yeni bir proje oluşturmanız ve deneme faturalandırma hesabını etkinleştirmeniz gerekir. Başlamak için lütfen aşağıdaki adımları uygulayın.
- (Ctrl + Üst Karakter + N veya Cmd + Üst Karakter + N) tuşlarına basarak gizli pencereler açın.
- Gizli pencereden bu ödeme portalına gidin.
- Kişisel Gmail hesabınızla giriş yapın ve deneme faturalandırma hesabı edinin.
- Kurulumu tamamlamak için bu sunumdaki talimatları uygulayın.
Cloud Shell'i yapılandırma
Şimdi de doğrudan Google Cloud Console'da kullanabileceğiniz pratik bir komut satırı arayüzü olan Cloud Shell'i ayarlayalım.
Cloud Shell'i başlatma
Google Cloud Console'unuzun sağ üst köşesinde terminale benzeyen bir simge (>_) görürsünüz. Cloud Shell'i etkinleştirmek için bu simgeyi tıklayın.
Erişim Yetkisi Ver
İstenirse Cloud Shell'e Google Cloud projenizle etkileşim kurması için gerekli izinleri vermek üzere Yetkilendir'i tıklayın.
Proje kimliğini doğrulama
Terminalinizdeki Project ID simgesine bakın. Aşağıdaki resimde gösterildiği gibi sarı renkte yazılır. Bu kimliğin, projeyi oluştururken kaydettiğiniz kimlikle aynı olduğundan emin olun.
Project ID terminale doğru şekilde yansıtılıyorsa Gerekli API'leri etkinleştirin adımına geçin.
Doğru proje kimliği (gerekirse)
Project ID yanlışsa veya tamamen görünmüyorsa düzeltmek için bu komutu kullanın. Komutu yürütmeden önce your-project-id metnini doğru Project ID ile değiştirdiğinizden emin olun.
gcloud config set project your-project-id
Gerekli API'leri etkinleştirme
Cloud Run gibi Google Cloud hizmetlerini kullanmak için önce 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 (ör. resimler ve metinler, çok formatlı özellikler olarak bilinir) işleyebilirken bazıları daha fazla bilgiyi aynı anda hatırlayıp işleyebilir (daha büyük bağlam pencereleri vardır). Daha büyük modellerde genellikle işlev çağrısı ve düşünme gibi daha gelişmiş özellikler bulunur.
İstediğiniz modelin, yayınlama aracı (bu örnekte 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 olarak sunulan en yeni Büyük Dil Modeli (LLM) ailesi 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 varyant olan 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:
- Bu proje için yeni bir klasör oluşturun.
- Yeni oluşturulan klasöre gidin.
- Bu klasörde boş bir .env dosyası oluşturun (bu dosya daha sonra ortam değişkenlerinizi içerecek).
Bu adımları uygulamak için gereken komut aşağıda verilmiştir:
mkdir vllm-gemma3
cd vllm-gemma3
touch .env
Ardından, aşağıda listelenen değişkenleri kopyalayıp yeni oluşturduğunuz .env dosyasına yapıştırın. 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)
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
.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 dahil olmak üzere tüm hassas veriler için Secret Manager kullanılması önerilir.
Gemma 3 modellerini kullanmadan önce, erişim kısıtlaması nedeniyle hüküm ve koşulları onaylamanız gerekir. Gamma3 Model Card On Hugging Face Hub adresine gidip hükümler ve koşulları kabul edin.
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 şunları yapabilirsiniz:
- +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 Dizi Oluştur düğmesini tıklayın.
Hugging Face erişim jetonunuz artık Google Cloud Secret Manager'da gizli olarak bulunuyor.
Aşağıdaki komutu terminalde çalıştırarak gizli erişiminizi test edebilirsiniz. Bu komut, gizliyi 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.
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 sınırlı olan ö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 resim 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 en iyi uygulamaları dokümanına göre, makine öğrenimi modellerini container resimlerinin içinde saklayabilir 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.
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.9.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}
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. cloudbuild.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önderin
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, dağıtıma hazır olan container görüntüsü Artifact Registry deponuzda kullanılabilir.
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. Secret Manager'daki gizli anahtarı silin:
gcloud secrets delete HF_TOKEN --quiet