Menjalankan evaluasi

Anda dapat menggunakan modul Evaluasi AI Generatif dari Agent Platform SDK untuk Python guna mengevaluasi model dan aplikasi bahasa generatif Anda secara terprogram dengan Gen AI evaluation service API. Halaman ini menunjukkan cara menjalankan evaluasi dengan Agent Platform SDK. Perhatikan bahwa evaluasi dalam skala besar hanya tersedia menggunakan REST API.

Sebelum memulai

Untuk mulai menjalankan evaluasi, selesaikan prasyarat berikut.

Menginstal Agent Platform SDK

Untuk menginstal modul Evaluasi AI Generatif dari Agent Platform SDK untuk Python, jalankan perintah berikut:

!pip install -q google-cloud-aiplatform[evaluation]

Untuk mengetahui informasi selengkapnya, lihat Menginstal Agent Platform SDK untuk Python.

Mengautentikasi Agent Platform SDK

Setelah menginstal Agent Platform SDK untuk Python, Anda harus melakukan autentikasi. Topik berikut menjelaskan cara melakukan autentikasi dengan Agent Platform SDK jika Anda bekerja secara lokal dan jika Anda bekerja di Colaboratory:

  • Jika Anda mengembangkan secara lokal, siapkan Kredensial Default Aplikasi (ADC) di lingkungan lokal Anda:

    1. Instal Google Cloud CLI, lalu lakukan inisialisasi dengan menjalankan perintah berikut:

      gcloud init

    2. Buat kredensial autentikasi lokal untuk Akun Google Anda:

      gcloud auth application-default login

      Layar login akan ditampilkan. Setelah Anda login, kredensial Anda akan disimpan dalam file kredensial lokal yang digunakan oleh ADC. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan ADC untuk lingkungan pengembangan lokal.

  • Jika Anda bekerja di Colaboratory, jalankan perintah berikut di sel Colab untuk melakukan autentikasi:

    from google.colab import auth
auth.authenticate_user()

    Perintah ini akan membuka jendela tempat Anda dapat menyelesaikan autentikasi.

Memahami akun layanan

Akun layanan digunakan oleh Gen AI evaluation service untuk mendapatkan prediksi dari Gemini API di Gemini Enterprise Agent Platform untuk metrik evaluasi berbasis model. Akun layanan ini otomatis disediakan pada permintaan pertama ke Gen AI evaluation service.

Nama Deskripsi Alamat email Peran
Agen Layanan Evaluasi Cepat Platform Agen Akun layanan yang digunakan untuk mendapatkan prediksi untuk evaluasi berbasis model. service-PROJECT_NUMBER@gcp-sa-vertex-eval.iam.gserviceaccount.com roles/aiplatform.rapidevalServiceAgent

Izin yang terkait dengan agen layanan evaluasi cepat adalah:

Peran Izin
Agen Layanan Evaluasi Cepat Platform Agen (roles/aiplatform.rapidevalServiceAgent) aiplatform.endpoints.predict

Menjalankan evaluasi

Gunakan class EvalTask untuk menjalankan evaluasi untuk kasus penggunaan berikut:

Class EvalTask

Class EvalTask membantu Anda mengevaluasi model dan aplikasi berdasarkan tugas tertentu. Untuk membuat perbandingan yang adil antara model generatif, Anda biasanya perlu berulang kali mengevaluasi berbagai model dan template perintah terhadap set data evaluasi tetap menggunakan metrik tertentu. Anda juga harus mengevaluasi beberapa metrik secara bersamaan dalam satu evaluasi.

EvalTask juga terintegrasi dengan Eksperimen Platform Agen untuk membantu Anda melacak konfigurasi dan hasil untuk setiap evaluasi. Eksperimen Platform Agen membantu mengelola dan menafsirkan hasil evaluasi, sehingga Anda dapat membuat keputusan yang tepat.

Contoh berikut menunjukkan cara membuat instance class EvalTask dan menjalankan evaluasi:

from vertexai.evaluation import (
    EvalTask,
    PairwiseMetric,
    PairwiseMetricPromptTemplate,
    PointwiseMetric,
    PointwiseMetricPromptTemplate,
    MetricPromptTemplateExamples,
)

eval_task = EvalTask(
    dataset=DATASET,
    metrics=[METRIC_1, METRIC_2, METRIC_3],
    experiment=EXPERIMENT_NAME,
)

eval_result = eval_task.evaluate(
    model=MODEL,
    prompt_template=PROMPT_TEMPLATE,
    experiment_run=EXPERIMENT_RUN,
)

Menjalankan evaluasi dengan metrik berbasis model

Untuk metrik berbasis model, gunakan class PointwiseMetric dan PairwiseMetric untuk menentukan metrik yang disesuaikan dengan kriteria spesifik Anda. Jalankan evaluasi menggunakan opsi berikut:

