Agent Platform 模型微調。當您需要使用 Agent Platform 基礎架構微調開放模型或 Gemini 模型時使用。請勿用於 Agent Platform 以外的模型訓練、將模型部署至端點（請使用 `agent-platform-deploy`），或管理服務端點（請使用 `agent-platform-endpoint-management`）。
Agent Platform 模型微調
概覽
本 Skill 提供使用 Agent Platform 微調服務來微調大型語言模型（包含開放模型與 Gemini 模型）的操作流程與實務知識。內容涵蓋從環境設定、資料準備到工作（Job）設定、監控與部署的完整生命週期。
工作流程決策樹
-
模型類別確認：使用者是否已明確說明要微調的是開放模型還是 Gemini 模型？
- 否 → 停止。詢問使用者想要微調開放模型還是 Gemini 模型。環境設定要求的關鍵例外：如果使用者是專門詢問環境設定說明（例如「需要進行哪些環境設定？」），您必須在初始回覆中提供完整的 Phase 0 環境設定 說明，同時提出澄清問題以確認模型類別。
- 如果使用者提供了特定的微調用途，您應該推薦三款模型：一款開放模型、一款 Gemini 模型，以及第三款通用推薦選項。簡要列出各自的優缺點（例如 Gemini 模型可能費用較高 等）。關鍵：在此步驟中，您必須閱讀
references/models.md，且僅能推薦該目錄中明確列出的模型。切勿推薦 Mistral 等不支援的模型。若使用者提及的模型不在目錄中，請遵循該目錄的備援（fallback）規則。在確認模型類別之前，請勿繼續進行模型設定。 - 是 → 繼續執行。
-
環境檢查：環境（驗證 Auth、API、IAM、虛擬環境 Venv）是否已初始化？
- 否 → 前往 Phase 0：環境與 IAM 設定。
- 是 → 繼續執行。
-
資料集狀態：資料集是否已準備好格式為 JSONL 的檔案、其結構是否符合微調規範，且已上傳至 Google Cloud Storage？
- **否** → 前往 [Phase 1：資料集準備與上傳](#phase-1)。 - **是** → 繼續執行。 -
欄位選取確認：您是否已向使用者展示欄位並確認對映關係？
- 否 → 停止。在繼續之前，您必須按照 Phase 1.0 的說明向使用者展示範例，並取得使用者對欄位對映的確認。
- 是 → 繼續執行。
-
設定：使用者是否已提供目標模型與超參數，或已明確同意您的推薦方案？
- 否 → 前往 Phase 2：模型設定與推薦。
- 是 → 繼續執行。
-
工作狀態：微調工作是否已提交？
- **否** → 前往 [Phase 3：微調工作執行](#phase-3-tuning-job-execution)。 - **是** → 繼續執行。 -
工作完成狀態：微調工作是否已完成？
- **否** → 前往 [Phase 4：監控](#phase-4-monitoring)。 - **是** → 繼續執行。 -
部署：微調後的模型是否已部署（若有需要）？
- **否** → 前往 [Phase 5：模型部署](#phase-5-model-deployment)。 - **是** → 任務完成。
Phase 0：環境與 IAM 設定 {#phase-0}
在繼續之前，請確保基礎環境已準備就緒。
0.1 身份驗證與專案上下文
- 檢查是否已安裝
gcloudCLI。如果未安裝，請先詢問使用者是否同意安裝後再繼續。如果已安裝，請將其更新：
gcloud components update --quiet > /dev/null 2>&1
- 驗證
gcloud auth list。若未通過身份驗證，請執行gcloud auth login。 - 確認已知曉
project。使用gcloud config get project取得目前專案。 - 關鍵：要求確認。 在繼續之前，您必須提示使用者確認取得的專案，以防他們想要切換至其他專案。位置也必須經過確認——請參閱 0.2 節，了解應根據模型類別建議哪種位置。
0.2 位置 (Location)
位置處理方式取決於您在工作流程決策樹中建立的模型類別。這兩種類別支援的位置不同——切勿將某一類別的位置套用到另一類別。
- 開放模型共用一組固定位置，建議選擇
global。 - Gemini 模型因模型而異，必須進行查閱。目前不支援對其使用
global。
如果使用者指定了對其模型和類別無效的位置，請停止。回覆錯誤訊息，指出所要求的位置不受支援，列出有效的位置，並且不要要求提供資料集、不要繼續進行任何其他設定步驟，也不要靜默地在其他地方重試。
開放模型 (推薦：global)
推薦 global 並與使用者確認。 請將其作為單一推薦選項提出，而不是讓使用者先選擇區域，也不要引導他們改選特定的區域。
以下是開放模型微調唯一可用的位置：
global（推薦選項）us-central1europe-west4us-west1us-east5asia-southeast1
global 端點會自動選擇具有可用容量且支援的區域，因此最有可能排程成功。預先指定區域會將工作限制在該單一區域的容量內，這正是推薦使用 global 進行開放模型微調的原因。
- 使用者已指定位置 → 只要該位置是
global或上述列出的區域之一，即直接使用。不要試圖說服他們變更。 - 使用者詢問支援哪些位置 → 回答該問題。分享上述清單，並說明為何推薦
global。切勿隱瞞。 - 使用者未指定位置 → 提出
global並要求他們在繼續之前進行確認。說明global可以讓服務自行選擇有可用容量的區域。切勿靜默假定使用global。
提出單一選項的目的，是為了避免讓區域選擇成為使用者在執行其他任何操作前必須決定的卡關點——這種順序在過去常常卡住使用者。但這並不是隱藏清單的理由：只要使用者詢問，或者在拒絕不支援的位置時，請務必引用該清單。
僅在下列情況下回退到明確的特定區域，並告知使用者為何要這樣做：
-
CMEK。 客戶管理密鑰 (Customer-managed encryption keys) 在
global上會被拒絕並傳回FAILED_PRECONDITION錯誤。受 CMEK 保護的工作必須指定保存密鑰的區域。 -
資料駐留 (Data residency)。 如果使用者要求工作必須保留在特定的管轄區域內，請尊重其指定的區域。目前
global會在us-central1或europe-west4中執行工作。
若 global 工作被接受，但隨後失敗並傳回 FAILED_PRECONDITION 錯誤（指出該模型不支援全域端點微調），代表該模型尚未整合至全域端點。模型本身仍然可以微調：請使用上述清單中的明確區域（us-central1 是最安全的選擇）重新提交一次，並告知使用者切換的原因。
使用 global 工作
- API 主機保持為
aiplatform.googleapis.com。不存在global-aiplatform.googleapis.com這樣的主機。 - 服務會在執行階段將
global解析為真實區域。子資源（微調後的模型、檢查點 checkpoint、TensorBoard）在其資源名稱中會返回該真實區域，而非global。在將其用於監控或部署之前，請從返回的資源名稱中讀取位置；切勿假定其仍為global。 - 配額在不同區域之間共享，因此指定固定區域不會獲得額外配額。
Gemini 模型 (按模型查閱)
global 目前不適用於 Gemini 微調 — 服務會在建立工作時拒絕並傳回 FAILED_PRECONDITION 錯誤，因此請勿在此處提出此建議。
Gemini 沒有單一的區域允許清單。 支援微調的區域因模型和模型版本而異：某些 Gemini 模型僅限於兩個區域，而其他模型則支援更多區域。切勿重用上述的開放模型清單，也切勿假定區域可以從另一個 Gemini 模型延用。
在提交之前，請在監督式微調文件中查閱所選的模型，並閱讀其 "Supported endpoint for model tuning" 橫列：
supervised tuning
- 使用者詢問支援哪些區域 → 查閱該特定模型並告知文件內容。不要憑記憶或從開放模型清單回答，也不要回答其他 Gemini 模型的資訊。
- 模型的橫列指定了特定區域 → 使用者的區域必須是其中之一。如果不是，請停止並回報該模型支援的區域。
- 模型的橫列缺失或文件不明確 → 請向使用者詢問區域，而不是盲目猜測。
在繼續之前與使用者確認區域。請注意，某些 Gemini 模型還會限制 CMEK，且僅在 us 和 eu 多區域端點上提供微調後的模型，因此在承諾之前請檢查同一表格的限制。
0.3 啟用 API
確保已啟用 aiplatform.googleapis.com 和 storage.googleapis.com。
gcloud services enable aiplatform.googleapis.com storage.googleapis.com \
--project=YOUR_PROJECT
0.4 IAM 權限
驗證以下身份是否具有所需的角色。
- Agent Platform 服務代理 (Service Agent)：
service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com - Managed OSS Fine Tuning 服務代理：
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 指示： 在檢查之前不要建立虛擬環境，也不要安裝任何東西。虛擬環境初始為空，會隱藏環境中已提供的套件，進而迫使進行數分鐘的冗餘安裝。
先進行探測，僅在探測失敗時才安裝：
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 資料集探索與確認
- 使用者提供之資料集驗證： 如果使用者在其提示詞中指定了資料集檔名或路徑，請驗證其是否存在於工作區中（例如透過指令稿執行或檢查拼字錯誤）。
- 如果完全找不到該檔案，您必須告知使用者資料集檔案不存在或無法存取。您必須提示使用者提供有效的資料集路徑。或者，如果在搜尋過程中於工作區中找到了候選資料集檔案，您必須將候選檔案展示給使用者，並要求他們選擇一個。在回報後，您必須立即停止工具執行
<!-- truncated for translation batch; full body continues in source -->
