agent-platform-tuning-management

Agent Platform 调优管理

本技能介绍如何使用 Agent Platform Python SDK 管理 GenAI 调优作业。当用户想要查看调优运行的状态、查找正在运行的调优作业，或取消运行时间过长的作业时，请使用本技能。

安全与确认级别（重要）

在代表用户执行任何命令之前，你必须根据所请求的操作遵守以下安全级别：

1. 级别 R：只读（list、get）
   • 规则：无需确认。你可以立即执行这些命令，为用户收集信息。
2. 级别 D：破坏性与中断性（cancel）
   • 规则：取消属于级别 D 操作，必须获得明确的输入确认（例如“I confirm”或“Yes, cancel it”）。
   • 试运行确认卡中必须包含的字段：取消调优作业之前，你必须提供试运行确认预览，并清楚列出：
     • 目标资源：完整的调优作业资源名称或 ID（例如 projects/<PROJECT_ID>/locations/<REGION>/tuningJobs/<JOB_ID>）。
     • 命令 / 脚本：将要执行的确切取消命令或 Python 代码。
     • 预期效果：停止正在进行的调优作业；任何正在进行的训练都会中止，且无法恢复。
     • 请用户明确确认（例如：“你确认吗？请回复‘I confirm’或‘Yes, cancel it’。”）。
   • 同轮限制：绝不能在提供预览卡的同一轮中执行取消操作。立即停止并等待用户在新一轮中确认。即使用户预先提供了确认（例如“Yes, I confirm, cancel tuning job ...”），或提供了更正后的作业 ID，你也必须针对该特定作业 ID 提供试运行预览，并等待用户在单独一轮中确认，然后才能发出取消命令。

阶段 0：环境设置

重要：运行以下任何 Python 代码片段之前，你必须按以下步骤确保环境已正确初始化：

1. Google Cloud 身份验证：使用你的 Google Cloud 账号进行身份验证，并为 Agent Platform 访问配置有效的应用默认凭据（ADC）：

   gcloud auth login
   gcloud auth application-default login
   

2. Python 依赖项：本技能需要 google-cloud-aiplatform。不要创建虚拟环境——它初始为空，并会隐藏环境已提供的包，导致重复安装。请先检查，只安装缺少的依赖项：

   python3 -c "import vertexai" || pip install google-cloud-aiplatform
   

3. 执行：使用普通的 python3 运行 Python 代码片段。无需先激活任何环境。

工作流决策树

1. 信息收集：你是否有项目 ID 和区域？

   • 没有 -> 你必须以纯文本形式向用户询问缺少的项目 ID 和区域，或建议他们检查 gcloud 配置。如果这两处都没有这些信息，请用户提供。不要自行尝试搜索任意区域。
   • 有 -> 继续执行第 2 步。

2. 任务类型：用户想做什么？

   • 查找或列出作业 -> 使用 Python SDK 列出调优作业。（级别 R）
   • 检查状态 / 查看特定作业 -> 使用 Python SDK 获取调优作业详情。（级别 R）
   • 取消作业 -> 先请求确认，然后使用 Python SDK 取消调优作业。（级别 D）

使用 Python SDK

说明

资源验证与项目／作业缺失： 如果执行 Python 代码片段时出错（例如出现 403 Permission Denied、404 Not Found、INVALID_ARGUMENT，或提示项目或作业 ID 是虚拟的／不存在），你必须告知用户该项目或调优作业不存在或无法访问。你必须要求用户提供有效的 Project ID 或 Job ID，并立即停止工具执行，等待用户回复。不要重试或循环执行，不要假设资源有效，也不要在收到用户提供的有效信息前执行其他脚本。

1. 列出调优作业（Tier R）

如果用户询问“我有哪些正在运行的调优作业？”或想查找特定的作业 ID：

from google.cloud import aiplatform_v1

project_id = "YOUR_PROJECT_ID"
region = "YOUR_REGION"
parent = f"projects/{project_id}/locations/{region}"

client = aiplatform_v1.GenAiTuningServiceClient(
    client_options={"api_endpoint": f"{region}-aiplatform.googleapis.com"}
)

jobs = client.list_tuning_jobs(parent=parent)
for job in jobs:
    print(f"Name: {job.name}")
    print(f"Base Model: {job.base_model}")
    print(f"State: {job.state}")

list_tuning_jobs 不接受 page_size 关键字参数。若要设置该参数，请传入请求： client.list_tuning_jobs(request={"parent": parent, "page_size": 50})。

2. 获取特定作业的详细信息（Tier R）

如果用户提供了 Tuning Job ID 并询问其状态：

from google.cloud import aiplatform_v1

project_id = "YOUR_PROJECT_ID"
region = "YOUR_REGION"
job_id = "YOUR_JOB_ID"  # 19-digit ID
name = f"projects/{project_id}/locations/{region}/tuningJobs/{job_id}"

client = aiplatform_v1.GenAiTuningServiceClient(
    client_options={"api_endpoint": f"{region}-aiplatform.googleapis.com"}
)

job = client.get_tuning_job(name=name)
print(f"Name: {job.name}")
print(f"Base Model: {job.base_model}")
print(f"State: {job.state}")
print(f"Tuning Model: {job.tuned_model_display_name}")

3. 取消作业（Tier D）

如果用户明确要求停止、中止或取消正在运行的调优作业：

安全检查：继续操作前必须获得用户明确的输入确认。 你必须提供一张试运行确认卡，列出目标资源、命令／脚本和预期效果，并要求用户输入“I confirm”或“Yes, cancel it”。即使用户提前表达了确认意愿，或提供了更正／新的作业 ID，你也必须针对该特定作业 ID 提供预览卡，并等待用户在新一轮对话中明确批准。

重要

在新一轮对话中收到用户回复前，绝不能提前执行任何取消代码或命令。 绝不能猜测或假设用户会确认。在提供预览卡的同一轮对话中执行取消操作，属于严重的安全违规。

from google.cloud import aiplatform_v1

project_id = "YOUR_PROJECT_ID"
region = "YOUR_REGION"
job_id = "YOUR_JOB_ID"  # 19-digit ID
name = f"projects/{project_id}/locations/{region}/tuningJobs/{job_id}"

client = aiplatform_v1.GenAiTuningServiceClient(
    client_options={"api_endpoint": f"{region}-aiplatform.googleapis.com"}
)

client.cancel_tuning_job(name=name)
print(f"Successfully requested cancellation for {name}")