本页介绍了如何使用 Vertex AI SDK 中的 GenAI 客户端，在各种应用场景中评估生成式 AI 模型和应用。
借助 Vertex AI SDK 中的 GenAI 客户端，您可以根据最相关的标准来衡量提示、基础模型和复杂 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 格式。您可以提供一个数据集，其中每行都是一个 JSON 对象，其结构类似于 OpenAI API 请求。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 客户端，通过将模型名称字符串传递给 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 部分，以检查任何结构化提示或响应的数据。
