从步骤调用扩展

要从操作调用定制扩展，请执行以下操作:

1. 在操作编辑器中，创建或打开要从中调用扩展的步骤。

2. 可选: 在 助手说 字段中，输入要在调用扩展之前向客户显示的消息 (例如，Please wait while I retrieve your account balance...)。

   此步骤的输出将发送到全局上下文变量 skip_user_input 设置为 true 的通道。 此变量指示通道显示消息，但 不 提示客户进行应答。 相反，通道会发送一条空消息，使助手能够继续调用扩展。

   所有内置通道集成 (例如，Web 聊天) 都遵循 skip_user_input 上下文变量。 如果要使用 API 来开发定制客户机，那么您应负责包含此变量的逻辑检查。 有关更多信息，请参阅 处理用户输入。

3. 在步骤编辑器中，单击 然后单击。

4. 单击 使用扩展。

5. 在扩展设置窗口中，指定以下信息：

   • 在 扩展 字段中，选择要调用的扩展。

   • 在操作字段中，选择要执行的操作。 ( 操作 是扩展支持的方法或函数。)

6. 指定每个必需输入参数的值。 参数 是发送到操作的输入值，例如要检索的客户记录的标识或要用于天气预报的位置。

   要为参数指定值，请单击该值的输入字段。 然后，可以从可用变量列表中进行选择，或者编写表达式以指定值。

   

   每个参数都具有数据类型 (例如 number 或 string)。 您选择的变量必须与参数的数据类型兼容; 有关更多信息，请参阅 参数的兼容变量。

   必须先指定所有必需参数的值，然后才能继续。

7. 如果要为任何可选参数指定值，请单击 可选参数。 然后，可以对要使用的每个可选参数重复此过程。

8. 单击应用。 (如果 应用 按钮不可用，请检查以确保为所有必需参数指定了值。)

现在，步骤编辑器的 然后 部分显示对扩展的调用的概述:

如果需要进行更改，请单击 编辑扩展 以重新打开“扩展设置”窗口。

访问扩展响应数据

调用扩展后，响应数据中的值将存储在可在后续步骤中访问的特殊操作变量中。

您可以通过访问其他操作变量的相同方式来访问这些变量。 您可以在 助手说 文本中对其进行引用，将其作为步骤条件的一部分进行求值，或者将其指定给会话变量，以便其他操作可以对其进行访问。 响应变量显示在可用变量列表中，在扩展名称和从中调用响应变量的步骤下进行分类:

对扩展的每个调用都会创建一组单独的响应变量。 如果您的操作多次从不同步骤调用同一扩展，请确保从正确的步骤中选择变量。

每个变量表示来自响应主体的值。 为了便于访问这些值，将从复杂嵌套对象中抽取数据并映射到各个响应变量。 每个变量的名称反映其在响应主体中的位置 (例如，body.name 或 body.customer.address.zipcode)。

例如，此操作步骤使用表达式来检查扩展响应中的 availability 属性:

如果响应变量包含数组，那么可以编写使用数组方法访问数组元素的表达式。 例如，您可以在步骤条件中使用 contains() 方法来测试数组是否包含特定值，或者使用 join() 方法将数组中的数据格式化为您可以包含在助手响应中的字符串。 有关数组方法的更多信息，请参阅 数组方法。

检查成功或失败

您可能希望助手能够处理调用定制扩展时发生的错误。 您可以通过检查随对扩展的调用的响应一起返回的 Ran successfully 响应变量来执行此操作。 此变量是布尔值 (true 或 false)。

如果定义用于检查 Ran successfully 变量的步骤条件，那么可以创建使助手能够根据对扩展的调用是否成功进行不同响应的步骤。 (有关步骤条件的更多信息，请参阅 步骤条件。)

以下示例显示用于从步骤 3 中的扩展检查失败的步骤条件。 通过使用此条件，您可以创建一个步骤来告知客户存在错误，并且可能提供连接到代理以获取更多帮助。

HTTP调整

除了 Ran successfully 变量，您可能还想根据响应HTTP创建一个步骤条件。 通过执行此操作，您可以根据故障原因创建以不同方式处理情境的步骤。 例如，如果因为超时错误 HTTP 状态408）导致调用失败，您可能需要重试调用。

HTTP 状态码有很多种，不同的方法使用不同的状态码来表示各种成功或失败。 要判断 HTTP，您需要知道外部服务在什么情况下返回什么 HTTP 状态码。 这些状态代码通常在描述外部API OpenAPI中指定。

