本頁說明如何使用 Vertex AI SDK 中的 GenAI Client，評估各種應用實例的生成式 AI 模型和應用程式。
您可以使用 Vertex AI SDK 中的 GenAI Client 評估提示、基礎模型和複雜 AI 代理的成效，並與最相關的標準進行比較。您可以一次評估任意數量的候選項目，微調提示、選取最佳模型，或疊代複雜的代理程式。
您可以使用 Vertex AI SDK 中的 GenAI 用戶端執行下列操作：
在單次執行中並排比較多個模型或設定，並使用勝率計算結果做為決策依據。
使用內建支援功能評估熱門第三方模型，並與這些模型進行基準測試，不必進行複雜的整合。
使用非同步批次評估功能，更有效率地處理大型資料集，並卸載大規模評估工作。
端對端範例
Vertex AI SDK 中的 GenAI 用戶端採用兩步驟工作流程：生成模型回覆並評估回覆。下列端對端範例說明 Vertex AI SDK 中的 GenAI 用戶端運作方式：
安裝 Vertex AI SDK for Python：
pip install --upgrade google-cloud-aiplatform[evaluation]準備評估資料集：
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?"]})執行評估作業：
# 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()比較多位候選人：
# 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檔案中的單行範例：{"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 用戶端會自動偵測這個格式。
此格式的單行範例如下：
{"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 用戶端會使用下列以用戶端為準的程序執行評估：
run_inference()：針對一組提示，從模型產生回覆。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()
如要分析單一評估中多個 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 Client，將模型名稱字串傳遞至 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()
視覺化
Vertex AI SDK 中的 GenAI 用戶端可讓您直接在開發環境 (例如 Colab 或 Jupyter 筆記本) 中，將結果視覺化。.show() 方法適用於 EvaluationDataset 和 EvaluationResult 物件，可轉譯用於分析的互動式 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() 時，系統會顯示報表，其中包含兩個主要部分：
摘要指標：所有指標的匯總檢視畫面，顯示整個資料集的平均分數和標準差。
詳細結果：逐一列出個案，方便您檢查提示、參考資料、候選人回覆，以及每個指標的具體分數和說明。
# 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()
報表格式會根據您評估單一候選人或比較多位候選人而有所不同。如果是多位候選人的評估，這份報告會並列顯示結果，並在摘要表格中計算勝率/平手率。
在所有報表中，您都可以展開「查看原始 JSON」部分，檢查任何結構化提示或回應的資料。
後續步驟
請嘗試評估快速入門導覽課程。