このページは Cloud Translation API によって翻訳されました。

評価を実行する

Vertex AI SDK for Python の Gen AI Evaluation モジュールを使用すると、Gen AI Evaluation Service API を使用して生成言語モデルとアプリケーションをプログラムで評価できます。このページでは、Vertex AI SDK を使用して評価を実行する方法について説明します。大規模な評価は、REST API を使用してのみ利用できます。

始める前に

Vertex AI SDK をインストールする

Vertex AI SDK for Python から生成 AI 評価モジュールをインストールするには、次のコマンドを実行します。

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

詳細については、Vertex AI SDK for Python をインストールするをご覧ください。

Vertex AI SDK を認証する

Vertex AI SDK for Python をインストールしたら、認証を行う必要があります。以下のトピックでは、ローカルで作業している場合と Colaboratory で作業している場合に、Vertex AI SDK で認証する方法について説明します。

ローカルで開発している場合は、ローカル環境でアプリケーションのデフォルト認証情報（ADC）を設定します。
1. Google Cloud CLI をインストールし、次のコマンドを実行して初期化します。
```
gcloud init
```
2. Google アカウントのローカル認証情報を作成します。
```
gcloud auth application-default login
```
  ログイン画面が表示されます。ログインすると、ADC で使用されるローカル認証情報ファイルに認証情報が保存されます。詳細については、ローカル開発環境の ADC を設定するをご覧ください。
Colaboratory で作業している場合は、Colab のセルで次のコマンドを実行して認証します。
```
from google.colab import auth
auth.authenticate_user()
```
このコマンドを実行するとウィンドウが開き、認証を完了できます。

サービスアカウントについて

サービスアカウントは、Gen AI Evaluation Service がモデルベースの評価指標の Vertex AI の Gemini API から予測を取得するために使用されます。このサービスアカウントは、Gen AI 評価サービスへの最初のリクエストで自動的にプロビジョニングされます。

名前	説明	メールアドレス	ロール
Vertex AI Rapid Eval サービスエージェント	モデルベースの評価で予測を行うために使用されるサービスアカウント。	`service-PROJECT_NUMBER@gcp-sa-vertex-eval.iam.gserviceaccount.com`	`roles/aiplatform.rapidevalServiceAgent`

Rapid Eval のサービスエージェントに関連付けられている権限は次のとおりです。

ロール	権限
Vertex AI Rapid Eval サービスエージェント（roles/aiplatform.rapidevalServiceAgent）	`aiplatform.endpoints.predict`

評価を実行する

EvalTask クラスを使用すると、次のユースケースで評価を実行できます。

モデルベースの指標
計算ベースの指標
大規模な評価を実行する（プレビュー）
その他の指標のカスタマイズ
レート制限と割り当てを増やす

`EvalTask` クラス

EvalTask クラスは、特定のタスクに基づいてモデルとアプリケーションを評価するのに役立ちます。生成モデルを公平に比較するには、通常、特定の指標を使用して、固定された評価データセットに対してさまざまなモデルとプロンプトテンプレートを繰り返し評価する必要があります。1 回の評価の実行で複数の指標を同時に評価することも重要です。

EvalTask は Vertex AI Experiments と統合されており、評価の実行ごとの構成と結果を追跡できます。Vertex AI Experiments は、評価結果の管理と解釈を支援し、十分な情報に基づいて意思決定できるようにします。

次の例は、EvalTask クラスをインスタンス化して評価を実行する方法を示しています。

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,
)

モデルベースの指標を使用して評価を実行する

モデルベースの指標の場合は、PointwiseMetric クラスと PairwiseMetric クラスを使用して、特定の基準に合わせて指標を定義します。次のオプションを使用して評価を実行します。

既存の例を使用する
テンプレート化されたインターフェースを使用する
指標をゼロから定義する

モデルベースの指標の例を使用する

Vertex AI SDK 内で組み込み定数 Metric Prompt Template Examples を直接使用できます。または、自由形式の指標定義インターフェースで変更して組み込むこともできます。

主なユースケースのほとんどを網羅する指標プロンプトテンプレートの例の一覧については、指標プロンプトテンプレートをご覧ください。

コンソール

Colab Enterprise ノートブックで評価を実行している場合は、 Google Cloud コンソール内から指標プロンプトテンプレートに直接アクセスできます。

目的の Gen AI Evaluation Service ノートブックのリンクをクリックします。
ノートブックが GitHub で開きます。[Colab Enterprise で開く] をクリックします。API を有効にするよう求めるダイアログが表示されたら、[有効にする] をクリックします。
サイドバーの [生成 AI の評価] アイコンをクリックします。[事前構築済みの指標テンプレート] パネルが開きます。
[ポイントワイズ] または [ペアワイズ] 指標を選択します。
使用する指標（[流暢さ] など）をクリックします。指標のコードサンプルが表示されます。
[コピー] をクリックして、コードサンプルをコピーします。必要に応じて、[カスタマイズ] をクリックして、指標の事前設定されたフィールドを変更します。
コードサンプルをノートブックに貼り付けます。