要基于 HTTP创建步骤条件，请按以下步骤操作：

1. 对于要测试的值，单击 表达式。

2. 在表达式字段中，输入美元符号 ($) 以显示可用变量的列表。

3. 从扩展中选择任何作为响应值的变量。 (您选择哪个变量无关紧要，只要它是扩展响应变量)。

   将自动更新表达式以显示对所选变量的引用，格式为 ${step_xxx_result_y.body.variablename}。 例如，如果选择了名为 body.id 的响应变量，那么引用可能是 ${step_596_result_1.body.id}。

4. 在花括号 ({}) 内，编辑此引用以除去 .body.variablename。 应该会留下类似 ${step_596_result_1} 的内容。

5. 在右花括号 (}) 后，添加 .status。 生成的引用标识从对扩展的调用返回的状态码 (例如，${step_596_result_1}.status)。

   有关编写表达式的更多信息，请参阅 编写表达式。

6. 通过添加运算符和比较值来完成表达式，因此表达式求值为布尔值 (true/false)。 例如，以下表达式用于测试 HTTP 状态408，表示超时错误：

   ${step_549_result_1}.status==408
   

调试自定义扩展失败

如果对分机的调用失败，您可能需要查看系统 API 发送和返回信息的详细信息来调试问题。 为此，您可以使用预览窗格中的“检查器”：

1. 转到“操作”页面或“操作编辑器”，然后单击“预览”打开“预览”窗格。

   您不能从预览页面上的助理预览访问检查器，该页面只显示客户看到的内容。 请改为使用“操作”页面中包含的预览功能，这将使您能够访问其他信息。

2. 像客户一样与助理互动。

3. 每次调用扩展时，预览窗格都会显示一条消息，允许您访问详细信息:

   单击 检查 以查看有关对扩展的调用的详细信息。

   您还可以单击“”图标来显示或隐藏“检查器”。 不过，您必须在预览窗格中单击“检查”，才能显示分机的特定呼叫信息。

   检查器的“概览”选项卡显示分机呼叫的以下信息：

   调试选项	描述
   扩展	扩展设置中指定的扩展的名称。
   操作	调用的操作。
   状态	回复中的 HTTP 状态代码。 此代码可帮助您确定是否从外部服务返回了错误。
   请求参数	作为请求的一部分发送到系统 API 的输入参数。
   响应属性	系统 API 响应中包含的所有属性值。 这些是在对扩展的调用完成后映射到操作变量的值。

   在 请求参数 和 响应属性 表中，可能会截断长属性名称以仅显示 JSON 路径的最后部分。 要查看完整路径和属性名，请将鼠标指针悬停在表中的属性名上。

4. 如果要查看原始请求和响应数据，请单击扩展检验员中的 高级 选项卡:

   • 该请求显示为 cURL 命令，您可以在命令提示符处运行该命令，也可以将其导入到诸如 Postman之类的工具中。 (出于安全原因，不包含任何 Authorization 头的内容。)
   • 响应显示为系统 API 返回的完整 JSON 数据。

调试对话式搜索或基于技能的操作的故障

如果对对话式搜索或基于技能的操作的调用失败，您可能需要查看系统 API 发送和返回的详细信息来调试问题。

只有在搜索集成中启用会话搜索时，才会显示会话搜索检查器。 如果使用自定义服务搜索集成，则在配置搜索集成时必须只使用服务器端搜索。 对话式搜索检查器不支持客户端搜索。

要查看分析问题的详细信息，请使用预览窗格中的检查器：

1. 转到“操作”页面，或在“操作”编辑器中单击“预览”打开“预览”窗格。

   无法从预览页面的助手预览访问检查器。 请改为使用“操作”页面中包含的预览功能，这将使您能够访问其他信息。

2. 像客户一样与助理互动。

3. 每次呼叫分机时，预览窗格都会显示一条信息，以便访问详细信息： 您还可以单击 图标以显示或隐藏扩展检验员。 单击预览窗格中的“检查”，显示搜索集成的特定调用信息。