Menggunakan contoh metrik berbasis model

Anda dapat langsung menggunakan konstanta bawaan Metric Prompt Template Examples dalam Agent Platform SDK. Atau, ubah dan gabungkan dalam antarmuka definisi metrik bentuk bebas.

Untuk daftar lengkap Contoh Template Perintah Metrik yang mencakup sebagian besar kasus penggunaan utama, lihat Template perintah metrik.

Konsol

Saat menjalankan evaluasi di notebook Colab Enterprise, Anda dapat mengakses template perintah metrik langsung dari dalam Google Cloud konsol.

  1. Klik link untuk notebook Gen AI evaluation service pilihan Anda.

  2. Notebook akan terbuka di GitHub. Klik Open in Colab Enterprise. Jika dialog meminta Anda untuk mengaktifkan API, klik Enable.

  3. Klik ikon Gen AI Evaluation di sidebar. Panel Pre-built metric templates akan terbuka.

  4. Pilih metrik Pointwise atau Pairwise.

  5. Klik metrik yang ingin Anda gunakan, seperti Fluency. Contoh kode untuk metrik akan muncul.

  6. Klik Copy untuk menyalin contoh kode. Jika mau, klik Customize untuk mengubah kolom yang telah ditetapkan sebelumnya untuk metrik.

  7. Tempelkan contoh kode ke notebook Anda.

Agent Platform SDK

Contoh Agent Platform SDK berikut menunjukkan cara menggunakan class MetricPromptTemplateExamples untuk menentukan metrik Anda:

# View all the available examples of model-based metrics
MetricPromptTemplateExamples.list_example_metric_names()

# Display the metric prompt template of a specific example metric
print(MetricPromptTemplateExamples.get_prompt_template('fluency'))

# Use the pre-defined model-based metrics directly
eval_task = EvalTask(
    dataset=EVAL_DATASET,
    metrics=[MetricPromptTemplateExamples.Pointwise.FLUENCY],
)

eval_result = eval_task.evaluate(
    model=MODEL,
)

Menggunakan antarmuka bertemplate metrik berbasis model

Sesuaikan metrik Anda dengan mengisi kolom seperti Criteria dan Rating Rubrics menggunakan class PointwiseMetricPromptTemplate dan PairwiseMetricPromptTemplate dalam Agent Platform SDK. Kolom tertentu, seperti Instruction, diberi nilai default jika Anda tidak memberikan input.

Jika mau, Anda dapat menentukan input_variables, yang merupakan daftar kolom input yang digunakan oleh template perintah metrik untuk menghasilkan hasil evaluasi berbasis model. Secara default, kolom response model disertakan untuk metrik pointwise, dan kolom response serta baseline_model_response model kandidat disertakan untuk metrik pairwise.

Untuk informasi tambahan, lihat bagian "Menyusun template perintah metrik" di Template perintah metrik.

# Define a pointwise metric with two custom criteria
custom_text_quality = PointwiseMetric(
    metric="custom_text_quality",
    metric_prompt_template=PointwiseMetricPromptTemplate(
        criteria={
          "fluency": "Sentences flow smoothly and are easy to read, avoiding awkward phrasing or run-on sentences. Ideas and sentences connect logically, using transitions effectively where needed.",
          "entertaining": "Short, amusing text that incorporates emojis, exclamations and questions to convey quick and spontaneous communication and diversion.",
        },
        rating_rubric={
          "1": "The response performs well on both criteria.",
          "0": "The response is somewhat aligned with both criteria",
          "-1": "The response falls short on both criteria",
        },
        input_variables=["prompt"],
    ),
)

# Display the serialized metric prompt template
print(custom_text_quality.metric_prompt_template)

# Run evaluation using the custom_text_quality metric
eval_task = EvalTask(
    dataset=EVAL_DATASET,
    metrics=[custom_text_quality],
)
eval_result = eval_task.evaluate(
    model=MODEL,
)

Menggunakan antarmuka SDK bentuk bebas metrik berbasis model

Untuk lebih fleksibel dalam menyesuaikan template perintah metrik, Anda dapat menentukan metrik secara langsung menggunakan antarmuka bentuk bebas, yang menerima input string langsung.

# Define a pointwise multi-turn chat quality metric
pointwise_chat_quality_metric_prompt = """Evaluate the AI's contribution to a meaningful conversation, considering coherence, fluency, groundedness, and conciseness.
 Review the chat history for context. Rate the response on a 1-5 scale, with explanations for each criterion and its overall impact.

# Conversation History
{history}

# Current User Prompt
{prompt}

# AI-generated Response
{response}
"""

freeform_multi_turn_chat_quality_metric = PointwiseMetric(
    metric="multi_turn_chat_quality_metric",
    metric_prompt_template=pointwise_chat_quality_metric_prompt,
)

