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分级操作规则Tier R只读操作list列表、get详情无需确认可立即执行以收集信息Tier D破坏性/中断性操作cancel取消必须显式打字确认必须先向用户输出文本消息说明这将停止调优进程所有进度将丢失并要求用户输入 I confirm 或 Yes, cancel it。必须在执行取消命令之前立即索要该确认尤其要注意绝对不允许在收到用户新回合回复之前预先提供或执行任何取消代码。即使脚本与确认请求在同一回合出现也被视为严重的安全违规。正确做法是先索取确认等待用户在新回合明确同意后再生成并执行取消脚本。三、Phase 0环境初始化运行下方任何 Python 片段之前必须先完成环境初始化步骤固定为三步1. Google Cloud 认证登录 Google Cloud 账户并为 Agent Platform 访问配置活动应用默认凭据ADCgcloud auth login gcloud auth application-default login2. Python 依赖探测本技能需要google-cloud-aiplatform。不要创建虚拟环境——虚拟环境初始为空会隐藏环境中已提供的包反而强制触发冗余安装。正确做法是先探测、只安装缺失的部分python3 -c import vertexai || pip install google-cloud-aiplatform3. 执行方式直接用普通的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_jobsfrom google.cloud import aiplatform_v1 project_id YOUR_PROJECT_ID region YOUR_REGION parent fprojects/{project_id}/locations/{region} client aiplatform_v1.GenAiTuningServiceClient( client_options{api_endpoint: f{region}-aiplatform.googleapis.com} ) jobs client.list_tuning_jobs(parentparent) for job in jobs: print(fName: {job.name}) print(fBase Model: {job.base_model}) print(fState: {job.state})要点说明parent采用projects/{project_id}/locations/{region}的资源命名空间格式这是 Agent Platform 所有调优相关接口统一使用的路径结构客户端构造时通过api_endpoint指定区域化端点{region}-aiplatform.googleapis.comjob.state即任务状态枚举详见下文第八节状态机可用于快速筛选运行中的任务。6.2 获取指定任务详情Tier R当用户提供了 Tuning Job ID 并询问其状态时使用get_tuning_jobfrom google.cloud import aiplatform_v1 project_id YOUR_PROJECT_ID region YOUR_REGION job_id YOUR_JOB_ID # 19-digit ID name fprojects/{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(namename) print(fName: {job.name}) print(fBase Model: {job.base_model}) print(fState: {job.state}) print(fTuning 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 fprojects/{project_id}/locations/{region}/tuningJobs/{job_id} client aiplatform_v1.GenAiTuningServiceClient( client_options{api_endpoint: f{region}-aiplatform.googleapis.com} ) client.cancel_tuning_job(namename) print(fSuccessfully 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_idjob_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_ADAPTERadapter_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 fprojects/{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(enterpriseTrue, project..., location...)调用client.tunings.get(namejob_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 的终止态判断调优任务的状态语义可归纳为状态含义是否终止态JOB_STATE_QUEUED/ 运行中各类中间态任务排队或正在执行否JOB_STATE_SUCCEEDED调优成功可进入模型部署阶段是JOB_STATE_FAILED调优失败如INVALID_ARGUMENT、FAILED_PRECONDITION等是JOB_STATE_CANCELLED已被用户取消是JOB_STATE_PARTIALLY_SUCCEEDED部分完成通常意味着部分检查点可用是8.2 location 语义global与真实区域开放模型Open Model调优任务通常以global作为 location 提交——服务会在运行时解析到有 GPU 容量的真实区域但子资源调优产物、检查点、TensorBoard的资源名中会携带真实区域而不是global。因此管理侧必须记住两条规则查询/取消时使用任务提交时的 locationglobal任务就用--location global轮询部署时从调优产物资源名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再向用户汇报取消已完成。九、实战检查清单将本文所有规则收敛为一张可执行的清单确认信息齐备Project ID 与 Region 均已从用户处确认缺失时停下询问环境就绪gcloud auth logingcloud auth application-default login已完成import vertexai探测通过失败才执行pip install google-cloud-aiplatform判断操作分级list/get直接执行Tier Rcancel先索要显式打字确认Tier D且确认与代码不得同回合出现构造资源名projects/{project_id}/locations/{region}/tuningJobs/{job_id}Job ID 为 19 位数字location 与提交时一致global就传global捕获失败遇到403/404/INVALID_ARGUMENT立即上报用户提示提供有效 ID停止执行等待回复不重试、不假设确认终止态取消后轮询至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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考