AMAZON.KendraSearchIntent

Amazon Kendra でインデックス付けしたドキュメントを検索するには、AMAZON.KendraSearchIntent インテントを使用します。Amazon Lex がユーザーとの会話の次のアクションを決定できない場合、検索インテントをトリガーします。

AMAZON.KendraSearchIntent は、英語 (米国) (en-US)、および米国東部 (バージニア北部)、米国東部 (バージニア北部)、米国西部 (オレゴン)、欧州 (アイルランド) の各リージョンでのみ利用できます。

Amazon Kendra は、PDF ドキュメントや Microsoft Word ファイルなどの自然言語ドキュメントにインデックス付けする機械学習ベースの検索サービスです。インデックス付けされたドキュメントを検索し、質問に対して以下のタイプのレスポンスを返すことができます。

• 回答

• 質問への回答になる可能性がある FAQ のエントリ

• 質問に関連するドキュメント

AMAZON.KendraSearchIntent の使用例については、「例: Amazon Kendra インデックスを使用する FAQ ボットを作成する」を参照してください。

ボットに AMAZON.KendraSearchIntent インテントを設定した場合、Amazon Lex は、スロットまたはインテントのユーザー発話を判別できないときは常に、そのインテントを呼び出します。例えば、ボットが「ピザのトッピング」というスロットタイプのレスポンスを引き出し、ユーザーが「ピザって何?」と言った場合、Amazon Lex は AMAZON.KendraSearchIntent を呼び出してその質問を処理します。Amazon Kendra からのレスポンスがない場合、会話はボットで設定されたとおりに進みます。

同じボットで AMAZON.KendraSearchIntent と AMAZON.FallbackIntent の両方を使用する場合、Amazon Lex は以下のようにインテントを使用します。

1. Amazon Lex は AMAZON.KendraSearchIntent を呼び出します。インテントは Amazon Kendra Query オペレーションを呼び出します。

2. Amazon Kendra がレスポンスを返す場合、Amazon Lex はユーザーに結果を表示します。

3. Amazon Kendra からのレスポンスがない場合、Amazon Lex はユーザーに再度プロンプトを表示します。以下のアクションは、ユーザーからのレスポンスによって異なります。

   • ユーザーからのレスポンスに、スロット値の入力やインテントの確認など、Amazon Lex が認識する発話が含まれている場合、ユーザーとの会話はボットで設定されたとおりに進みます。

   • ユーザーからのレスポンスに Amazon Lex が認識する発話が含まれていない場合、Amazon Lex は Query オペレーションを再度呼び出します。

4. 設定された再試行回数の後にレスポンスがない場合、Amazon Lex は AMAZON.FallbackIntent を呼び出し、ユーザーとの会話を終了します。

AMAZON.KendraSearchIntent を使用して Amazon Kendra へのリクエストを作成するには、3 つの方法があります。

• 検索インテントからリクエストを作成します。Amazon Lex では、ユーザーの発話を検索文字列として Amazon Kendra を呼び出します。インテントを作成するときに、Amazon Kendra が返すレスポンスの数を制限するクエリフィルタ文字列を定義できます。Amazon Lex は、クエリリクエストでフィルターを使用します。

• ダイアログ Lambda 関数を使用して、追加のクエリパラメータをリクエストに追加します。Amazon Kendra クエリパラメータを含む kendraQueryFilterString フィールドを delegate ダイアログアクションに追加します。Lambda 関数を使用してクエリパラメータをリクエストに追加すると、それらのパラメータは、インテントを作成したときに定義したクエリフィルタよりも優先されます。

• ダイアログ Lambda 関数を使用して、新しいクエリを作成します。Amazon Lex によって送信される完全な Amazon Kendra クエリリクエストを作成できます。delegate ダイアログアクションの kendraQueryRequestPayload フィールドでクエリを指定します。kendraQueryRequestPayload フィールドは kendraQueryFilterString フィールドよりも優先されます。

ボットを作成するときに queryFilterString パラメータを指定したり、ダイアログ Lambda 関数で delegate アクションを呼び出すときに kendraQueryFilterString フィールドを指定したりするには、Amazon Kendra クエリの属性フィルターとして使用する文字列を指定します。文字列が有効な属性フィルターでないと、実行時に InvalidBotConfigException 例外が発生します。属性ドキュメントの詳細については、「Amazon Kendra Developer Guide」(Amazon Kendra デベロッパーガイド) の「Using document attributes to filter queries」(ドキュメント属性を使用してクエリをフィルタリングする) を参照してください。

