迁移到 V2 API

2018 年 11 月推出了 watsonx Assistant v2 运行时 API，支持使用助手和技能。此 API 相比于 V1 运行时 API，提供了多项显著优势，包括自动状态管理、轻松部署、技能版本控制以及可用的新功能（如搜索技能）。

V2 API 可供所有用户使用，与服务套餐无关，也无需额外费用。

V2 API 目前仅支持与现有助手的运行时交互。用于创建或修改工作空间的编写应用程序应该继续使用 V1 API。

概述

通过 v2 API，您的客户机应用程序与一个助手进行通信，该助手是一个编排层，提供多种功能，包括自动状态管理，技能版本控制和更轻松的部署。

与助手的所有交流都是在届会的上下文中进行的，它在整个对话过程中保持对话状态。 watsonx Assistant 会自动存储状态数据（包括对话或客户机应用程序定义的任何上下文变量），无需应用程序方面执行任何操作。

状态数据会持久存储，直到您显式删除会话，或者由于没有活动而导致会话超时为止。

如果您希望自己管理状态，那么 v2 API 还提供了一种无状态 message 方法，其功能更类似于 v1 API。如果使用无状态 message 方法，那么不需要显式创建或删除会话，并且应用程序负责维护上下文。有关无状态 message 方法的更多信息，请参阅 API 参考。

如果您有现有应用程序是使用 V1 API 将用户输入直接发送到工作空间，那么迁移应用程序以使用 V2 API 是一个简单的过程。

助手标识

v2 运行时 API 将消息发送到助手。在助手设置页面上，查找助手标识。应用程序使用此标识与助手进行通信。 V1 和 V2 API 的服务凭证相同。

目前，API 不支持检索助手标识。要查找助手标识，必须使用 watsonx Assistant 用户界面。

调用 V2 运行时 API

创建助手后，您可以更新客户端应用程序，以使用 v2 运行时 API 而不是 v1 运行时 API。

在会话中发送第一条信息之前，请使用 v2 创建会话方法创建会话。保存返回的会话标识：

service
.createSession({
 assistant_id: assistantId,
})
.then(res => {
 sessionId = res.session_id;
})

session_id = service.create_session(
   assistant_id = assistant_id
).get_result()['session_id']

CreateSessionOptions createSessionOptions = new CreateSessionOptions.Builder(assistantId).build();
SessionResponse session = service.createSession(createSessionOptions).execute().getResult();
String sessionId = session.getSessionId();

使用 v2 发送用户输入到助手方法将用户输入发送到助手。不要像使用 V1 API 那样指定工作空间标识，请改为指定助手标识和会话标识：

service
  .message({
    assistant_id: assistantId,
    session_id: sessionId,
    input: messageInput
  })

 response = service.message(
    assistant_id,
    session_id,
    input = message_input
 ).get_result()

 MessageInput input = new MessageInput.Builder().text(inputText).build();
 MessageOptions messageOptions = new MessageOptions.Builder(assistantId, sessionId)
   .input(input)
   .build();
 MessageResponse response = service.message(messageOptions)
   .execute()
   .getResult();

基本消息结构未更改；尤其是，用户输入仍作为 input.text 发送。

对话结束后，使用 v2 删除会话方法删除会话。

service
  .deleteSession({
    assistant_id: assistantId,
    session_id: sessionId,
  })

service.delete_session(
    assistant_id = assistant_id,
    session_id = session_id
)

DeleteSessionOptions deleteSessionOptions = new DeleteSessionOptions.Builder(assistantId, sessionId
  .build();
service.deleteSession(deleteSessionOptions).execute();

如果您未显式删除会话，那么系统将在配置的超时时间间隔后自动删除该会话。超时持续时间取决于您的计划。

要查看简单客户端应用程序中 v2 API 的示例，请参阅使用 API 构建自定义客户端。

处理 V2 响应格式

应用程序可能需要更新才能处理 V2 运行时响应格式，具体取决于应用程序需要访问响应的哪些部分：

所有响应类型（例如，text 和 option）的输出仍在 output.generic 对象中返回。用于处理这些响应的应用程序代码应该无需修改就能正常工作。
现在，检测到的意向和实体会作为 output 对象的一部分返回，而不是在响应 JSON 的根返回。
现在，交谈上下文组织成两个对象：
- 全局上下文包含系统级上下文数据，由助手中的所有技能共享。
- 技能上下文包含对话框技能使用的任何用户定义的上下文变量。
但是，请谨记，状态数据（包括交谈上下文）现在由助手进行维护，因此应用程序可能根本不需要访问上下文（请参阅让助手维护状态）。

有关 v2 回复格式的完整文档，请参阅 v2 应用程序接口参考。

让助手维护状态

对于大多数应用程序，您现在可以删除任何用于维护状态的代码。不必再保存上下文并针对每轮交谈将其发送回 watsonx Assistant。上下文将由 watsonx Assistant 自动维护，并且对话可以像以前一样访问上下文。

请注意，使用 V2 API 时，缺省情况下，上下文并不会包含在对客户机应用程序的响应中。但是，如果需要，代码仍可以访问上下文变量：

您仍然可以将 context 对象作为消息输入的一部分发送。您加入的任何上下文变量都将作为 watsonx Assistant 维护的上下文的一部分存储。（如果发送的上下文变量在上下文中已存在，那么新值会覆盖先前存储的值。）

确保您发送的上下文对象符合 v2 格式。应用程序发送的所有用户定义的上下文变量都应是技能上下文的一部分；通常，您可能需要设置的唯一全局上下文变量是 system.user_id，这是 Plus 和 Premium 计划用于计费目的的变量。
您仍可以从全局或技能上下文中检索上下文变量。要使 context 对象包含在消息响应中，请使用消息输入选项中的 return_context 属性。有关更多信息，请参阅在对话框中访问上下文数据。