Cloud Run Jobs'ı kullanarak LLM'de ince ayar yapma

1. Giriş

Genel Bakış

Bu codelab'de, Gemma 3 modelini ince ayarlamak için Cloud Run işlerini kullanacak, ardından vLLM kullanarak sonucu Cloud Run'da sunacaksınız.

Yapacaklarınız

KomeijiForce/Text2Emoji veri kümesini kullanarak belirli bir ifadeye belirli bir sonuçla yanıt verecek bir model eğitin. Bu veri kümesi, EmojiLM: Modeling the New Emoji Language (EmojiLM: Yeni Emoji Dilini Modelleme) kapsamında oluşturulmuştur.

Eğitimden sonra model, "Emojiye çevir: " ön ekiyle başlayan bir cümleye, o cümleye karşılık gelen bir dizi emoji ile yanıt verir.

Neler öğreneceksiniz?

• Cloud Run Jobs GPU kullanarak ince ayar yapma
• vLLM ile Cloud Run kullanarak model sunma
• Modelin daha hızlı yüklenmesi ve sunulması için GPU işinde doğrudan VPC yapılandırması kullanma

2. Başlamadan önce

API'leri etkinleştir

Bu codelab'i kullanmaya başlamadan önce aşağıdaki API'leri etkinleştirin:

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

GPU kotası

Kota isteme hakkında bilgi edinmek için GPU kotası dokümanlarını inceleyin.

"GPU kullanma kotanız yok" gibi bir hatayla karşılaşırsanız g.co/cloudrun/gpu-quota adresinden kotanızı onaylayın.

Not: Yeni bir proje kullanıyorsanız API'nin etkinleştirilmesi ile kotaların kota sayfasında görünmesi arasında birkaç dakika geçebilir.

Hugging Face

Bu codelab'de Hugging Face'te barındırılan bir model kullanılır. Bu modeli edinmek için "Okuma" izniyle Hugging Face kullanıcı erişim jetonu isteğinde bulunun. Bunu daha sonra YOUR_HF_TOKEN olarak referans alacaksınız.

gemma-3-1b-it modelini kullanmak için kullanım şartlarını kabul etmeniz gerekir.

3. Kurulum ve Gereksinimler

Aşağıdaki kaynakları ayarlayın:

• IAM hizmet hesabı ve ilişkili IAM izinleri,
• Hugging Face jetonunuzu depolamak için Secret Manager gizli anahtarı,
• İnce ayarlı modelinizi depolamak için Cloud Storage paketi ve
• Modelinizi ince ayarlamak için oluşturacağınız görüntüyü depolayacak Artifact Registry deposu.

1. Bu codelab için ortam değişkenlerini ayarlayın. Sizin için önceden doldurulmuş birkaç değişken vardır. Proje kimliğinizi, bölgenizi ve Hugging Face jetonunuzu belirtin.

   export PROJECT_ID=<YOUR_PROJECT_ID>
   export REGION=<YOUR_REGION>
   export HF_TOKEN=<YOUR_HF_TOKEN>
   
   export NEW_MODEL=gemma-emoji
   export AR_REPO=codelab-finetuning-jobs
   export IMAGE_NAME=finetune-to-gcs
   export JOB_NAME=finetuning-to-gcs-job
   export BUCKET_NAME=$PROJECT_ID-codelab-finetuning-jobs
   export SECRET_ID=HF_TOKEN
   export SERVICE_ACCOUNT="finetune-job-sa"
   export SERVICE_ACCOUNT_ADDRESS=$SERVICE_ACCOUNT@$PROJECT_ID.iam.gserviceaccount.com
   

2. Aşağıdaki komutu çalıştırarak hizmet hesabını oluşturun:

   gcloud iam service-accounts create $SERVICE_ACCOUNT \
     --display-name="Service account for fine-tuning codelab"
   

3. Hugging Face erişim jetonunu depolamak için Secret Manager'ı kullanın:

   gcloud secrets create $SECRET_ID \
         --replication-policy="automatic"
   
   printf $HF_TOKEN | gcloud secrets versions add $SECRET_ID --data-file=-
   

4. Hizmet hesabınıza Secret Manager Gizli Anahtar Erişeni rolünü verin:

   gcloud secrets add-iam-policy-binding $SECRET_ID \
     --member serviceAccount:$SERVICE_ACCOUNT_ADDRESS \
     --role='roles/secretmanager.secretAccessor'
   