Amazon Lex が Amazon Kendra に送信するクエリを制御するには、ダイアログ Lambda 関数の kendraQueryRequestPayload フィールドでクエリを指定できます。クエリが有効でない場合、Amazon Lex は InvalidLambdaResponseException の例外を返します。詳細については、「Amazon Kendra Developer Guide」(Amazon Kendra デベロッパーガイド) の 「Query operation」 (クエリオペレーション) を参照してください。

AMAZON.KendraSearchIntent の使用方法の例については、「例: Amazon Kendra インデックスを使用する FAQ ボットを作成する」を参照してください。

Amazon Kendra 検索の IAM ポリシー

AMAZON.KendraSearchIntent インテントを使用するには、AWS Identity and Access Management (IAM) ポリシーがアタッチされたロールを使用して、Amazon Kendra Query インテントを呼び出すアクセス許可を持つランタイムロールを Amazon Lex が引き受けられるようにする必要があります。使用する IAM 設定は、Amazon Lex コンソールを使用して AMAZON.KendraSearchIntent を作成するか、AWS SDK や AWS Command Line Interface (AWS CLI) を使用して作成するかによって異なります。コンソールを使用する場合、Amazon Lex サービスにリンクされたロールに Amazon Kendra を呼び出すアクセス許可を追加するか、Amazon Kendra Query オペレーションを呼び出すための専用のロールを使用するかを選択できます。AWS CLI または SDK を使用してインテントを作成するときは、Query オペレーションを呼び出すための専用のロールを使用する必要があります。

アクセス許可のアタッチ

コンソールを使用して、Amazon Kendra Query オペレーションに対するアクセス許可をデフォルトの Amazon Lex サービスにリンクされたロールにアタッチできます。サービスにリンクされたロールにアクセス許可をアタッチする場合は、Amazon Kendra インデックスに接続するための専用のランタイムロールを作成して管理する必要はありません。

Amazon Lex コンソールへのアクセスに使用するユーザー、ロール、またはグループには、ロールポリシーを管理するアクセス許可が必要です。以下の IAM ポリシーをコンソールのアクセスロールにアタッチします。これらのアクセス許可を付与すると、既存のサービスにリンクされたロールポリシーを変更するアクセス許可がロールに付与されます。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iam:AttachRolePolicy",
                "iam:PutRolePolicy",
                "iam:GetRolePolicy"
            ],
            "Resource": "arn:aws:iam::*:role/aws-service-role/lex.amazonaws.com/AWSServiceRoleForLexBots"
        },
        {
            "Effect": "Allow",
            "Action": "iam:ListRoles",
            "Resource": "*"
        }
    ]
}

ロールの指定

コンソール、AWS CLI、または API を使用して、Amazon Kendra Query オペレーションを呼び出すときに使用するランタイムロールを指定できます。

ランタイムロールの指定に使用する ユーザー、ロール、またはグループには、iam:PassRole アクセス許可が必要です。以下のポリシーでは、このアクセス許可を定義しています。iam:AssociatedResourceArn および iam:PassedToService 条件コンテキストキーを使用して、アクセス許可の範囲をさらに制限できます。詳細については、[AWS STS ユーザーガイド] で [IAM と AWS Identity and Access Management 条件コンテキストキー] を参照してください。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "iam:PassRole",
            "Resource": "arn:aws:iam::account:role/role"
        }
    ]
}

Amazon Lex が Amazon Kendra の呼び出しに使用する必要があるランタイムロールには、kendra:Query アクセス許可が必要です。Amazon Kendra Query オペレーションを呼び出すアクセス許可に既存の IAM ロールを使用する場合、そのロールには以下のポリシーがアタッチされている必要があります。

IAM コンソール、IAM API、または AWS CLI を使用して、ポリシーを作成し、ロールにアタッチすることができます。以下の手順では、AWS CLI を使用してロールとポリシーを作成します。

注記

次のコードは、Linux と MacOS 用にフォーマットされています。Windows の場合、Linux 行連結記号 (\) をキャレット (^) に置き換えます。

Query オペレーションのアクセス許可をロールに追加するには

1. 現在のディレクトリに KendraQueryPolicy.json という名前でドキュメントを作成し、以下のコードを追加して保存します。

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Effect": "Allow",
               "Action": [
                   "kendra:Query"
               ],
               "Resource": [
                   "arn:aws:kendra:region:account:index/index ID"
               ]
           }
       ]
   }

2. AWS CLI で次のコマンドを実行して、Amazon Kendra Query オペレーションを実行するための IAM ポリシーを作成します。

   aws iam create-policy \
       --policy-name query-policy-name \
       --policy-document file://KendraQueryPolicy.json

