このチュートリアルでは、 Google Cloudのマルチノード、マルチ GPU GKE クラスタで Gemma 3 大規模言語モデル（LLM）をファインチューニングする方法について説明します。このクラスタは、8 個の NVIDIA B200 GPU を搭載した A4 仮想マシン（VM）インスタンスを使用します。
このチュートリアルで説明する主なプロセスは次の 2 つです。
- GKE Autopilot を使用して、高パフォーマンスの GKE クラスタをデプロイします。このデプロイの一環として、必要なソフトウェアがプリインストールされたカスタム VM イメージを作成します。
- クラスタがデプロイされたら、このチュートリアルに付属するスクリプトのセットを使用して、分散型ファインチューニング ジョブを実行します。このジョブは、Hugging Face Accelerate ライブラリを活用します。
このチュートリアルは、LLM のトレーニングに Google Cloud で GKE クラスタをデプロイすることに関心のある ML エンジニア、研究者、プラットフォーム管理者、オペレーター、データおよび AI スペシャリストを対象としています。
目標
Hugging Face を使用して Gemma 3 モデルにアクセスします。
環境を準備します。
A4 GKE クラスタを作成してデプロイします。
完全にシャーディングされたデータ並列処理（FSDP）で Hugging Face Accelerate ライブラリを使用して、Gemma 3 モデルをファインチューニングします。
ジョブをモニタリングします。
クリーンアップする。
費用
このドキュメントでは、課金対象である次の Google Cloudコンポーネントを使用します。
料金計算ツールを使うと、予想使用量に基づいて費用の見積もりを生成できます。
始める前に
- Google Cloud アカウントにログインします。 Google Cloudを初めて使用する場合は、 アカウントを作成して、実際のシナリオでの Google プロダクトのパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。
-
Google Cloud CLI をインストールします。
-
外部 ID プロバイダ（IdP）を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。
-
gcloud CLI を初期化するには、次のコマンドを実行します。
gcloud init -
Google Cloud プロジェクトを作成または選択します。
プロジェクトの選択または作成に必要なロール
- プロジェクトを選択する: プロジェクトの選択に特定の IAM ロールは必要ありません。ロールが付与されているプロジェクトであれば、どのプロジェクトでも選択できます。
-
プロジェクトを作成する: プロジェクトを作成するには、
resourcemanager.projects.create権限を含むプロジェクト作成者ロール（roles/resourcemanager.projectCreator）が必要です。ロールを付与する方法を確認する。
-
Google Cloud プロジェクトを作成します。
gcloud projects create PROJECT_ID
PROJECT_IDは、作成する Google Cloud プロジェクトの名前に置き換えます。 -
作成した Google Cloud プロジェクトを選択します。
gcloud config set project PROJECT_ID
PROJECT_IDは、 Google Cloud プロジェクトの名前に置き換えます。
必要な API を有効にします。
API を有効にするために必要なロール
API を有効にするには、
serviceusage.services.enable権限を含む Service Usage 管理者 IAM ロール（roles/serviceusage.serviceUsageAdmin）が必要です。ロールを付与する方法を確認する。gcloud services enable gcloud services enable compute.googleapis.com container.googleapis.com file.googleapis.com logging.googleapis.com cloudresourcemanager.googleapis.com servicenetworking.googleapis.com
-
Google Cloud CLI をインストールします。
-
外部 ID プロバイダ（IdP）を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。
-
gcloud CLI を初期化するには、次のコマンドを実行します。
gcloud init -
Google Cloud プロジェクトを作成または選択します。
プロジェクトの選択または作成に必要なロール
- プロジェクトを選択する: プロジェクトの選択に特定の IAM ロールは必要ありません。ロールが付与されているプロジェクトであれば、どのプロジェクトでも選択できます。
-
プロジェクトを作成する: プロジェクトを作成するには、
resourcemanager.projects.create権限を含むプロジェクト作成者ロール（roles/resourcemanager.projectCreator）が必要です。ロールを付与する方法を確認する。
-
Google Cloud プロジェクトを作成します。
gcloud projects create PROJECT_ID
PROJECT_IDは、作成する Google Cloud プロジェクトの名前に置き換えます。 -
作成した Google Cloud プロジェクトを選択します。
gcloud config set project PROJECT_ID
PROJECT_IDは、 Google Cloud プロジェクトの名前に置き換えます。
必要な API を有効にします。
API を有効にするために必要なロール
API を有効にするには、
serviceusage.services.enable権限を含む Service Usage 管理者 IAM ロール（roles/serviceusage.serviceUsageAdmin）が必要です。ロールを付与する方法を確認する。gcloud services enable gcloud services enable compute.googleapis.com container.googleapis.com file.googleapis.com logging.googleapis.com cloudresourcemanager.googleapis.com servicenetworking.googleapis.com
-
ユーザー アカウントにロールを付与します。次の IAM ロールごとに次のコマンドを 1 回実行します。
roles/compute.admin, roles/iam.serviceAccountUser, roles/cloudbuild.builds.editor, roles/artifactregistry.admin, roles/storage.admin, roles/serviceusage.serviceUsageAdmingcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE
次のように置き換えます。
PROJECT_ID: プロジェクト ID。USER_IDENTIFIER: ユーザー アカウントの識別子。例:myemail@example.comROLE: ユーザー アカウントに付与する IAM ロール。
- Google Cloud プロジェクトのデフォルトのサービス アカウントを有効にします。
gcloud iam service-accounts enable PROJECT_NUMBER-compute@developer.gserviceaccount.com \ --project=PROJECT_ID
PROJECT_NUMBER は、使用するプロジェクト番号に置き換えます。プロジェクト番号を確認するには、 既存のプロジェクトを取得するをご覧ください。
- デフォルトのサービス アカウントに編集者ロール（
roles/editor）を付与します。gcloud projects add-iam-policy-binding PROJECT_ID \ --member="serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com" \ --role=roles/editor
- ユーザー アカウントのローカル認証情報を作成します。
gcloud auth application-default login
- プロジェクトで OS Login を有効にします。
gcloud compute project-info add-metadata --metadata=enable-oslogin=TRUE
- Hugging Face アカウントにログインするか、アカウントを作成します。
Hugging Face を使用して Gemma 3 にアクセスする
Hugging Face を使用して Gemma 3 にアクセスする手順は次のとおりです。
- Hugging Face にログインする
- Hugging Face
readアクセス トークンを作成します。
[Your Profile] > [Settings] > [Access tokens] > [+Create new token] をクリックします。 read accessトークンの値をコピーして保存します。これは、このチュートリアルの後半で使用します。
環境を準備する
環境を準備するには、次の設定を行います。
gcloud config set project PROJECT_NAME
gcloud config set billing/quota_project PROJECT_NAME
export RESERVATION=YOUR_RESERVATION_ID
export PROJECT_ID=$(gcloud config get project)
export REGION=CLUSTER_REGION
export CLUSTER_NAME=CLUSTER_NAME
export HF_TOKEN=YOUR_TOKEN
export NETWORK=default
次のように置き換えます。
PROJECT_NAME: GKE クラスタを作成する Google Cloud プロジェクトの名前。YOUR_RESERVATION_ID: 予約済み容量の識別子。CLUSTER_REGION: GKE クラスタを作成するリージョン。クラスタを作成できるのは、予約が存在するリージョンのみです。CLUSTER_NAME: 作成する GKE クラスタの名前。HF_TOKEN: 前のセクションで作成した Hugging Face アクセス トークン。
Autopilot モードの GKE クラスタを作成する
Autopilot モードで GKE クラスタを作成するには、次のコマンドを実行します。
gcloud container clusters create-auto ${CLUSTER_NAME} \
--project=${PROJECT_ID} \
--location=${REGION} \
--release-channel=rapid
GKE クラスタの作成には時間がかかることがあります。 Google Cloud がクラスタの作成を完了したことを確認するには、 Google Cloud コンソールの [Kubernetes クラスタ] に移動します。
Hugging Face の認証情報用の Kubernetes Secret を作成する
Hugging Face の認証情報用の Kubernetes Secret を作成する手順は次のとおりです。
GKE クラスタと通信するように
kubectlを構成します。gcloud container clusters get-credentials $CLUSTER_NAME \ --location=$REGIONHugging Face トークンを保存する Kubernetes Secret を作成します。
gcloud container clusters get-credentials ${CLUSTER_NAME} \ --location=${REGION} kubectl create secret generic hf-secret \ --from-literal=hf_api_token=${HF_TOKEN} \ --dry-run=client -o yaml | kubectl apply -f -
ワークロードを準備する
ワークロードを準備する手順は次のとおりです。
ワークロード スクリプトを作成する
ファインチューニング ワークロードで使用するスクリプトを作成するには、次の操作を行います。
ワークロード スクリプト用のディレクトリを作成します。このディレクトリを作業ディレクトリとして使用します。
mkdir llm-finetuning-gemma cd llm-finetuning-gemmaGoogle Cloud Build を使用する
cloudbuild.yamlファイルを作成します。このファイルは、ワークロード コンテナを作成して Artifact Registry に保存します。steps: - name: 'gcr.io/cloud-builders/docker' args: [ 'build', '-t', 'us-docker.pkg.dev/$PROJECT_ID/gemma/finetune-gemma-gpu:1.0.0', '.' ] images: - 'us-docker.pkg.dev/$PROJECT_ID/gemma/finetune-gemma-gpu:1.0.0'ファインチューニング ジョブを実行する
Dockerfileファイルを作成します。FROM nvidia/cuda:12.8.1-cudnn-devel-ubuntu24.04 RUN apt-get update && \ apt-get -y install python3 python3-dev gcc python3-pip python3-venv git curl vim RUN python3 -m venv /opt/venv ENV PATH="/opt/venv/bin:/usr/local/nvidia/bin:$PATH" ENV LD_LIBRARY_PATH="/usr/local/nvidia/lib64:$LD_LIBRARY_PATH" RUN pip3 install setuptools wheel packaging ninja RUN pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128 RUN pip3 install \ transformers==4.53.3 \ datasets==4.0.0 \ accelerate==1.9.0 \ evaluate==0.4.5 \ bitsandbytes==0.46.1 \ trl==0.19.1 \ peft==0.16.0 \ tensorboard==2.20.0 \ protobuf==6.31.1 \ sentencepiece==0.2.0 COPY finetune.py /finetune.py COPY accel_fsdp_gemma3_config.yaml /accel_fsdp_gemma3_config.yaml CMD accelerate launch --config_file accel_fsdp_gemma3_config.yaml finetune.pyaccel_fsdp_gemma3_config.yamlファイルを作成します。この構成ファイルは、チューニング ジョブを複数の GPU に分割するように Hugging Face Accelerate に指示します。compute_environment: LOCAL_MACHINE debug: false distributed_type: FSDP downcast_bf16: 'no' enable_cpu_affinity: false fsdp_config: fsdp_activation_checkpointing: false fsdp_auto_wrap_policy: TRANSFORMER_BASED_WRAP fsdp_cpu_ram_efficient_loading: true fsdp_offload_params: false fsdp_reshard_after_forward: true fsdp_state_dict_type: FULL_STATE_DICT fsdp_transformer_layer_cls_to_wrap: Gemma3DecoderLayer fsdp_version: 2 machine_rank: 0 main_training_function: main mixed_precision: bf16 num_machines: 1 num_processes: 8 rdzv_backend: static same_network: true tpu_env: [] tpu_use_cluster: false tpu_use_sudo: false use_cpu: falsefinetune.yamlファイルを作成します。apiVersion: batch/v1 kind: Job metadata: name: finetune-job namespace: default spec: backoffLimit: 2 template: metadata: annotations: kubectl.kubernetes.io/default-container: finetuner spec: terminationGracePeriodSeconds: 600 containers: - name: finetuner image: $IMAGE_URL command: ["accelerate","launch"] args: - "--config_file" - "accel_fsdp_gemma3_config.yaml" - "finetune.py" - "--model_id" - "google/gemma-3-12b-pt" - "--output_dir" - "gemma-12b-text-to-sql" - "--per_device_train_batch_size" - "8" - "--gradient_accumulation_steps" - "8" - "--num_train_epochs" - "3" - "--learning_rate" - "1e-5" - "--save_strategy" - "steps" - "--save_steps" - "100" resources: limits: nvidia.com/gpu: "8" env: - name: HF_TOKEN valueFrom: secretKeyRef: name: hf-secret key: hf_api_token volumeMounts: - mountPath: /dev/shm name: dshm volumes: - name: dshm emptyDir: medium: Memory nodeSelector: cloud.google.com/gke-accelerator: nvidia-b200 cloud.google.com/reservation-name: $RESERVATION cloud.google.com/reservation-affinity: "specific" cloud.google.com/gke-gpu-driver-version: latest restartPolicy: OnFailurefinetune.pyファイルを作成します。import torch import argparse import subprocess from datasets import load_dataset from transformers import AutoTokenizer, AutoModelForCausalLM, BitsAndBytesConfig, AutoConfig from peft import LoraConfig, prepare_model_for_kbit_training, get_peft_model from trl import SFTTrainer, SFTConfig from huggingface_hub import login def get_args(): parser = argparse.ArgumentParser() parser.add_argument("--model_id", type=str, default="google/gemma-3-12b-pt", help="Hugging Face model ID") parser.add_argument("--hf_token", type=str, default=None, help="Hugging Face token for private models") parser.add_argument("--trust_remote", type=bool, default="False", help="Trust remote code when loading tokenizer") parser.add_argument("--use_fast", type=bool, default="True", help="Determines if a fast Rust-based tokenizer should be used") parser.add_argument("--dataset_name", type=str, default="philschmid/gretel-synthetic-text-to-sql", help="Hugging Face dataset name") parser.add_argument("--output_dir", type=str, default="gemma-12b-text-to-sql", help="Directory to save model checkpoints") # LoRA arguments parser.add_argument("--lora_r", type=int, default=16, help="LoRA attention dimension") parser.add_argument("--lora_alpha", type=int, default=16, help="LoRA alpha scaling factor") parser.add_argument("--lora_dropout", type=float, default=0.05, help="LoRA dropout probability") # SFTConfig arguments parser.add_argument("--max_seq_length", type=int, default=512, help="Maximum sequence length") parser.add_argument("--num_train_epochs", type=int, default=3, help="Number of training epochs") parser.add_argument("--per_device_train_batch_size", type=int, default=8, help="Batch size per device during training") parser.add_argument("--gradient_accumulation_steps", type=int, default=1, help="Gradient accumulation steps") parser.add_argument("--learning_rate", type=float, default=1e-5, help="Learning rate") parser.add_argument("--logging_steps", type=int, default=10, help="Log every X steps") parser.add_argument("--save_strategy", type=str, default="steps", help="Checkpoint save strategy") parser.add_argument("--save_steps", type=int, default=100, help="Save checkpoint every X steps") parser.add_argument("--push_to_hub", action='store_true', help="Push model back up to HF") parser.add_argument("--hub_private_repo", type=bool, default="True", help="Push to a private repo") return parser.parse_args() def main(): args = get_args() # --- 1. Setup and Login --- if args.hf_token: login(args.hf_token) # --- 2. Create and prepare the fine-tuning dataset --- # The `create_conversation` function is no longer needed. # The SFTTrainer will use the `formatting_func` to apply the chat template. dataset = load_dataset(args.dataset_name, split="train") dataset = dataset.shuffle().select(range(12500)) dataset = dataset.train_test_split(test_size=2500/12500) # --- 3. Configure Model and Tokenizer --- if torch.cuda.is_available() and torch.cuda.get_device_capability()[0] >= 8: torch_dtype_obj = torch.bfloat16 torch_dtype_str = "bfloat16" else: torch_dtype_obj = torch.float16 torch_dtype_str = "float16" tokenizer = AutoTokenizer.from_pretrained(args.model_id, trust_remote_code=args.trust_remote, use_fast=args.use_fast) tokenizer.pad_token = tokenizer.eos_token gemma_chat_template = ( "" "" ) tokenizer.chat_template = gemma_chat_template # --- 4. Define the Formatting Function --- # This function will be used by the SFTTrainer to format each sample # from the dataset into the correct chat template format. def formatting_func(example): # The create_conversation logic is now implicitly handled by this. # We need to construct the messages list here. system_message = "You are a text to SQL query translator. Users will ask you questions in English and you will generate a SQL query based on the provided SCHEMA." user_prompt = "Given the <USER_QUERY> and the <SCHEMA>, generate the corresponding SQL command to retrieve the desired data, considering the query's syntax, semantics, and schema constraints.\n\n<SCHEMA>\n{context}\n</SCHEMA>\n\n<USER_QUERY>\n{question}\n</USER_QUERY>\n" messages = [ {"role": "user", "content": user_prompt.format(question=example["sql_prompt"][0], context=example["sql_context"][0])}, {"role": "assistant", "content": example["sql"][0]} ] return tokenizer.apply_chat_template(messages, tokenize=False) # --- 5. Load Model and Apply PEFT --- config = AutoConfig.from_pretrained(args.model_id) config.use_cache = False # We'll be loading this model full precision because we're planning to do FSDP # Load the base model with quantization print("Loading base model...") model = AutoModelForCausalLM.from_pretrained( args.model_id, config=config, attn_implementation="eager", torch_dtype=torch_dtype_obj, ) # Prepare the model for k-bit training model = prepare_model_for_kbit_training(model) # Configure LoRA. peft_config = LoraConfig( lora_alpha=args.lora_alpha, lora_dropout=args.lora_dropout, r=args.lora_r, bias="none", target_modules=["q_proj", "k_proj", "v_proj", "o_proj", "gate_proj", "up_proj", "down_proj"], task_type="CAUSAL_LM", ) # Apply the PEFT config to the model print("Applying PEFT configuration...") model = get_peft_model(model, peft_config) model.print_trainable_parameters() # --- 6. Configure Training Arguments --- training_args = SFTConfig( output_dir=args.output_dir, max_seq_length=args.max_seq_length, num_train_epochs=args.num_train_epochs, per_device_train_batch_size=args.per_device_train_batch_size, gradient_accumulation_steps=args.gradient_accumulation_steps, learning_rate=args.learning_rate, logging_steps=args.logging_steps, save_strategy=args.save_strategy, save_steps=args.save_steps, packing=False, label_names=["domain"], gradient_checkpointing=True, gradient_checkpointing_kwargs={"use_reentrant": False}, optim="adamw_torch", fp16=True if torch_dtype_obj == torch.float16 else False, bf16=True if torch_dtype_obj == torch.bfloat16 else False, max_grad_norm=0.3, warmup_ratio=0.03, lr_scheduler_type="constant", push_to_hub=True, report_to="tensorboard", dataset_kwargs={ "add_special_tokens": False, "append_concat_token": True, } ) # --- 7. Create Trainer and Start Training --- trainer = SFTTrainer( model=model, args=training_args, train_dataset=dataset["train"], eval_dataset=dataset["test"], formatting_func=formatting_func, ) print("Starting training...") trainer.train() print("Training finished.") # --- 8. Save the final model --- print(f"Saving final model to {args.output_dir}") model.cpu() trainer.save_model(args.output_dir) torch.distributed.destroy_process_group() if __name__ == "__main__": main()
Docker と Cloud Build を使用してファインチューニング コンテナを作成する
Artifact Registry Docker リポジトリを作成します。
gcloud artifacts repositories create gemma \ --project=${PROJECT_ID} \ --repository-format=docker \ --location=us \ --description="Gemma Repo"前の手順で作成した
llm-finetuning-gemmaディレクトリで、次のコマンドを実行して、ファインチューニング コンテナを作成し、Artifact Registry に push します。gcloud builds submit .画像の URL をエクスポートします。この値は、このチュートリアルの後半のステップで使用します。
export IMAGE_URL=us-docker.pkg.dev/${PROJECT_ID}/gemma/finetune-gemma-gpu:1.0.0
ファインチューニング ワークロードを開始する
ファインチューニング ワークロードを開始するには、次の操作を行います。
ファインチューニング マニフェストを適用して、ファインチューニング ジョブを作成します。
envsubst < finetune.yaml | kubectl apply -f -GKE Autopilot モードでクラスタを使用しているため、GPU 対応ノードの起動には数分かかることがあります。
次のコマンドを実行して、ジョブをモニタリングします。
ewatch kubectl get pods次のコマンドを実行して、ジョブのログを確認します。
kubectl logs job.batch/finetune-job -fJob リソースはモデルデータをダウンロードし、8 つすべての GPU を使用してモデルをファインチューニングします。ダウンロードには 5 分ほどかかります。ダウンロードが完了すると、ファインチューニング プロセスが完了するまでに約 2 時間 30 分かかります。
ワークロードをモニタリングする
GKE クラスタでの GPU の使用状況をモニタリングして、ファインチューニング ジョブが効率的に実行されていることを確認できます。ブラウザで次のリンクを開きます。
https://console.cloud.google.com/kubernetes/clusters/details/us-central1/[CLUSTER_NAME]/observability?mods=monitoring_api_prod&project=[YOUR_PROJECT_ID]]&pageState=("timeRange":("duration":"PT1H"),"nav":("section":"gpu"),"groupBy":("groupByType":"namespacesTop5"))
ワークロードをモニタリングすると、次の情報を確認できます。
- GPU 使用率: 正常なファインチューニング ジョブでは、8 個の GPU すべての使用率が上昇し、トレーニング全体を通して高いレベルで安定することが予想されます。
- ジョブの所要時間: 指定した A4 クラスタでジョブが完了するまでに約 10 分かかります。
クリーンアップ
このチュートリアルで使用したリソースについて、Google Cloud アカウントに課金されないようにするには、リソースを含むプロジェクトを削除するか、プロジェクトを維持して個々のリソースを削除します。
プロジェクトの削除
Google Cloud プロジェクトを削除します。
gcloud projects delete PROJECT_ID
リソースを削除する
ファインチューニング ジョブを削除するには、次のコマンドを実行します。
kubectl delete job finetune-jobGKE クラスタを削除するには、次のコマンドを実行します。
gcloud container clusters delete $CLUSTER_NAME \ --region=$REGION