Tutorial: Melakukan evaluasi menggunakan Klien GenAI di Vertex AI SDK

Halaman ini menunjukkan cara mengevaluasi model dan aplikasi AI generatif Anda di berbagai kasus penggunaan menggunakan Klien GenAI di Vertex AI SDK.

Klien GenAI di layanan evaluasi AI generatif Vertex AI SDK untuk Gen AI memungkinkan Anda mengukur performa perintah, model dasar, dan agen AI kompleks terhadap kriteria yang paling relevan. Anda dapat mengevaluasi sejumlah kandidat sekaligus untuk menyempurnakan perintah, memilih model terbaik, atau melakukan iterasi pada agen yang kompleks.

Anda dapat melakukan hal berikut dengan Klien GenAI di Vertex AI SDK:

  • Bandingkan beberapa model atau konfigurasi secara berdampingan dalam satu proses, menggunakan perhitungan rasio kemenangan untuk memandu keputusan Anda.

  • Gunakan dukungan bawaan untuk mengevaluasi dan membandingkan dengan model pihak ketiga populer tanpa integrasi yang rumit.

  • Tangani set data besar dengan lebih efisien dan lakukan tugas evaluasi berskala besar menggunakan evaluasi batch asinkron.

Contoh end-to-end

Klien AI Generatif di Vertex AI SDK menggunakan alur kerja dua langkah: membuat respons model dan mengevaluasi respons. Contoh menyeluruh berikut menunjukkan cara kerja Klien GenAI di Vertex AI SDK:

  1. Instal Vertex AI SDK untuk Python:

    pip install --upgrade google-cloud-aiplatform[evaluation]

  2. Siapkan set data evaluasi:

    import pandas as pd
from vertexai import Client, types

client = Client(project="your-project-id", location="us-central1")

prompts_df = pd.DataFrame({"prompt": ["How does AI work?"]})

  3. Jalankan evaluasi:

    # Evaluating a single model.
eval_dataset = client.evals.run_inference(
    model="gemini-2.5-flash",
    src=prompts_df,
)
eval_result = client.evals.evaluate(
    dataset=eval_dataset,
    metrics=[types.RubricMetric.GENERAL_QUALITY]
)
eval_result.show()

  4. Membandingkan beberapa kandidat:

    # Comparing multiple candidates.
candidate_1 = client.evals.run_inference(
    model="gemini-2.0-flash", src=prompts_df
)
candidate_2 = client.evals.run_inference(
    model="gemini-2.5-flash", src=prompts_df
)
comparison_result = client.evals.evaluate(
    dataset=[candidate_1, candidate_2],
    metrics=[types.RubricMetric.GENERAL_QUALITY]
)
comparison_result.show()

Tentukan metrik Anda

Tentukan metrik Anda sebagai metrik berbasis LLM atau metrik berbasis komputasi.

Metrik berbasis LLM

Metrik berbasis LLM menggunakan model bahasa besar (LLM) sebagai "penilai" untuk mengevaluasi kriteria yang rumit seperti gaya atau kualitas penulisan, yang sulit diukur hanya dengan algoritma.

Menggunakan metrik berbasis rubrik terkelola

Klien GenAI di Vertex AI SDK menyediakan berbagai metrik berbasis model siap pakai seperti GENERAL_QUALITY, SAFETY, dan INSTRUCTION_FOLLOWING. Anda dapat mengaksesnya melalui class RubricMetric. Definisi metrik berbasis rubrik terkelola dimuat sesuai permintaan dari library terpusat untuk menciptakan konsistensi di seluruh versi metrik berbasis rubrik.

# Assumes 'eval_dataset' is an EvaluationDataset object created via run_inference()

eval_result = client.evals.evaluate(
    dataset=eval_dataset,
    metrics=[
        types.RubricMetric.GENERAL_QUALITY,
        types.RubricMetric.INSTRUCTION_FOLLOWING,
    ]
)

Untuk membuat hasil yang konsisten di berbagai versi SDK, Anda dapat menyematkan metrik ke versi tertentu. Secara default, versi terbaru akan digunakan.

# Pin to a specific version of a pre-built metric
instruction_following_v1 = types.RubricMetric.INSTRUCTION_FOLLOWING(version='v1')

Menyesuaikan metrik LLM

