配置高级自动补全

本页介绍了 Agent Search 的高级自动补全功能。

与基本自动补全功能一样，高级自动补全功能会根据您输入的查询的前几个字符生成查询建议。

在阅读本页面之前，请先熟悉代理搜索的基本自动补全功能。请参阅配置自动补全。

高级自动补全功能的主要特点

高级自动补全与基本自动补全的主要区别在于以下关键功能：

  • 混合搜索：高级自动补全功能可用于混合搜索应用，即连接到多个数据存储区的自定义搜索应用。

  • 访问权限控制：高级自动补全功能会遵守访问权限控制。（访问权限控制也称为 ACL，即访问控制列表。）高级自动补全功能只会推荐与搜索者有权访问的文档相关的搜索查询。如需了解访问权限控制，请参阅使用数据源访问权限控制。

  • 语言提升：高级自动补全功能可设置为提升一种或多种语言的建议效果。例如，如果浏览器语言为荷兰语，则可以提高该语言的自动补全建议的优先级。如需了解详情，请参阅发送包含语言提升的自动补全请求。
  • 近期查询：借助高级自动补全功能，用户可以获得与他们输入的字母前缀匹配的近期查询，而不是常规的自动补全查询建议。如需了解详情，请参阅发送自动补全请求并返回最近的查询。

准备工作

在开始使用高级自动补全功能之前，请执行以下操作：

  • 查看并根据需要修改应用的自动补全设置。请参阅更新自动补全设置。

  • 对于较小的数据存储区，请将启用自动补全设置为立即。我们之所以建议您这样做，是因为小型数据存储区可能没有足够的数据来提供准确的建议。

  • 如果您的数据存储区包含任何个人身份信息 (PII)，或者您使用的是搜索记录或用户事件查询建议模型，请查看防范 PII 泄露，并设置可能需要的数据泄露防护 (DLP) 安全措施，以防止 PII 泄露。

  • 如果您打算使用近期搜索建议 (RECENT_SEARCH)，请确保记录搜索用户事件。使用 SearchService.Search 方法执行搜索时，Agent Search 不会自动填充最近搜索索引。如需返回近期查询，您必须使用 userEvents.write 方法记录搜索用户事件。请参阅准备工作 - 近期查询。

发送自动补全请求

以下示例展示了如何使用 completionConfig.completeQuery 方法发送高级自动补全请求。

REST

如需使用 API 发送自动补全请求，请按以下步骤操作：

  1. 找到应用 ID。如果您已拥有应用 ID，请跳到下一步。

    1. 在 Google Cloud 控制台中，前往 AI Applications 页面。

      前往应用

    2. 在应用页面上，找到应用的名称，并从 ID 列获取应用的 ID。

  2. 调用 completionConfig.completeQuery 方法。

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/completionConfig:completeQuery" \
-d '{
      "query":"QUERY_STRING"
    }'

    替换以下内容：

    • PROJECT_ID：您的 Google Cloud 项目的 ID。

    • APP_ID：Agent Search 应用的 ID。

    • QUERY_STRING：用于获取建议的已输入内容。

发送包含语言提升的自动补全请求

您可以根据语言代码提升或隐藏自动补全建议，例如，使某些语言的自动补全建议更可能或更不可能显示。

提升值必须介于 -1 和 1 之间。设置负数会“隐藏”相应语言的自动补全建议，而设置正数会提升相应语言的优先级。

使用 BCP 47 定义的双字母语言标记，例如 en、fr、hi 和 zh。

REST

如需发送包含语言提升值的自动补全请求，请按以下步骤操作：

  1. 找到应用 ID。如果您已拥有应用 ID，请跳到下一步。

    1. 在 Google Cloud 控制台中，前往 AI Applications 页面。

      前往应用

    2. 在应用页面上，找到应用的名称，并从 ID 列获取应用的 ID。

  2. 调用 completionConfig.completeQuery 方法。

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/completionConfig:completeQuery" \
-d '{
      "query":"QUERY_STRING",
      "boostSpec": {
         "conditionBoostSpecs": [{
           "condition": "(langCode: ANY(LANG_CODE))",
           "boost": BOOST_VALUE
         }]
      }
    }'

    替换以下内容：

    • PROJECT_ID：您的 Google Cloud 项目的 ID。

    • APP_ID：Agent Search 应用的 ID。

    • QUERY_STRING：用于获取建议的已输入内容。

    • LANG_CODE：一种或多种语言的双字母代码，以转义的英文引号括起来。例如，\"fr\", \"es\" 可将提升值应用于西班牙语和法语。

    • BOOST_VALUE：一个介于 -1 和 1 之间的浮点数。当值为负时，相应语言的自动建议会被降权（在建议列表中位置下沉）。当值为正时，建议会被提权（在列表中位置上浮）。

