Gemini Enterprise Agent Platform'da Gemini'a ince ayar yapma

1. Giriş

Bu laboratuvarda, belirli bir göreve (makale özetleme) uyarlamak için Google Gemini modelinde denetimli ince ayar iş akışının tamamını gerçekleştirmeyi öğreneceksiniz. Büyük dil modelleri güçlü olsa da genel amaçlı olmaları nedeniyle ince ayar yapılarak belirli kullanım alanlarında daha da etkili hale getirilebilir. Modeli yüksek kaliteli bir örnek veri kümesi üzerinde eğiterek hedef göreviniz için tutarlılığını, kalitesini ve verimliliğini artırabilirsiniz.

Hafif ve uygun maliyetli bir model olan Gemini 3.5 Flash'i kullanacak ve Gemini Enterprise Agent Platform'u kullanarak ince ayar yapacaksınız.

Mimariye Genel Bakış

Geliştireceğimiz özellikler:

  • Cloud Shell: Geliştirme ortamınız.
  • Cloud Storage: Eğitim/doğrulama verilerini JSONL biçiminde depolar.
  • Gemini Enterprise Agent Platform Training: İnce ayar işini yönetir.
  • Gemini Enterprise Agent Platform Endpoint: İnce ayarlı modelinizi barındırır.

Neler öğreneceksiniz?

  • Gözetimli ince ayar için yüksek kaliteli veri kümeleri hazırlayın.
  • Python için Gemini Enterprise Agent Platform SDK'yı kullanarak ince ayar işlerini yapılandırın ve başlatın.
  • Modelleri otomatik metrikleri (ROUGE puanları) kullanarak değerlendirin.
  • İyileştirmeleri ölçmek için temel ve ince ayarlı modelleri karşılaştırın.

2. Proje ayarlama

Google Hesabı

Kişisel Google Hesabınız yoksa Google Hesabı oluşturmanız gerekir.

İş veya okul hesabı yerine kişisel hesap kullanın.

Google Cloud Console'da oturum açma

Kişisel bir Google Hesabı kullanarak Google Cloud Console'da oturum açın.

Faturalandırmayı Etkinleştir

Google Cloud kredilerini kullanma (isteğe bağlı)

Bu atölyeyi düzenlemek için biraz kredisi olan bir faturalandırma hesabına ihtiyacınız var. Başlamak için bu codelab'in üst kısmındaki banner'da yer alan kredileri kullanın. Zaten bir faturalandırma hesabına bağlıysanız bu adımı atlayabilirsiniz.

Proje oluşturma (isteğe bağlı)

Bu laboratuvarda kullanmak istediğiniz mevcut bir projeniz yoksa buradan yeni bir proje oluşturun.

3. Cloud Shell Düzenleyici'yi açma

  1. Doğrudan Cloud Shell Düzenleyici'ye gitmek için bu bağlantıyı tıklayın.
  2. Bugün herhangi bir noktada yetkilendirmeniz istenirse devam etmek için Yetkilendir'i tıklayın. Cloud Shell'i yetkilendirmek için tıklayın.
  3. Terminal ekranın alt kısmında görünmüyorsa açın:
    • Görünüm'ü tıklayın.
    • Terminal'i tıklayın.Cloud Shell Düzenleyici'de yeni terminal açma
  4. Terminalde şu komutla projenizi ayarlayın:
    gcloud config set project [PROJECT_ID]
    
    • Örnek:
      gcloud config set project lab-project-id-example
      
    • Proje kimliğinizi hatırlamıyorsanız tüm proje kimliklerinizi şu komutla listeleyebilirsiniz:
      gcloud projects list
      
      Cloud Shell Düzenleyici terminalinde proje kimliğini ayarlama
  5. Şu mesajı görürsünüz:
    Updated property [core/project].
    

4. API'leri etkinleştir

Gemini Enterprise Agent Platform'u ve diğer hizmetleri kullanmak için Google Cloud projenizde gerekli API'leri etkinleştirmeniz gerekir.

  1. Terminalde API'leri etkinleştirin:
    • Vertex AI API (aiplatform.googleapis.com): Modelleri ince ayarlamak ve sunmak için Vertex AI'nin kullanılmasını sağlar.
    • Cloud Storage API (storage.googleapis.com): Veri kümelerinin ve model yapıtlarının depolanmasını sağlar.
    gcloud services enable aiplatform.googleapis.com \
        storage.googleapis.com
    

5. Proje ortamını ayarlama

