如何将 AI 聊天机器人从 GPT Assistant v1.2.0 迁移到 v1.3.0（Assistants API → Responses API）
本指南面向已经在 v1.2.0 上运行聊天机器人，并且需要在 Assistants API 停用之前在 v1.3.0 上重建它的客户。
为什么需要迁移
OpenAI 已弃用 Assistants API，并将其停用时间定为 2026 年 8 月 26 日。在该日期之后，任何仍基于 v1.2.0 的聊天机器人都可能停止工作。为避免服务中断，请在该日期之前迁移到基于 Responses API 的 v1.3.0 聊天机器人。
这次迁移是什么，不是什么
| 迁移不是自动的 | 没有可以把 v1.2.0 升级到 v1.3.0 的按钮。你需要创建一个新的 v1.3.0 扩展并重新进行配置。 |
| 会创建一个新的扩展 | 你的 v1.2.0 扩展保持不变。你会在它旁边单独安装一个 v1.3.0 扩展。 |
| 你的 v1.2.0 聊天机器人继续运行 | 在新机器人完全验证通过之前，保持旧机器人在线，这样你的客户始终不会收不到回复。 |
| 终端用户不受影响 | 客户仍然通过同一个 WhatsApp、Instagram、Facebook Messenger 或 Webchat 渠道发消息。改变的只是与 OpenAI 的内部连接。 |
推荐做法：先测试再迁移。
先创建新的 v1.3.0 聊天机器人，在测试环境中用一小组测试人员进行验证，等到你完全有把握后再切换到生产环境。这样在整个过程中，你的客户始终在与已经验证过的 v1.2.0 聊天机器人对话，不会中断。
开始之前
请确保你具备：
- 访问 v1.2.0 扩展配置的权限（你需要从中复制设置）。
- 你的 OpenAI API Key（可以复用同一个密钥）。
- 在 WOZTELL 中已连接至少一个渠道（WhatsApp Business Platform / Cloud API、Instagram、Facebook Messenger 或 Webchat）。
- 几位测试人员，你可以用他们的账号或电话号码安全地测试新的聊天机器人。
最快的迁移方式是：在一个标签页打开 v1.2.0 的配置，在另一个标签页打开新的 v1.3.0 扩展，然后逐项把设置复制过去。
步骤 1 — 保持 v1.2.0 聊天机器人在线
暂时不要断开或删除当前的聊天机器人。在你搭建和测试新机器人的整个过程中，它都保持在线并继续回复客户。你只会在最后切换到生产环境时（步骤 6）才将其停用。
步骤 2 — 创建新的 v1.3.0 扩展
你将作为一个独立的扩展，从头创建新的聊天机器人。
- 前往 Marketplace → + New Extension。
- 找到 ChatGPT 扩展卡片（Artificial Intelligence · OpenAI | WOZTELL），点击 Learn More。
- 在 Extension Version 中，选择 v1.3.0。
- 输入一个唯一的 Alias（小写、无空格），例如 my-gpt-assistant-v13。
- 点击 Install，然后在 Installed Extensions 中打开新的扩展。
- 在 API Key Setup 区域，粘贴你的 OpenAI API Key 并点击 Save。出现绿色对勾即表示密钥有效，并会解锁 Configuration 和 Connect to Channel 区域。
如需完整的、带截图的逐步设置说明，请参阅完整指南：How to Create an AI Chatbot with OpenAI in WOZTELL。本迁移指南只聚焦于从 v1.2.0 迁移所特有的步骤。
重要： 在保存 API Key 之前，你无法配置聊天机器人，也无法将其连接到渠道。
步骤 3 — 复制你的配置
在 v1.2.0 中，聊天机器人的所有行为都写在 prompt（Instructions）里。迁移它，主要就是把这个 prompt 复制过来并选择合适的模型。
在新的 v1.3.0 扩展中，打开 Configuration → AI Chatbot，设置 Instructions（prompt）、Model、Transcription model 以及高级设置。
了解渠道与环境
这是让安全迁移成为可能的关键概念，因此在连接任何东西之前值得先了解清楚。
- 渠道是连接到 WOZTELL 的沟通渠道，例如 WhatsApp、Instagram、Facebook Messenger 或 Webchat。
- 环境是渠道内部的一个工作空间，用于将测试与生产分开。如果你没有创建额外的环境，渠道会使用 Default 环境。
在迁移期间，环境让你可以在测试环境中运行新的 v1.3.0 聊天机器人，同时让你的 v1.2.0 聊天机器人继续留在线上（Default/生产）环境。在你决定切换之前，客户始终在与经过验证的旧聊天机器人对话。
如果两个聊天机器人最终在同一个环境中同时处于激活状态，就会产生不可预测的回复（用户会被随机引导到其中一个机器人，无法控制）。使用独立的测试环境正是避免这种情况的方法。
步骤 4 — 将新聊天机器人连接到测试环境
现在连接新的聊天机器人——但要连接到测试环境，而不是生产环境。
- 如果还没有测试环境，请为你的渠道创建一个测试环境并指定测试人员。参阅：How to create a test environment。
- 在 v1.3.0 扩展中，打开 Connect to Channel 区域。
- 找到你的渠道，选择你创建的测试环境——不要选择 v1.2.0 正在运行的 Default/生产环境。
- 点击 Connect。
- 如有要求，输入一个 Prefix Name；使用清晰的标签，例如 AI-CHATBOT-WHATSAPP-TEST。
- 点击 Confirm，然后再次点击 Connect。
当按钮变为 Disconnect 时，说明新的聊天机器人已仅在测试环境中上线。
步骤 5 — 测试与验证
现在，只有你白名单中的测试人员才会被引导到测试环境和新的 v1.3.0 聊天机器人。生产环境——以及你真正的客户——仍然停留在 v1.2.0，不受影响。
让你的测试人员对新聊天机器人进行充分测试：
- 用白名单中的设备或号码，向该渠道发送消息。
- 确认聊天机器人会回复，并且回复内容与你的 Instructions 一致。
- 测试不同类型的问题和边界情况（包括超出聊天机器人范围的问题）。
- 如果你添加了 Knowledge Base / File Search，提出一些应当依据你的文档来回答的问题，确认其正常工作。
- 查看 logs，检查是否有错误（API Key、模型、tools、File Search 或渠道连接问题）。
步骤 6 — 切换到生产环境
当你对新聊天机器人有把握后，把线上渠道从 v1.2.0 切换到 v1.3.0。
- 将 v1.2.0 聊天机器人从生产（Default）渠道/环境断开。
- 将 v1.3.0 聊天机器人连接到该生产环境（步骤与步骤 4 相同，但这一次选择生产环境）。
- 发送最后一次实时测试，确认新聊天机器人在生产环境中正常回复。
确认 v1.3.0 在生产环境中正常运行后，你就可以安全地删除旧的 v1.2.0 扩展了。
迁移期间的常见问题
| 问题 | 原因 | 解决方法 |
|---|---|---|
| 回复不可预测／用户被引导到错误的机器人 | 两个聊天机器人在同一个环境中同时处于激活状态。 | 让 v1.2.0 和 v1.3.0 处于不同的环境。切换时，先断开一个，再在同一环境中连接另一个。 |
| 测试人员无法访问新的聊天机器人 | 没有分配 Priority Group，或测试人员未被加入其中。 | 确认 Priority Group 已分配给测试环境，并且每位测试人员都在白名单中（WhatsApp 测试人员必须先向 WABA 发送消息）。 |
| 某些基于 prompt 的逻辑表现不同 | Responses API 处理上下文的方式与 Assistants API 不同。 | 在验证期间检查并调整 prompt；可考虑将参考内容移到 File Search。 |
| 助手在测试环境中没有回复 | 未保存 API Key、未连接聊天机器人，或选择了错误的环境。 | 确认 API Key 已保存、聊天机器人已连接，并且你是在向正确的环境发送消息。 |
相关文章
- How to Create an AI Chatbot with OpenAI in WOZTELL | User Guide
- How to create a new environment
- Introduction to AI Chatbots with OpenAI + WOZTELL
- 14 Frequently Asked Questions About the New AI Chatbots with OpenAI + WOZTELL