Vertex AI SDK

次の Vertex AI SDK の例は、MetricPromptTemplateExamples クラスを使用して指標を定義する方法を示しています。

# 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,
)

モデルベースの指標テンプレートインターフェースを使用する

Vertex AI SDK 内の PointwiseMetricPromptTemplate クラスと PairwiseMetricPromptTemplate クラスを使用して、Criteria や Rating Rubrics などのフィールドにデータを入力して指標をカスタマイズします。Instruction などの特定のフィールドには、入力が指定されていない場合にデフォルト値が割り当てられます。

必要に応じて、input_variables を指定できます。これは、指標プロンプトテンプレートがモデルベースの評価結果の生成に使用する入力フィールドのリストです。デフォルトでは、ポイントワイズ指標の場合はモデルの response 列が含まれ、ペアワイズ指標の場合は候補モデルの response 列と baseline_model_response 列の両方が含まれます。

詳細については、指標プロンプトテンプレートの「指標プロンプトテンプレートの構造」セクションをご覧ください。

# 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,
)

モデルベースの指標の自由形式の SDK インターフェースを使用する

指標プロンプトテンプレートをより柔軟にカスタマイズするには、自由形式インターフェースを使用して指標を直接定義します。このインターフェースでは、文字列を直接入力できます。

# 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,
)

翻訳モデルを評価する

翻訳モデルを評価するには、Vertex AI SDK を使用するときに、評価指標として BLEU、MetricX、または COMET を指定します。

#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()

計算ベースの指標を使用して評価を実行する

計算ベースの指標は、単独で使用することも、モデルベースの指標と組み合わせて使用することもできます。

# 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,
)

評価を大規模に実行する

大規模な評価データセットがある場合や、本番環境で評価を定期的に実行する場合は、Gen AI Evaluation Service の EvaluateDataset API を使用して、評価を大規模に実行できます。

リクエストのデータを使用する前に、次のように置き換えます。

PROJECT_NUMBER: プロジェクト番号。
DATASET_URI: 評価インスタンスを含む JSONL ファイルの Cloud Storage パス。ファイル内の各行は単一のインスタンスを表し、キーは metric_prompt_template（モデルベースの指標の場合）のユーザー定義の入力フィールドまたは必須の入力パラメータ（計算ベースの指標の場合）に対応します。指定できる JSONL ファイルは 1 つだけです。次の例は、ポイントワイズ評価インスタンスの行です。
```
{"response": "The Roman Senate was filled with exuberance due to Pompey's defeat in Asia."}
```


  METRIC_SPEC: 評価に使用する 1 つ以上の指標仕様。大規模な評価を実行する場合は、"pointwise_metric_spec"、"pairwise_metric_spec"、"exact_match_spec"、"bleu_spec"、"rouge_spec" の指標仕様を使用できます。
  METRIC_SPEC_FIELD_NAME: 選択した指標仕様に必要なフィールド。例: "metric_prompt_template"
  METRIC_SPEC_FIELD_CONTENT: 選択した指標仕様のフィールド コンテンツ。たとえば、ポイントワイズ評価には次のフィールド コンテンツを使用できます。"Evaluate the fluency of this sentence: {response}. Give score from 0 to
      1. 0 - not fluent at all. 1 - very fluent."
  OUTPUT_BUCKET: 評価結果を保存する Cloud Storage バケットの名前。







  HTTP メソッドと URL:

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




リクエストの本文（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"
    }
  }
}






リクエストを送信するには、次のいずれかのオプションを選択します。





  curl

  
  
    
      注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザー アカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。
    
  

  
    
      リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。
    

  

  
  
    
  

  
  

  
  

  
  

  
  

  
  
    
  

  
  
    
  

  
  

  
  
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

  
  
    
      注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザー アカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。
        
      
    
  

  
    
      リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。
    

  

  
  
    
  

  
  

  
  
    
    
  

  
  

  
  

  
  

  
  

  

  
  
    
  

  
  
    
  

  
  
    
  

  
  
  
    
  

  
$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












次のような JSON レスポンスが返されます。



レスポンス

  
{
  "name": "projects/PROJECT_NUMBER/locations/us-central1/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1beta1.EvaluateDatasetOperationMetadata",
    "genericMetadata": {
      "createTime": CREATE_TIME,
      "updateTime": UPDATE_TIME
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1beta1.EvaluateDatasetResponse",
    "outputInfo": {
      "gcsOutputDirectory": "gs://OUTPUT_BUCKET/evaluation_GENERATION_TIME"
    }
  }
}
