5. İnce ayarlı modelinizi barındıracak bir paket oluşturun:

   gcloud storage buckets create -l $REGION gs://$BUCKET_NAME
   

6. Hizmet hesabınıza pakete erişim izni verin:

   gcloud storage buckets add-iam-policy-binding gs://$BUCKET_NAME \
     --member=serviceAccount:$SERVICE_ACCOUNT_ADDRESS \
     --role=roles/storage.objectAdmin
   

7. Container görüntüsünü depolamak için bir Artifact Registry deposu oluşturun:

   gcloud artifacts repositories create $AR_REPO \
       --repository-format=docker \
       --location=$REGION \
       --description="codelab for finetuning using CR jobs" \
       --project=$PROJECT_ID
   

4. Cloud Run işi görüntüsünü oluşturma

Sonraki adımda, aşağıdaki işlemleri yapan kodu oluşturacaksınız:

• Hugging Face'ten Gemma modelini içe aktarır.
• Hugging Face'teki veri kümesiyle modelde ince ayar yapar. İş, ince ayar için tek bir L4 GPU kullanır.
• new_model adlı ince ayarlı modeli Cloud Storage paketinize yükler.

1. İnce ayar işi kodunuz için bir dizin oluşturun.

   mkdir codelab-finetuning-job
   cd codelab-finetuning-job
   

2. finetune.py adlı bir dosya oluşturun.

   # Copyright 2025 Google LLC
   #
   # Licensed under the Apache License, Version 2.0 (the "License");
   # you may not use this file except in compliance with the License.
   # You may obtain a copy of the License at
   #
   #      http://www.apache.org/licenses/LICENSE-2.0
   #
   # Unless required by applicable law or agreed to in writing, software
   # distributed under the License is distributed on an "AS IS" BASIS,
   # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   # See the License for the specific language governing permissions and
   # limitations under the License.
   
   import os
   
   import torch
   from datasets import load_dataset
   from peft import LoraConfig, PeftModel
   from transformers import (
       AutoModelForCausalLM,
       AutoTokenizer,
       BitsAndBytesConfig,
       TrainingArguments,
   )
   from trl import SFTTrainer
   
   # Cloud Storage bucket to upload the model
   bucket_name = os.getenv("BUCKET_NAME", "YOUR_BUCKET_NAME")
   
   # The model that you want to train from the Hugging Face hub
   model_name = os.getenv("MODEL_NAME", "google/gemma-3-1b-it")
   
   # The instruction dataset to use
   dataset_name = "KomeijiForce/Text2Emoji"
   
   # Fine-tuned model name
   new_model = os.getenv("NEW_MODEL", "gemma-emoji")
   
   ############################ Setup ############################################
   
   # Load the entire model on the GPU 0
   device_map = {"": torch.cuda.current_device()}
   
   # Limit dataset to a random selection
   dataset = load_dataset(dataset_name, split="train").shuffle(seed=42).select(range(1000))
   
   # Setup input formats: trains the model to respond to "Translate to emoji:" with emoji output.
   tokenizer = AutoTokenizer.from_pretrained(model_name)
   
   def format_to_chat(example):
       return {
           "conversations": [
               {"role": "user", "content": f"Translate to emoji: {example['text']}"},
               {"role": "assistant", "content": example["emoji"]},
           ]
       }
   
   formatted_dataset = dataset.map(
       format_to_chat,
       batched=False,                        # Process row by row
       remove_columns=dataset.column_names,  # Optional: Keep only the new column
   )
   
   def apply_chat_template(examples):
       texts = tokenizer.apply_chat_template(examples["conversations"], tokenize=False)
       return {"text": texts}
   
   final_dataset = formatted_dataset.map(apply_chat_template, batched=True)
   
   ############################# Config #########################################
   
   # Load tokenizer and model with QLoRA configuration
   bnb_4bit_compute_dtype = "float16"  # Compute dtype for 4-bit base models
   compute_dtype = getattr(torch, bnb_4bit_compute_dtype)
   
   bnb_config = BitsAndBytesConfig(
       load_in_4bit=True,  # Activate 4-bit precision base model loading
       bnb_4bit_quant_type="nf4",  # Quantization type (fp4 or nf4)
       bnb_4bit_compute_dtype=compute_dtype,
       bnb_4bit_use_double_quant=False,  # Activate nested quantization for 4-bit base models (double quantization)
   )
   
   # Load base model
   model = AutoModelForCausalLM.from_pretrained(
       model_name,
       quantization_config=bnb_config,
       device_map=device_map,
       torch_dtype=torch.float16,
   )
   model.config.use_cache = False
   model.config.pretraining_tp = 1
   
   ############################## Train ##########################################
   
   # Load LoRA configuration
   peft_config = LoraConfig(
       lora_alpha=16,     # Alpha parameter for LoRA scaling
       lora_dropout=0.1,  # Dropout probability for LoRA layers,
       r=8,               # LoRA attention dimension
       bias="none",
       task_type="CAUSAL_LM",
       target_modules=["q_proj", "v_proj"],
   )
   
   # Set training parameters
   training_arguments = TrainingArguments(
       output_dir="./results",
       num_train_epochs=1,
       per_device_train_batch_size=1,  # Batch size per GPU for training
       gradient_accumulation_steps=2,  # Number of update steps to accumulate the gradients for
       optim="paged_adamw_32bit",
       save_steps=0,
       logging_steps=5,
       learning_rate=2e-4,    # Initial learning rate (AdamW optimizer)
       weight_decay=0.001,    # Weight decay to apply to all layers except bias/LayerNorm weights
       fp16=True, bf16=False, # Enable fp16/bf16 training
       max_grad_norm=0.3,     # Maximum gradient normal (gradient clipping)
       warmup_ratio=0.03,     # Ratio of steps for a linear warmup (from 0 to learning rate)
       group_by_length=True,  # Group sequences into batches with same length # Saves memory and speeds up training considerably
       lr_scheduler_type="cosine",
   )
   
   trainer = SFTTrainer(
       model=model,
       train_dataset=final_dataset,
       peft_config=peft_config,
       dataset_text_field="text",
       max_seq_length=512,  # Maximum sequence length to use
       tokenizer=tokenizer,
       args=training_arguments,
       packing=False,       # Pack multiple short examples in the same input sequence to increase efficiency
   )
   
   trainer.train()
   trainer.model.save_pretrained(new_model)
   
   ################################# Save ########################################
   
   # Reload model in FP16 and merge it with LoRA weights
   base_model = AutoModelForCausalLM.from_pretrained(
       model_name,
       low_cpu_mem_usage=True,
       return_dict=True,
       torch_dtype=torch.float16,
       device_map=device_map,
   )
   model = PeftModel.from_pretrained(base_model, new_model)
   model = model.merge_and_unload()
   
   # push results to Cloud Storage
   file_path_to_save_the_model = "/finetune/new_model"
   model.save_pretrained(file_path_to_save_the_model)
   tokenizer.save_pretrained(file_path_to_save_the_model)
   
   

