迁移到新模型

本文档介绍了如何将现有 CX Agent Studio 智能体应用迁移到其他基础模型、验证智能体质量，以及分阶段部署更新后的配置，而不会中断实时生产流量。

迁移工作流概览

完整的模型迁移分为四个阶段：

  1. 隔离更改：为生产代理应用创建不可变的版本，或将应用导出并导入到单独的测试环境中。
  2. 更新模型设置：使用控制台、导出的配置文件或 REST API 更改全局模型、查看分代理和工具模型替换，以及验证重试和后备设置。
  3. 评估和优化性能：在模拟器中测试对话，使用利用 AI 发现问题运行评估，并使用 AI Co-Builder：Arc 调整指令，直到质量指标达到目标阈值。
  4. 分阶段部署：将经过验证的配置保存为版本，并在部署渠道上使用流量分配，以便在监控结果的同时逐步转移实时流量。

第 1 步：隔离更改

在更改模型设置之前，请先隔离您的工作，以免更新和测试影响实际的客户对话。您可以通过在同一代理应用中使用版本，或将应用导出到单独的沙盒环境来隔离更改。

在同一代理应用中使用版本

当部署渠道指向特定的不可变版本时，您对代理应用草稿所做的修改不会影响实时流量，直到您创建版本并将其分配给部署渠道。

如需保存当前配置的基准快照，请执行以下操作：

  1. 打开 CX Agent Studio 控制台，然后选择您的代理应用。
  2. 在代理构建器中打开版本窗格。
  3. 点击 + 创建版本。
  4. 输入描述性名称（例如 pre-model-migration-baseline）和可选说明，然后点击创建。
  5. 打开部署标签页，验证您的有效部署渠道是否指向不可变版本（由版本窗格中的有效标记指示），而不是可变草稿。

导出和导入到沙盒环境

如果您希望在单独的项目或预演应用中测试模型更改，请导出代理应用并将其导入测试环境：

  1. 打开 CX Agent Studio 控制台，然后选择您的项目。
  2. 在代理应用列表中，打开应用的菜单，然后选择导出。
  3. 如果您的沙盒环境使用不同的外部依赖项（例如数据存储区或服务端点），请解压缩下载的归档文件，更新 environment.json 文件，然后将目录压缩为 ZIP 归档文件。如需了解详情，请参阅环境文件。
  4. 在沙盒项目或测试应用中，打开应用菜单，选择导入，然后上传归档。
  5. 可选：从源应用导出评估测试用例，并将其导入沙盒应用，以便运行回归测试。

第 2 步：更新模型设置

查看支持的模型列表，选择与代理的模态（文本或语音）相匹配的目标 Gemini 模型。您可以使用控制台、导出的配置文件或 REST API 更新模型设置。

使用控制台更新模型

在控制台中迁移代理应用时，请检查全局应用模型、各个代理替换、数据存储区工具模型和后备设置：

  1. 更改全局模型：
    1. 在代理构建器中，打开设置以查看代理应用设置。
    2. 在基本 > 互动下，在全局模型字段中选择目标模型。此模型将作为应用中所有未指定替换项的智能体的默认模型。
  2. 检查根智能体和子智能体模型替换设置：
    1. 在 Agent Builder 中，打开根代理标题栏中的菜单，然后选择修改配置以查看代理设置。
    2. 检查模型字段。如果代理替换了全局模型，请选择目标模型或清除替换，以便代理继承全局模型。
    3. 对代理层次结构中的每个子代理重复此检查。
  3. 检查数据存储区工具模型：
    1. 如果您的应用使用数据存储区工具，请打开工具面板，然后选择每个数据存储区工具。
    2. 展开高级 > 模态，然后验证文本和语音配置的重写器模型和摘要模型选择。
  4. 查看重试和回退设置：
    1. 打开代理应用的设置，然后依次前往基本 > 行为 > 后备行为。
    2. 验证重试、智能体回答和后备是否已正确配置，以便在模型生成期间进行错误处理。

