agent-platform-tuning

Agent Platform 模型微调

概述

本 Skill 提供了基于 Agent Platform 微调服务微调大语言模型（涵盖开源模型与 Gemini 模型）的流程操作指南。包含从环境配置、数据准备到任务配置、监控与部署的完整生命周期。

工作流决策树

1. 确定模型类别：用户是否已明确说明要微调**开源模型（Open Model）**还是 Gemini 模型？

   • 否 → 停止。询问用户希望微调开源模型还是 Gemini 模型。针对环境配置请求的重项例外：如果用户专门询问环境配置说明（例如“需要做哪些环境配置？”），你必须在初始回复中提供完整的 Phase 0 环境配置与 IAM 权限 说明，同时询问模型类别的确认问题。
   • 如果用户提供了具体的微调目标，你应该推荐三种模型：一款开源模型、一款 Gemini 模型，以及一款通用推荐选择。简要列出各自的优缺点（例如，Gemini 模型可能成本较高）。重要提示：在此步骤中，你必须读取 references/models.md，并且只能推荐该目录中明确列出的模型。切勿推荐 Mistral 等不受支持的模型。如果用户指名的模型不在目录中，请遵循该目录中的降级规则（fallback rule）。在确认模型类别之前，不要继续进行模型配置。
   • 是 → 继续。

2. 环境检查：基础环境（身份认证、API、IAM、虚拟环境）是否已初始化？

   • 否 → 前往 Phase 0：环境配置与 IAM 权限。
   • 是 → 继续。