3. requirements.txt dosyası oluşturma:

   accelerate==0.34.2
   bitsandbytes==0.45.5
   datasets==2.19.1
   transformers==4.51.3
   peft==0.11.1
   trl==0.8.6
   torch==2.3.0
   

4. Dockerfile oluşturma:

   FROM nvidia/cuda:12.6.2-runtime-ubuntu22.04
   
   RUN apt-get update && \
       apt-get -y --no-install-recommends install python3-dev gcc python3-pip git && \
       rm -rf /var/lib/apt/lists/*
   
   COPY requirements.txt /requirements.txt
   
   RUN pip3 install -r requirements.txt --no-cache-dir
   
   COPY finetune.py /finetune.py
   
   ENV PYTHONUNBUFFERED 1
   
   CMD python3 /finetune.py --device cuda
   

5. Container'ı Artifact Registry deponuzda oluşturun:

   gcloud builds submit \
     --tag $REGION-docker.pkg.dev/$PROJECT_ID/$AR_REPO/$IMAGE_NAME \
     --region $REGION
   

5. İşi dağıtma ve yürütme

Bu adımda, Google Cloud Storage'a daha hızlı yükleme için doğrudan VPC çıkışı olan işi oluşturacaksınız.

1. Cloud Run işini oluşturun:

   gcloud run jobs create $JOB_NAME \
     --region $REGION \
     --image $REGION-docker.pkg.dev/$PROJECT_ID/$AR_REPO/$IMAGE_NAME \
     --set-env-vars BUCKET_NAME=$BUCKET_NAME \
     --set-secrets HF_TOKEN=$SECRET_ID:latest \
     --cpu 8.0 \
     --memory 32Gi \
     --gpu 1 \
     --add-volume name=finetuned_model,type=cloud-storage,bucket=$BUCKET_NAME \
     --add-volume-mount volume=finetuned_model,mount-path=/finetune/new_model \
     --service-account $SERVICE_ACCOUNT_ADDRESS
   

2. İşi yürütün:

   gcloud run jobs execute $JOB_NAME --region $REGION --async
   

İşin tamamlanması yaklaşık 10 dakika sürer. Durumu, son komutun çıktısında verilen bağlantıyı kullanarak kontrol edebilirsiniz.

6. vLLM ile ince ayarını yaptığınız modeli sunmak için Cloud Run hizmetini kullanma

Bu adımda bir Cloud Run hizmeti dağıtacaksınız. Bu yapılandırma, daha hızlı indirme için özel ağ üzerinden Cloud Storage paketine erişmek üzere doğrudan VPC'yi kullanır.

• Cloud Run hizmetinizi dağıtın:

  gcloud run deploy serve-gemma-emoji \
    --image us-docker.pkg.dev/vertex-ai/vertex-vision-model-garden-dockers/pytorch-vllm-serve:20250601_0916_RC01 \
    --region $REGION \
    --port 8000 \
    --set-env-vars MODEL_ID=new_model,HF_HUB_OFFLINE=1 \
    --cpu 8.0 \
    --memory 32Gi \
    --gpu 1 \
    --add-volume name=finetuned_model,type=cloud-storage,bucket=$BUCKET_NAME \
    --add-volume-mount volume=finetuned_model,mount-path=/finetune/new_model \
    --service-account $SERVICE_ACCOUNT_ADDRESS \
    --max-instances 1 \
    --command python3 \
    --args="-m,vllm.entrypoints.api_server,--model=/finetune/new_model,--tensor-parallel-size=1" \
    --no-gpu-zonal-redundancy \
    --labels=dev-tutorial=codelab-tuning \
    --no-invoker-iam-check
  

7. İnce ayarını yaptığınız modeli test etme

Bu adımda, modelinizi curl kullanarak ince ayarı test etmeye yönlendireceksiniz.

1. Cloud Run hizmetinizin hizmet URL'sini alın:

   SERVICE_URL=$(gcloud run services describe serve-gemma-emoji \
       --region $REGION --format 'value(status.url)')
   

2. Modeliniz için isteminizi oluşturun.

   USER_PROMPT="Translate to emoji: I ate a banana for breakfast, later I'm thinking of having soup!"
   

3. Modelinize istem göndermek için curl'ü kullanarak hizmetinizi çağırın ve sonuçları jq ile filtreleyin:

   curl -s -X POST ${SERVICE_URL}/v1/chat/completions \
   -H "Content-Type: application/json" \
   -H "Authorization: bearer $(gcloud auth print-identity-token)" \
   -d @- <<EOF | jq ".choices[0].message.content"
   {   "model": "${NEW_MODEL}",
       "messages": [{
           "role": "user",
           "content": [ { "type": "text", "text": "${USER_PROMPT}"}]
       }]
   }
   EOF
   
   

Aşağıdakine benzer bir yanıt görmeniz gerekir:

🍌🤔😋🥣

8. Tebrikler!

Codelab'i tamamladığınız için tebrikler.

Cloud Run Jobs GPU dokümanını incelemenizi öneririz.

İşlediğimiz konular

• Cloud Run Jobs GPU kullanarak ince ayar yapma
• vLLM ile Cloud Run kullanarak model sunma
• Modelin daha hızlı yüklenmesi ve sunulması için GPU işinde doğrudan VPC yapılandırması kullanma

9. Temizleme

Örneğin, Cloud Run hizmetlerinin ücretsiz katmandaki aylık Cloud Run çağırma tahsisinizden daha fazla sayıda çağrılması gibi yanlışlıkla ücretlendirmeleri önlemek için 6. adımda oluşturduğunuz Cloud Run hizmetini silebilirsiniz.

Cloud Run hizmetini silmek için https://console.cloud.google.com/run adresinden Cloud Run Cloud Console'a gidin ve serve-gemma-emoji hizmetini silin.

Projenin tamamını silmek için Kaynakları Yönet'e gidin, 2. adımda oluşturduğunuz projeyi seçin ve Sil'i tıklayın. Projeyi silerseniz Cloud SDK'nızda projeleri değiştirmeniz gerekir. gcloud projects list komutunu çalıştırarak kullanılabilir tüm projelerin listesini görüntüleyebilirsiniz.