4. 使用概览选项卡，查找对话式搜索无法正常工作的原因。

   在了解“概览”选项卡中显示的字段之前，请先了解搜索扩展的两个阶段。

   • 检索阶段

     代表初始搜索阶段，即调用外部文档搜索引擎检索初始结果集。

   • 生成答案阶段

     在检索阶段，数据被检索出来，并被发送到 LLM，以便为用户生成人可读的答案。

   检查器的“概览”选项卡会显示以下有关调用搜索集成的信息。

   调试选项	描述
   扩展	扩展设置中指定的扩展的名称。
   索引	搜索使用的Elasticsearch索引的名称，仅在搜索扩展配置为使用Elasticsearch 时可见。
   项目标识	IBM Watson® Discovery在检索阶段使用的项目 ID。 只有当您将搜索扩展配置为使用IBM Watson® Discovery 时，此字段才会显示。
   查询	系统在文档引擎Elasticsearch、IBM Watson® Discovery 或服务器端自定义服务）上启动搜索时使用的查询。 该字段的值反映了系统重写的查询。
   原始查询	用户发起搜索的查询。 只有在启用多轮会话搜索时，系统重写查询时才会显示该字段。
   自定义结果过滤器	显示自定义结果过滤器（如果对话搜索的触发器上提供了该过滤器）。 此字段可能不会总是出现在回复中。
   LLM 类型	在答案生成阶段调用的 LLM。 该值为 watsonx.ai。 要了解在助手中配置 LLM 的更多信息，请参阅基础 LLM。
   模型	基础 LLM 在搜索答案生成阶段使用的模型。
   溪流关闭原因	给出数据流结束或关闭的原因，并在用户界面中给出相应的值。 只有在网络聊天中启用流媒体时，该字段才可见。
   LLM 输入标记计数	给出在搜索的答案生成阶段发送给 LLM 的请求中的标记数。
   LLM 生成的令牌计数	在搜索的答案生成阶段，给出 LLM 响应的答案中标记的数量。
   IDK 答复	该字段仅在搜索答案解析为 IDK（我不知道）回复时可见。
   原因不明	系统将搜索答案解析为 IDK（我不知道）回复的原因会与相应的值一起显示。
   IDK 触发器开场白	该字段显示检测到的触发 IDK（我不知道）回复的标准开头短语，只有当 IDK 原因是由该短语引起时才可见。
   IDK 触发短语	该字段显示导致 IDK（我不知道）响应的检测到的触发短语，只有当 IDK 原因是由该短语引起时才可见。
   返回总时间	系统完成会话搜索的总时间。
   搜索时间	在搜索的检索阶段，系统调用搜索引擎和检索结果所需的时间。
   答案生成时间	系统完成搜索答案生成阶段所需的时间。
   置信阈值	表示搜索置信度阈值的数值，在助手配置中也称为说“不知道”的倾向。
   萃取	得分反映了答复中有多少内容直接引用了资料来源。 得分越高，说明引用越直接，得分越低，说明对来源进行了改写或缺乏来源支持。
   检索信心	置信度值表示系统对搜索结果的确定程度。 如果低于阈值，系统会显示IDK并给出“检索置信度过低”的原因。
   回应信心	置信度值表示系统对生成答案的确定性。 如果低于阈值，系统会以 IDK 和原因 Response confidence too low 作答。

重新配置缺少的扩展

如果有人在“集成”页面上从助手中移除扩展，或者如果导出操作，然后将其导入到未配置所需扩展的其他助手中，那么扩展可能会变为不可用。 如果发生此情况，那么调用扩展的任何操作步骤都将变为无效。

要更正该问题，请遵循以下步骤：

1. 如有必要，请使用先前使用的同一 OpenAPI 规范重新创建扩展。 (有关更多信息，请参阅 构建定制扩展。)

2. 确保已将扩展添加到助手。 (有关更多信息，请参阅 向助手添加扩展。)

3. 在操作编辑器中，编辑调用扩展的操作步骤，并检查是否正确配置了对扩展的调用。 如果 watsonx Assistant 识别所需的扩展，那么会自动复原扩展配置。

   如果看到消息 Extension not fully configured，这意味着 watsonx Assistant 找不到所需的扩展。 单击 编辑扩展。

4. 在“扩展设置”窗口中，选择要调用的扩展。

   如果 watsonx Assistant 识别使用同一 OpenAPI 文档构建的可用扩展，那么将显示一条消息，建议您选择此扩展。 但是，您可以选择任何可用的扩展。

5. 验证是否在 操作 和 参数 字段中指定了正确的值。

6. 单击应用。

7. 如果选择的扩展与用于构建操作的扩展不同，那么可能需要修改访问扩展响应属性的后续步骤。 请检查引用响应属性的任何后续步骤，并确保引用仍然有效且正确。