3. 数据集状态：数据集是否已准备为 JSONL 格式、数据结构是否符合微调要求，并且已上传至 Google Cloud Storage？

   -   **否** → 前往 [Phase 1：数据集准备与上传](#phase-1)。
   -   **是** → 继续。
   

4. 列选择确认：你是否已向用户展示数据列并确认了字段映射？

   • 否 → 停止。在继续之前，你必须展示数据示例，并按照 Phase 1.0 的要求获得用户对字段映射的确认。
   • 是 → 继续。

5. 配置确认：用户是否已提供目标模型与超参数，或者明确同意了你的推荐方案？

   • 否 → 前往 Phase 2：模型配置与推荐。
   • 是 → 继续。

6. 任务状态：微调任务（Tuning Job）是否已提交？

   -   **否** → 前往 [Phase 3：微调任务执行](#phase-3-tuning-job-execution)。
   -   **是** → 继续。
   

7. 任务完成状态：微调任务是否已完成？

   -   **否** → 前往 [Phase 4：任务监控](#phase-4-monitoring)。
   -   **是** → 继续。
   

8. 部署状态：微调后的模型是否已部署（如需要）？

   -   **否** → 前往 [Phase 5：模型部署](#phase-5-model-deployment)。
   -   **是** → 任务完成。
   

Phase 0：环境配置与 IAM 权限 {#phase-0}

在继续之前，请确保基础环境已就绪。

0.1 身份认证与项目上下文

• 检查是否已安装 gcloud CLI。如果未安装，在继续之前提示用户授权安装。如果已安装，请执行更新：

gcloud components update --quiet > /dev/null 2>&1

• 校验 gcloud auth list。如果未认证，运行 gcloud auth login。
• 确保明确了 project。使用 gcloud config get project 获取当前项目。
• 重要提示：请求用户确认。 在继续之前，必须提示用户确认获取到的项目，以防他们想切换到其他项目。Location（位置）也必须确认——关于推荐哪个 location，详见 0.2 节，这取决于模型类别。

0.2 Location（位置/区域设置）

Location 的处理取决于工作流决策树中确定的模型类别。这两类模型支持的 location 不同——切勿将一类的 location 设置套用到另一类上。

• 开源模型（Open models） 共享一组固定的 location 列表，推荐选择 global。
• Gemini 模型 各模型支持的 location 不同，必须单独查询。目前 Gemini 模型不支持 global。

如果用户指定的 location 对于其选择的模型和类别无效，立即停止。返回错误并明确指出请求的 location 不受支持，列出有效的 location 列表。切勿索要数据集，切勿继续执行任何其他配置步骤，也切勿静默重试其他位置。

开源模型（推荐：global）

推荐 global 并向用户确认。 将其作为单一推荐选项提出，而不是让用户先挑选区域，也不要引导他们选择具体区域。

以下是开源模型微调仅支持的 location 列表：

• global（推荐选项）
• us-central1
• europe-west4
• us-west1
• us-east5
• asia-southeast1

global Endpoint 会自动选择有可用容量且受支持的区域，因此成功调度任务的概率最高。预先固定某个区域会将任务限制在对应区域的容量中，这就是为什么 global 是开源模型微调推荐 Location 的原因。

• 用户指定了 Location → 只要是 global 或上述列表中的区域，直接原样使用，不要试图说服他们修改。
• 用户询问支持哪些 Location → 回答该问题。提供上述列表，并说明为什么推荐 global。切勿隐瞒信息。
• 用户未指定 Location → 建议使用 global，并在继续前要求他们确认。告知用户 global 能让服务自动挑选有可用容量的区域。切勿在未确认的情况下静默默认使用 global。

提出单一推荐选项的目的是避免让区域选择成为阻碍后续流程的前置决策——这种顺序过去常导致流程卡住。但这并不是隐藏支持列表的理由：每当用户询问时，或者在拒绝不受支持的 location 时，都应当完整列出。

仅在以下情况下降级使用具体区域，并向用户说明原因：

• CMEK（客户管理的加密密钥）。 global 上的 CMEK 保护任务会被拒绝并返回 FAILED_PRECONDITION 错误。受 CMEK 保护的任务必须明确指定保存密钥的具体区域。

• 数据驻留需求。 如果用户要求任务数据留在特定司法管辖区内，请尊重其区域选择。global 目前会在 us-central1 或 europe-west4 中运行任务。

如果提交 global 任务被接受，但随后因 FAILED_PRECONDITION 报错（提示模型不支持 global endpoint tuning），说明该模型尚未接入 global endpoint。模型本身依然支持微调：请从上述列表中显式指定一个区域（us-central1 是最稳妥的选择）重新提交一次，并向用户解释切换区域的原因。

使用 global 任务注意事项

• API Host 仍为 aiplatform.googleapis.com，不存在 global-aiplatform.googleapis.com 这个域名。
• 服务会在运行时将 global 解析为实际区域。子资源（微调后的模型、检查点 checkpoint、TensorBoard）在返回时，其资源名称中会包含实际区域，而不是 global。在将返回的资源名称用于监控或部署前，请从中提取实际 location，切勿盲目假设其仍为 global。
• 配额（Quota）是跨区域共享的，因此固定特定区域并不会获得额外的配额。

Gemini 模型（按模型查询）

目前 Gemini 微调不支持 global ——服务会在创建任务时拒绝并报错 FAILED_PRECONDITION，因此切勿在此处推荐 global。

Gemini 没有统一的区域白名单。 支持微调的区域因模型和模型版本而异：部分 Gemini 模型仅限制在两个区域，而其他模型则支持更多区域。切勿复用上述开源模型的区域列表，也切勿假设某个区域可以从其他 Gemini 模型继承。

在提交任务之前，请务必查阅监督式微调（supervised fine-tuning）官方文档，并读取其 "Supported endpoint for model tuning" 对应行：
supervised tuning

• 用户询问支持哪些区域 → 查询该特定模型并告知文档中的说明。不要凭记忆或参考开源模型列表回答，也不要参考其他 Gemini 模型回答。
• 模型的表格行中列出了具体区域 → 用户指定的区域必须是其中之一。如果不在其中，立即停止并告知用户该模型支持的区域。
• 模型的表格行缺失或文档不明确 → 询问用户要使用哪个区域，而不是盲目猜测。

在继续操作前向用户确认区域。请注意，某些 Gemini 模型还会限制 CMEK，并且仅在 us 和 eu 多区域 Endpoint 上提供微调模型的服务，因此在做出承诺前请先查阅同一表格中的相关限制。

0.3 启用 API

确保已启用 aiplatform.googleapis.com 和 storage.googleapis.com。

gcloud services enable aiplatform.googleapis.com storage.googleapis.com \
    --project=YOUR_PROJECT

0.4 IAM 权限

验证以下身份是否具有所需的 Role（角色）：

• Agent Platform Service Agent：
  service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com
• Managed OSS Fine Tuning Service Agent：
  service-PROJECT_NUMBER@gcp-sa-vertex-moss-ft.iam.gserviceaccount.com
• 用户身份：运行命令的账号。

0.5 Python 依赖

本 Skill 中的脚本导入了 vertexai（来自 google-cloud-aiplatform）、google-genai、google-cloud-storage 以及 datasets。

Agent 重要指令： 切勿创建虚拟环境（venv），也不要在检查之前安装任何依赖。全新的 venv 是空的，会掩盖当前环境已提供的软件包，从而强制进行冗长且重复的数分钟安装。

请先进行检测，仅在检测失败时才安装：

python3 -c "import vertexai, google.genai, google.cloud.storage, datasets" \
  || pip install -r references/requirements.txt

随后直接使用 python3 scripts/... 运行每个脚本——无需激活虚拟环境前缀。

references/requirements.txt 中的版本锁定仅作为未提供这些 SDK 的环境的降级备选方案。切勿在已有可用环境的基础上重复叠加安装：这可能会降级其他工具共用的软件包。

Phase 1：数据集准备与上传 {#phase-1}

1.0 数据集查找与确认

• 用户提供的数据集验证： 如果用户在 Prompt 中指定了数据集文件名或路径，请验证其在工作区中的存在性（例如通过运行脚本检查或排查拼写错误）。
  • 如果完全找不到该文件，你必须告知用户数据集文件不存在或无法访问。你必须提示用户提供有效的数据集路径。或者，如果在搜索过程中在工作区中找到了候选数据集文件，你必须将候选列表展示给用户并请他们选择一个。在汇报后你必须立即停止工具执行