Menjalankan pipeline evaluasi berbasis komputasi

Anda dapat mengevaluasi performa model dasar dan model AI generatif yang telah disesuaikan di Gemini Enterprise Agent Platform. Model dievaluasi menggunakan kumpulan metrik terhadap set data evaluasi yang Anda berikan. Halaman ini menjelaskan cara kerja evaluasi model berbasis komputasi melalui layanan pipeline evaluasi, cara membuat dan memformat set data evaluasi, serta cara melakukan evaluasi menggunakan Google Cloud konsol, Agent Platform API, atau Agent Platform SDK untuk Python.

Cara kerja evaluasi model berbasis komputasi

Untuk mengevaluasi performa model, Anda harus membuat set data evaluasi yang berisi pasangan perintah dan kebenaran nyata terlebih dahulu. Untuk setiap pasangan, perintah adalah input yang ingin Anda evaluasi, dan kebenaran nyata adalah respons ideal untuk perintah tersebut. Selama evaluasi, perintah dalam setiap pasangan set data evaluasi diteruskan ke model untuk menghasilkan output. Output yang dihasilkan oleh model dan kebenaran nyata dari set data evaluasi digunakan untuk mengomputasi metrik evaluasi.

Jenis metrik yang digunakan untuk evaluasi bergantung pada tugas yang Anda evaluasi. Tabel berikut menunjukkan tugas yang didukung dan metrik yang digunakan untuk mengevaluasi setiap tugas:

Tugas Metrik
Klasifikasi Mikro-F1, Makro-F1, Per class F1
Perangkuman ROUGE-L
Proses menjawab pertanyaan Pencocokan Persis
Pembuatan teks BLEU, ROUGE-L

Model yang didukung

Evaluasi model didukung untuk model berikut:

  • text-bison: Versi dasar dan yang disesuaikan.

  • Gemini: Semua tugas kecuali klasifikasi.

Menyiapkan set data evaluasi

Set data evaluasi yang digunakan untuk evaluasi model mencakup pasangan perintah dan kebenaran nyata yang selaras dengan tugas yang ingin Anda evaluasi. Set data Anda harus menyertakan minimal 1 pasangan perintah dan kebenaran nyata serta minimal 10 pasangan untuk metrik yang bermakna. Semakin banyak contoh yang Anda berikan, semakin bermakna hasilnya.

Format set data

Set data evaluasi Anda harus ada dalam format JSON Lines (JSONL) dengan setiap baris berisi satu pasangan perintah dan kebenaran nyata yang ditentukan di masing-masing kolom input_text dan output_text. Kolom input_text berisi perintah yang ingin Anda evaluasi dan kolom output_text berisi respons ideal untuk perintah tersebut.

Panjang token maksimum untuk input_text adalah 8.192, dan panjang token maksimum untuk output_text adalah 1.024.

Mengupload set data evaluasi ke Cloud Storage

Anda dapat membuat bucket Cloud Storage baru atau menggunakan bucket yang sudah ada untuk menyimpan file set data. Bucket harus berada di region yang sama dengan model.

Setelah bucket siap, upload file set data Anda ke bucket.

Melakukan evaluasi model

Anda dapat mengevaluasi model menggunakan REST API atau Google Cloud konsol.

REST