Çalışma dizini oluşturma

  1. Terminalde projeniz için bir dizin oluşturun ve bu dizine gidin.
    mkdir gemini-finetuning
    cd gemini-finetuning
    

Ortam değişkenlerini ayarlama

  1. Terminalde projenizin ortam değişkenlerini tanımlayın. Oturumunuzun bağlantısı kesilirse kolayca yeniden yüklenebilmeleri için bu değişkenleri saklamak üzere bir env.sh dosyası oluşturacağız.
    cat <<EOF > env.sh
    export PROJECT_ID=\$(gcloud config get-value project)
    export REGION="us-central1"
    export LOCATION="global"
    export BUCKET_NAME="\${PROJECT_ID}-gemini-tuning"
    EOF
    
    source env.sh
    

Cloud Storage paketi oluşturma

  1. Terminalde, veri kümenizi ve model yapıtlarınızı depolamak için bir paket oluşturun.
    gcloud storage buckets create gs://$BUCKET_NAME --project=$PROJECT_ID --location=$REGION
    

Sanal ortamı ayarlama

  1. Python ortamımızı yönetmek için uv kullanacağız. Terminalde şunu çalıştırın:
    uv venv .venv
    source .venv/bin/activate
    
  2. Terminalde gerekli Python paketlerini yükleyin.
    uv pip install google-cloud-aiplatform rouge-score matplotlib pandas tqdm
    

6. Eğitim verilerini hazırlama

Kaliteli veriler, başarılı ince ayarın temelini oluşturur. WikiLingua veri kümesini kullanacak, bunu Gemini'ın gerektirdiği belirli JSONL biçimine dönüştürecek ve depolama paketinize yükleyeceksiniz.

  1. Terminalde prepare_data.py adlı bir dosya oluşturun.
    cloudshell edit prepare_data.py
    
  2. Aşağıdaki kodu prepare_data.py dosyasına yapıştırın.
    import json
    import os
    import pandas as pd
    from google.cloud import storage
    import subprocess
    
    # Configuration
    BUCKET_NAME = os.environ["BUCKET_NAME"]
    PROJECT_ID = os.environ["PROJECT_ID"]
    
    def download_data():
        print("Downloading WikiLingua dataset...")
        # Using gsutil to copy from public bucket
        subprocess.run(["gsutil", "cp", "gs://github-repo/generative-ai/gemini/tuning/summarization/wikilingua/*", "."], check=True)
    
    def convert_to_gemini_format(input_file, output_file, max_samples=1000):
        print(f"Converting {input_file} to Gemini format (first {max_samples} samples)...")
        converted_data = []
        with open(input_file, 'r') as f:
            for i, line in enumerate(f):
                if i >= max_samples:
                    break
                obj = json.loads(line)
                messages = obj.get("messages", [])
    
                # Convert messages to Gemini format
                # Input: {"messages": [{"role": "user", "content": "..."}, {"role": "model", "content": "..."}]}
                # Output: {"contents": [{"role": "user", "parts": [{"text": "..."}]}, {"role": "model", "parts": [{"text": "..."}]}]}
    
                contents = []
                for msg in messages:
                    role = msg["role"]
                    content = msg["content"]
                    contents.append({
                        "role": role,
                        "parts": [{"text": content}]
                    })
    
                converted_data.append({"contents": contents})
    
        with open(output_file, 'w') as f:
            for item in converted_data:
                f.write(json.dumps(item) + "\n")
    
        print(f"Saved {len(converted_data)} examples to {output_file}")
    
    def upload_to_gcs(local_file, destination_blob_name):
        print(f"Uploading {local_file} to gs://{BUCKET_NAME}/{destination_blob_name}...")
        storage_client = storage.Client(project=PROJECT_ID)
        bucket = storage_client.bucket(BUCKET_NAME)
        blob = bucket.blob(destination_blob_name)
        blob.upload_from_filename(local_file)
        print("Upload complete.")
    
    def main():
        download_data()
    
        # Process Training Data
        convert_to_gemini_format("sft_train_samples.jsonl", "train_gemini.jsonl")
        upload_to_gcs("train_gemini.jsonl", "datasets/train/train_gemini.jsonl")
    
        # Process Validation Data
        convert_to_gemini_format("sft_val_samples.jsonl", "val_gemini.jsonl")
        upload_to_gcs("val_gemini.jsonl", "datasets/val/val_gemini.jsonl")
    
        print("Data preparation complete!")
    
    if __name__ == "__main__":
        main()
    
  3. Terminalde veri hazırlama komut dosyasını çalıştırın.
    python prepare_data.py
    

