数据存储区搜索配置

您可以通过配置提升和过滤规范来影响从 Dialogflow CX 数据存储区工具检索到的搜索结果。这样，当代理使用数据存储区查找信息时，您就可以获得更加个性化且情境感知能力更强的互动。

（可选）您可以添加动态表达式，以便根据对话上下文微调结果。例如，您的代理已捕获表明最终用户拥有“手机”的信息。您可以配置数据存储区工具，以便在对话后期回答“如何查看语音信息？”等一般查询时，提升与手机相关的文档的排名。

您可以使用控制台、API 或 Dialogflow CX Messenger 集成来配置数据存储区搜索结果。

搜索条件输入

您可以使用 SearchConfig 对象中的提升规范 (BoostSpec) 和过滤条件规范 (FilterSpec) 字段来配置搜索结果。这些配置适用于工具中的每个数据存储区，让您可以控制每个关联的数据存储区的行为。

您可以通过以下两种方式之一配置搜索条件：使用控制台或发送直接 API 调用。

两者之间存在重要区别：

• API 调用：您可以使用 DetectIntent API 调用在 SearchConfig 中发送 BoostSpec 和 FilterSpec。您必须在请求中提供完整的 SearchConfig 对象。通过直接 API 调用发送的 SearchConfig 始终会覆盖使用控制台发送的 SearchConfig。不支持动态表达式和参数引用。

• 控制台：控制台使用您的 BoostSpec 和 FilterSpec 配置来构建 SearchConfig 对象，并将其与搜索请求一起发送。（可选）您可以添加参数引用和动态表达式，以便根据从对话中记录的情境数据来定制结果。您只需提供 ConditionBoostSpec 对象和过滤条件字符串列表即可构建 FilterSpecs，而无需提供完整的 SearchConfig 对象。

最终用户信息在 detectIntentRequest 中以 JSON 格式提供。没有预期的架构，因此您可以定义对象属性。

提升规范（提升规范）

借助提升规范，您可以通过对特定文档应用提升值来更改搜索结果排名。您可以向单个数据存储区添加多个升位规范。

您需要以 JSON 字符串的形式输入每个 Boost Spec，该字符串表示单个 ConditionBoostSpec 对象。

关键字段：

• condition：（字符串）一个表达式，用于指定何时应应用提升。这会使用标准过滤表达式语法。您可以使用 Dialogflow CX 表达式使结果动态化，例如 $session.params.YOUR_PARAM_NAME 或 $request.end-user-metadata.YOUR_KEY。
• boost：（数字）介于 -1.0 和 1.0 之间的值，用于确定提升强度。
  • 正值会提升匹配的文档。值为 1.0 表示大幅提升排名。
  • 负值会降低匹配文档的排名。值为 -1.0 表示强烈降级。
  • 值为 0.0 表示不应用任何提升，这是不允许的。
• boostControlSpec：与条件和提升的基本组合相比，它可提供更多用于自定义排名的控件。如需详细了解如何配置此字段，请参阅参考文档。

控制台输入示例：

如果您在控制台中配置代理，请按以下格式提供 ConditionBoostSpecs 列表：

{
  "condition": "uri: ANY(\"http://www.example.com/docs/$session.params.doc_id\")",
  "boost": 0.5
}

注意： 在此示例中，URI 与 $session.params.doc_id 会话参数的值匹配的文档会以 0.5 的强度进行提升。

API 输入示例：

如果您直接调用 API，则必须在完整的 SearchConfig 对象中提供 ConditionBoostSpecs。以下搜索配置描述了提升规范：

"searchConfig": {
  "boostSpecs": [
    {
      "dataStores": [ "DATASTORE_ID" ],
      "spec": [
        {
          "conditionBoostSpecs": {
            "condition": "CONDITION",
            "boost": "1.0"
          }
        }
      ]
    }
  ]
}

注意： DATASTORE_ID 是数据存储区的全名：projects/your_project_id/locations/your_location/collections/your_collection_name/dataStores/your_datastore_name，
CONDITION 必须遵循 Agent Search 的过滤表达式语法，
提升值必须介于 -1.0 和 1.0 之间。

过滤规范

过滤条件规范会将搜索结果限制为仅包含符合指定条件的文档。您可以向单个数据存储区添加多个过滤条件规范。

每个过滤条件规范都必须以字符串表达式的形式输入。该字符串必须符合标准过滤表达式语法。您可以在此字符串中使用 Dialogflow CX 表达式，使结果变为动态，例如 $session.params.YOUR_PARAM_NAME 或 $request.end-user-metadata.YOUR_KEY。

控制台过滤条件规范字符串示例：

如果您使用控制台配置代理，则必须提供 filter 字符串列表以形成 FilterSpec 对象。

在此示例中，过滤条件仅返回 numeric_field 大于或等于 $session.params.min_value 值且 stock_availability 为 "IN_STOCK" 的文档：

"numeric_field >= $session.params.min_value AND stock_availability: ANY(\"IN_STOCK\")"

API 过滤条件配置示例：

如果您直接调用 API，则必须在完整的 SearchConfig 对象中提供 filter 字符串：

"searchConfig": {
  "filterSpecs": [
    {
      "dataStores": [ "DATASTORE_ID" ],
      "filter": "CONDITION"
    }
  ]
}

注意： DATASTORE_ID 是数据存储区的全名：projects/your_project_id/locations/your_location/collections/your_collection_name/dataStores/your_datastore_name，
和 CONDITION 必须遵循 Agent Search 的过滤表达式语法。

Dialogflow CX 动态表达式

注意 ：动态表达式仅适用于数据存储区工具。它们不适用于数据存储区处理程序。