# Run evaluation using the freeform_multi_turn_chat_quality_metric metric
eval_task = EvalTask(
    dataset=EVAL_DATASET,
    metrics=[freeform_multi_turn_chat_quality_metric],
)
eval_result = eval_task.evaluate(
    model=MODEL,
)

Mengevaluasi model terjemahan

Untuk mengevaluasi model terjemahan Anda, Anda dapat menentukan BLEU, MetricX, atau COMET sebagai metrik evaluasi saat menggunakan Agent Platform SDK.

#Prepare the dataset for evaluation.
sources = [
    "Dem Feuer konnte Einhalt geboten werden",
    "Schulen und Kindergärten wurden eröffnet.",
]

responses = [
    "The fire could be stopped",
    "Schools and kindergartens were open",
]

references = [
    "They were able to control the fire.",
    "Schools and kindergartens opened",
]

eval_dataset = pd.DataFrame({
    "source": sources,
    "response": responses,
    "reference": references,
})

# Set the metrics.

metrics = [
    "bleu",
    pointwise_metric.Comet(),
    pointwise_metric.MetricX(),
]

eval_task = evaluation.EvalTask(
    dataset=eval_dataset,
    metrics=metrics,
)
eval_result = eval_task.evaluate()

Menjalankan evaluasi dengan metrik berbasis komputasi

Anda dapat menggunakan metrik berbasis komputasi secara mandiri, atau bersama dengan metrik berbasis model.

# Combine computation-based metrics "ROUGE" and "BLEU" with model-based metrics
eval_task = EvalTask(
    dataset=EVAL_DATASET,
    metrics=["rouge_l_sum", "bleu", custom_text_quality],
)
eval_result = eval_task.evaluate(
    model=MODEL,
)

Menjalankan evaluasi dalam skala besar

Jika memiliki set data evaluasi yang besar atau menjalankan evaluasi secara berkala di lingkungan produksi, Anda dapat menggunakan EvaluateDataset API di Gen AI evaluation service untuk menjalankan evaluasi dalam skala besar.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_NUMBER: Nomor project Anda.
  • DATASET_URI: Jalur Cloud Storage ke file JSONL yang berisi instance evaluasi. Setiap baris dalam file harus mewakili satu instance, dengan kunci yang sesuai dengan kolom input yang ditentukan pengguna di metric_prompt_template (untuk metrik berbasis model) atau parameter input yang diperlukan (untuk metrik berbasis komputasi). Anda hanya dapat menentukan satu file JSONL. Contoh berikut adalah baris untuk instance evaluasi pointwise: 
    {"response": "The Roman Senate was filled with exuberance due to Pompey's defeat in Asia."}
  • METRIC_SPEC: Satu atau beberapa spesifikasi metrik yang Anda gunakan untuk evaluasi. Anda dapat menggunakan spesifikasi metrik berikut saat menjalankan evaluasi dalam skala besar: "pointwise_metric_spec", "pairwise_metric_spec", "exact_match_spec", "bleu_spec", dan "rouge_spec".
  • METRIC_SPEC_FIELD_NAME: Kolom yang diperlukan untuk spesifikasi metrik yang Anda pilih. Misalnya, "metric_prompt_template"
  • METRIC_SPEC_FIELD_CONTENT: Konten kolom untuk spesifikasi metrik yang Anda pilih. Misalnya, Anda dapat menggunakan konten kolom berikut untuk evaluasi pointwise: "Evaluate the fluency of this sentence: {response}. Give score from 0 to 1. 0 - not fluent at all. 1 - very fluent."
  • OUTPUT_BUCKET: Nama bucket Cloud Storage tempat Anda ingin menyimpan hasil evaluasi.

Metode HTTP dan URL: 

POST https://us-central1-aiplatform.googleapis.com/v1beta1/projects/PROJECT_NUMBER/locations/us-central1/evaluateDataset

Meminta isi JSON: 

{
  "dataset": {
    "gcs_source": {
      "uris": "DATASET_URI"
    }
  },
  "metrics": [
    {
      METRIC_SPEC: {
        METRIC_SPEC_FIELD_NAME: METRIC_SPEC_FIELD_CONTENT
      }
    }
  ],
  "output_config": {
    "gcs_destination": {
      "output_uri_prefix": "OUTPUT_BUCKET"
    }
  }
}

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://us-central1-aiplatform.googleapis.com/v1beta1/projects/PROJECT_NUMBER/locations/us-central1/evaluateDataset"

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://us-central1-aiplatform.googleapis.com/v1beta1/projects/PROJECT_NUMBER/locations/us-central1/evaluateDataset" | Select-Object -Expand Content

Anda akan melihat respons JSON yang mirip seperti berikut:

Anda dapat menggunakan OPERATION_ID yang Anda terima dalam respons untuk meminta status evaluasi:

curl -X GET \
  -H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
  -H "Content-Type: application/json; charset=utf-8" \
  "https://us-central1-aiplatform.googleapis.com/v1beta1/projects/PROJECT_NUMBER/locations/us-central1/operations/OPERATION_ID"

Penyesuaian metrik tambahan

Jika perlu menyesuaikan metrik lebih lanjut, seperti memilih model penilai yang berbeda untuk metrik berbasis model, atau menentukan metrik berbasis komputasi baru, Anda dapat menggunakan class CustomMetric di Agent Platform SDK. Untuk mengetahui detail selengkapnya, lihat notebook berikut:

Menjalankan evaluasi berbasis model dengan peningkatan batas frekuensi dan kuota

Satu permintaan evaluasi untuk metrik berbasis model menghasilkan beberapa permintaan yang mendasarinya ke Gemini API di Agent Platform dan menggunakan kuota untuk model penilai. Anda harus menetapkan batas frekuensi layanan evaluasi yang lebih tinggi dalam kasus penggunaan berikut:

  • Peningkatan volume data: Jika Anda memproses data yang jauh lebih banyak menggunakan metrik berbasis model, Anda mungkin akan mencapai kuota permintaan per menit (RPM) default. Dengan meningkatkan kuota, Anda dapat menangani volume yang lebih besar tanpa penurunan performa atau gangguan.

  • Evaluasi yang lebih cepat: Jika aplikasi Anda memerlukan waktu penyelesaian yang lebih cepat untuk evaluasi, Anda mungkin memerlukan kuota RPM yang lebih tinggi. Hal ini sangat penting untuk aplikasi yang sensitif terhadap waktu atau aplikasi dengan interaksi real-time yang penundaan evaluasinya dapat memengaruhi pengalaman pengguna.

  • Tugas evaluasi yang kompleks: Kuota RPM yang lebih tinggi memastikan Anda memiliki kapasitas yang cukup untuk menangani evaluasi yang memerlukan banyak resource untuk tugas yang kompleks atau teks dalam jumlah besar.

  • Konkurensi pengguna yang tinggi: Jika Anda memperkirakan banyak pengguna yang secara bersamaan meminta evaluasi berbasis model dan inferensi model dalam project Anda, batas RPM model yang lebih tinggi sangat penting untuk mencegah kemacetan dan mempertahankan responsivitas.

Jika Anda menggunakan model penilai default gemini-2.0-flash atau model yang lebih baru, sebaiknya gunakan Throughput yang Disediakan untuk mengelola kuota Anda.

Untuk model yang lebih lama dari gemini-2.0-flash, gunakan petunjuk berikut untuk meningkatkan kuota RPM model penilai:

  1. Di Google Cloud konsol, buka halaman IAM & Admin Quotas.

    Lihat Kuota di Konsol

  2. Di kolom Filter, tentukan Dimension (ID model) dan Metric (ID kuota untuk model Gemini): base_model:gemini-2.0-flash dan Metric:aiplatform.googleapis.com/generate_content_requests_per_minute_per_project_per_base_model.

  3. Untuk kuota yang ingin Anda tingkatkan, klik menu more actions .

  4. Di menu drop-down, klik Edit quota. Panel Quota changes akan terbuka.

  5. Di bagian Edit quota, masukkan nilai kuota baru.

  6. Klik Submit request.

  7. Permintaan Peningkatan Kuota (QIR) akan dikonfirmasi melalui email dan biasanya memerlukan waktu dua hari kerja untuk diproses.

Untuk menjalankan evaluasi menggunakan kuota baru, tetapkan parameter evaluation_service_qps sebagai berikut:

from vertexai.evaluation import EvalTask

# GEMINI_RPM is the requests per minute (RPM) quota for gemini-2.0-flash-001 in your region
# Evaluation Service QPS limit is equal to (gemini-2.0-flash-001 RPM / 60 sec / default number of samples)
CUSTOM_EVAL_SERVICE_QPS_LIMIT = GEMINI_RPM / 60 / 4

eval_task = EvalTask(
    dataset=DATASET,
    metrics=[METRIC_1, METRIC_2, METRIC_3],
)

eval_result = eval_task.evaluate(
    evaluation_service_qps=CUSTOM_EVAL_SERVICE_QPS_LIMIT,
    # Specify a retry_timeout limit for a more responsive evaluation run
    # the default value is 600 (in seconds, or 10 minutes)
    retry_timeout=RETRY_TIMEOUT,
)

Untuk mengetahui informasi selengkapnya tentang kuota dan batas, lihat Kuota layanan evaluasi AI generatif, dan Gen AI evaluation service API.

Langkah berikutnya