7. Temel performans oluşturma

İnce ayar yapmadan önce bir karşılaştırma yapmanız gerekir. ROUGE puanlarını kullanarak temel gemini-3.5-flash modelinin özetleme görevindeki performansını ölçeceksiniz.

  1. Terminalde evaluate.py adlı bir dosya oluşturun.
    cloudshell edit evaluate.py
    
  2. Aşağıdaki kodu evaluate.py dosyasına yapıştırın.
    import argparse
    import json
    import os
    import pandas as pd
    from google import genai
    from google.genai import types
    from rouge_score import rouge_scorer
    from tqdm import tqdm
    import matplotlib.pyplot as plt
    import time
    
    # Configuration for Google Gen AI SDK
    PROJECT_ID = os.environ.get("PROJECT_ID", "")
    
    def get_client(model_name):
        os.environ["GOOGLE_GENAI_USE_ENTERPRISE"] = "true"
        os.environ["GOOGLE_CLOUD_PROJECT"] = PROJECT_ID
        if "locations/" in model_name:
            parts = model_name.split("/")
            loc = parts[parts.index("locations") + 1]
            if loc == "us":
                loc = "us-central1"
        else:
            loc = os.environ.get("LOCATION", "global")
        os.environ["GOOGLE_CLOUD_LOCATION"] = loc
        return genai.Client()
    
    def evaluate(model_name, test_file, max_samples=50, output_json="results.json"):
        print(f"Evaluating model: {model_name}")
        client = get_client(model_name)
    
        # Load Test Data
        test_df = pd.read_csv(test_file)
        test_df = test_df.head(max_samples)
    
        config = types.GenerateContentConfig(
            temperature=0.1,
            max_output_tokens=1024,
        )
    
        scorer = rouge_scorer.RougeScorer(['rouge1', 'rouge2', 'rougeL'], use_stemmer=True)
        results = []
    
        for index, row in tqdm(test_df.iterrows(), total=len(test_df)):
            input_text = row['input_text']
            reference_summary = row['output_text']
    
            try:
                response = client.models.generate_content(
                    model=model_name,
                    contents=input_text,
                    config=config,
                )
                generated_summary = response.text
    
                scores = scorer.score(reference_summary, generated_summary)
    
                results.append({
                    "generated": generated_summary,
                    "reference": reference_summary,
                    "rouge1": scores['rouge1'].fmeasure,
                    "rouge2": scores['rouge2'].fmeasure,
                    "rougeL": scores['rougeL'].fmeasure
                })
            except Exception as e:
                print(f"Error processing example {index}: {e}")
                # Sleep briefly to avoid quota issues if hitting limits
                time.sleep(1)
    
        # Save results
        with open(output_json, 'w') as f:
            json.dump(results, f, indent=2)
    
        return pd.DataFrame(results)
    
    def plot_results(df, title, filename):
        os.makedirs("plots", exist_ok=True)
    
        metrics = ['rouge1', 'rouge2', 'rougeL']
        fig, axes = plt.subplots(1, 3, figsize=(15, 5))
    
        for i, metric in enumerate(metrics):
            axes[i].hist(df[metric], bins=10, alpha=0.7, color='skyblue', edgecolor='black')
            axes[i].set_title(f'{metric} Distribution')
            axes[i].set_xlabel('Score')
            axes[i].set_ylabel('Count')
    
        plt.suptitle(title)
        plt.tight_layout()
        plt.savefig(f"plots/{filename}")
        print(f"Plot saved to plots/{filename}")
    
    def compare_results(baseline_file, tuned_file):
        with open(baseline_file, 'r') as f:
            baseline_data = pd.DataFrame(json.load(f))
        with open(tuned_file, 'r') as f:
            tuned_data = pd.DataFrame(json.load(f))
    
        print("\n--- Comparison ---")
        metrics = ['rouge1', 'rouge2', 'rougeL']
        for metric in metrics:
            base_mean = baseline_data[metric].mean()
            tuned_mean = tuned_data[metric].mean()
            diff = tuned_mean - base_mean
            print(f"{metric}: Base={base_mean:.4f}, Tuned={tuned_mean:.4f}, Diff={diff:+.4f}")
    
        # Comparative Plot
        os.makedirs("plots", exist_ok=True)
        comparison_df = pd.DataFrame({
            'Metric': metrics,
            'Baseline': [baseline_data[m].mean() for m in metrics],
            'Tuned': [tuned_data[m].mean() for m in metrics]
        })
    
        comparison_df.plot(x='Metric', y=['Baseline', 'Tuned'], kind='bar', figsize=(10, 6))
        plt.title('Baseline vs Tuned Model Performance')
        plt.ylabel('Average Score')
        plt.xticks(rotation=0)
        plt.tight_layout()
        plt.savefig("plots/comparison.png")
        print("Comparison plot saved to plots/comparison.png")
    
    def main():
        parser = argparse.ArgumentParser()
        parser.add_argument("--model", type=str, default="gemini-3.5-flash", help="Model resource name")
        parser.add_argument("--baseline", type=str, help="Path to baseline results json for comparison")
        parser.add_argument("--output", type=str, default="results.json", help="Output file for results")
        args = parser.parse_args()
    
        # Ensure test data exists (it was downloaded in prepare_data step)
        if not os.path.exists("sft_test_samples.csv"):
            # Fallback download if needed
            subprocess.run(["gsutil", "cp", "gs://github-repo/generative-ai/gemini/tuning/summarization/wikilingua/sft_test_samples.csv", "."], check=True)
    
        df = evaluate(args.model, "sft_test_samples.csv", output_json=args.output)
    
        print("\n--- Results Summary ---")
        print(df.describe())
    
        plot_filename = "baseline_dist.png" if not args.baseline else "tuned_dist.png"
        plot_results(df, f"ROUGE Scores - {args.model}", plot_filename)
    
        if args.baseline:
            compare_results(args.baseline, args.output)
    
    if __name__ == "__main__":
        main()
    
  3. Terminalde temel değerlendirmeyi çalıştırın.
    python evaluate.py --model "gemini-3.5-flash" --output "baseline.json"
    
    Bu işlem, baseline.json dosyası ve plots/baseline_dist.png biçiminde bir grafik oluşturur.