Untuk membuat tugas evaluasi model, kirim permintaan POST menggunakan metode pipelineJobs.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: Google Cloud Project yang menjalankan komponen pipeline.
  • PIPELINEJOB_DISPLAYNAME: Nama tampilan untuk pipelineJob.
  • LOCATION: Region untuk menjalankan komponen pipeline. Saat ini, hanya us-central1 yang didukung.
  • DATASET_URI: Cloud Storage URI dari set data referensi Anda. Anda dapat menentukan satu atau beberapa URI. Parameter ini mendukung karakter pengganti. Untuk mempelajari parameter ini lebih lanjut, lihat InputConfig.
  • OUTPUT_DIR: URI Cloud Storage untuk menyimpan output evaluasi.
  • MODEL_NAME: Tentukan model penayang atau resource model yang disesuaikan seperti berikut:
    • Model penayang: publishers/google/models/MODEL@MODEL_VERSION

      Contoh: publishers/google/models/text-bison@002

    • Model yang disesuaikan: projects/PROJECT_NUMBER/locations/LOCATION/models/ENDPOINT_ID

      Contoh: projects/123456789012/locations/us-central1/models/1234567890123456789

    Tugas evaluasi tidak memengaruhi deployment model atau resource yang ada.

  • EVALUATION_TASK: Tugas yang ingin Anda gunakan untuk mengevaluasi model. Tugas evaluasi mengomputasi kumpulan metrik yang relevan dengan tugas spesifik tersebut. Nilai yang dapat diterima mencakup hal berikut:
    • summarization
    • question-answering
    • text-generation
    • classification
  • INSTANCES_FORMAT: Format set data Anda. Saat ini, hanya jsonl yang didukung. Untuk mempelajari parameter ini lebih lanjut, lihat InputConfig.
  • PREDICTIONS_FORMAT: Format output evaluasi. Saat ini, hanya jsonl yang didukung. Untuk mempelajari parameter ini lebih lanjut, lihat InputConfig.
  • MACHINE_TYPE: (Opsional) Jenis mesin untuk menjalankan tugas evaluasi. Nilai defaultnya adalah e2-highmem-16. Untuk mengetahui daftar jenis mesin yang didukung, lihat Jenis mesin.
  • SERVICE_ACCOUNT: (Opsional) Akun layanan yang akan digunakan untuk menjalankan tugas evaluasi. Untuk mempelajari cara membuat akun layanan kustom, lihat Mengonfigurasi akun layanan dengan izin terperinci. Jika tidak ditentukan, Agen Layanan Kode Kustom Gemini Enterprise Agent Platform akan digunakan.
  • NETWORK: (Opsional) Nama jaringan Compute Engine yang sepenuhnya memenuhi syarat untuk di-peering dengan tugas evaluasi. Format nama jaringannya adalah projects/PROJECT_NUMBER/global/networks/NETWORK_NAME. Jika menentukan kolom ini, Anda harus memiliki VPC Jaringan Peering untuk Gemini Enterprise Agent Platform. Jika tidak ditentukan, tugas evaluasi tidak di-peering dengan jaringan apa pun.
  • KEY_NAME: (Opsional) Nama kunci enkripsi yang dikelola pelanggan (CMEK). Jika dikonfigurasi, resource yang dibuat oleh tugas evaluasi akan dienkripsi menggunakan kunci enkripsi yang disediakan. Format nama kunci adalah projects/PROJECT_ID/locations/REGION/keyRings/KEY_RING/cryptoKeys/KEY. Kunci tersebut harus berada di region yang sama dengan tugas evaluasi.

Metode HTTP dan URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/pipelineJobs

Meminta isi JSON: 

{
  "displayName": "PIPELINEJOB_DISPLAYNAME",
  "runtimeConfig": {
    "gcsOutputDirectory": "gs://OUTPUT_DIR",
    "parameterValues": {
      "project": "PROJECT_ID",
      "location": "LOCATION",
      "batch_predict_gcs_source_uris": ["gs://DATASET_URI"],
      "batch_predict_gcs_destination_output_uri": "gs://OUTPUT_DIR",
      "model_name": "MODEL_NAME",
      "evaluation_task": "EVALUATION_TASK",
      "batch_predict_instances_format": "INSTANCES_FORMAT",
      "batch_predict_predictions_format: "PREDICTIONS_FORMAT",
      "machine_type": "MACHINE_TYPE",
      "service_account": "SERVICE_ACCOUNT",
      "network": "NETWORK",
      "encryption_spec_key_name": "KEY_NAME"
    }
  },
  "templateUri": "https://us-kfp.pkg.dev/vertex-evaluation/pipeline-templates/evaluation-llm-text-generation-pipeline/1.0.1"
}

Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

curl

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/pipelineJobs"

PowerShell

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/pipelineJobs" | Select-Object -Expand Content

Anda akan menerima respons JSON yang mirip dengan yang berikut ini: Perhatikan bahwa pipelineSpec telah dipotong untuk menghemat ruang penyimpanan.

Contoh perintah curl

PROJECT_ID=myproject
REGION=us-central1
MODEL_NAME=publishers/google/models/text-bison@002
TEST_DATASET_URI=gs://my-gcs-bucket-uri/dataset.jsonl
OUTPUT_DIR=gs://my-gcs-bucket-uri/output