レスポンスで受け取った OPERATION_ID を使用して、評価のステータスをリクエストできます。

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"


その他の指標のカスタマイズ

モデルベースの指標に別のジャッジモデルを選択する場合、または、新しい計算ベースの指標を定義するなど、指標をさらにカスタマイズする必要がある場合は、Vertex AI SDK の CustomMetric クラスを使用できます。詳しくは、次のノートブックをご覧ください。





カスタム指標を使用して独自のジャッジモデルを使用する例を確認するには、次のいずれかの環境でノートブック「カスタム指標を使用して独自のジャッジモデルを使用する」を実行します。
Colab で開く

        
      
         | 
        
Colab Enterprise で開く

        
      
         | 
        
Vertex AI Workbench で開く

        
      
         | 
        
GitHub で表示する






独自の計算ベースのカスタム指標の例を確認するには、次のいずれかの環境でノートブック「独自の計算ベースのカスタム指標」を実行します。
Colab で開く

        
      
         | 
        
Colab Enterprise で開く

        
      
         | 
        
Vertex AI Workbench で開く

        
      
         | 
        
GitHub で表示する


レート制限と割り当てを増やしてモデルベースの評価を実行する

モデルベースの指標の 1 回の評価リクエストで、Vertex AI の Gemini API に対して基盤となるリクエストが複数回発生し、ジャッジモデルの割り当てが消費されます。次のユースケースでは、評価サービスのレート制限を高く設定する必要があります。


データ量の増加: モデルベースの指標を使用して処理するデータ量が大幅に増加すると、デフォルトの 1 分あたりのリクエスト数（RPM）の割り当てに達する可能性があります。割り当てを増やすと、パフォーマンスの低下や中断なしでより多くのボリュームを処理できます。
評価の迅速化: アプリケーションで評価の処理時間を短縮する必要がある場合は、RPM の割り当てを増やす必要があります。これは、時間に敏感なアプリケーションや、評価の遅延がユーザー エクスペリエンスに影響する可能性があるリアルタイム インタラクションを使用するアプリケーションでは特に重要です。
複雑な評価タスク: RPM 割り当てを増やすと、複雑なタスクや大量のテキストのリソース集約的な評価を処理するのに十分な容量を確保できます。
ユーザーの同時実行が多い場合: プロジェクト内でモデルベースの評価とモデル推論を多数のユーザーが同時にリクエストすると予想される場合は、ボトルネックを回避し、応答性を維持するために、モデルの RPM の上限を高くすることが重要です。


gemini-2.0-flash のデフォルトの審査モデルまたはそれ以降のモデルを使用している場合は、プロビジョニングされたスループットを使用して割り当てを管理することをおすすめします。

gemini-2.0-flash より前のモデルの場合は、次の手順で判定モデルの RPM 割り当てを増やします。


 Google Cloud コンソールで、[IAM と管理] の [割り当て] ページに移動します。
コンソールに割り当てを表示する

[フィルタ] フィールドで、ディメンション（モデル ID）と指標（Gemini モデルの割り当て ID）を指定します。base_model:gemini-2.0-flash と Metric:aiplatform.googleapis.com/generate_content_requests_per_minute_per_project_per_base_model です。
増加させる割り当てで、[その他の操作] メニュー more_vert ボタンをクリックします。
プルダウン メニューで [割り当てを編集] をクリックします。[割り当ての変更] パネルが開きます。
[割り当ての編集] で、新しい割り当て値を入力します。
[リクエストを送信] をクリックします。
割り当ての増加リクエスト（QIR）はメールで確認されます。通常、処理には 2 営業日かかります。


新しい割り当てを使用して評価を実行するには、evaluation_service_qps パラメータを次のように設定します。
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,
)

割り当てと上限の詳細については、Gen AI Evaluation Service の割り当てと Gen AI Evaluation Service API をご覧ください。

次のステップ


評価結果を表示する。
モデルベースの指標テンプレートを見つける。
評価用のサンプル ノートブックを試す。

評価を実行する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

始める前に

Vertex AI SDK をインストールする

Vertex AI SDK を認証する

サービス アカウントについて

評価を実行する

EvalTask クラス

モデルベースの指標を使用して評価を実行する

モデルベースの指標の例を使用する

コンソール

Vertex AI SDK

モデルベースの指標テンプレート インターフェースを使用する

モデルベースの指標の自由形式の SDK インターフェースを使用する

翻訳モデルを評価する

計算ベースの指標を使用して評価を実行する

評価を大規模に実行する

curl

PowerShell

レスポンス

その他の指標のカスタマイズ

レート制限と割り当てを増やしてモデルベースの評価を実行する

次のステップ

評価を実行する

サービスアカウントについて

`EvalTask` クラス

モデルベースの指標テンプレートインターフェースを使用する