8. İnce ayarı yapılandırma ve başlatma

Şimdi Gemini Enterprise Agent Platform'da yönetilen bir ince ayar işi başlatacaksınız.

  1. Terminalde tune.py adlı bir dosya oluşturun.
    cloudshell edit tune.py
    
  2. Aşağıdaki kodu tune.py dosyasına yapıştırın.
    import os
    import time
    from google import genai
    from google.genai import types
    
    # Configuration for Google Gen AI SDK
    os.environ["GOOGLE_GENAI_USE_ENTERPRISE"] = "true"
    os.environ["GOOGLE_CLOUD_PROJECT"] = os.environ.get("PROJECT_ID", "")
    os.environ["GOOGLE_CLOUD_LOCATION"] = os.environ.get("REGION", "us-central1")
    
    BUCKET_NAME = os.environ["BUCKET_NAME"]
    client = genai.Client()
    
    def train():
        print("Launching fine-tuning job...")
    
        training_dataset = types.TuningDataset(
            gcs_uri=f"gs://{BUCKET_NAME}/datasets/train/train_gemini.jsonl"
        )
        validation_dataset = types.TuningValidationDataset(
            gcs_uri=f"gs://{BUCKET_NAME}/datasets/val/val_gemini.jsonl"
        )
    
        tuning_job = client.tunings.tune(
            base_model="gemini-3.5-flash",
            training_dataset=training_dataset,
            config=types.CreateTuningJobConfig(
                tuned_model_display_name="gemini-3.5-flash-wikilingua",
                validation_dataset=validation_dataset,
                adapter_size=types.AdapterSize.ADAPTER_SIZE_FOUR,
                epoch_count=1,
            ),
        )
    
        print(f"Job started: {tuning_job.name}")
        print("Waiting for job to complete... (this may take ~45 minutes)")
    
        running_states = {"JOB_STATE_PENDING", "JOB_STATE_RUNNING"}
        while tuning_job.state in running_states:
            time.sleep(60)
            tuning_job = client.tunings.get(name=tuning_job.name)
            print(f"Status: {tuning_job.state}")
    
        print("Job completed!")
        print(f"Tuned Model Endpoint: {tuning_job.tuned_model.endpoint}")
        return tuning_job.tuned_model.endpoint
    
    if __name__ == "__main__":
        train()
    
  3. Terminalde ince ayar komut dosyasını çalıştırın.
    python tune.py
    
    Not: Bu işlem yaklaşık 45 dakika sürebilir. İşi Gemini Enterprise Agent Platform Konsolu'nda izleyebilirsiniz.