发送自动补全请求并返回近期查询

以建议的形式返回与请求中的查询存在前缀匹配关系的用户最近查询的列表。

匹配的查询建议会按时间由近及远列出。如需使用“近期的搜索”，必须提供用户伪 ID。

准备工作

您必须先通过调用 userEvents.write 方法将用户搜索记录为搜索用户事件，然后才能通过自动补全功能检索最近的查询。

如果未写入搜索用户事件，则对 completionConfig.completeQuery 的请求（包含 suggestionTypes: ["RECENT_SEARCH"]）会返回一个空建议列表 ({})。

如需记录搜索用户事件，请向 userEvents.write 方法发送 POST 请求，并提供以下值：

  • eventType：设置为 "search"
  • userPseudoId：设置为用户的唯一假名化标识符
  • engine：设置为引擎的资源名称
  • searchInfo.searchQuery：设置为用户输入的搜索查询字符串
curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/userEvents:write" \
  -d '{
        "eventType": "search",
        "userPseudoId": "USER_PSEUDO_ID",
        "engine": "projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID",
        "searchInfo": {
          "searchQuery": "SEARCH_QUERY"
        }
      }'

替换以下内容：

  • PROJECT_ID：您的 Google Cloud 项目的 ID。
  • LOCATION：应用或数据存储区的位置（例如 global 或 us）。
  • APP_ID：Agent Search 应用的 ID。
  • USER_PSEUDO_ID：用户的假名化标识符。此值必须与后续 completionConfig.completeQuery 请求中传递的 userPseudoId 相匹配。
  • SEARCH_QUERY：用户搜索的查询字符串。

如需了解详情，请参阅使用 userEvents.write 方法记录实时用户事件。

示例

某员工正在查询公司内网网站，以获取有关休假的信息。该员工执行了以下查询（按从最新到最旧的顺序列出）：

PTO、Vacation blackout periods、How much vacation time do I have?、Time off、Vacation policy、covering a vacant position during absences 和 Can I take unpaid time off?。

现在，当员工在搜索框中输入 vac 时，自动补全建议如下所示：

  • Vacation blackout periods
  • How much vacation time do I have?
  • Vacation policy
  • Covering a vacant position during absences

过程

如需发送返回用户最近查询的自动补全请求，请按以下步骤操作：

REST

  1. 找到应用 ID。如果您已拥有应用 ID，请跳到下一步。

    1. 在 Google Cloud 控制台中，前往 AI Applications 页面。

      前往应用

    2. 在应用页面上，找到应用的名称，并从 ID 列获取应用的 ID。

  2. 调用 completionConfig.completeQuery 方法。

    
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/completionConfig:completeQuery" \
-d '{
      "query":"QUERY_STRING",
      "suggestionTypes": ["RECENT_SEARCH"],
      "userPseudoId": "USER_PSEUDO_ID"
    }'

    替换以下内容：

    • PROJECT_ID：您的 Google Cloud 项目的 ID。

    • APP_ID：Agent Search 应用的 ID。

    • QUERY_STRING：用于获取建议的已输入内容。

    • USER_PSEUDO_ID：用户的假名化标识符。您可以为此字段使用 HTTP Cookie，该 Cookie 可唯一标识单个设备上的访问者。请勿为多个用户设置相同的标识符。这样一来，系统就会合并他们的查询记录。请勿在此字段中包含个人身份信息 (PII)。

使用自动补全拒绝名单

可以使用拒绝名单来防止特定词条显示为自动补全建议。

虽然高级自动补全功能是在应用级实现的，但拒绝名单是在数据存储区级实现的。如果您的应用是混合搜索应用，这一点非常重要。请为与应用关联的每个数据存储区创建拒绝名单。

如需了解如何创建和使用拒绝名单，请参阅使用自动补全拒绝名单。

使用导入的自动补全建议列表

您可以选择提供自己的自动补全建议列表，而不是使用从自动补全数据模型生成的自动补全建议。

如需了解如何导入列表，请参阅使用导入的自动补全建议列表。