Untuk kasus penggunaan yang memerlukan kriteria khusus, Anda dapat menentukan metrik berbasis LLM sendiri dengan membuat instance class LLMMetric. Tindakan ini memberi Anda kontrol penuh atas template prompt evaluasi, model penilai, dan parameter lainnya.

Class helper MetricPromptBuilder membuat template perintah terstruktur untuk model penilai dengan memungkinkan Anda menentukan instruction, criteria, dan rating_scores secara terpisah.

# Define a custom metric to evaluate language simplicity
simplicity_metric = types.LLMMetric(
    name='language_simplicity',
    prompt_template=types.MetricPromptBuilder(
        instruction="Evaluate the story's simplicity for a 5-year-old.",
        criteria={
            "Vocabulary": "Uses simple words.",
            "Sentences": "Uses short sentences.",
        },
        rating_scores={
            "5": "Excellent: Very simple, ideal for a 5-year-old.",
            "4": "Good: Mostly simple, with minor complex parts.",
            "3": "Fair: Mix of simple and complex; may be challenging for a 5-year-old.",
            "2": "Poor: Largely too complex, with difficult words/sentences.",
            "1": "Very Poor: Very complex, unsuitable for a 5-year-old."
        }
    )
)
# Use the custom metric in an evaluation
eval_result = client.evals.evaluate(
    dataset=inference_results,
    metrics=[simplicity_metric]
)

Metrik berbasis komputasi dan fungsi kustom

Metrik berbasis komputasi secara matematis membandingkan output model dengan kebenaran dasar atau referensi. Metrik ini, yang dihitung dengan kode menggunakan class Metric dasar, mendukung algoritma berbasis komputasi yang telah ditentukan sebelumnya seperti exact_match, bleu, dan rouge_1. Untuk menggunakan metrik berbasis komputasi, buat instance class Metric dengan nama metrik. Metrik ini memerlukan kolom reference dalam set data Anda untuk perbandingan.

eval_result = client.evals.evaluate(
    dataset=eval_dataset,
    metrics=[
        types.Metric(name='exact_match'),
        types.Metric(name='bleu'),
        types.Metric(name='rouge_1'),
    ]
)

Menerapkan metrik fungsi kustom

Anda juga dapat menerapkan logika evaluasi kustom dengan meneruskan fungsi Python kustom ke parameter custom_function untuk kontrol penuh. Klien GenAI di Vertex AI SDK menjalankan fungsi ini untuk setiap baris set data Anda.

# Define a custom function to check for the presence of a keyword
def contains_keyword(instance: dict) -> dict:
    keyword = "magic"
    response_text = instance.get("response", "")
    score = 1.0 if keyword in response_text.lower() else 0.0
    return {"score": score}

keyword_metric = types.Metric(
    name="keyword_check",
    custom_function=contains_keyword
)


eval_result = client.evals.evaluate(
    dataset=eval_dataset,
    metrics=[keyword_metric]
)

Menyiapkan set data evaluasi

Klien GenAI di Vertex AI SDK secara otomatis mendeteksi dan menangani beberapa format data umum. Artinya, Anda sering kali dapat menggunakan data apa adanya tanpa perlu melakukan konversi manual, baik saat membuat respons baru dengan run_inference maupun mengevaluasi respons yang ada dengan evaluate.

Klien GenAI di Vertex AI SDK mendukung format berikut:

  • Pandas DataFrame (format yang diratakan)

    Untuk evaluasi yang mudah, Anda dapat menggunakan pandas.DataFrame. Klien GenAI di Vertex AI SDK mencari nama kolom umum seperti prompt, response, dan reference. Format ini sepenuhnya kompatibel dengan versi lama.

    import pandas as pd

# Simple DataFrame with prompts and ground truth references
prompts_df = pd.DataFrame({
    "prompt": [
        "What is the capital of France?",
        "Who wrote 'Hamlet'?",
    ],
    "reference": [
        "Paris",
        "William Shakespeare",
    ]
})

