AMAZON.KendraSearchIntent

Pour rechercher des documents que vous avez indexés avec Amazon Kendra, utilisez l'AMAZON.KendraSearchIntentintention. Lorsqu'Amazon Lex ne parvient pas à déterminer l'action suivante dans une conversation avec l'utilisateur, cela déclenche l'intention de recherche.

AMAZON.KendraSearchIntentIl est disponible uniquement dans la région anglaise (États-Unis) (en-États-Unis) et dans les régions USA Est (Virginie du Nord), USA Ouest (Oregon) et Europe (Irlande).

Amazon Kendra est un service de machine-learning-based recherche qui indexe les documents en langage naturel tels que les documents PDF ou les fichiers Microsoft Word. Il peut effectuer des recherches sur des documents indexés et renvoyer les types de réponse suivants à une question :

• Une réponse

• Une entrée de FAQ qui pourrait répondre à la question

• Un document lié à la question

Pour obtenir un exemple d'utilisation de AMAZON.KendraSearchIntent, veuillez consulter Exemple : création d'un bot FAQ pour un index Amazon Kendra.

Si vous configurez une AMAZON.KendraSearchIntent intention pour votre bot, Amazon Lex appelle l'intention chaque fois qu'il ne parvient pas à déterminer l'énoncé de l'utilisateur pour un emplacement ou une intention. Par exemple, si votre bot obtient une réponse pour un type de machine à sous appelé « garniture à pizza » et que l'utilisateur demande « Qu'est-ce qu'une pizza ? », Amazon Lex les appelle AMAZON.KendraSearchIntent pour répondre à la question. En l'absence de réponse de la part d'Amazon Kendra, la conversation se poursuit telle que configurée dans le bot.

Lorsque vous utilisez à la fois le AMAZON.KendraSearchIntent et le AMAZON.FallbackIntent dans le même bot, Amazon Lex utilise les intentions suivantes :

1. Amazon Lex appelle leAMAZON.KendraSearchIntent. L'objectif est l'opération Amazon KendraQuery.

2. Si Amazon Kendra renvoie une réponse, Amazon Lex affiche le résultat à l'utilisateur.

3. En l'absence de réponse de la part d'Amazon Kendra, Amazon Lex réinvite l'utilisateur. L'action suivante dépend de la réponse de l'utilisateur.

   • Si la réponse de l'utilisateur contient un énoncé reconnu par Amazon Lex, tel que le remplissage d'une valeur de créneau ou la confirmation d'une intention, la conversation avec l'utilisateur se déroule comme configuré pour le bot.

   • Si la réponse de l'utilisateur ne contient aucun énoncé reconnu par Amazon Lex, Amazon Lex lance un autre appel à l'Queryopération.

4. S'il n'y a aucune réponse après le nombre de tentatives configuré, Amazon Lex appelle l'utilisateur AMAZON.FallbackIntent et met fin à la conversation avec l'utilisateur.

Vous pouvez utiliser le pour envoyer une demande AMAZON.KendraSearchIntent à Amazon Kendra de trois manières :

• Laissez l'intention de recherche faire la demande pour vous. Amazon Lex appelle Amazon Kendra en utilisant l'énoncé de l'utilisateur comme chaîne de recherche. Lorsque vous créez l'intention, vous pouvez définir une chaîne de filtre de requête qui limite le nombre de réponses renvoyées par Amazon Kendra. Amazon Lex utilise le filtre dans la demande de requête.

• Ajoutez des paramètres de requête supplémentaires à la demande pour affiner les résultats de recherche à l'aide de la fonction Lambda de votre boîte de dialogue. Vous ajoutez un kendraQueryFilterString champ contenant les paramètres de requête Amazon Kendra à l'action de delegate dialogue. Lorsque vous ajoutez des paramètres de requête à la demande avec la fonction Lambda, ils ont priorité sur le filtre de requête que vous avez défini lors de la création de l'intention.

• Créez une nouvelle requête à l'aide de la fonction Lambda de dialogue. Vous pouvez créer une demande de requête Amazon Kendra complète envoyée par Amazon Lex. Vous spécifiez la requête dans le champ kendraQueryRequestPayload de l’action de dialogue delegate. Le champ kendraQueryRequestPayload a priorité sur le champ kendraQueryFilterString.

