用于 ADK 智能体的 MLflow 评分器¶
MLflow 将五个 ADK 评估器包装为第三方评分器，使你可以在任何 mlflow.genai.evaluate() 运行中使用 ADK 的轨迹匹配、ROUGE 响应相似度和 LLM-judge 指标。该集成涵盖了 ADK 的 TrajectoryEvaluator、RougeEvaluator、FinalResponseMatchV2Evaluator、SafetyEvaluatorV1 和 HallucinationsV1Evaluator。
如果你还在追踪 ADK 智能体，请参阅 MLflow Tracing 集成了解一行 OTel 自动追踪设置。下面的确定性评分器直接从这些追踪中读取工具调用。
使用场景¶
- 工具轨迹评估：使用
EXACT、IN_ORDER或ANY_ORDER匹配验证智能体是否以正确的顺序调用了正确的工具。 - 响应相似度：使用 ROUGE-1 F-measure 对智能体的最终响应与参考答案进行评分。
- LLM 评判的响应质量：使用 Gemini 以多数投票方式对智能体的响应是否语义匹配预期响应进行评分。
- 幻觉检测：使用 Gemini 对智能体的响应是否包含捏造事实进行评分。
- 安全检查：使用 Vertex AI 的预构建 SAFETY 指标标记不安全输出，无需管理评判模型。
- 混合匹配评分：在单个
mlflow.genai.evaluate()调用中同时运行确定性评分器和 LLM 评判，在更昂贵的评判调用之下叠加廉价的结构检查。
前置条件¶
- MLflow 3.13 或更高版本以获得完整评分器集。MLflow 3.11 提供两个确定性评分器；三个 LLM-judge 评分器在 3.13 中引入。
- 环境中已安装 ADK。
- 对于 LLM-judge 评分器：需要
GEMINI_API_KEY（Gemini Developer API）或 Google Cloud 项目凭据（Vertex AI）。Safety始终需要 Vertex AI 路径，因为它委托给托管指标。
安装依赖¶
可用评分器¶
五个 MLflow 评分器，按评分方式分组：
| 评分器 | 评估内容 | 包装 |
|---|---|---|
ToolTrajectory |
智能体是否以正确的顺序调用了正确的工具 | TrajectoryEvaluator |
ResponseMatch |
实际响应和预期响应之间的词法相似度（ROUGE-1 F-measure） | RougeEvaluator |
ResponseEvaluation |
最终响应是否语义匹配预期响应（LLM judge） | FinalResponseMatchV2Evaluator |
Safety |
响应是否包含不安全内容 | SafetyEvaluatorV1（Vertex AI 托管） |
Hallucination |
响应是否包含幻觉内容（LLM judge） | HallucinationsV1Evaluator |
ToolTrajectory 和 ResponseMatch 在微秒级运行，无 API 成本。ResponseEvaluation 和 Hallucination 调用默认的 Gemini Flash 评判模型并进行五次采样多数投票；模型和采样次数均可配置。Safety 是例外。它通过 Vertex AI 的预构建 SAFETY 指标路由，该指标管理自己的模型选择，因此如果你传入 model 或 num_samples，评分器会抛出 TypeError。
快速入门¶
直接调用评分器：
from mlflow.genai.scorers.google_adk import ToolTrajectory
scorer = ToolTrajectory(match_type="EXACT", threshold=0.5)
feedback = scorer(
inputs="Book a flight to Paris",
outputs="Booked flight AA123 to Paris",
expectations={
"expected_tool_calls": [
{"name": "search_flights", "args": {"destination": "Paris"}},
{"name": "book_flight", "args": {"flight_id": "AA123"}},
],
"actual_tool_calls": [
{"name": "search_flights", "args": {"destination": "Paris"}},
{"name": "book_flight", "args": {"flight_id": "AA123"}},
],
},
)
print(feedback.value) # "yes" or "no"
print(feedback.metadata["score"]) # 1.0 on a full match
或者在单次评估中组合多个评分器：
import mlflow
from mlflow.genai.scorers.google_adk import (
ToolTrajectory,
ResponseMatch,
ResponseEvaluation,
)
eval_data = [
{
"inputs": {"query": "Find me a flight to Paris next Friday."},
"outputs": "I found 3 flights to Paris on Friday: AA101, DL202, UA303.",
"expectations": {
"expected_tool_calls": [
{"name": "search_flights", "args": {"destination": "Paris"}},
],
"actual_tool_calls": [
{"name": "search_flights", "args": {"destination": "Paris"}},
],
"expected_response": "Here are flights to Paris next Friday.",
},
},
]
results = mlflow.genai.evaluate(
data=eval_data,
scorers=[
ToolTrajectory(match_type="EXACT", threshold=0.5),
ResponseMatch(threshold=0.5),
ResponseEvaluation(threshold=0.6),
],
)
工具调用如何解析¶
ToolTrajectory 需要预期工具调用（来自 expectations["expected_tool_calls"]）和智能体实际进行的工具调用。它按以下顺序解析实际调用：
expectations["actual_tool_calls"]（如存在）。适用于已将工具调用捕获为数据的离线评估。- MLflow 追踪上的
TOOL跨度。当未提供显式覆盖时，评分器遍历追踪并从标记为TOOL的跨度中读取工具调用。这是直接传递追踪或使用mlflow.genai.evaluate(predict_fn=...)的实时评估路径。 - 空列表。如果两者都不可用，评分器将预期列表与空的实际列表进行比较，这将导致非空预期的评分为 0.0。
将其与 MLflow Tracing 集成配对使用，实现完全在线的设置：ADK 在智能体执行期间发出 OTel 跨度，MLflow 接收它们，评分器从追踪中读回工具调用，无需任何显式数据管道。
LLM-judge 配置¶
ResponseEvaluation 和 Hallucination 接受 Gemini 模型 ID、通过/失败阈值和多数投票的采样次数：
from mlflow.genai.scorers.google_adk import Hallucination, ResponseEvaluation
response_eval = ResponseEvaluation(
model="gemini-flash-latest",
threshold=0.5,
num_samples=5,
)
hallucination = Hallucination(model="gemini-flash-latest", threshold=0.5)
模型必须是 ADK 的 LlmRegistry 可以解析的名称，如 gemini-flash-latest 或 gemini-pro-latest。databricks 或 openai:/gpt-4o 等 MLflow 模型 URI 不受支持，因为 ADK 的评估器直接连接到 Google 的模型注册表。
Safety 通过 Vertex AI 的托管 SAFETY 指标运行。它需要 GOOGLE_CLOUD_PROJECT、GOOGLE_CLOUD_LOCATION 和 gcloud auth application-default login（或服务账号）：
当缺少认证时，LLM-judge 评分器返回带有 error 字段的 Feedback 而非抛出异常。评估运行继续，并按样本显示配置错误。