查询建议 - Amazon Kendra
使用查询历史记录查询建议使用文档字段查询建议从建议中屏蔽某些查询或文档字段内容

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

查询建议

Amazon Kendra 查询建议可以帮助您的用户更快地键入搜索查询并指导他们的搜索。

Amazon Kendra 根据以下其中一项建议与您的用户相关的查询：

  • 查询历史记录或查询日志中的热门查询

  • 文档字段/属性的内容

您可以通过将 SuggestionTypes 设置为 QUERY 或 DOCUMENT_ATTRIBUTES 并调用 GetQuerySuggestions 来设置使用查询历史记录或文档字段的首选项。默认情况下， Amazon Kendra 使用查询历史记录作为建议的基础。如果在您致电时查询历史记录和文档字段均已激活，UpdateQuerySuggestionsConfig并且您尚未将SuggestionTypes首选项设置为使用文档字段，则 Amazon Kendra 使用查询历史记录。

如果您使用控制台，则可以根据查询历史记录或文档字段提出查询建议。首先选择索引，然后在导航菜单的富集下选择查询建议。然后选择配置查询建议。配置查询建议后，系统会将您定向到搜索控制台，您可以在其中选择右侧面板中的查询历史记录或文档字段，然后在搜索栏中输入搜索查询。

默认情况下，使用查询历史记录和文档字段的查询建议均已激活，无需支付额外费用。您可以随时使用 UpdateQuerySuggestionsConfig API 停用这些类型的查询建议。要停用基于查询历史记录的查询建议，请在调用 UpdateQuerySuggestionsConfig 时将 Mode 设置为 DISABLED。要停用基于文档字段的查询建议，请在文档字段配置中将 AttributeSuggestionsMode 设置为 INACTIVE，然后调用 UpdateQuerySuggestionsConfig>。如果您使用控制台，则可以在查询建议设置中停用查询建议。

查询建议不区分大小写。 Amazon Kendra 将查询前缀和建议的查询转换为小写，忽略所有单引号和双引号，并将多个空格字符替换为单个空格。 Amazon Kendra 按原样匹配所有其他特殊字符。 Amazon Kendra 如果用户键入的字符少于两个或超过 60 个字符，则不会显示任何建议。

使用查询历史记录查询建议

您可以选择根据查询历史记录或查询日志中的热门查询来建议与用户相关的查询。 Amazon Kendra 使用您的用户搜索并从这些查询中学到的所有查询来向您的用户提出建议。 Amazon Kendra 当用户开始键入查询时，向他们推荐热门查询。 Amazon Kendra 如果查询的前缀或前几个字符与用户开始键入的查询内容相匹配，则建议进行查询。

例如，用户开始键入查询“即将举行的活动”。 Amazon Kendra 从查询历史中了解到，许多用户已经多次搜索“2050 年即将举行的活动”。用户会看到“2050 年即将举行的活动”直接出现在他们的搜索栏下方，从而自动完成搜索查询。用户选择此查询建议，搜索结果中会返回文档“新事件：2050 年发生的事情”。

您可以指定如何 Amazon Kendra 选择符合条件的查询以向用户推荐。例如，您可以指定查询建议必须由至少 10 个独立用户进行搜索（默认值为 3 个），且在过去 30 天内搜索过，并且不包含屏蔽列表中的任何单词或短语。 Amazon Kendra 要求查询至少有一个搜索结果并且包含至少一个超过四个字符的单词。

为建议选择查询的设置

您可以使用 UpdateQuerySuggestionsConfig API 配置以下设置，以便为建议选择查询：

  • 模式 - 使用查询历史记录为 ENABLED 或 LEARN_ONLY 的查询建议。 Amazon Kendra 默认情况下会激活查询建议。LEARN_ONLY 会关闭查询建议。如果禁用，则会 Amazon Kendra 继续学习建议，但不会向用户提出查询建议。

  • 查询日志时段 - 查询在查询日志时段中的最近查询时间。时段是从当天到过去几天的天数的整数值。

  • 不包含用户信息的查询 - 设置为 TRUE 以包含所有查询，或者设置为 FALSE 以仅包含具有用户信息的查询。如果您的搜索应用程序在用户发出查询时包含用户信息（例如用户 ID），则可以使用此设置。默认情况下，如果没有与查询关联的特定用户信息，则此设置不会筛选出查询。但是，您可以使用此设置仅根据包含用户信息的查询提出建议。

  • 唯一用户 - 必须搜索查询才有资格向您的用户推荐查询的最少唯一用户数。此数字是一个整数值。

  • 查询次数 - 必须搜索查询的最少次数，才有资格向用户推荐该查询。此数字是一个整数值。

