数据存储区搜索配置

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

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

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

搜索条件输入

搜索结果是使用 提升规范 (BoostSpec) 和 过滤条件规范 (FilterSpec) 字段在 SearchConfig 对象中进行配置的。这些配置是在工具中按数据存储区应用的，因此您可以精细控制每个已连接的数据存储区的行为。

您可以通过以下两种方式之一配置搜索条件：使用 控制台， 或发送直接 API 调用。 这两种方式之间存在重要区别。

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

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

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

提升规范（提升规范）

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

每个提升规范 都以 JSON 字符串的形式输入。此 JSON 字符串必须表示单个 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 。

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

{
  "condition": "uri: ANY(\"http://www.example.com/docs/$session.params.doc_id\")",
  "boost": 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. 此时会显示配置数据存储区 菜单。您可以在此处添加提升规范和过滤条件规范，以修改搜索结果。
   • 对于提升规范，请提供一个定义 ConditionBoostSpec的 JSON 对象。如需了解详情，请参阅提升 规范。
   • 对于过滤条件规范 ，请提供一个定义过滤条件 标准的字符串。如需了解详情，请参阅过滤条件 规范。
6. 添加并配置规范后，点击侧边栏底部的确认 。
7. 在数据存储区工具修改页面上，点击保存 以保存更改。

API 配置

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

在 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 方法。

问题排查

本部分概述了配置期间遇到的一些常见问题的解决方案。请务必通过模拟会话来全面测试您的配置，这些会话会触发不同的会话参数和最终用户元数据值。

表达式无效

如果提升规范条件或过滤条件规范字符串包含无效的 Dialogflow CX 表达式（例如，语法不正确或引用不存在的参数），表达式编译将失败。与 表达式编译相关的错误通常会在 DetectIntentResponse diagnostic_info中以 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 条件和系统函数参考文档。
• 如需详细了解搜索的过滤表达式语法，请参阅 过滤和排序结果。