Pour spécifier le queryFilterString paramètre lorsque vous créez un bot, ou pour spécifier le kendraQueryFilterString champ lorsque vous appelez l'delegateaction dans une fonction Lambda de dialogue, vous devez spécifier une chaîne qui est utilisée comme filtre d'attribut pour la requête Amazon Kendra. Si la chaîne n'est pas un filtre d'attribut valide, vous obtiendrez une exception InvalidBotConfigException lors de l'exécution. Pour plus d'informations sur les filtres d'attributs, consultez la section Utilisation des attributs de document pour filtrer les requêtes dans le manuel Amazon Kendra Developer Guide.

Pour contrôler la requête qu'Amazon Lex envoie à Amazon Kendra, vous pouvez spécifier une requête dans le kendraQueryRequestPayload champ de votre fonction Lambda de dialogue. Si la requête n'est pas valide, Amazon Lex renvoie une InvalidLambdaResponseException exception. Pour plus d'informations, consultez l'opération de requête dans le manuel Amazon Kendra Developer Guide.

Pour obtenir un exemple de la façon d'utiliser l’intention AMAZON.KendraSearchIntent, veuillez consulter Exemple : création d'un bot FAQ pour un index Amazon Kendra.

Politique IAM pour Amazon Kendra Search

Pour utiliser l'AMAZON.KendraSearchIntentintention, vous devez utiliser un rôle fournissant des politiques AWS Identity and Access Management (IAM) permettant à Amazon Lex d'assumer un rôle d'exécution autorisé à appeler l'intention Amazon Query Kendra. Les paramètres IAM que vous utilisez varient selon que vous les avez créés à l'AMAZON.KendraSearchIntentaide de la console Amazon Lex, d'un SDK AWS ou du AWS Command Line Interface ()AWS CLI. Lorsque vous utilisez la console, vous pouvez choisir entre ajouter l'autorisation d'appeler Amazon Kendra au rôle lié au service Amazon Lex ou utiliser un rôle spécifique pour appeler l'opération Amazon Kendra. Query Lorsque vous utilisez l’AWS CLI ou un kit SDK pour créer l'intention, vous devez utiliser un rôle spécifique pour appeler l'opération Query.

Attachement d’autorisations

Vous pouvez utiliser la console pour associer des autorisations d'accès à l'Queryopération Amazon Kendra au rôle lié au service Amazon Lex par défaut. Lorsque vous associez des autorisations au rôle lié au service, vous n'avez pas besoin de créer et de gérer un rôle d'exécution spécifiquement pour vous connecter à l'index Amazon Kendra.

L'utilisateur, le rôle ou le groupe que vous utilisez pour accéder à la console Amazon Lex doit disposer des autorisations nécessaires pour gérer les politiques relatives aux rôles. Associez la politique IAM suivante au rôle d'accès à la console. Lorsque vous accordez ces autorisations, le rôle dispose des autorisations permettant de modifier la stratégie de rôle liée à un service existante.

{
    "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": "*"
        }
    ]
}

Spécification d'un rôle

Vous pouvez utiliser la consoleAWS CLI, le ou l'API pour spécifier un rôle d'exécution à utiliser lors de l'appel de l'opération Amazon KendraQuery.

L'utilisateur, le rôle ou le groupe que vous utilisez pour spécifier le rôle d'exécution doit disposer de l'iam:PassRoleautorisation. La stratégie suivante définit l'autorisation. Vous pouvez utiliser les clés de contexte de condition iam:AssociatedResourceArn et iam:PassedToService pour limiter davantage la portée des autorisations. Pour plus d'informations, consultez les sections IAM et AWS STS Condition Context Keys dans le guide de l'AWS Identity and Access Managementutilisateur.

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

Le rôle d'exécution qu'Amazon Lex doit utiliser pour appeler Amazon Kendra doit disposer des kendra:Query autorisations requises. Lorsque vous utilisez un rôle IAM existant pour obtenir l'autorisation d'appeler l'opération Amazon Query Kendra, le rôle doit être associé à la politique suivante.

Vous pouvez utiliser la console IAM, l'API IAM ou le AWS CLI pour créer une politique et l'associer à un rôle. Ces instructions utilisent l’AWS CLI pour créer le rôle et les stratégies.

Note

Le code suivant est formaté pour Linux et macOS. Sous Windows, remplacez le caractère de continuité de ligne Linux (\) par le caret (^).

Pour ajouter une autorisation d'opération Query à un rôle

1. Créez un document appelé KendraQueryPolicy.json dans le répertoire courant, ajoutez-y le code suivant et enregistrez-le.

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