这些设置会影响如何选择查询作为向用户推荐的热门查询。如何调整设置将取决于您的特定需求，例如：

  • 如果您的用户通常平均每月搜索一次，则可以将查询日志时段中的天数设置为 30 天。通过使用该设置，您可以在用户最近的大多数查询在时段内过时之前捕获这些查询。

  • 如果您的查询中只有少量包含用户信息，并且您不想根据较小的样本量建议查询，则可以将查询设置为包括所有用户。

  • 如果您将热门查询定义为至少有 10 个独立用户搜索并且搜索了至少 100 次，则可以将唯一用户设置为 10，将查询计数设置为 100。

警告

您对设置的更改可能不会立即生效。您可以使用 DescribeQuerySuggestionsConfig API 跟踪设置更改。更新后的设置生效的时间取决于您所做的更新和索引中搜索查询的数量。在您更改设置或应用屏蔽列表后， Amazon Kendra 每 24 小时自动更新一次建议。

CLI

检索查询建议

aws kendra get-query-suggestions \
 --index-id index-id \
 --query-text "query-text" \
 --suggestion-types '["QUERY"]' \
 --max-suggestions-count 1 // If you want to limit the number of suggestions

更新查询建议

例如，要更改查询日志的时段和必须搜索查询的最小次数，请执行以下操作：

aws kendra update-query-suggestions-config \
 --index-id index-id \
 --query-log-look-back-window-in-days 30 \
 --minimum-query-count 100
Python

检索查询建议

import boto3
from botocore.exceptions import ClientError

kendra = boto3.client("kendra")

print("Get query suggestions.")

# Provide the index ID
index_id = "index-id"

# Provide the query text
query_text = "query"

# Provide the query suggestions type
query_suggestions_type = "QUERY"


# If you want to limit the number of suggestions
num_suggestions = 1
 
try:
    query_suggestions_response = kendra.get_query_suggestions(
        IndexId = index_id,
        QueryText = query_text,
        SuggestionTypes = query_suggestions_type,
        MaxSuggestionsCount = num_suggestions
    )

    # Print out the suggestions you received
    if ("Suggestions" in query_suggestions_response.keys()) {
        for (suggestion: query_suggestions_response["Suggestions"]) {
            print(suggestion["Value"]["Text"]["Text"]);
        }
    }
   
except ClientError as e:
        print("%s" % e)

print("Program ends.")

更新查询建议

例如，要更改查询日志的时段和必须搜索查询的最小次数，请执行以下操作：

import boto3
from botocore.exceptions import ClientError
import pprint
import time

kendra = boto3.client("kendra")

print("Updating query suggestions settings/configuration for an index.")

# Provide the index ID
index_id = "index-id"

# Configure the settings you want to update
minimum_query_count = 100
query_log_look_back_window_in_days = 30

try:
    kendra.update_query_suggestions_config(
        IndexId = index_id,
        MinimumQueryCount = minimum_query_count,
        QueryLogLookBackWindowInDays = query_log_look_back_window_in_days
    )

    print("Wait for Amazon Kendra to update the query suggestions.")

    while True:
        # Get query suggestions description of settings/configuration
        query_sugg_config_response = kendra.describe_query_suggestions_config(
            IndexId = index_id
        )
        
        # If status is not UPDATING, then quit
        status = query_sugg_config_response["Status"]
        print(" Updating query suggestions config. Status: " + status)
        if status != "UPDATING":
            break
        time.sleep(60)

except ClientError as e:
        print("%s" % e)

print("Program ends.")

在保留查询历史记录的同时清除建议

您可以使用 ClearQuerySuggestions API 清除查询建议。清除建议只会删除现有的查询建议，而不会删除查询历史记录中的查询。当您清除建议时， Amazon Kendra 会根据您清除建议后添加到查询日志中的新查询来学习新的建议。

CLI

清除查询建议

aws  kendra clear-query-suggestions \
 --index-id index-id
Python

清除查询建议

import boto3
from botocore.exceptions import ClientError

kendra = boto3.client("kendra")

print("Clearing out query suggestions for an index.")

# Provide the index ID
index_id = "index-id"

try:
    kendra.clear_query_suggestions(
        IndexId = index_id
    )

    # Confirm last cleared date-time and that there are no suggestions
    query_sugg_config_response = kendra.describe_query_suggestions_config(
        IndexId = index_id
    )
    print("Query Suggestions last cleared at: " + str(query_sugg_config_response["LastClearTime"]));
    print("Number of suggestions available from the time of clearing: " + str(query_sugg_config_response["TotalSuggestionsCount"]));
        
