Stratégie IAM Utilisation des attributs de demande et de session en tant que filtres Utilisation de la réponse de recherche Utilisation d'une fonction Lambda pour gérer la demande et la réponse

AMAZON.KendraSearchIntent

Pour rechercher des documents que vous avez indexés avec Amazon Kendra, utilisez l'AMAZON.KendraSearchIntentintention. Lorsqu'Amazon Lex V2 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 V2 appelle l'intention chaque fois qu'il ne parvient pas à déterminer l'intention exprimée par l'utilisateur. En l'absence de réponse de la part d'Amazon Kendra, la conversation se poursuit telle que configurée dans le bot.

Note

Amazon Lex V2 ne prend actuellement pas en charge le processus AMAZON.KendraSearchIntent d'obtention de créneaux. Si Amazon Lex V2 ne parvient pas à déterminer l'énoncé de l'utilisateur pour un emplacement, il appelle le. AMAZON.FallbackIntent

Lorsque vous utilisez le AMAZON.KendraSearchIntent with AMAZON.FallbackIntent dans le même bot, Amazon Lex V2 utilise les intentions suivantes :

Amazon Lex V2 appelle leAMAZON.KendraSearchIntent. L'objectif est l'opération Amazon KendraQuery.
Si Amazon Kendra renvoie une réponse, Amazon Lex V2 affiche le résultat à l'utilisateur.
En l'absence de réponse de la part d'Amazon Kendra, Amazon Lex V2 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 V2, 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 V2, Amazon Lex V2 lance un autre appel à l'Queryopération.
S'il n'y a aucune réponse après le nombre de tentatives configuré, Amazon Lex V2 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 V2 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 V2 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 votre fonction Lambda. 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 à l'aide de 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. Vous pouvez créer une demande de requête Amazon Kendra complète envoyée par Amazon Lex V2. 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 V2 envoie à Amazon Kendra, vous pouvez spécifier une requête dans le kendraQueryRequestPayload champ de votre fonction Lambda. Si la requête n'est pas valide, Amazon Lex V2 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 qui fournit des politiques AWS Identity and Access Management (IAM) permettant à Amazon Lex V2 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 V2, 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 V2 ou utiliser un rôle spécifique pour appeler l'opération Amazon Kendra. Query Lorsque vous utilisez le AWS CLI ou un SDK pour créer l'intention, vous devez utiliser un rôle spécifique pour appeler l'Queryopération.

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 V2 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 V2 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/lexv2.amazonaws.com/AWSServiceRoleForLexBots*"
    },
    {
        "Effect": "Allow",
        "Action": "iam:ListRoles",
        "Resource": "*"
    }
]
}

Spécification d'un rôle

Vous pouvez utiliser la console AWS 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 Management utilisateur.


{
"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 V2 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

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"
        ]
    }
]
}

Dans le AWS 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
```

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 V2 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

Connectez-vous à la console Amazon Lex AWS Management Console et ouvrez-la à l'adresse https://console.aws.amazon.com/lex/.
Choisissez le bot auquel vous souhaitez ajouter l’intention AMAZON.KendraSearchIntent.
Choisissez le signe plus (+) en regarde de Intents (Intentions).
Dans Add intent (Ajouter une intention), choisissez Search existing intents (Rechercher des intentions existantes).
Dans Search intents (Rechercher des intentions), entrez, AMAZON.KendraSearchIntent puis choisissez Add (Ajouter).
Dans Copy built-in intent (Copier une intention intégrée), entrez un nom pour l'intention, par exemple KendraSearchIntent, puis choisissez Add (Ajouter).
Ouvrez la section Amazon Kendra query (Requête Amazon Kendra).
Pour IAM role (Rôle IAM) choisissez une des options suivantes :
- Pour mettre à jour le rôle lié au service Amazon Lex V2 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.

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 demande. 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 une réponse tirée de la déclaration d'IntentClosingSettingintention. L'intention doit comporter une closingResponse déclaration, sauf si une fonction Lambda produit un message de réponse de clôture.

Amazon Kendra propose cinq types de réponses.

Les deux réponses suivantes nécessitent la configuration d'une FAQ pour votre index Amazon Kendra. Pour plus de détails, voir Ajouter des questions et réponses directement à un index.
- 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.
Les trois réponses suivantes nécessitent la configuration d'une source de données pour votre index Amazon Kendra. Pour plus de détails, consultez la section Création d'une source de données.
- 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 closingResponse 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 V2 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 V2 avec le dialogAction champ de réponse défini surdelegate. Amazon Lex V2 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 V2 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 V2 utilise l'closingResponseinstruction pour les réponses.

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

AMAZON.HelpIntent

Exemple : création d'un bot FAQ pour un index Amazon Kendra