2. Dans leAWS CLI, exécutez la commande suivante pour créer la politique IAM permettant d'exécuter l'opération Amazon Query Kendra.

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

3. Attachez la politique au rôle IAM que vous utilisez pour appeler l'Queryopération.

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

Vous pouvez choisir de mettre à jour le rôle lié au service Amazon Lex ou d'utiliser un rôle que vous avez créé lors de la création du rôle AMAZON.KendraSearchIntent pour votre bot. La procédure suivante indique comment choisir le rôle IAM à utiliser.

Pour spécifier le rôle d'exécution pour AMAZON. KendraSearchIntent

1. Connectez-vous à la console Amazon Lex AWS Management Console et ouvrez-la à l'adresse https://console.aws.amazon.com/lex/.

2. Choisissez le bot auquel vous souhaitez ajouter l’intention AMAZON.KendraSearchIntent.

3. Choisissez le signe plus (+) en regarde de Intents (Intentions).

4. Dans Add intent (Ajouter une intention), choisissez Search existing intents (Rechercher des intentions existantes).

5. Dans Search intents (Rechercher des intentions), entrez, AMAZON.KendraSearchIntent puis choisissez Add (Ajouter).

6. Dans Copy built-in intent (Copier une intention intégrée), entrez un nom pour l'intention, par exemple KendraSearchIntent, puis choisissez Add (Ajouter).

7. Ouvrez la section Amazon Kendra query (Requête Amazon Kendra).

8. Pour IAM role (Rôle IAM) choisissez une des options suivantes :

   • Pour mettre à jour le rôle lié au service Amazon Lex afin de permettre à votre bot d'interroger les index Amazon Kendra, choisissez Ajouter des autorisations Amazon Kendra.

   • Pour utiliser un rôle autorisé à appeler l'Queryopération Amazon Kendra, choisissez Utiliser un rôle existant.

Utilisation des attributs de demande et de session en tant que filtres

Pour filtrer la réponse d'Amazon Kendra aux éléments liés à la conversation en cours, utilisez les attributs de session et de demande comme filtres en ajoutant le queryFilterString paramètre lorsque vous créez votre bot. Vous spécifiez un espace réservé pour l'attribut lorsque vous créez l'intention, puis Amazon Lex V2 remplace une valeur avant d'appeler Amazon Kendra. Pour de plus amples informations sur les attributs de demande, veuillez consulter Définition des attributs de demandes. Pour en savoir plus sur les attributs de session, consultez Définition des attributs de session.

Voici un exemple de queryFilterString paramètre qui utilise une chaîne pour filtrer la requête Amazon Kendra.

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

Voici un exemple de queryFilterString paramètre qui utilise un attribut de session appelé "SourceURI" pour filtrer la requête Amazon Kendra.

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

Voici un exemple de queryFilterString paramètre qui utilise un attribut de requête appelé "DepartmentName" pour filtrer la requête Amazon Kendra.

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

Les AMAZON.KendraSearchInteng filtres utilisent le même format que les filtres de recherche Amazon Kendra. Pour plus d'informations, consultez la section Utilisation des attributs de document pour filtrer les résultats de recherche dans le guide du développeur Amazon Kendra.

La chaîne de filtre de requête utilisée avec le AMAZON.KendraSearchIntent doit utiliser des lettres minuscules pour la première lettre de chaque filtre. Par exemple, le filtre de requête suivant est valide pour leAMAZON.KendraSearchIntent.

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

Utilisation de la réponse de recherche

Amazon Kendra renvoie la réponse à une recherche dans la déclaration d'conclusionintention. L'intention doit comporter une conclusion déclaration, sauf si une fonction Lambda d'exécution produit un message de conclusion.

Amazon Kendra propose quatre types de réponses.

• x-amz-lex:kendra-search-response-question_answer-question-<N>— La question d'une FAQ qui correspond à la recherche.

• x-amz-lex:kendra-search-response-question_answer-answer-<N>— La réponse d'une FAQ qui correspond à la recherche.

• x-amz-lex:kendra-search-response-document-<N>— Extrait d'un document de l'index lié au texte de l'énoncé.

• x-amz-lex:kendra-search-response-document-link-<N>— L'URL d'un document dans l'index qui est lié au texte de l'énoncé.

• x-amz-lex:kendra-search-response-answer-<N>— Un extrait d'un document de l'index qui répond à la question.

Les réponses sont renvoyées dans les attributs request. Il peut y avoir jusqu'à cinq réponses pour chaque attribut, numérotées de 1 à 5. Pour plus d'informations sur les réponses, consultez la section Types de réponses dans le manuel Amazon Kendra Developer Guide.

