Cloud Run ジョブを使用して LLM を微調整する方法

1. はじめに

概要

この Codelab では、Cloud Run ジョブを使用して Gemma 3 モデルをファインチューニングし、vLLM を使用して Cloud Run で結果をサービングします。

演習内容

EmojiLM: Modeling the New Emoji Language の一部として確立された KomeijiForce/Text2Emoji データセットを使用して、特定のフレーズに特定の結果で応答するモデルをトレーニングします。

トレーニング後、モデルは「Translate to emoji: 」で始まる文に対して、その文に対応する一連の絵文字で応答します。

学習内容

• Cloud Run Jobs GPU を使用してファインチューニングを行う方法
• vLLM を使用して Cloud Run でモデルをサービングする方法
• モデルのアップロードとサービングを高速化するために GPU ジョブでダイレクト VPC 構成を使用する方法

2. 始める前に

API を有効にする

この Codelab を使用する前に、次のコマンドを実行して次の API を有効にします。

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

GPU 割り当て

GPU 割り当てのドキュメントで、割り当てをリクエストする方法を確認します。

「You do not have quota for using GPUs」というエラーが発生した場合は、g.co/cloudrun/gpu-quota で割り当てを確認してください。

注: 新しいプロジェクトを使用している場合、API を有効にしてから割り当てが割り当てページに表示されるまでに数分かかることがあります。

Hugging Face

この Codelab では、Hugging Face でホストされているモデルを使用します。このモデルを取得するには、「読み取り」権限を持つ Hugging Face ユーザー アクセス トークンをリクエストします。これは後で YOUR_HF_TOKEN として参照します。

gemma-3-1b-it モデルを使用するには、利用規約に同意する必要があります。

3. 設定と要件

次のリソースを設定します。

• IAM サービス アカウントと関連する IAM 権限、
• Hugging Face トークンを保存する Secret Manager シークレット。
• ファインチューニングされたモデルを保存する Cloud Storage バケット。
• モデルをファインチューニングするためにビルドするイメージを保存する Artifact Registry リポジトリ。

1. この Codelab の環境変数を設定します。いくつかの変数はあらかじめ入力されています。プロジェクト ID、リージョン、Hugging Face トークンを指定します。

   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. 次のコマンドを実行して、サービス アカウントを作成します。

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

3. Secret Manager を使用して Hugging Face アクセス トークンを保存します。

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

4. サービス アカウントに Secret Manager のシークレット アクセサーのロールを付与します。

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

5. ファインチューニングされたモデルをホストするバケットを作成します。

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

6. サービス アカウントにバケットへのアクセス権を付与します。

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

7. コンテナ イメージを保存する Artifact Registry リポジトリを作成します。

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

4. Cloud Run ジョブ イメージを作成する

次のステップでは、次の処理を行うコードを作成します。

• Hugging Face から Gemma モデルをインポートする
• Hugging Face のデータセットを使用してモデルのファインチューニングを行います。ジョブはファインチューニングに単一の L4 GPU を使用します。
• new_model というファインチューニングされたモデルを Cloud Storage バケットにアップロードします。

1. ファインチューニング ジョブコード用のディレクトリを作成します。

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

2. finetune.py というファイルを作成します。

   # 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 ファイルを作成します。

   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 を作成します。

   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. Artifact Registry リポジトリにコンテナをビルドします。

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

5. ジョブをデプロイして実行する

このステップでは、Google Cloud Storage へのアップロードを高速化するために、ダイレクト VPC 下り（外向き）を使用してジョブを作成します。

1. Cloud Run ジョブを作成します。

   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. ジョブを実行します。

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

ジョブが完了するまでに 10 分ほどかかります。ステータスは、最後のコマンドの出力に表示されるリンクを使用して確認できます。

6. Cloud Run サービスを使用して、vLLM でファインチューニングされたモデルをサービングする

このステップでは、Cloud Run サービスをデプロイします。この構成では、高速ダウンロードのために、プライベート ネットワーク経由で Cloud Storage バケットにアクセスする直接 VPC を使用します。

• Cloud Run サービスをデプロイします。

  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. ファインチューニングしたモデルをテストする

このステップでは、curl を使用してファインチューニングをテストするようにモデルにプロンプトを表示します。

1. Cloud Run サービスのサービス URL を取得します。

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

2. モデルのプロンプトを作成します。

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

3. curl を使用してサービスを呼び出し、モデルをプロンプトし、jq で結果をフィルタします。

   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
   
   

次のようなレスポンスが表示されます。

🍌🤔😋🥣

8. 完了

以上で、この Codelab は完了です。

Cloud Run Jobs GPU のドキュメントを確認することをおすすめします。

学習した内容

• Cloud Run Jobs GPU を使用してファインチューニングを行う方法
• vLLM を使用して Cloud Run でモデルをサービングする方法
• モデルのアップロードとサービングを高速化するために GPU ジョブでダイレクト VPC 構成を使用する方法

9. クリーンアップ

たとえば、Cloud Run サービスが無料枠の月間 Cloud Run 呼び出し割り当てよりも多く呼び出された場合など、意図しない課金を避けるには、ステップ 6 で作成した Cloud Run サービスを削除します。

Cloud Run サービスを削除するには、https://console.cloud.google.com/run で Cloud Run Cloud Console に移動し、serve-gemma-emoji サービスを削除します。

プロジェクト全体を削除するには、[リソースの管理] に移動し、ステップ 2 で作成したプロジェクトを選択して、[削除] を選択します。プロジェクトを削除した場合は、Cloud SDK でプロジェクトを変更する必要があります。gcloud projects list を実行すると、使用可能なすべてのプロジェクトのリストを表示できます。