이 튜토리얼에서는 Google Cloud의 멀티 노드, 멀티 GPU GKE 클러스터에서 Gemma 3 대규모 언어 모델 (LLM)을 미세 조정하는 방법을 보여줍니다. 이 클러스터는 NVIDIA B200 GPU가 8개 있는 A4 가상 머신 (VM) 인스턴스를 사용합니다.
이 튜토리얼에 설명된 두 가지 주요 프로세스는 다음과 같습니다.
- 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권한이 포함된 서비스 사용량 관리자 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권한이 포함된 서비스 사용량 관리자 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.com입니다.ROLE: 사용자 계정에 부여하는 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 로그인을 사용 설정합니다.
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액세스 토큰을 만듭니다.
내 프로필 > 설정 > 액세스 토큰 > +새 토큰 만들기를 클릭합니다. 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 보안 비밀 만들기
Hugging Face 사용자 인증 정보용 Kubernetes 보안 비밀을 만들려면 다음 단계를 따르세요.
GKE 클러스터와 통신하도록
kubectl을 구성합니다.gcloud container clusters get-credentials $CLUSTER_NAME \ --location=$REGIONHugging Face 토큰을 저장할 Kubernetes 보안 비밀을 만듭니다.
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파일을 생성합니다. 이 구성 파일은 Hugging Face Accelerate가 여러 GPU에 걸쳐 조정 작업을 분할하도록 지시합니다.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에 푸시합니다.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 -f작업 리소스는 모델 데이터를 다운로드한 후 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