3. Query オペレーションの呼び出しに使用している IAM ロールに、そのポリシーをアタッチします。

   aws iam attach-role-policy \
       --policy-arn arn:aws:iam::account-id:policy/query-policy-name
       --role-name role-name

Amazon Lex サービスにリンクされたロールを更新するか、ボット用に AMAZON.KendraSearchIntent を作成したときに作成したロールを使用するかを選択できます。以下の手順は、使用する IAM ロールを選択する方法を示しています。

AMAZON.KendraSearchIntent のランタイムロールを指定するには

1. AWS Management Console にサインインし、Amazon Lex コンソール (https://console.aws.amazon.com/lex/) を開きます。

2. AMAZON.KendraSearchIntent を追加するボットを選択します。

3. [インテント] の横のプラス (+) を選択します。

4. [インテントの追加] で、[既存のインテントの検索] を選択します。

5. [インテントの検索] に「AMAZON.KendraSearchIntent」と入力し、[追加] を選択します。

6. [組み込みインテントのコピー] にインテントの名前 (「KendraSearchIntent」など) を入力し、[追加] を選択します。

7. [Amazon Kendra クエリ] セクションを開きます。

8. [IAM ロール] で、以下のいずれかのオプションを選択します。

   • ボットが Amazon Kendra インデックスをクエリできるように Amazon Lex サービスにリンクされたロールを更新するには、[Add Amazon Kendra permissions] (Amazon Kendra アクセス許可の追加) を選択します。

   • Amazon Kendra Query オペレーションを呼び出すアクセス許可を持つロールを使用するには、[Use an existing role] (既存のロールを使用) を選択します。

フィルタとしてのリクエスト属性とセッション属性の使用

Amazon Kendra から現在の会話に関連するアイテムへのレスポンスをフィルター処理するには、ボットの作成時に queryFilterString パラメータを追加して、セッション属性とリクエスト属性をフィルターとして使用します。インテントを作成するときに属性のプレースホルダーを指定します。それにより、Amazon Lex V2 が Amazon Kendra を呼び出す前にプレースホルダーを値に置き換えます。リクエスト属性の詳細については、「リクエスト属性の設定」を参照してください。セッション属性の詳細については、「セッション属性の設定」を参照してください。

以下に示しているのは、string to filter というリクエスト属性を使用して Amazon Kendra クエリをフィルター処理する queryFilterString パラメータの例です。

"{"equalsTo": {"key": "City", "value": {"stringValue": "Seattle"}}}"

以下に示しているのは、"SourceURI" というセッション属性を使用して Amazon Kendra クエリをフィルター処理する queryFilterString パラメータの例です。

"{"equalsTo": {"key": "SourceURI","value": {"stringValue": "[FileURL]"}}}"

以下に示しているのは、"DepartmentName" というリクエスト属性を使用して Amazon Kendra クエリをフィルター処理する queryFilterString パラメータの例です。

"{"equalsTo": {"key": "Department","value": {"stringValue": "((DepartmentName))"}}}"

AMAZON.KendraSearchInteng フィルターは Amazon Kendra 検索フィルターと同じ形式を使用します。詳細については、[Amazon Kendra デベロッパーガイド] の [ドキュメント属性を使用して検索結果をフィルターする] を参照してください。

AMAZON.KendraSearchIntent で使用されるクエリフィルタ文字列は、各フィルターの最初の文字には小文字を使用する必要があります。例えば、次は AMAZON.KendraSearchIntent の有効なクエリフィルターです。

{
    "andAllFilters": [
        {
            "equalsTo": {
                "key": "City",
                "value": {
                    "stringValue": "Seattle"
                }
            }
        },
        {
            "equalsTo": {
                "key": "State",
                "value": {
                    "stringValue": "Washington"
                }
            }
        }
    ]
}

検索レスポンスの使用

Amazon Kendra は、インテントの conclusion ステートメントでの検索に対するレスポンスを返します。フルフィルメント Lambda 関数が結論メッセージを生成しない限り、インテントには conclusion ステートメントが必要です。

Amazon Kendra には 4 タイプのレスポンスがあります。

• x-amz-lex:kendra-search-response-question_answer-question-<N> - 検索に一致する FAQ からの質問。

• x-amz-lex:kendra-search-response-question_answer-answer-<N> - 検索に一致する FAQ からの回答。

• x-amz-lex:kendra-search-response-document-<N> - 発話のテキストに関連するインデックス内のドキュメントからの抜粋。

• x-amz-lex:kendra-search-response-document-link-<N> - 発話のテキストに関連するインデックス内のドキュメントからの抜粋。

• x-amz-lex:kendra-search-response-answer-<N> - 質問への回答があるインデックス内のドキュメントからの抜粋。

レスポンスは request 属性で返されます。各属性には、最大 5 つのレスポンスがあり 1～5 の番号が付けられます。レスポンスの詳細については、[Amazon Kendra デベロッパーガイド] の [レスポンスのタイプ] を参照してください。

conclusion ステートメントには、1 つ以上のメッセージグループが必要です。各メッセージグループには、1 つ以上のメッセージが含まれます。各メッセージには、Amazon Kendra からのレスポンスでリクエスト属性によって置き換えられる 1 つ以上のプレースホルダー変数を含めることができます。メッセージ内のすべての変数がランタイムレスポンスのリクエスト属性値で置き換えられるメッセージグループには、1 つ以上のメッセージが必要です。プレースホルダー変数のないメッセージグループには、1 つのメッセージが必要です。リクエスト属性は二重かっこ (( )) で囲みます。以下のメッセージグループのメッセージは Amazon Kendra からのレスポンスに一致します。

• 「FAQ の質問 ((x-amz-lex:kendra-search-response-question_answer-question-1)) を見つけました。回答は ((x-amz-lex:kendra-search-response-question_answer -answer-1)) です」

• 「参考になるドキュメント ((x-amz-lex:kendra-search-response-document-1)) からの抜粋を見つけました」

• 「質問への回答はおそらく ((x-amz-lex:kendra-search-response-answer-1)) です」

Lambda 関数を使用したリクエストとレスポンスの管理

AMAZON.KendraSearchIntent インテントでは、ダイアログコードフックとフルフィルメントコードフックを使用して、Amazon Kendra へのリクエストとレスポンスを管理できます。Amazon Kendra に送信するクエリを変更する場合はダイアログコードフック Lambda 関数を使用し、レスポンスを変更する場合はフルフィルメントコードフック Lambda 関数を使用します。

ダイアログコードフックを使用したクエリの作成

ダイアログコードフックを使用して、Amazon Kendra に送信するクエリを作成できます。ダイアログコードフックを使用するかどうかはオプションです。ダイアログコードフックを指定しない場合、Amazon Lex によってユーザー発話からクエリが作成され、queryFilterString が使用されます (インテントの設定時に指定した場合)。

ダイアログコードフックレスポンスで 2 つのフィールドを使用して、Amazon Kendra へのリクエストを変更できます。

• kendraQueryFilterString - この文字列を使用して、Amazon Kendra リクエストの属性フィルタを指定します。インデックスで定義されたインデックスフィールドのいずれかを使用して、クエリをフィルタ処理できます。フィルター文字列の構造については、「Amazon Kendra Developer Guide」(Amazon Kendra デベロッパーガイド) の「Using document attributes to filter queries」(ドキュメント属性を使用してクエリをフィルタリングする) を参照してください。指定したフィルタ文字列が有効でないと、InvalidLambdaResponseException 例外が発生します。kendraQueryFilterString 文字列は、インテント用に設定された queryFilterString で指定されたクエリ文字列を上書きします。

• kendraQueryRequestPayload - この文字列を使用して、Amazon Kendra クエリを指定します。クエリでは、Amazon Kendra の任意の機能を使用できます。有効なクエリを指定しないと、InvalidLambdaResponseException 例外が発生します。これらの制限の詳細については、「Amazon Kendra Developer Guide」(Amazon Kendra デベロッパーガイド) の「Query」(クエリ) を参照してください。

フィルターまたはクエリ文字列を作成したら、レスポンスの dialogAction フィールドを delegate に設定してAmazon Lex にレスポンスを送信します。Amazon Lex は、クエリを Amazon Kendra に送信し、クエリレスポンスをフルフィルメントコードフックに返します。

レスポンスでのフルフィルメントコードフックの使用

Amazon Lex がクエリを Amazon Kendra に送信すると、クエリレスポンスが AMAZON.KendraSearchIntent フルフィルメント Lambda 関数に返されます。コードフックへの入力イベントには、Amazon Kendra からの完全なレスポンスが含まれます。クエリデータは、Amazon Kendra Query オペレーションによって返されるものと同じ構造になります。詳細については、[Amazon Kendra デベロッパーガイド] の [クエリレスポンス構文] を参照してください。

フルフィルメントコードフックはオプションです。フルフィルメントコードフックがない場合、またはレスポンスでメッセージを返さない場合、Amazon Lex はレスポンスに conclusion ステートメントを使用します。