BoostSpec 条件和 FilterSpec 字符串都可以包含 Dialogflow CX 表达式，使其具有动态性。这样，您就可以根据从正在进行的对话中检索到的情境数据，定制搜索行为。直接 API 调用不支持动态表达式，只有在使用控制台进行配置时才能使用动态表达式。

您可以通过以下两种方式访问对话情境数据：

• 会话参数：使用 $session.params.YOUR_PARAMETER_ID 在对话期间收集的值。
• 最终用户元数据：使用 $request.end-user-metadata.YOUR_KEY 在 DetectIntentRequest 中传递的最终用户元数据。如需使此选项可用，请验证 end_user_metadata 是否包含在 DetectIntent 调用的 QueryParameters 中。如需了解详情，请参阅 endUserMetadata。

如需详细了解可用的系统函数和表达式语法，请参阅条件和系统函数参考文档。

在运行时应用的搜索条件

当数据存储区工具执行搜索时：

1. 评估您为提升规范提供的 JSON 字符串。每个有效的 JSON 字符串都会转换为 ConditionBoostSpec 对象。然后，这些对象会被分组到特定数据存储区连接的 BoostSpecs 对象中，该对象会被添加到整体 SearchConfig 中。
2. 将您为过滤条件规范提供的字符串作为 Dialogflow CX 表达式进行评估。每个生成的过滤条件字符串都用于为数据存储区创建 FilterSpecs 对象，该对象也会添加到 SearchConfig 中。
3. 将此动态构建的 SearchConfig 包含在发送到数据存储区的搜索请求的 QueryParameters 中。

配置搜索条件

如需配置搜索条件，请确保您已满足以下前提条件：

• 现有的 Dialogflow CX 智能体。
• 为您的智能体配置的数据存储区工具，其中启用了一个或多个数据存储区。

控制台配置

1. 打开 Conversational Agents 控制台，然后选择一个Google Cloud 项目。
2. 从下拉菜单中选择代理。
3. 找到左侧菜单，然后点击工具。选择要配置的数据存储区工具。
4. 在工具修改页面中，前往数据存储区部分。点击要修改的数据存储区旁边的设置图标 (⚙️)。
5. 系统随即会显示配置数据存储区菜单。您可以在此处添加提升规范和过滤规范，以修改搜索结果。
   • 对于Boost Spec，请提供一个定义 ConditionBoostSpec 的 JSON 对象。如需了解详情，请参阅提升规范。
   • 对于过滤条件规范，请提供一个定义过滤条件的字符串。如需了解详情，请参阅过滤条件规范。
6. 添加并配置规范后，点击侧边栏底部的确认。
7. 在数据存储区工具修改页面上，点击保存以保存更改。

API 配置

您可以在发送检测 intent 请求时向 Dialogflow CX 提供搜索配置数据。您必须在每个检测 intent 请求中提供此信息，因为它不会保留在会话中。

在 Sessions.detectIntent 方法的 queryParams.searchConfig 字段中提供此信息。

转到 Session API 参考文档

选择会话引用的协议和版本：

协议	V3	V3beta1
REST	会话资源	会话资源
RPC	会话接口	会话接口
C++	SessionsClient	不可用
C#	SessionsClient	不可用
Go	SessionsClient	不可用
Java	SessionsClient	SessionsClient
Node.js	SessionsClient	SessionsClient
PHP	不可用	不可用
Python	SessionsClient	SessionsClient
Ruby	不可用	不可用

关闭

Dialogflow CX Messenger 配置

您可以向 Dialogflow CX Messenger 集成提供搜索配置数据。如需了解详情，请参阅 setContext 方法。

如需应用搜索规范或搜索配置，您必须在将 Dialogflow CX Messenger 代码嵌入网站时，将以下代码段添加到该代码中：

<script>
  document.addEventListener('df-messenger-loaded', () => {
    const dfMessenger = document.querySelector('df-messenger');
    const searchConfig = { ... }
    dfMessenger.setQueryParameters(searchConfig);
  });
</script>

如需了解详情，请参阅 setQueryParameters 方法。

问题排查

以下解决方案可解决配置期间遇到的一些常见问题。通过模拟触发不同会话参数和最终用户元数据值的对话，全面测试您的配置。

无效表达式

如果 Boost Spec 条件或 Filter Spec 字符串包含无效的 Dialogflow CX 表达式（例如，语法不正确或引用了不存在的参数），则表达式编译将失败。与表达式编译相关的错误通常在 diagnostic_info 字段内的 DetectIntentResponse 中作为 SystemFunctionResults 返回。

ConditionBoostSpec JSON 无效

Conversational Agents 控制台会在保存 ConditionBoostSpec JSON 字符串时对其进行一些验证，以检查它是否为有效的 JSON，以及其结构是否可以映射到 ConditionBoostSpec 对象。如果 JSON 有效，但根据底层搜索服务，它会导致 SearchConfig 无效（例如，参数替换后条件字符串无效），则搜索服务将返回错误。

运行时替换错误

如果 ConditionBoostSpec JSON 字符串有效且可解析，但在其字段（例如条件字符串）中的 Dialogflow CX 表达式运行时替换期间发生错误，这些错误将在 diagnostic_info 中报告为 SystemFunctionResults。

查看已编译的 SearchConfig

运行查询时应用的 SearchConfig 可以在响应中的 search_signals 中找到。查看 SearchConfig 可以深入了解此处未列出的其他问题。

后续步骤

• 如需详细了解 SearchConfig 及其组件的结构，请参阅 search_config 文档。
• 如需详细了解表达式语法，请参阅 Dialogflow CX 条件和系统函数参考文档。
• 如需详细了解搜索的过滤表达式语法，请参阅过滤和排序结果。