企业官网建设流程全解析

Agent Platform 调优任务管理实战：基于 Python SDK 的列表、查询与取消全流程

【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills

导读

本文聚焦 Agent Platform 中GenAI 调优任务（Tuning Job）的生命周期管理，围绕本仓库skills/cloud/agent-platform-tuning-management/SKILL.md的核心指令，系统讲解如何用 Agent Platform Python SDK 完成调优任务的列表查询（list）、**单任务详情获取（get）与任务取消（cancel）**三大操作。读完本文，你将掌握：调优任务管理的安全分级与确认机制、环境初始化流程、任务资源的命名规范、状态机与常见错误处理，并能对照仓库中的配套脚本理解底层调用链，在实际项目中安全地管理正在运行的模型调优作业。

一、调优任务管理：能力边界与适用场景

在 Agent Platform 生态中，"调优"相关的技能有明确分工。本技能（agent-platform-tuning-management）只负责管理已经提交的调优作业，其边界定义如下：

• 适用场景：用户想知道自己有哪些调优任务在跑、查找某个任务的 ID、查询某个任务的运行状态、或取消一个运行时间过长的任务。
• 不适用场景：
  • 发起新的模型微调（请使用agent-platform-tuning，其完整工作流见 SKILL.md）；
  • 将调优完成的模型部署到端点（请使用agent-platform-deploy）；
  • 管理服务端点（请使用agent-platform-endpoint-management）。

管理操作通过 Agent Platform Python SDK 的GenAiTuningServiceClient完成，核心接口为list_tuning_jobs、get_tuning_job与cancel_tuning_job。

二、安全分级与确认机制（CRITICAL）

在代表用户执行任何命令之前，必须严格遵守以下基于操作类型划分的安全分级（Safety & Confirmation Tiers）：

尤其要注意：绝对不允许在收到用户新回合回复之前，预先提供或执行任何取消代码。即使脚本与确认请求在同一回合出现，也被视为严重的安全违规。正确做法是：先索取确认，等待用户在新回合明确同意后，再生成并执行取消脚本。

三、Phase 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 片段，无需先激活任何环境。

这一"先探测后安装、不建 venv"的原则与本仓库其他技能保持一致（参见 agent-platform-tuning 的 Phase 0.5），其原因是环境中可能已预装 SDK，直接覆盖会降级其他工具共享的包版本。

四、工作流决策树

面对用户请求，按如下流程决策：

第 1 步——信息收集：是否已经掌握 Project ID 和 Region？

• 否→ 必须以纯文本形式向用户询问缺失的 Project ID 和 Region，或建议用户检查 gcloud 配置；若两处均无信息，则请用户提供。不要自行在随机区域搜索。
• 是→ 进入第 2 步。

第 2 步——任务类型：用户想做什么？

• 查找或列出任务（Find/List Jobs）→ 使用 Python SDK 列出调优任务（Tier R）；
• 检查状态 / 查看特定任务（Check Status/Inspect）→ 使用 Python SDK 获取调优任务详情（Tier R）；
• 取消任务（Cancel a Job）→ 先索要确认，再使用 Python SDK 取消调优任务（Tier D）。

五、资源验证与错误处理规则（重要）

[!NOTE]资源验证与缺失项目/任务：如果 Python 片段执行失败并返回如下错误——403 Permission Denied、404 Not Found、INVALID_ARGUMENT，或提示占位/缺失的 project 或 job ID——你必须告知用户该项目或调优任务不存在或无法访问，并必须提示用户提供有效的 Project ID 或 Job ID，同时立即停止工具执行等待用户回复。不要重试或循环，不要假设资源有效，在收到用户提供的有效信息前不要继续执行任何后续脚本。

这条规则的本质是：任何一次 API 失败都应当被当作"资源无效"的信号上报，而不是被静默吞掉或反复重试。这与 agent-platform-tuning 技能中 GCS 预检规则（提交前必须用gcloud storage ls验证数据集 URI 真实存在）是同一设计哲学——宁可在执行前停下向用户确认，也不要在错误的资源上继续投入。

六、使用 Python SDK 管理调优任务

6.1 列出调优任务（Tier R）

当用户问"我有哪些调优任务在跑？"或想查找某个具体任务 ID 时，使用list_tuning_jobs：

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}")

要点说明：

• parent采用projects/{project_id}/locations/{region}的资源命名空间格式，这是 Agent Platform 所有调优相关接口统一使用的路径结构；
• 客户端构造时通过api_endpoint指定区域化端点{region}-aiplatform.googleapis.com；
• job.state即任务状态枚举（详见下文第八节状态机），可用于快速筛选运行中的任务。

6.2 获取指定任务详情（Tier R）

当用户提供了 Tuning Job ID 并询问其状态时，使用get_tuning_job：

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}")

要点说明：

• Job ID 为 19 位数字，请原样从列表输出或用户处获取，不要自行拼接或截断；
• 任务资源的完整名称为projects/{project_id}/locations/{region}/tuningJobs/{job_id}；
• tuned_model_display_name在任务成功后会给出调优产物的显示名称，可据此定位最终模型。

6.3 取消调优任务（Tier D）

当用户明确要求停止、中止或取消一个运行中的调优任务时：

安全检查：在生成或提供本脚本之前，必须先征求用户确认——即使对方已给出 Job ID，除非用户明确使用了如 "Yes, I confirm, cancel tuning job 123456" 之类的确认措辞。

[!IMPORTANT]绝对禁止在收到用户新回合回复前预先提供或执行任何取消代码。不得推测或假设确认一定会被给予。在同一并行回合中既索取确认又提供代码，是严重的安全违规。

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}")