使用导出的配置文件更新模型

如果您通过版本控制或 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>：目标模型的标识符，例如 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>：目标模型标识符，例如 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"
    }
  }'

如需更新单个根智能体或子智能体上的模型替换，请向 projects.locations.apps.agents.patch 方法发送 PATCH 请求，并附带 updateMask=modelSettings：

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. 在代理构建器中打开模拟器，然后点击开始新对话。
  2. 测试具有代表性的文本或音频互动，并验证智能体是否遵循指令、使用有效参数调用工具，以及是否按预期在子智能体之间切换。
  3. 展开每个轮次的跟踪记录详情，以检查步骤延迟时间、工具输入和输出以及原始 JSON 响应。
  4. 可选：如需将对话添加到回归套件，请打开模拟器菜单，然后选择另存为黄金。

使用 AI 运行评估并诊断问题

使用评估来衡量黄金测试用例、场景测试用例和模拟测试用例的效果，并将结果与基准版本进行比较：

  1. 点击智能体构建器顶部的评估。
  2. 选择涵盖关键用户历程和代理变体的测试用例，然后点击运行所选测试用例。
  3. 在运行对话框中，选择使用 AI 查找问题，将运行次数设置为 3 次或更多，以获得最佳 AI 分析效果，然后开始运行。如需了解详情，请参阅使用 AI 改进测试用例。
  4. 运行完成后，查看评估指标，包括工具正确性、语义匹配、用户目标满意度、目标达成次数、幻觉和任务完成情况，并检查所有失败的轮次或未达成的目标。
  5. 在结果页面上，点击问问 Gemini，查看生成的 loss_report、总结失败运行的根本原因，以及查看建议的指令或配置修复。

AI Co-Builder 爬坡说明：Arc

如果评估结果显示目标模型下存在回归或行为变化，请使用 AI Co-Builder: Arc 和评估辅助工具来迭代优化提示：

  1. 点击智能体构建器顶部的 Arc，打开 AI Co-Builder。
  2. 点击选择上下文，然后选择需要调整的特定代理或指令，或者附加失败的转录内容和损失报告。
  3. 提示 Arc 更新指令或工具说明，以解决观察到的失败问题，同时保留其他测试用例的行为。您还可以使用重构指令功能将指令整理成结构化格式。
  4. 应用修复后，重新运行评估套件，并重复此过程，直到所有测试用例都符合通过条件。如需更多指导，请参阅评估和爬山最佳实践。

第 4 步：通过流量分配分阶段部署

更新后的智能体通过评估后，使用版本和部署流量分配功能逐步发布。

为迁移后的代理创建版本

保存已验证配置的不可变快照：

  1. 如果您在单独的沙盒应用中测试了更改，请导出经过验证的应用软件包，并将其导入到生产应用中。
  2. 在生产应用中，打开版本窗格，然后点击 + 创建版本。
  3. 输入用于标识目标模型的名称和说明，例如 v2-gemini-3-5-flash，然后点击创建。

逐步迁移实时流量

使用流量分配将一小部分实时对话路由到迁移后的版本，然后再将其提升到 100% 的流量：

  1. 点击代理构建器顶部的部署标签页，然后选择部署渠道。
  2. 在智能体版本下，点击添加版本，然后添加基准正式版和迁移后的候选版本。
  3. 为候选版本分配一个较小的初始流量百分比（例如，基准版本为 90%，候选版本为 10%，总计 100%），然后保存渠道配置。您还可以使用 REST API 以编程方式配置 experimentConfig.versionRelease.trafficAllocations。
  4. 监控不同版本的实时性能：
  5. 在确认稳定性和质量后，分阶段提高迁移版本的流量百分比，直到其处理 100% 的实时流量。如果您在发布期间检测到意外问题，请将 100% 的流量路由回基准版本，或在版本窗格中恢复先前版本。