except ClientError as e:
        print("%s" % e)

print("Program ends.")

没有可用的建议

如果未看到查询建议，可能是出于以下原因之一：

  • 您的索引中没有足够的查询 Amazon Kendra 可供借鉴。

  • 您的查询建议设置过于严格，导致大多数查询都被从建议中筛选掉。

  • 您最近清除了建议， Amazon Kendra 但仍需要时间积累新的查询，以便学习新的建议。

您可以使用 DescribeQuerySuggestionsConfig API 检查当前设置。

使用文档字段查询建议

您可以选择根据文档字段的内容建议与用户相关的查询。您可以使用文档字段中包含的有助于自动完成查询的信息，而不是使用查询历史记录来建议其他常见的相关查询。 Amazon Kendra 在设置为Suggestable且与用户查询非常一致的字段中查找相关内容。然后，当您的用户开始键入查询内容时，向他们 Amazon Kendra 推荐这些内容。

例如，如果您指定了作为建议基础的标题字段，然后用户开始键入查询 “How amazon ken... '，可以建议使用最相关的标题 “ Amazon Kendra 工作原理” 来自动完成搜索。用户会看到 “ Amazon Kendra 工作原理” 直接出现在他们的搜索栏下方，自动完成了他们的搜索查询。用户选择此查询建议，搜索结果中将返回 “ Amazon Kendra 工作原理” 文档。

您可以使用 String 和 StringList 类型的任意文档字段的内容来建议查询，方法是将该字段作为查询建议字段配置的一部分设置为 Suggestable。您也可以使用屏蔽列表，这样就不会向用户显示包含某些单词或短语的建议文档字段。您可以使用一个阻止列表。无论您将查询建议设置为使用查询历史记录还是文档字段，屏蔽列表都适用。

为建议选择字段的设置

您可以使用 AttributeSuggestionsConfig 并调用 UpdateQuerySuggestionsConfig API 来更新索引级别的设置来配置以下设置，以便为建议选择文档字段：

  • 字段/属性建议模式 - 使用文档字段为 ACTIVE 或 INACTIVE 的查询建议。 Amazon Kendra 在默认情况下会激活查询建议。

  • 可建议的字段/属性 - 作为建议基础的字段名称或字段键。作为字段配置的一部分，必须将这些字段设置为 Suggestable 的 TRUE。您可以在查询级别覆盖字段配置，同时保持索引级别的配置。使用 GetQuerySuggestionsAPI 在查询AttributeSuggestionConfig级别进行更改。查询级别的这种配置对于快速尝试使用不同的文档字段非常有用，而不必在索引级别更新配置。

  • 其他字段/属性 - 您要在查询建议的响应中包含的其他字段。这些字段用于在回复中提供额外信息；但是，它们不用于作为建议的依据。

警告

您对设置的更改可能不会立即生效。您可以使用 DescribeQuerySuggestionsConfig API 跟踪设置更改。更新后的设置生效的时间取决于您所做的更新。 Amazon Kendra 在您更改设置后或应用屏蔽列表后，每 24 小时自动更新一次建议。

CLI

在查询级别检索查询建议并覆盖文档字段配置，而不必在索引级别更改配置。

aws kendra get-query-suggestions \
 --index-id index-id \
 --query-text "query-text" \
 --suggestion-types '["DOCUMENT_ATTRIBUTES"]' \
 --attribute-suggestions-config '{"SuggestionAttributes":'["field/attribute key 1", "field/attribute key 2"]', "AdditionalResponseAttributes":'["response field/attribute key 1", "response field/attribute key 2"]'}' \
 --max-suggestions-count 1 // If you want to limit the number of suggestions

更新查询建议

例如，要更改索引级别的文档字段配置，请执行以下操作：

aws kendra update-query-suggestions-config \
 --index-id index-id \
 --attribute-suggestions-config '{"SuggestableConfigList": '[{"SuggestableConfig": "_document_title", "Suggestable": true}]', "AttributeSuggestionsMode": "ACTIVE"}'
Python

在查询级别检索查询建议并覆盖文档字段配置，而不必在索引级别更改配置。

import boto3
from botocore.exceptions import ClientError

kendra = boto3.client("kendra")

print("Get query suggestions.")

# Provide the index ID
index_id = "index-id"

# Provide the query text
query_text = "query"

# Provide the query suggestions type
query_suggestions_type = "DOCUMENT_ATTRIBUTES"