cancel_tuning_job是一个异步请求——调用成功仅代表取消请求已提交，任务状态转变为JOB_STATE_CANCELLED还需要服务端处理。取消后建议结合第八节的状态监控确认任务最终进入终止态。

七、底层实现对照：仓库脚本与 SDK 调用的关系

理解GenAiTuningServiceClient的三个接口后，对照本仓库skills/cloud/agent-platform-tuning/下的脚本，可以更清楚地看到 Agent Platform 调优任务管理的完整调用链。

7.1 任务提交侧的同等资源名构造

任务管理接口使用的projects/{project}/locations/{location}/tuningJobs/{job_id}资源名，与提交侧完全一致。在 tune_open_model.py 中，任务通过google.genai客户端的client.tunings.tune()提交，脚本会从返回的tuning_job.name中截取末段作为job_id：

job_id = tuning_job.name.split("/")[-1] if tuning_job.name else "unknown"

也就是说，提交任务后拿到的job_id，可以直接无缝套用本文 6.2 与 6.3 中的name构造方式用于查询与取消。该脚本还展示了提交参数与本文管理操作之间的映射关系：

• tuning_mode取值FULL/PEFT_ADAPTER，分别映射到TuningMode.TUNING_MODE_FULL与TUNING_MODE_PEFT_ADAPTER；
• adapter_size支持的取值为1, 4, 8, 16, 32，映射到ADAPTER_SIZE_ONE至ADAPTER_SIZE_THIRTY_TWO；
• 任务会附带labels={"mg-source": "agent-platform-tuning-skill"}标签，可用于在列表结果中区分来源。

7.2 管理侧脚本：取消与监控

仓库提供了两个与本文主题直接相关的可执行脚本：

cancel_tuning_job.py使用vertexai.tuning.sft.SupervisedTuningJob封装实现取消逻辑，其核心如下：

job_resource = f"projects/{project}/locations/{location}/tuningJobs/{job_id}" job = sft.SupervisedTuningJob(job_resource) job.cancel()

它通过命令行参数--project、--location、--job_id接收输入。脚本注释特别提醒：--location必须与任务提交时使用的 location 一致——对于未固定区域的开放模型任务，提交 location 是global，查询与取消时也必须传global。

monitor_tuning_job.py则实现了本文 6.1/6.2 背后所依赖的状态机语义。它以genai.Client(enterprise=True, project=..., location=...)调用client.tunings.get(name=job_resource)轮询任务状态，直到命中以下终止态才退出：

• JOB_STATE_SUCCEEDED（成功）
• JOB_STATE_FAILED（失败）
• JOB_STATE_CANCELLED（已取消）
• JOB_STATE_PARTIALLY_SUCCEEDED（部分成功）

否则按默认 60 秒的轮询间隔（可用--poll_interval_secs调整）持续等待。该脚本的轮询逻辑即get_tuning_job在生产环境中的典型用法：先 get 状态，再依据状态机决定是否继续等待。

八、任务状态机与区域语义

8.1 状态机速查

结合 monitor_tuning_job.py 的终止态判断，调优任务的状态语义可归纳为：

8.2 location 语义：global与真实区域

开放模型（Open Model）调优任务通常以global作为 location 提交——服务会在运行时解析到有 GPU 容量的真实区域，但子资源（调优产物、检查点、TensorBoard）的资源名中会携带真实区域，而不是global。因此管理侧必须记住两条规则：

1. 查询/取消时：使用任务提交时的 location（global任务就用--location global轮询）；
2. 部署时：从调优产物资源名projects/.../locations/<REGION>/models/...中读出真实区域再部署，不能猜测（详见 agent-platform-tuning 的 Phase 5）。

8.3 取消后的校验点

取消请求返回成功 ≠ 任务立即消失。正确做法是：执行cancel_tuning_job后，用 6.2 的get_tuning_job（或复用 monitor_tuning_job.py）轮询确认状态迁移到JOB_STATE_CANCELLED，再向用户汇报"取消已完成"。

九、实战检查清单

将本文所有规则收敛为一张可执行的清单：

1. 确认信息齐备：Project ID 与 Region 均已从用户处确认，缺失时停下询问；
2. 环境就绪：gcloud auth login+gcloud auth application-default login已完成，import vertexai探测通过（失败才执行pip install google-cloud-aiplatform）；
3. 判断操作分级：list/get直接执行（Tier R）；cancel先索要显式打字确认（Tier D），且确认与代码不得同回合出现；
4. 构造资源名：projects/{project_id}/locations/{region}/tuningJobs/{job_id}，Job ID 为 19 位数字，location 与提交时一致（global就传global）；
5. 捕获失败：遇到403/404/INVALID_ARGUMENT立即上报用户，提示提供有效 ID，停止执行等待回复，不重试、不假设；
6. 确认终止态：取消后轮询至JOB_STATE_CANCELLED再汇报结果。

遵循这套流程，即可在 Agent Platform 中安全、可靠地完成调优任务的查找、状态查看与取消管理，避免因误操作中断宝贵且不可恢复的调优进程。

参考资源

• 本文核心技能文档：agent-platform-tuning-management/SKILL.md
• 调优任务提交与完整生命周期：agent-platform-tuning/SKILL.md
• 取消任务的可执行脚本：cancel_tuning_job.py
• 状态轮询与终止态定义：monitor_tuning_job.py
• 任务提交参数与资源名构造：tune_open_model.py

【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills