チュートリアル: Vertex AI SDK の GenAI クライアントを使用して評価を行う

スタートガイド: GenAI クライアントを介して Vertex AI SDK を使用して評価を実行するの例を確認するには、次のいずれかの環境でノートブック「スタートガイド: GenAI クライアントを介して Vertex AI SDK を使用して評価を実行する」を実行します。

Colab で開く | Colab Enterprise で開く | Vertex AI Workbench で開く | GitHub で表示する

このページでは、Vertex AI SDK の GenAI クライアントを使用して、さまざまなユースケースで生成 AI モデルとアプリケーションを評価する方法について説明します。

Vertex AI SDK for Gen AI Evaluation Service の GenAI クライアントを使用すると、最も関連性の高い基準に照らして、プロンプト、基盤モデル、複雑な AI エージェントのパフォーマンスを測定できます。一度に任意の数の候補を評価して、プロンプトをファインチューニングしたり、最適なモデルを選択したり、複雑なエージェントを反復処理したりできます。

Vertex AI SDK の GenAI クライアントでは、次の操作を行うことができます。

• 勝率の計算を使用して、1 回の実行で複数のモデルまたは構成を並べて比較し、意思決定に役立てます。

• 組み込みのサポートを使用して、複雑な統合なしで一般的なサードパーティ モデルを評価し、ベンチマークします。

• 非同期バッチ評価を使用して、大規模なデータセットをより効率的に処理し、大規模な評価タスクをオフロードします。

エンドツーエンドの例

Vertex AI SDK の GenAI クライアントは、モデルのレスポンスの生成とレスポンスの評価という 2 つのステップのワークフローを使用します。次のエンドツーエンドの例は、Vertex AI SDK の GenAI クライアントの動作を示しています。

1. Vertex AI SDK for Python をインストールします。

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

2. 評価データセットを準備します。

   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. 評価を実行します。

   # 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. 複数の候補を比較する:

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

指標を定義する

指標は、LLM ベースの指標または計算ベースの指標として定義します。

LLM ベースの指標

LLM ベースの指標では、大規模言語モデル（LLM）を「判定」として使用し、スタイルや文章の質など、アルゴリズムだけでは測定が難しい微妙な基準を評価します。

マネージド ルブリックベースの指標を使用する

Vertex AI SDK の GenAI クライアントには、GENERAL_QUALITY、SAFETY、INSTRUCTION_FOLLOWING などのさまざまなモデルベースの指標が用意されています。これらは RubricMetric クラスからアクセスできます。管理対象のルーブリックベースの指標定義は、一元化されたライブラリからオンデマンドで読み込まれ、ルーブリックベースの指標のバージョン間で一貫性が保たれます。

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

さまざまな SDK バージョンで一貫した結果を作成するには、指標を特定のバージョンに固定します。デフォルトでは、最新バージョンが使用されます。

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

LLM 指標をカスタマイズする

特別な基準が必要なユースケースでは、LLMMetric クラスをインスタンス化して、独自の LLM ベースの指標を定義できます。これにより、評価プロンプト テンプレート、判定モデル、その他のパラメータを完全に制御できます。

MetricPromptBuilder ヘルパークラスは、instruction、criteria、rating_scores を個別に定義できるようにすることで、判定モデルの構造化されたプロンプト テンプレートを作成します。

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

計算ベースの指標とカスタム関数指標

計算ベースの指標は、モデルの出力をグラウンド トゥルースまたは基準値と数学的に比較します。ベースの Metric クラスを使用してコードで計算されるこれらの指標は、exact_match、bleu、rouge_1 などの事前定義された計算ベースのアルゴリズムをサポートします。計算ベースの指標を使用するには、指標の名前を使用して Metric クラスをインスタンス化します。この指標では、比較のためにデータセットの reference 列が必要です。

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

カスタム関数指標を実装する

カスタム Python 関数を custom_function パラメータに渡して、カスタム評価ロジックを実装することもできます。Vertex AI SDK の GenAI クライアントは、データセットの各行に対してこの関数を実行します。

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

評価データセットを準備する

Vertex AI SDK の GenAI クライアントは、一般的なデータ形式を自動的に検出し、処理します。つまり、run_inference で新しいレスポンスを生成する場合でも、evaluate で既存のレスポンスを評価する場合でも、手動で変換を行う必要なく、データをそのまま使用できることがよくあります。