L'instruction conclusion doit comporter un ou plusieurs groupes de messages. Chaque groupe de messages contient un ou plusieurs messages. Chaque message peut contenir une ou plusieurs variables d'espace réservé qui sont remplacées par des attributs de demande dans la réponse d'Amazon Kendra. Il doit y avoir au moins un message du groupe de messages dans lequel toutes les variables du message sont remplacées par des valeurs d'attribut de demande dans la réponse d'exécution, ou il doit y avoir un message du groupe de messages sans aucune variable d'espace réservé. Les attributs de demande sont définis avec des parenthèses doubles ("((" "))"). Les messages du groupe de messages suivants correspondent à toutes les réponses d'Amazon Kendra :

• « J'ai trouvé une question FAQ pour vous : ((x-amz-lex: kendra-search-response-question _answer-question-1)), et la réponse est ((x-amz-lex: _answer-answer-1)) » kendra-search-response-question

• « J'ai trouvé un extrait d'un document utile : ((x-amz-lex: kendra-search-response-document -1)) »

• « Je pense que la réponse à vos questions est ((x-amz-lex: kendra-search-response-answer -1)) »

Utilisation d'une fonction Lambda pour gérer la demande et la réponse

L'AMAZON.KendraSearchIntentintention peut utiliser votre crochet de code de dialogue et votre crochet de code d'expédition pour gérer la demande adressée à Amazon Kendra et la réponse. Utilisez la fonction Lambda du crochet de code de dialogue lorsque vous souhaitez modifier la requête que vous envoyez à Amazon Kendra, et la fonction Lambda du crochet de code d'expédition lorsque vous souhaitez modifier la réponse.

Création d'une requête avec le hook de code de dialogue

Vous pouvez utiliser le code hook de dialogue pour créer une requête à envoyer à Amazon Kendra. L'utilisation du hook de code de dialogue est facultative. Si vous ne spécifiez pas de crochet de dialogue, Amazon Lex crée une requête à partir de l'énoncé de l'utilisateur et utilise queryFilterString celui que vous avez fourni lors de la configuration de l'intention, si vous en avez fourni un.

Vous pouvez utiliser deux champs dans la réponse au crochet de code de la boîte de dialogue pour modifier la demande adressée à Amazon Kendra :

• kendraQueryFilterString— Utilisez cette chaîne pour spécifier les filtres d'attributs pour la demande Amazon Kendra. Vous pouvez filtrer la requête à l'aide de l'un des champs d'index définis dans votre index. Pour connaître la structure de la chaîne de filtre, consultez la section Utilisation des attributs de document pour filtrer les requêtes dans le manuel Amazon Kendra Developer Guide. Si la chaîne de filtre spécifiée n'est pas valide, vous obtiendrez une exception InvalidLambdaResponseException. La chaîne kendraQueryFilterString remplace toute chaîne de requête spécifiée dans queryFilterString configuré pour l'intention.

• kendraQueryRequestPayload— Utilisez cette chaîne pour spécifier une requête Amazon Kendra. Votre requête peut utiliser n'importe laquelle des fonctionnalités d'Amazon Kendra. Si vous ne spécifiez pas de requête valide, vous obtenez une exception InvalidLambdaResponseException. Pour plus d'informations, consultez la section Requête dans le guide du développeur Amazon Kendra.

Après avoir créé le filtre ou la chaîne de requête, vous envoyez la réponse à Amazon Lex avec le dialogAction champ de réponse défini surdelegate. Amazon Lex envoie la requête à Amazon Kendra, puis renvoie la réponse à la requête au hook du code d'expédition.

Utilisation du hook de code d'exécution pour la réponse

Une fois qu'Amazon Lex a envoyé une requête à Amazon Kendra, la réponse à la requête est renvoyée à la fonction AMAZON.KendraSearchIntent Lambda d'expédition. L'événement d'entrée dans le code hook contient la réponse complète d'Amazon Kendra. Les données de requête ont la même structure que celles renvoyées par l'opération Amazon KendraQuery. Pour plus d'informations, consultez la section Syntaxe des réponses aux requêtes dans le manuel Amazon Kendra Developer Guide.

Le hook de code d'exécution est facultatif. S'il n'en existe pas, ou si le crochet de code ne renvoie aucun message dans la réponse, Amazon Lex utilise l'conclusioninstruction pour les réponses.