# Generate responses using the DataFrame as a source
inference_results = client.evals.run_inference(
    model="gemini-2.5-flash",
    src=prompts_df
)
inference_results.show()

  • Format prediksi batch Gemini

    Anda dapat langsung menggunakan output tugas prediksi batch Vertex AI, yang biasanya berupa file JSONL yang disimpan di Cloud Storage, dengan setiap baris berisi objek request dan response. Klien GenAI di Vertex AI SDK mengurai struktur ini secara otomatis untuk menyediakan integrasi dengan layanan Vertex AI lainnya.

    Contoh satu baris dalam file jsonl:

    {"request": {"contents": [{"role": "user", "parts": [{"text": "Why is the sky blue?"}]}]}, "response": {"candidates": [{"content": {"role": "model", "parts": [{"text": "The sky appears blue to the human eye as a result of a phenomenon known as Rayleigh scattering."}]}}]}}

    Kemudian, Anda dapat mengevaluasi respons yang telah dibuat sebelumnya dari tugas batch secara langsung:

    # Cloud Storage path to your batch prediction output file
batch_job_output_uri = "gs://path/to/your/batch_output.jsonl"

# Evaluate the results directly from Cloud Storage
eval_result = client.evals.evaluate(
    dataset=batch_job_output_uri,
    metrics=[
        types.RubricMetric.COHERENCE,
        types.RubricMetric.FLUENCY,
    ]
)
eval_result.show()

  • Format Penyelesaian Chat OpenAI

    Untuk mengevaluasi atau membandingkan dengan model pihak ketiga, Klien GenAI di Vertex AI SDK mendukung format Penyelesaian Chat OpenAI. Anda dapat menyediakan set data dengan setiap baris berupa objek JSON yang disusun seperti permintaan OpenAI API. Klien GenAI di Vertex AI SDK otomatis mendeteksi format ini.

    Contoh satu baris dalam format ini:

    {"request": {"messages": [{"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "What's the capital of France?"}], "model": "gpt-4o"}}

    Anda dapat menggunakan data ini untuk membuat respons dari model pihak ketiga dan mengevaluasi respons:

    # Ensure your third-party API key is set
# e.g., os.environ['OPENAI_API_KEY'] = 'Your API Key'

openai_request_uri = "gs://path/to/your/openai_requests.jsonl"

# Generate responses using a LiteLLM-supported model string
openai_responses = client.evals.run_inference(
    model="gpt-4o",
    src=openai_request_uri,
)

# The resulting dataset can then be evaluated
eval_result = client.evals.evaluate(
    dataset=openai_responses,
    metrics=[
        types.RubricMetric.GENERAL_QUALITY,
        types.RubricMetric.FLUENCY,
    ]
)

eval_result.show()

Jalankan evaluasi

Klien GenAI di Vertex AI SDK menggunakan proses berbasis klien berikut untuk menjalankan evaluasi:

  1. run_inference(): Menghasilkan respons dari model Anda untuk serangkaian perintah tertentu.

  2. evaluate(): Menghitung metrik pada respons yang dihasilkan.

eval_dataset = client.evals.run_inference(
    model="gemini-2.5-flash",
src="gs://vertex-evaluation-llm-dataset-us-central1/genai_eval_sdk/test_prompts.jsonl",
)
eval_dataset.show()


eval_result = client.evals.evaluate(
    dataset=eval_dataset,
    metrics=[
        types.RubricMetric.GENERAL_QUALITY,
        types.RubricMetric.QUESTION_ANSWERING_QUALITY,
        types.Metric(name='bleu'),
        types.Metric(name='rouge_1'),
    ]
)
eval_result.show()

Untuk menganalisis performa beberapa model atau sistem AI dalam satu evaluasi, buat respons untuk setiap kandidat dan teruskan dalam daftar ke metode evaluate():

inference_result_1 = client.evals.run_inference(
    model="gemini-2.0-flash",
    src=prompts_df,
)
inference_result_2 = client.evals.run_inference(
    model="gemini-2.5-flash",
    src=prompts_df,
)

# Compare the responses against each other
comparison_result = client.evals.evaluate(
    dataset=[inference_result_1, inference_result_2],
    metrics=[
        types.RubricMetric.TEXT_QUALITY,
        types.RubricMetric.INSTRUCTION_FOLLOWING,
    ]
)

comparison_result.show()

Evaluasi asinkron dan berskala besar

Untuk set data besar, Klien GenAI di Vertex AI SDK menyediakan metode evaluasi batch asinkron yang berjalan lama. Cara ini ideal untuk skenario saat Anda tidak memerlukan hasil langsung dan ingin memindahkan komputasi.

Metode batch_evaluate() menampilkan objek operasi yang dapat Anda polling untuk melacak progresnya. Parameter kompatibel dengan metode evaluate().

GCS_DEST_BUCKET = "gs://your-gcs-bucket/batch_eval_results/"

inference_result_saved = client.evals.run_inference(
    model="gemini-2.0-flash",
    src=prompts_df,
    config={'dest': GCS_DEST_BUCKET}
)
print(f"Eval dataset uploaded to: {inference_result_saved.gcs_source}")

batch_eval_job  = client.evals.batch_evaluate(
   dataset = inference_result_saved,
   metrics = [
        types.RubricMetric.TEXT_QUALITY,
        types.RubricMetric.INSTRUCTION_FOLLOWING,
        types.RubricMetric.FLUENCY,
        types.Metric(name='bleu'),
    ],
   dest=GCS_DEST_BUCKET
)

Mengevaluasi model pihak ketiga

Anda dapat menggunakan Klien GenAI di Vertex AI SDK untuk mengevaluasi dan membandingkan model dari penyedia seperti OpenAI dengan meneruskan string nama model ke metode run_inference. Klien GenAI di Vertex AI SDK menggunakan library litellm untuk memanggil API model.

Pastikan untuk menetapkan kunci API yang diperlukan sebagai variabel lingkungan (OPENAI_API_KEY):

import os

# Set your third-party model API key
os.environ['OPENAI_API_KEY'] = 'YOUR_OPENAI_API_KEY'

# Run inference on an OpenAI model
gpt_response = client.evals.run_inference(
    model='gpt-4o',
    src=prompt_df
)

# You can now evaluate the responses
eval_result = client.evals.evaluate(
    dataset=gpt_response,
    metrics=[types.RubricMetric.GENERAL_QUALITY]
)

eval_result.show()

Visualisasi

GenAI Client di Vertex AI SDK memungkinkan Anda memvisualisasikan hasil secara langsung dalam lingkungan pengembangan, seperti notebook Colab atau Jupyter. Metode .show(), yang tersedia di objek EvaluationDataset dan EvaluationResult, merender laporan HTML interaktif untuk analisis.

Memvisualisasikan hasil inferensi

Setelah membuat respons dengan run_inference(), Anda dapat memanggil .show() pada objek EvaluationDataset yang dihasilkan untuk memeriksa output model bersama dengan perintah dan referensi asli Anda. Hal ini berguna untuk pemeriksaan kualitas cepat sebelum menjalankan evaluasi lengkap.

# First, run inference to get an EvaluationDataset
gpt_response = client.evals.run_inference(
    model='gpt-4o',
    src=prompt_df
)

# Now, visualize the inference results
gpt_response.show()

Tabel akan ditampilkan dengan setiap perintah, referensi yang sesuai (jika ada), dan respons yang baru dibuat.

Memvisualisasikan hasil inferensi

Memvisualisasikan laporan evaluasi

Saat Anda memanggil .show() pada objek EvaluationResult, laporan akan ditampilkan dengan dua bagian utama:

  • Metrik ringkasan: Tampilan gabungan dari semua metrik, yang menampilkan skor rata-rata dan simpangan baku di seluruh set data.

  • Hasil mendetail: Perincian kasus per kasus, yang memungkinkan Anda memeriksa perintah, referensi, respons kandidat, serta skor dan penjelasan spesifik untuk setiap metrik.

# First, run an evaluation on a single candidate
eval_result = client.evals.evaluate(
    dataset=eval_dataset,
    metrics=[types.RubricMetric.TEXT_QUALITY]
)

# Visualize the detailed evaluation report
eval_result.show()

Laporan evaluasi

Format laporan akan disesuaikan, bergantung pada apakah Anda mengevaluasi satu kandidat atau membandingkan beberapa kandidat. Untuk evaluasi multi-kandidat, laporan memberikan tampilan berdampingan dan menyertakan perhitungan rasio kemenangan/seri dalam tabel ringkasan.

Untuk semua laporan, Anda dapat meluaskan bagian Lihat JSON Mentah untuk memeriksa data untuk setiap perintah atau respons terstruktur.

Perbandingan mendetail

Langkah berikutnya