遷移至新模型

本文件說明如何將現有的 CX Agent Studio 代理應用程式遷移至其他基礎模型、驗證代理品質，以及分階段部署更新後的設定，不中斷實際正式環境流量。

遷移工作流程總覽

完整的模型遷移作業分為四個階段：

1. 隔離變更：為正式版代理應用程式建立不可變更的版本，或將應用程式匯出並匯入至獨立的測試環境。
2. 更新模型設定：使用控制台、匯出的設定檔或 REST API，變更全域模型、查看子代理和工具模型覆寫設定，以及驗證重試和備用設定。
3. 評估及調整成效：在模擬器中測試對話，使用「找出 AI 問題」功能執行評估，並使用 AI Co-Builder：Arc 調整指令，直到品質指標達到目標門檻。
4. 分階段部署：將驗證過的設定儲存為版本，並在部署管道上使用流量拆分，逐步轉移實際流量，同時監控結果。

步驟 1：隔離變更

變更模型設定前，請先隔離工作，以免更新和測試影響實際客戶對話。如要隔離變更，您可以在同一個代理應用程式中使用版本，或將應用程式匯出至獨立的沙箱環境。

在同一個代理應用程式中使用版本

如果部署管道指向特定不可變更的版本，則您對草稿代理應用程式所做的編輯，不會影響實際流量，直到您建立版本並指派給部署管道為止。

如要儲存目前設定的基準數據匯報，請按照下列步驟操作：

1. 開啟 CX Agent Studio 控制台，然後選取代理應用程式。
2. 在代理建構工具中開啟「Versions」(版本) 窗格。
3. 按一下「+ 建立版本」。
4. 輸入描述性名稱 (例如 pre-model-migration-baseline) 和說明 (選填)，然後按一下「Create」(建立)。
5. 開啟「Deploy」(部署) 分頁，確認有效的部署管道指向不可變更的版本 (「Versions」(版本) 窗格中會顯示「Live」(上線) 徽章)，而非可變更的草稿。

匯出及匯入至沙箱環境

如要改在獨立專案或測試應用程式中測試模型變更，請匯出代理應用程式，並匯入測試環境：

1. 開啟 CX Agent Studio 控制台，然後選取專案。
2. 在代理應用程式清單中，開啟應用程式的選單，然後選取「Export」(匯出)。
3. 如果沙箱環境使用不同的外部依附元件，例如資料儲存庫或服務端點，請擷取下載的封存檔、更新 environment.json 檔案，並將目錄壓縮成 ZIP 封存檔。詳情請參閱「環境檔案」。
4. 在沙箱專案或測試應用程式中，開啟應用程式選單，選取「Import」(匯入)，然後上傳封存檔。
5. 選用：從來源應用程式匯出評估測試案例，並匯入沙箱應用程式，以便執行迴歸測試。

步驟 2：更新模型設定

查看支援的模型清單，選擇與代理模態 (文字或語音) 相符的目標 Gemini 模型。您可以使用控制台、匯出的設定檔或 REST API 更新模型設定。

使用控制台更新模型

在控制台遷移代理應用程式時，請檢查全域應用程式模型、個別代理覆寫、資料儲存庫工具模型和備用設定：

1. 變更全域模型：
   1. 在代理建構工具中，開啟「Settings」(設定)，查看代理應用程式設定。
   2. 在「Basic」(基本) >「Interactions」(互動) 下方，選取「Global model」(全域模型) 欄位中的目標模型。如果應用程式中的代理未指定覆寫值，則預設使用這個模型。
2. 檢查根代理和子代理模型覆寫設定：
   1. 在代理建構工具中，開啟根代理標題列中的選單，然後選取「Edit config」(編輯設定)，查看代理設定。
   2. 查看「Model」(模型) 欄位。如果代理覆寫全域模型，請選取目標模型，或清除覆寫設定，讓代理沿用全域模型。
   3. 請對代理階層中的每個子代理重複這項檢查。
3. 查看資料儲存庫工具模型：
   1. 如果應用程式使用資料儲存庫工具，請開啟「Tools」(工具) 面板，然後選取各項資料儲存庫工具。
   2. 依序展開「Advanced」>「Modalities」，確認「Text」和「Voice」設定的「Rewriter model」和「Summarization model」選項。
4. 查看重試和備用設定：
   1. 開啟代理應用程式的「Settings」(設定)，然後依序前往「Basic」(基本) >「Behavior」(行為) >「Fallback behavior」(備用行為)。
   2. 確認「重試」、「代理回覆」和「備用」已正確設定，以便在模型生成期間處理錯誤。

注意：如果您要將語音代理從 gemini-composite-v1 遷移至 gemini-composite-v2，請一併檢查說話風格提示，並將方括號內嵌標記轉換為角括號。詳情請參閱「從 Composite V1 遷移」。

使用匯出的設定檔更新模型

如果您透過版本管控或 CI/CD 管道管理代理應用程式，可以在匯出的封存檔中更新模型設定，然後重新匯入套件：

1. 解壓縮匯出的代理應用程式 ZIP 封存檔。

2. 針對 agents/<var>AGENT_NAME</var>/ 下的每個代理目錄，開啟 agents/<var>AGENT_NAME</var>/<var>AGENT_NAME</var>.yaml 檔案，並將 modelSettings.model 欄位更新為目標模型 ID：

   displayName: "AGENT_NAME"
   modelSettings:
     model: "MODEL_ID"
   instruction: "agents/AGENT_NAME/instruction.txt"
   

   更改下列內容：

   • <var>AGENT_NAME</var>：代理的顯示名稱。
   • <var>MODEL_ID</var>：目標模型的 ID，例如 gemini-3.5-flash 或 gemini-composite-v2。

3. 將根目錄壓縮成 ZIP 封存檔，然後將更新後的封存檔匯入 CX Agent Studio。

使用 REST API 更新模型

您可以使用 CX Agent Studio REST API，以程式輔助方式更新代理應用程式和個別代理的 ModelSettings。

呼叫 API 前，請先收集下列值：

• <var>PROJECT_ID</var>：您的 Google Cloud 專案 ID。
• <var>LOCATION_ID</var>：代理應用程式的區域，例如 us 或 eu。
• <var>APP_ID</var>：代理應用程式的資源 ID。
• <var>AGENT_ID</var>：特定根代理或子代理的資源 ID。
• <var>MODEL_ID</var>：目標模型 ID，例如 gemini-3.5-flash。

如要更新代理應用程式的預設全域模型，請使用 updateMask=modelSettings 向 projects.locations.apps.patch 方法傳送 PATCH 要求：

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://ces.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/apps/APP_ID?updateMask=modelSettings" \
  -d '{
    "modelSettings": {
      "model": "MODEL_ID"
    }
  }'

如要更新個別根層級代理或子代理的模型覆寫設定，請使用 updateMask=modelSettings 向 projects.locations.apps.agents.patch 方法傳送 PATCH 要求：

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://ces.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/apps/APP_ID/agents/AGENT_ID?updateMask=modelSettings" \
  -d '{
    "modelSettings": {
      "model": "MODEL_ID"
    }
  }'

步驟 3：評估及調整代理成效

基礎模型的推論風格、指令遵循程度、詳細程度和工具呼叫行為可能有所不同。切換模型後，請測試代理並調整指令，再將實際客戶流量轉送至更新後的設定。

在模擬器中進行互動式測試

在「預覽代理」模擬器中執行初步健全狀態檢查：

1. 在代理建構工具中開啟模擬器，然後點選「Start new conversation」(發起新對話)。
2. 測試代表性的文字或音訊互動，並確認代理是否遵循指示、使用有效引數叫用工具，以及在子代理之間正常轉換。
3. 展開每個對話回合的追蹤記錄詳細資料，即可查看步驟延遲時間、工具輸入和輸出內容，以及原始 JSON 回覆。
4. 選用：如要將對話新增至迴歸套件，請開啟模擬器選單，然後選取「Save as golden」(儲存為黃金)。

運用 AI 執行評估及診斷問題

使用評估功能，評估黃金、情境和模擬測試案例的成效，並與基準版本比較結果：

1. 按一下代理建構工具頂端的「評估」。
2. 選取涵蓋關鍵使用者歷程和代理變體的測試案例，然後按一下「Run selected」(執行所選項目)。
3. 在執行對話方塊中，選取「Find issues with AI」，將執行次數設為 3 次以上，以獲得最佳 AI 分析結果，然後開始執行。詳情請參閱「使用 AI 改善測試案例」。
4. 執行完畢後，請查看評估指標，包括工具正確性、語意比對、使用者目標滿意度、目標達成數、幻覺和工作完成率，並檢查失敗的回合或未達成的目標。
5. 在結果頁面中，按一下「問問 Gemini」，即可查看生成的 loss_report、彙整失敗執行的根本原因，以及查看建議的指令或設定修正。

AI Co-Builder 登山指示：Arc

如果評估結果顯示目標模型有迴歸或行為變更，請使用 AI Co-Builder：Arc 和評估輔助工具，反覆調整提示：

1. 點選代理建構工具頂端的「Arc」，開啟 AI 協作建構工具。
2. 按一下「選取情境」，然後選取需要調整的特定代理或指令，或附加失敗的轉錄稿和損失報表。
3. 提示 Arc 更新指令或工具說明，解決觀察到的失敗問題，同時保留其他測試案例的行為。您也可以使用重組指令功能，將指令整理成結構化格式。
4. 套用修正後，請重新執行評估套件，並重複執行，直到所有測試案例都符合通過條件。如需其他指引，請參閱「評估和爬坡最佳做法」。

步驟 4：透過流量拆分功能分階段部署

更新後的代理通過評估後，請使用版本和部署流量拆分功能，逐步推出。

為遷移的代理建立版本

儲存已驗證設定的不可變更快照：

1. 如果您在獨立的沙箱應用程式中測試變更，請匯出經過驗證的應用程式套件，並匯入至正式版應用程式。
2. 在正式版應用程式中，開啟「Versions」(版本) 窗格，然後按一下「+ Create version」(建立版本)。
3. 輸入目標模型的名稱和說明 (例如 v2-gemini-3-5-flash)，然後點選「Create」(建立)。

逐步轉移實際流量

使用流量拆分功能，將一小部分即時對話轉送至遷移版本，然後再將流量提升至 100%：

1. 按一下代理建構工具頂端的「Deploy」(部署) 分頁標籤，然後選取部署管道。
2. 在「Agent version」(代理程式版本) 下方，按一下「Add version」(新增版本)，然後加入基準正式版和遷移候選版本。
3. 為候選版本指派較小的初始「流量百分比」(例如基準版本為 90%，候選版本為 10%，總計 100%)，然後儲存管道設定。您也可以使用 REST API，透過程式輔助方式設定 experimentConfig.versionRelease.trafficAllocations。
4. 監控各版本的實際成效：
   • 在監控資訊主頁查看工作階段數量、延遲時間和提報率。
   • 在對話記錄中檢查即時轉錄稿。
   • 在 BigQuery 中依 app_version_id 查詢匯出的互動記錄，比較不同版本的工具執行和結果率。如需 SQL 查詢範例，請參閱「在 BigQuery 中分析版本效能」。
5. 確認穩定性和品質後，請分階段提高遷移版本的流量百分比，直到該版本處理 100% 的即時流量。如果在推出期間發現非預期的問題，請將所有流量導回基準版本，或在「Versions」(版本) 窗格中還原先前的版本。