9. Eğitim kodunu anlama

İşiniz çalışırken ince ayarın nasıl çalıştığını anlamak için tune.py komut dosyasına daha yakından bakalım.

Yönetilen Denetimli İnce Ayar

Komut dosyası, yönetilen bir ayarlama işi göndermek için vertexai.tuning.sft.train yöntemini kullanır. Bu, altyapı sağlama, eğitimi dağıtma ve kontrol noktalarını yönetme işlemlerinin karmaşıklığını ortadan kaldırır.

sft_tuning_job = sft.train(
    source_model="gemini-3.5-flash",
    train_dataset=f"gs://{BUCKET_NAME}/datasets/train/train_gemini.jsonl",
    # ...
)

LoRA Yapılandırması

Açık kaynak çerçevelerinde olduğu gibi LoraConfig'ı manuel olarak tanımlamak yerine, Gemini Enterprise Agent Platform bu işlemi birkaç temel parametreye indirger:

  • adapter_size: Bu parametre (komut dosyamızda 4 olarak ayarlanır), LoRA bağdaştırıcılarının sıralamasını kontrol eder. Daha büyük bir boyut, modelin daha karmaşık uyarlamaları öğrenmesine olanak tanır ancak eğitilebilir parametrelerin sayısını artırır.
  • epochs: Bu laboratuvarda eğitim süresini kısa tutmak için (~20 dakika) bu değeri 1 olarak ayarladık. Üretim senaryosunda, modelin verilerinizden daha derinlemesine öğrenmesini sağlamak için bu değeri artırabilirsiniz. Ancak aşırı uyum konusunda dikkatli olmanız gerekir.

Model Seçimi

source_model="gemini-3.5-flash" değerini açıkça belirtiriz. Gemini Enterprise Agent Platform, Gemini'ın çeşitli sürümlerini destekler. Belirli bir sürümü sabitlemek, işlem hattınızın kararlı ve tekrarlanabilir kalmasını sağlar.

10. Model karşılaştırma

İnce ayar işi tamamlandıktan sonra yeni modelinizin performansını temel performansla karşılaştırabilirsiniz.

  1. Hassaslaştırılmış modelinizin uç noktasını alın. tune.py senaryosunun sonunda yazdırılır. Bu, projects/.../locations/.../endpoints/... gibi görünür.
  2. Değerlendirme komut dosyasını tekrar çalıştırın. Bu kez karşılaştırma için ayarlanmış modelinizi ve temel sonuçları iletin.
    # Replace [YOUR_TUNED_MODEL_ENDPOINT] with the actual endpoint name
    export TUNED_MODEL="projects/[YOUR_PROJECT_ID]/locations/[YOUR_REGION]/endpoints/[YOUR_ENDPOINT_ID]"
    
    python evaluate.py --model "$TUNED_MODEL" --baseline "baseline.json" --output "tuned.json"
    
  3. Sonuçları görüntüleyin. Komut dosyası, ROUGE puanlarının karşılaştırmasını verir ve iyileşmeyi gösteren bir plots/comparison.png grafiği oluşturur.Grafikleri Cloud Shell Düzenleyici'de plots klasörünü açarak görüntüleyebilirsiniz.

11. Temizleme

Ücret ödememek için oluşturduğunuz kaynakları silin.

  1. Terminalde Cloud Storage paketini ve ayarlanmış modeli silin.
    gcloud storage rm -r gs://$BUCKET_NAME
    # Note: You can delete the model endpoint from the Gemini Enterprise Agent Platform Console
    

12. Tebrikler!

Gemini Enterprise Agent Platform'da Gemini 3.5 Flash'ı başarıyla ince ayarladınız.

Özet

Bu laboratuvarda şunları öğreneceksiniz:

  • Gemini ince ayarı için JSONL biçiminde bir veri kümesi hazırladıysanız.
  • Temel Gemini 3.5 Flash modelini kullanarak bir temel oluşturdu.
  • Gemini Enterprise Agent Platform'da denetimli ince ayar işi başlattıysanız.
  • İnce ayarlı modeli, temel modelle karşılaştırarak değerlendirdik.

Sırada ne var?

Bu laboratuvar, Google Cloud ile Üretime Hazır Yapay Zeka öğrenme rotasının bir parçasıdır.

Prototip aşamasından üretime geçiş yapmanıza yardımcı olacak tüm müfredatı keşfedin.

İlerlemenizi #ProductionReadyAI hashtag'iyle paylaşın.