よくある質問 (FAQ) のインデックスへの追加

コンソールまたは CreateFQ API を使用して、よくある質問 (FAQ) をインデックスに直接追加できます。インデックスへのよくある質問の追加は、非同期演算です。よくある質問のデータは、 Amazon Simple Storage Service バケットに保存するファイルに入力します。CSV ファイルまたは JSON ファイルをよくある質問の入力として使用できます。

例えば、以下は、米国ワシントン州スポケーンと米国ミズーリ州マウンテンビューにある無料診療所に関する質問に対する回答を提供する基本 CSV ファイルです。

How many free clinics are in Spokane WA?, 13
How many free clinics are there in Mountain View Missouri?, 7

よくある質問ファイルのインデックスフィールドの作成

入力にカスタム CSV または JSON ファイルを使用すると、よくある質問の質問のカスタムフィールドを宣言できます。例えば、各よくある質問の質問にビジネス部門を割り当てるカスタムフィールドを作成できます。よくある質問がレスポンスで返されたら、部門をファセットとして使用して、例えば「HR」や「Finance」のみに検索を絞り込めます。

カスタムフィールドは、インデックスフィールドにマッピングする必要があります。コンソールでは、[ファセットの定義] ページを使用して、インデックスフィールドを作成します。最初に、UpdateIndex API を使用してインデックスフィールドを作成する必要があります。

よくある質問ファイルのフィールド/属性タイプは、関連するインデックスフィールドのタイプと一致する必要があります。例えば、「Department」フィールドは STRING_LIST タイプフィールドです。そのため、よくある質問ファイルでは、部門フィールドの値を、文字列リストとして指定する必要があります。インデックスフィールドのタイプは、コンソールの [ファセットの定義] ページを使用して、または DescribeIndex API を使用してチェックできます。

カスタム属性にマッピングするインデックスフィールドを作成する場合、その属性を表示可能、ファセット可能、またはソート可能にマークできます。カスタム属性を検索可能にすることはできません。

カスタム属性に加えて、カスタム CSV または JSON ファイル内の Amazon Kendra 予約フィールドや共通フィールドを使用することもできます。詳細については、「Document attributes or fields」を参照してください。

基本 CSV ファイル

よくある質問に単純な構造を使用する場合は、基本 CSV ファイルを使用します。基本 CSV ファイルには、各行に、質問、回答、および詳細情報を含むドキュメントを参照するオプションのソース URI の 2 つまたは 3 つのフィールドがあります。

ファイルの内容は、カンマ区切り値 (CSV) ファイルの RFC 4180 共通形式と MIME タイプに従う必要があります。

以下は、基本 CSV 形式のよくある質問ファイルです。

How many free clinics are in Spokane WA?, 13, https://s3.region.company.com/bucket-name/directory/faq.csv
How many free clinics are there in Mountain View Missouri?, 7, https://s3.region.company.com/bucket-name/directory/faq.csv

カスタム CSV ファイル

よくある質問の質問にカスタムフィールド/属性を追加する場合は、カスタム CSV ファイルを使用します。カスタム CSV ファイルでは、CSV ファイルのヘッダー行を使用して、追加の属性を定義します。

CSV ファイルには、2 つの必須フィールドが含まれている必要があります。

カスタム CSV ファイルには、 Amazon Kendra 予約済みフィールド (_faq_id、_data_source_id、_document_title、および を除く_file_type) と任意のカスタムフィールドの両方を含めることができます。

次はカスタム CSV ファイルの例です。

_question,_answer,_last_updated_at,custom_string
How many free clinics are in Spokane WA?, 13, 2012-03-25T12:30:10+01:00, Note: Some free clinics require you to meet certain criteria in order to use their services
How many free clinics are there in Mountain View Missouri?, 7, 2012-03-25T12:30:10+01:00, Note: Some free clinics require you to meet certain criteria in order to use their services

カスタムファイルの内容は、カンマ区切り値 (CSV) ファイルの RFC 4180 共通形式と MIME タイプに従う必要があります。

カスタムフィールドの種類を以下に示します。

カスタム CSV ファイルにはユーザーアクセスコントロールフィールドを含められます。これらのフィールドを使用して、よくある質問へのアクセスを特定のユーザーおよびグループに制限できます。ユーザーコンテキストでフィルタリングするには、ユーザーはクエリでユーザーおよびグループ情報を提供する必要があります。それ以外の場合は、関連するよくある質問がすべて返されます。詳細については、「User context filtering」を参照してください。

よくある質問のユーザーコンテキストフィルターを以下に示します。

許可リストと拒否リストの値を、引用符で囲んだコンマ区切りのリストで指定します (例えば、"user1,user2,user3")。許可リストまたは拒否リストのいずれかにユーザーまたはグループを含めることはできますが、同一ユーザーが個別に許可されているもののグループでは拒否されているような場合は、両方に含めることはできません。両方にユーザーまたはグループを含めると、エラーが発生します。