curl \
-X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
"https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${REGION}/pipelineJobs" -d \
$'{
  "displayName": "evaluation-llm-text-generation-pipeline",
  "runtimeConfig": {
    "gcsOutputDirectory": "'${OUTPUT_DIR}'",
    "parameterValues": {
      "project": "'${PROJECT_ID}'",
      "location": "'${REGION}'",
      "batch_predict_gcs_source_uris": ["'${TEST_DATASET_URI}'"],
      "batch_predict_gcs_destination_output_uri": "'${OUTPUT_DIR}'",
      "model_name": "'${MODEL_NAME}'",
    }
  },
  "templateUri": "https://us-kfp.pkg.dev/vertex-evaluation/pipeline-templates/evaluation-llm-text-generation-pipeline/1.0.1"
}'

Python

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Python di Panduan memulai Agent Platform menggunakan library klien.

Untuk melakukan autentikasi ke Agent Platform, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 

import os

import vertexai
from vertexai.evaluation import EvalResult, EvalTask

# TODO (Developer) Set environment variables
PROJECT_ID = os.getenv("GOOGLE_CLOUD_PROJECT")
LOCATION_ID = os.getenv("LOCATION_ID", "us-central1")
MODEL_NAME = os.getenv("MODEL_NAME", "gemini-2.5-flash")


def evaluate_model() -> EvalResult:
    """Evaluate the performance of a generative AI model."""

    vertexai.init(project=PROJECT_ID, location=LOCATION_ID)

    # Dataset URI containing input prompts and ground truth labels
    dataset_uri = "gs://cloud-samples-data/ai-platform/generative_ai/llm_classification_bp_input_prompts_with_ground_truth.jsonl"

    metric_column_mapping = {"reference": "ground_truth"}

    # Define evaluation task
    eval_task = EvalTask(
        dataset=dataset_uri,
        metrics=["exact_match"],
        experiment="gemini-classification-eval",
        metric_column_mapping=metric_column_mapping,
    )

    # Define a prompt template so the generative Gemini model produces formatted labels
    prompt_template = (
        "Classify the following text into exactly one category from "
        "[nature, news, sports, health, startups]. Return only the category name:\n\n{prompt}"
    )

    # Evaluate using a modern Gemini model
    eval_result = eval_task.evaluate(
        model=MODEL_NAME,
        prompt_template=prompt_template,
    )

    print("=== SUMMARY METRICS ===")
    print(eval_result.summary_metrics)

    print("\n=== METRICS TABLE SAMPLE ===")
    print(eval_result.metrics_table.head())

    return eval_result

Konsol

Untuk membuat tugas evaluasi model menggunakan Google Cloud konsol, lakukan langkah-langkah berikut:

  1. Di Google Cloud konsol, buka halaman Gemini Enterprise Agent Platform Model Registry.

    Buka Gemini Enterprise Agent Platform Model Registry

  2. Klik nama model yang ingin dievaluasi.
  3. Di tab Evaluasi, klik Buat evaluasi dan konfigurasikan sebagai berikut:
    • Tujuan: Pilih tugas yang ingin dievaluasi.
    • Kolom target: (Khusus klasifikasi) Masukkan kolom target untuk prediksi. Contoh: ground_truth.
    • Source path: Masukkan atau pilih URI set data evaluasi Anda.
    • Format output: Masukkan format output evaluasi. Saat ini, hanya jsonl yang didukung.
    • Jalur Cloud Storage: Masukkan atau pilih URI untuk menyimpan output evaluasi.
    • Nama class: (Khusus klasifikasi) Masukkan daftar kemungkinan nama class.
    • Jumlah node komputasi: Masukkan jumlah node komputasi untuk menjalankan tugas evaluasi.
    • Jenis mesin: Pilih jenis mesin yang akan digunakan untuk menjalankan tugas evaluasi.
  4. Klik Mulai evaluasi

Melihat hasil evaluasi

Anda dapat menemukan hasil evaluasi di direktori output Cloud Storage yang Anda tentukan saat membuat tugas evaluasi. File tersebut diberi nama evaluation_metrics.json.

Untuk model yang disesuaikan, Anda juga dapat melihat hasil evaluasi di Google Cloud konsol:

  1. Di bagian Agent Platform pada Google Cloud konsol, buka halaman Gemini Enterprise Agent Platform Model Registry.

    Buka Gemini Enterprise Agent Platform Model Registry

  2. Klik nama model untuk melihat metrik evaluasinya.

  3. Di tab Evaluasi, klik nama proses evaluasi yang ingin Anda lihat.

Langkah berikutnya