本文详解如何在 Vertex AI 中查询指定实验的所有运行（Runs），涵盖 SDK 编程调用、控制台操作及关键注意事项，弥补 google.cloud.aiplatform 官方库缺失原生 list_runs() 方法的空白。
本文详解如何在 vertex ai 中查询指定实验的所有运行（runs），涵盖 sdk 编程调用、控制台操作及关键注意事项，弥补 `google.cloud.aiplatform` 官方库缺失原生 `list_runs()` 方法的空白。
在 Vertex AI 的实验（Experiment）管理中，用户常需批量查看、筛选或分析某次实验下所有历史运行（Run）的元数据（如创建时间、参数、指标、状态等）。然而，截至当前版本（google-cloud-aiplatform >= 1.40.0），官方 Python SDK 并未提供类似 experiment.list_runs() 的直接接口——这是开发者普遍遇到的“功能可见但不可编程调用”的典型场景。
所幸，Google 提供了两种可靠且生产可用的替代方案：基于 REST API 的手动调用（推荐用于自动化与集成），以及通过 Google Cloud Console 可视化查看（适用于调试与快速验证）。以下重点介绍可编程方式。
✅ 方案一：调用 Vertex AI Experiments REST API（推荐）
由于 SDK 尚未封装该能力，需直接调用底层 Experiments.ListTrials 接口（注意：Vertex AI 实验中的 Run 在后端对应 Trial 资源）。需满足前提：
- 已启用 Vertex AI API；
- 具备 aiplatform.experiments.get 和 aiplatform.trials.list 权限（如 roles/aiplatform.user）；
- 实验已通过 aiplatform.init(experiment=...) 创建并关联了至少一个 Run。
以下是完整示例代码（使用 google-auth + requests）：
import os
from google.auth import default
from google.auth.transport.requests import Request
import requests
def list_experiment_runs(
experiment_name: str,
project_id: str,
location: str = "us-central1",
page_size: int = 100,
) -> list:
"""
列出指定 Vertex AI Experiment 下所有 Runs（即 Trials）
注意：experiment_name 格式为 'projects/{pid}/locations/{loc}/experiments/{exp_name}'
"""
# 获取认证凭据
credentials, _ = default()
if not credentials.valid:
credentials.refresh(Request())
# 构造 Trials 列表端点（实验下的 Trials 即 Runs）
parent = f"projects/{project_id}/locations/{location}/experiments/{experiment_name}"
url = f"https://{location}-aiplatform.googleapis.com/v1/{parent}/trials"
headers = {
"Authorization": f"Bearer {credentials.token}",
"Content-Type": "application/json",
}
params = {"pageSize": page_size}
runs = []
while True:
response = requests.get(url, headers=headers, params=params)
response.raise_for_status()
data = response.json()
runs.extend(data.get("trials", []))
# 分页处理
next_page_token = data.get("nextPageToken")
if not next_page_token:
break
params["pageToken"] = next_page_token
return runs
# 使用示例
if __name__ == "__main__":
runs = list_experiment_runs(
experiment_name="my-experiment",
project_id="my-gcp-project",
location="us-central1"
)
for run in runs[:5]: # 打印前5个 Run 的基本信息
print(f"Run ID: {run.get('name')}")
print(f" State: {run.get('state')}")
print(f" Start Time: {run.get('startTime')}")
print(f" Parameters: {run.get('parameters', [])}")
print(f" Metrics: {run.get('finalMeasurement', {}).get('metrics', {})}\n")⚠️ 重要说明：
- experiment_name 参数必须为完整资源路径（如 projects/my-proj/locations/us-central1/experiments/my-exp），而非仅实验名字符串；可通过 aiplatform.Experiment.list() 获取完整路径。
- 每个 Trial 对应一次 start_run() 调用，其 finalMeasurement 字段包含 log_metrics() 记录的指标，parameters 字段包含 log_params() 记录的超参。
- 建议配合 page_size 和分页逻辑处理大规模实验（>100 Runs）。
✅ 方案二：Google Cloud Console 可视化查看（辅助验证）
进入 Vertex AI Experiments 控制台 → 选择目标实验 → 点击「Runs」标签页，即可以表格形式查看所有 Run，并支持按状态、时间、指标范围等条件筛选与排序。此方式适合人工排查，不适用于 CI/CD 或监控告警等自动化场景。
? 总结与最佳实践
- ❌ 不要依赖 aiplatform.Experiment 对象的任意未文档化属性尝试获取 Runs —— 官方明确未实现该功能；
- ✅ 生产环境强烈推荐使用 REST API 方案，可轻松集成至 ML Ops 流水线、结果看板或自动归档脚本；
- ? 调用 API 前务必校验服务账号权限，并在敏感环境中使用 Workload Identity Federation 或短期凭据；
- ? 若未来 SDK 新增 Experiment.list_runs() 方法（可关注 GitHub issue #5823），建议平滑迁移以提升可维护性。
掌握上述方法，即可在无原生 SDK 支持的前提下，高效、可靠地完成 Vertex AI 实验运行的全生命周期可观测性建设。