次はユーザーコンテキスト情報を含むカスタム CSV ファイルの例です。

_question, _answer, _acl_user_allow, _acl_user_deny, _acl_group_allow, _acl_group_deny
How many free clinics are in Spokane WA?, 13, "userID6201,userID7552", "userID1001,userID2020", groupBasicPlusRate, groupPremiumRate

JSON ファイル

JSON ファイルを使用して、インデックスの質問、回答、およびフィールドを指定できます。よくある質問には、任意の Amazon Kendra 予約済みフィールドまたはカスタムフィールドを追加できます。

以下に、JSON のスキーマを示します。

{
    "SchemaVersion": 1,
    "FaqDocuments": [
        {
            "Question": string,
            "Answer": string,
            "Attributes": {
                string: object
                additional attributes
            },
            "AccessControlList": [
               {
                   "Name": string,
                   "Type": enum( "GROUP" | "USER" ),
                   "Access": enum( "ALLOW" | "DENY" )
               },
               additional user context
            ]
        },
        additional FAQ documents
    ]
}

次の JSON ファイルの例は、2 つのよくある質問ドキュメントを示しています。1 つのドキュメントには、必要な質問と回答のみが含まれています。もう 1 つのドキュメントには、追加のフィールド情報、ユーザーコンテキスト、またはアクセスコントロール情報も含まれています。

{
    "SchemaVersion": 1,
    "FaqDocuments": [
        {
            "Question": "How many free clinics are in Spokane WA?",
            "Answer": "13"
        },
        {
            "Question": "How many free clinics are there in Mountain View Missouri?",
            "Answer": "7",
            "Attributes": {
                "_source_uri": "https://s3.region.company.com/bucket-name/directory/faq.csv",
                "_category": "Charitable Clinics"
            },
            "AccessControlList": [
               {
                   "Name": "user@amazon.com",
                   "Type": "USER",
                   "Access": "ALLOW"
               },
               {
                   "Name": "Admin",
                   "Type": "GROUP",
                   "Access": "ALLOW"
               }
            ]
        }
    ]
}

カスタムフィールドの種類を以下に示します。

JSON ファイルには、ユーザーアクセスコントロールフィールドを含めることができます。これらのフィールドを使用して、よくある質問へのアクセスを特定のユーザーおよびグループに制限できます。ユーザーコンテキストでフィルタリングするには、ユーザーはクエリでユーザーおよびグループ情報を提供する必要があります。それ以外の場合は、関連するよくある質問がすべて返されます。詳細については、「User context filtering」を参照してください。

許可リストまたは拒否リストのいずれかにユーザーまたはグループを含めることはできますが、同一ユーザーが個別に許可されているもののグループでは拒否されているような場合は、両方に含めることはできません。両方にユーザーまたはグループを含めると、エラーが発生します。

以下は、JSON のよくある質問に、ユーザーアクセスコントロールを含める例です。

"AccessControlList": [
                {
                    "Name": "group or user name",
                    "Type": "GROUP | USER",
                    "Access": "ALLOW | DENY"
                },
                additional user context
            ]
   

よくある質問ファイルの使用

よくある質問入力ファイルを S3 バケットに保存した後、コンソールまたは CreateFaq API を使用して、質問と回答をインデックスに入れます。よくある質問を更新する場合は、よくある質問を削除してもう一度作成します。DeleteFaq API を使用してよくある質問を削除します。

ソースファイルを含む S3 バケットにアクセスできる IAM ロールを指定する必要があります。ロールは、コンソールまたは RoleArn パラメータで指定します。次は、よくある質問ファイルをインデックスに追加する例です。

import boto3

kendra = boto3.client("kendra")

# Provide the index ID
index_id = "index-id"
# Provide the IAM role ARN required to index documents in an S3 bucket
role_arn = "arn:aws:iam::${accountId}:role/${roleName}"

# Provide the S3 bucket path information to the FAQ file
faq_path = {
    "Bucket": "bucket-name",
    "Key": "FreeClinicsUSA.csv"
}

response = kendra.create_faq(
    S3Path =  faq_path,
    Name = "FreeClinicsUSA",
    IndexId = index_id,
    RoleArn = role_arn
)

print(response)

英語以外の言語のよくある質問ファイル

よくある質問は、サポートされている言語でインデックスを作成できます。言語を指定しない場合、デフォルトでは英語で Amazon Kendra インデックスFAQsできます。言語コードは、CreateFaq 演算を呼び出すか、よくある質問のメタデータによくある質問の言語コードをフィールドとして含める場合に指定します。よくある質問のメタデータフィールドで指定されたメタデータに言語コードがない場合、よくある質問は、CreateFAQ 演算を呼び出したときに指定した言語コードを使用してインデックス作成されます。コンソールでサポートされている言語でよくある質問ドキュメントのインデックス作成をするには、[FAQs] (よくある質問) いｎ移動し、[Add FAQ] (よくある質問の追加) を選択します。[言語] のドロップダウンから言語を選択します。