# Override fields/attributes configuration at query level
configuration = {"SuggestionAttributes":
    '["field/attribute key 1", "field/attribute key 2"]', 
      "AdditionalResponseAttributes":
          '["response field/attribute key 1", "response field/attribute key 2"]'
          }

# If you want to limit the number of suggestions
num_suggestions = 1

try:
    query_suggestions_response = kendra.get_query_suggestions(
        IndexId = index_id,
        QueryText = query_text,
        SuggestionTypes = [query_suggestions_type],
        AttributeSuggestionsConfig = configuration,
        MaxSuggestionsCount = num_suggestions
    )

    # Print out the suggestions you received
    if ("Suggestions" in query_suggestions_response.keys()) {
        for (suggestion: query_suggestions_response["Suggestions"]) {
            print(suggestion["Value"]["Text"]["Text"]);
        }
    }
   
except ClientError as e:
        print("%s" % e)

print("Program ends.")

更新查询建议

例如，要更改索引级别的文档字段配置，请执行以下操作：

import boto3
from botocore.exceptions import ClientError
import pprint
import time

kendra = boto3.client("kendra")

print("Updating query suggestions settings/configuration for an index.")

# Provide the index ID
index_id = "index-id"

# Configure the settings you want to update at the index level
configuration = {"SuggestableConfigList": 
    '[{"SuggestableConfig": "_document_title", "Suggestable": true}]', 
       "AttributeSuggestionsMode": "ACTIVE"
       }

try:
    kendra.update_query_suggestions_config(
        IndexId = index_id,
        AttributeSuggestionsConfig = configuration
    )

    print("Wait for Amazon Kendra to update the query suggestions.")

    while True:
        # Get query suggestions description of settings/configuration
        query_sugg_config_response = kendra.describe_query_suggestions_config(
            IndexId = index_id
        )
        
        # If status is not UPDATING, then quit
        status = query_sugg_config_response["Status"]
        print(" Updating query suggestions config. Status: " + status)
        if status != "UPDATING":
            break
        time.sleep(60)

except ClientError as e:
        print("%s" % e)

print("Program ends.")

文档字段中的用户控制

您可以将用户上下文筛选应用于要作为查询建议基础的文档字段。这会根据用户或其群组对文档的访问权限来筛选文档字段信息。例如，实习生搜索公司的门户网站，却无权访问公司绝密文档。因此，不会向实习生显示基于绝密文档标题或任何其他可建议字段的建议查询。

您可以使用访问控制列表（ACL）为文档编制索引，该列表定义为哪些用户和组分配了对哪些文档的访问权限。然后，您可以对文档字段应用用户上下文筛选以获得查询建议。当前为您的索引设置的用户上下文筛选与应用于您的文档字段配置的查询建议的用户上下文筛选相同。用户上下文筛选是您的文档字段配置的一部分。您使用 AttributeSuggestionsGetConfig 并调用 GetQuerySuggestions。

从建议中屏蔽某些查询或文档字段内容

屏蔽 Amazon Kendra 列表不会向您的用户建议某些查询。屏蔽列表是您要从查询建议中排除的单词或短语的列表。 Amazon Kendra 不包括包含与屏蔽列表中的单词或短语完全匹配的查询。

您可以使用屏蔽列表来防范经常出现在您的查询历史记录或文档字段中，并且 Amazon Kendra 可能将其选为建议的冒犯性单词或短语。屏蔽列表还可以 Amazon Kendra 防止建议包含尚未准备好公开发布或宣布的信息的查询。例如，您的用户经常询问即将发布的潜在新产品。但是，您不想推荐该产品，因为您尚未准备好发布该产品。您可以屏蔽建议中包含产品名称和产品信息的查询。

您可以使用 CreateQuerySuggestionsBlockList API 为查询创建阻止列表。将每个屏蔽单词或短语放在文本文件中单独一行中。然后，您将文本文件上传到您的 Amazon S3 存储桶，并在中提供该文件的路径或位置 Amazon S3。 Amazon Kendra 目前仅支持创建一个阻止列表。

您可以替换 Amazon S3 存储桶中屏蔽的单词和短语的文本文件。要更新中的屏蔽列表 Amazon Kendra，请使用 UpdateQuerySuggestionsBlockListAPI。

使用 DescribeQuerySuggestionsBlockList API 获取屏蔽列表的状态。DescribeQuerySuggestionsBlockList 还可以为您提供其他有用的信息，例如以下信息：

  • 上次更新屏蔽名单的时间

  • 您当前的屏蔽列表中有多少个单词或短语

  • 创建屏蔽名单时的有用错误消息