Vertex AI SDK の GenAI クライアントは、次の形式をサポートしています。

• Pandas DataFrame（フラット化された形式）

  簡単な評価には、pandas.DataFrame を使用できます。Vertex AI SDK の GenAI クライアントは、prompt、response、reference などの一般的な列名を探します。この形式には完全な下位互換性があります。

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

• Gemini バッチ予測の形式

  通常、Vertex AI バッチ予測ジョブの出力は Cloud Storage に保存された JSONL ファイルです。各行には request オブジェクトと response オブジェクトが含まれています。この出力を直接使用できます。Vertex AI SDK の GenAI クライアントは、この構造を自動的に解析して、他の Vertex AI サービスとの統合を提供します。

  jsonl ファイルの 1 行の例:

  {"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."}]}}]}}
  

  バッチジョブから事前に生成されたレスポンスを直接評価できます。

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

• OpenAI Chat Completion 形式

  サードパーティ モデルとの評価や比較を行う場合、Vertex AI SDK の GenAI クライアントは OpenAI Chat Completion 形式をサポートしています。各行が OpenAI API リクエストのような構造の JSON オブジェクトであるデータセットを指定できます。Vertex AI SDK の GenAI クライアントは、この形式を自動的に検出します。

  この形式の 1 行の例を次に示します。

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

  このデータを使用して、サードパーティ モデルからレスポンスを生成し、レスポンスを評価できます。

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

評価を実行

Vertex AI SDK の GenAI クライアントは、次のクライアントベースのプロセスを使用して評価を実行します。

1. run_inference(): 指定された一連のプロンプトに対してモデルからレスポンスを生成します。

2. evaluate(): 生成されたレスポンスの指標を計算します。

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

1 回の評価で複数の AI モデルまたはシステムのパフォーマンスを分析するには、候補ごとにレスポンスを生成し、それらをリストで 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()

非同期の大規模評価

大規模なデータセットの場合、Vertex AI SDK の GenAI クライアントは、非同期の長時間実行バッチ評価メソッドを提供します。これは、すぐに結果を必要とせず、計算をオフロードしたいシナリオに最適です。

batch_evaluate() メソッドは、ポーリングして進行状況を追跡できるオペレーション オブジェクトを返します。パラメータは 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
)

サードパーティ モデルの評価

Vertex AI SDK の GenAI クライアントを使用して、モデル名文字列を run_inference メソッドに渡すことで、OpenAI などのプロバイダのモデルを評価して比較できます。Vertex AI SDK の GenAI クライアントは、litellm ライブラリを使用してモデル API を呼び出します。

必要な API キーを環境変数（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()

Visualization

Vertex AI SDK の GenAI クライアントを使用すると、Colab や Jupyter ノートブックなどの開発環境内で結果を直接可視化できます。EvaluationDataset オブジェクトと EvaluationResult オブジェクトの両方で使用できる .show() メソッドは、分析用のインタラクティブな HTML レポートをレンダリングします。

推論結果を可視化する

run_inference() でレスポンスを生成したら、結果の EvaluationDataset オブジェクトで .show() を呼び出して、元のプロンプトとリファレンスとともにモデルの出力を検査できます。これは、完全な評価を実行する前に品質を簡単にチェックする場合に便利です。

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

各プロンプト、対応するリファレンス（指定されている場合）、新しく生成されたレスポンスが表に表示されます。

評価レポートを可視化する

EvaluationResult オブジェクトで .show() を呼び出すと、次の 2 つの主要セクションを含むレポートが表示されます。

• 概要指標: すべての指標の集計ビュー。データセット全体の平均スコアと標準偏差が表示されます。

• 詳細な結果: ケースごとの内訳。プロンプト、参照、候補レスポンス、各指標の特定のスコアと説明を確認できます。

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

レポートの形式は、1 人の候補者を評価するか、複数の候補者を比較するかによって異なります。複数候補の評価の場合、レポートには並列ビューが表示され、概要表には勝率/引き分け率の計算が含まれます。

すべてのレポートで、[View Raw JSON] セクションを開いて、構造化されたプロンプトまたはレスポンスのデータを調べることができます。

次のステップ

• 評価のクイックスタートを試す。

• 評価指標を定義する。