您还可以使用 ListQuerySuggestionsBlockLists API 获取索引的屏蔽列表摘要列表。

要删除您的屏蔽名单，请使用 DeleteQuerySuggestionsBlockListAPI。

您对屏蔽列表的更新可能不会立即生效。您可以使用 DescribeQuerySuggestionsBlockList API 跟踪更新。

CLI

创建屏蔽列表

aws kendra create-query-suggestions-block-list \
 --index-id index-id \
 --name "block-list-name" \
 --description "block-list-description" \
 --source-s3-path "Bucket=bucket-name,Key=query-suggestions/block_list.txt" \
 --role-arn role-arn

更新屏蔽列表

aws kendra update-query-suggestions-block-list \
 --index-id index-id \
 --name "new-block-list-name" \
 --description "new-block-list-description" \
 --source-s3-path "Bucket=bucket-name,Key=query-suggestions/new_block_list.txt" \
 --role-arn role-arn

删除屏蔽列表

aws kendra delete-query-suggestions-block-list \
 --index-id index-id \
 --id block-list-id
Python

创建屏蔽列表

import boto3
from botocore.exceptions import ClientError
import pprint
import time

kendra = boto3.client("kendra")

print("Create a query suggestions block list.")

# Provide a name for the block list
block_list_name = "block-list-name"
# Provide an optional description for the block list
block_list_description = "block-list-description"
# Provide the IAM role ARN required for query suggestions block lists
block_list_role_arn = "role-arn"

# Provide the index ID
index_id = "index-id"

s3_bucket_name = "bucket-name"
s3_key = "query-suggestions/block_list.txt"
source_s3_path = {
    'Bucket': s3_bucket_name,
    'Key': s3_key
}

try:
    block_list_response = kendra.create_query_suggestions_block_list(
        Description = block_list_description,
        Name = block_list_name,
        RoleArn = block_list_role_arn,
        IndexId = index_id,
        SourceS3Path = source_s3_path
    )

    print(block_list_response)

    block_list_id = block_list_response["Id"]

    print("Wait for Amazon Kendra to create the block list.")

    while True:
        # Get block list description
        block_list_description = kendra.describe_query_suggestions_block_list(
            Id = block_list_id,
            IndexId = index_id
        )
        # If status is not CREATING, then quit
        status = block_list_description["Status"]
        print("Creating block list. Status: " + status)
        if status != "CREATING":
            break
        time.sleep(60)
        
except ClientError as e:
        print("%s" % e)

print("Program ends.")

更新屏蔽列表

import boto3
from botocore.exceptions import ClientError
import pprint
import time
                        
kendra = boto3.client("kendra")
                        
print("Update a block list for query suggestions.")

# Provide the block list name you want to update
block_list_name = "new-block-list-name"
# Provide the block list description you want to update
block_list_description = "new-block-list-description"
# Provide the IAM role ARN required for query suggestions block lists
block_list_role_arn = "role-arn"

# Provide the block list ID
block_list_id = "block-list-id"
# Provide the index ID
index_id = "index-id"
                        
s3_bucket_name = "bucket-name"
s3_key = "query-suggestions/new_block_list.txt"
source_s3_path = {
'Bucket': s3_bucket_name,
'Key': s3_key
}
                        
try:
    kendra.update_query_suggestions_block_list(
        Id = block_list_id,
        IndexId = index_id,
        Description = block_list_description,
        Name = block_list_name,
        RoleArn = block_list_role_arn,
        SourceS3Path = source_s3_path
    )
                        
    print("Wait for Amazon Kendra to update the block list.")
                        
    while True:
        # Get block list description
        block_list_description = kendra.describe_query_suggestions_block_list(
            Id = block_list_id,
            IndexId = index_id
        )
        # If status is not UPDATING, then the update has finished 
        status = block_list_description["Status"]
        print("Updating block list. Status: " + status)
        if status != "UPDATING":
            break
        time.sleep(60)
                        
except ClientError as e:
print("%s" % e)
                        
print("Program ends.")

删除屏蔽列表

import boto3
from botocore.exceptions import ClientError

kendra = boto3.client("kendra")

print("Delete a block list for query suggestions.")

# provide the block list ID
query_suggestions_block_list_id = "query-suggestions-block-list-id"
# Provide the index ID
index_id = "index-id"

try:
    kendra.delete_query_suggestions_block_list(
        Id = query_suggestions_block_list_id,
        IndexId = index_id
    )

except ClientError as e:
        print("%s" % e)

print("Program ends.")