AMAZON.KendraSearchIntent - Amazon Lex V1
Política de IAMUso de atributos de solicitud y sesión como filtrosUso de la respuesta de búsquedaUsar una función de Lambda para administrar la solicitud y la respuesta

Si utiliza Amazon Lex V2, consulte la guía de Amazon Lex V2.

 

Si utiliza Amazon Lex V1, le recomendamos que actualice los bots a Amazon Lex V2. Hemos dejado de agregar nuevas características a V1, por lo que recomendamos encarecidamente utilizar V2 para todos los nuevos bots.

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

AMAZON.KendraSearchIntent

Para buscar documentos indexados con Amazon Kendra, utilice la intención AMAZON.KendraSearchIntent. Cuando Amazon Lex no puede determinar la siguiente acción en una conversación con el usuario, desencadena la intención de búsqueda.

Solo AMAZON.KendraSearchIntent está disponible en la configuración regional en inglés (EE. UU.) (en-US) y en el Este de EE. UU. (Norte de Virginia), Oeste de EE. UU. (Oregón) y Europa (Irlanda).

Amazon Kendra es un servicio de búsqueda basado en aprendizaje automático que indexa documentos en lenguaje natural, como documentos PDF o archivos de Microsoft Word. Puede buscar documentos indexados y devolver los siguientes tipos de contestaciones a una pregunta:

  • Una respuesta

  • Una entrada de una pregunta frecuente que podría dar respuesta a la pregunta

  • Un documento relacionado con la pregunta

Para ver un ejemplo del uso de AMAZON.KendraSearchIntent, consulte Ejemplo: Creación de un bot de preguntas frecuentes sobre un índice de Amazon Kendra.

Si configura una intención AMAZON.KendraSearchIntent para su bot, Amazon Lex la llamará siempre que no pueda determinar el enunciado del usuario en una ranura o una intención. Por ejemplo, si el bot está obteniendo una respuesta de un tipo de ranura denominado “ingrediente de pizza” y el usuario dice “¿Qué es una pizza?”, Amazon Lex llamará a AMAZON.KendraSearchIntent para administrar la pregunta. Si no hay respuesta de Amazon Kendra, la conversación continuará tal y como está configurada en el bot.

Cuando AMAZON.KendraSearchIntent y AMAZON.FallbackIntent se usan en el mismo bot, Amazon Lex utiliza las intenciones de la siguiente manera:

  1. Amazon Lex llama a AMAZON.KendraSearchIntent. La intención llama a la operación Query de Amazon Kendra.

  2. Si Amazon Kendra devuelve una respuesta, Amazon Lex muestra el resultado al usuario.

  3. Si no hay respuesta por parte de Amazon Kendra, Amazon Lex vuelve a preguntar al usuario. La siguiente acción dependerá de la respuesta del usuario.

    • Si la respuesta del usuario contiene un enunciado que Amazon Lex reconoce, como llenar un valor de ranura o confirmar una intención, la conversación con el usuario continúa conforme a la configuración del bot.

    • Si la respuesta del usuario no contiene un enunciado que Amazon Lex reconozca, Amazon Lex hará otra llamada a la operación Query.

  4. Si tras un número establecido de nuevos intentos no hay ninguna respuesta, Amazon Lex llamará a AMAZON.FallbackIntent y finalizará la conversación con el usuario.

Hay tres formar de usar la AMAZON.KendraSearchIntent para hacer una solicitud a Amazon Kendra:

  • Deje que la intención de búsqueda haga la solicitud por usted. Amazon Lex llama a Amazon Kendra con el enunciado del usuario como cadena de búsqueda. Cuando cree la intención, puede definir una cadena de filtro de consulta que limite el número de respuestas devueltas por Amazon Kendra. Amazon Lex utiliza el filtro en la solicitud de consulta.

  • Agregue parámetros de consulta adicionales a la solicitud para acotar los resultados de la búsqueda mediante la función de Lambda de diálogo. Puede agregar un campo kendraQueryFilterString que contenga parámetros de consulta de Amazon Kendra a la acción de diálogo delegate. Cuando se agregan parámetros de consulta a la solicitud con la función de Lambda, estos tienen prioridad sobre el filtro de consulta que se definió al crear la intención.

  • Crear una nueva consulta mediante la función de Lambda de diálogo. Puede crear una solicitud de consulta de Amazon Kendra completa para que Amazon Lex la envíe. Especifique la consulta en el campo kendraQueryRequestPayload de la acción de diálogo delegate. El campo kendraQueryRequestPayload tiene prioridad sobre el campo kendraQueryFilterString.

Si desea especificar el parámetro queryFilterString al crear un bot o el campo kendraQueryFilterString al llamar a la acción delegate en una función de Lambda de diálogo, especifique una cadena que se utilice como filtro de atributos en la consulta de Amazon Kendra. Si la cadena no es un filtro de atributos válido, aparecerá una excepción InvalidBotConfigException en tiempo de ejecución. Para obtener más información sobre los filtros de atributos, consulte Usar atributos de documentos para filtrar las consultas en la Guía para desarrolladores de Amazon Kendra.

Para mantener el control sobre la consulta que Amazon Lex envía a Amazon Kendra, puede especificar una consulta en el campo kendraQueryRequestPayload de la función de Lambda de diálogo. Si la consulta no es válida, Amazon Lex devolverá una excepción InvalidLambdaResponseException. Para obtener más información, consulte la Operación Query en la Guía para desarrolladores de Amazon Kendra.

Si desea ver un ejemplo de cómo se usa AMAZON.KendraSearchIntent, consulte Ejemplo: Creación de un bot de preguntas frecuentes sobre un índice de Amazon Kendra.

Política de IAM para Amazon Kendra Search

Para poder utilizar la intención AMAZON.KendraSearchIntent, debe tener un rol que proporcione políticas de AWS Identity and Access Management (IAM) que permitan a Amazon Lex adoptar un rol de tiempo de ejecución con permiso para llamar a la intención Query de Amazon Kendra. La configuración de IAM que utilice dependerá de si crea la AMAZON.KendraSearchIntent con la consola de Amazon Lex, con un SDK de AWS o con la AWS Command Line Interface (AWS CLI). Si utiliza la consola, puede decidir si desea agregar permisos al rol vinculado al servicio de Amazon Lex para que llame a Amazon Kendra o si prefiere utilizar un rol específico para llamar a la operación Query de Amazon Kendra. Si utiliza AWS CLI o un SDK para crear la intención, debe usar un rol específico para llamar a la operación Query.

Asociación de permisos

Puede utilizar la consola para asociar permisos que permitan al rol vinculado al servicio de Amazon Lex predeterminado acceder a la operación Query de Amazon Kendra. Si asocia permisos al rol vinculado al servicio, no es necesario crear y administrar específicamente un rol en tiempo de ejecución para conectarse al índice de Amazon Kendra.

El usuario, el rol o el grupo que utilice para obtener acceso a la consola de Amazon Lex debe tener permisos para administrar políticas de roles. Asocie la siguiente política de IAM al rol de acceso de la consola. Al conceder estos permisos, el rol podrá cambiar la política del rol vinculado al servicio existente. 

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

Especificación de un rol

Puede utilizar la consola, la AWS CLI o la API para especificar un rol en tiempo de ejecución que se utilice para llamar a la operación Query de Amazon Kendra.

El usuario, rol o grupo que utilice para especificar el rol en tiempo de ejecución debe tener el permiso iam:PassRole. La siguiente política define el permiso. Puede utilizar las claves de contexto de condición iam:AssociatedResourceArn y iam:PassedToService para limitar aún más el alcance de los permisos. Para obtener más información, consulte IAM y claves de contexto de condición de AWS STS en la Guía del usuario de AWS Identity and Access Management.

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

El rol en tiempo de ejecución que Amazon Lex tiene que usar para llamar a Amazon Kendra debe tener permisos kendra:Query. Cuando se utiliza un rol de IAM existente para obtener permiso para llamar a la operación Query de Amazon Kendra, el rol debe tener asociada la siguiente política.

Puede utilizar la consola de IAM, la API de IAM o la AWS CLI para crear una política y asociarla a un rol. Estas instrucciones utilizan la CLI de AWS para crear el rol y las políticas.

nota

El siguiente código tiene formato para Linux y MacOS. Para Windows, reemplace el carácter de continuación de línea de Linux (\) por un signo de intercalación (^).

Para agregar permisos de la operación Query a un rol

  1. Cree un documento llamado KendraQueryPolicy.json en el directorio actual, agregue el código siguiente y guárdelo.

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

  2. En AWS CLI, ejecute el siguiente comando para crear la política de IAM y ejecutar la operación Query de Amazon Kendra.

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

  3. Asocie la política al rol de IAM que esté utilizando para llamar a la operación Query.

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

Puede optar por actualizar el rol vinculado al servicio de Amazon Lex o utilizar el rol que creó al generar la AMAZON.KendraSearchIntent de su bot. En el siguiente procedimiento, se muestra cómo puede elegir el rol de IAM que se va a utilizar.

Para especificar el rol en tiempo de ejecución de AMAZON.KendraSearchIntent

  1. Inicie sesión en la AWS Management Console y abra la consola de Amazon Lex en https://console.aws.amazon.com/lex/.

  2. Seleccione el bot al que desee agregar la AMAZON.KendraSearchIntent.

  3. Seleccione el signo más (+) situado junto a Intenciones.

  4. En Agregar intención, seleccione Buscar intenciones existentes.

  5. En Intenciones de búsqueda, escriba AMAZON.KendraSearchIntent y seleccione Agregar.

  6. En Copiar intención integrada, escriba un nombre para la intención, como KendraSearchIntent, y seleccione Agregar.

  7. Abra la sección de consultas de Amazon Kendra.

  8. En Rol de IAM, elija una de las opciones siguientes:

    • Para actualizar el rol vinculado al servicio de Amazon Lex y permitir que el bot consulte los índices de Amazon Kendra, seleccione Agregar permisos de Amazon Kendra.

    • Para utilizar un rol que tenga permiso para llamar a la operación Query de Amazon Kendra, seleccione Usar un rol existente.

Uso de atributos de solicitud y sesión como filtros

Para filtrar la respuesta de Amazon Kendra y obtener los elementos relacionados con la conversación actual, use los atributos de sesión y solicitud como filtros agregando el parámetro queryFilterString cuando cree el bot. Especifique un marcador de posición para el atributo cuando cree la intención. De ese modo, Amazon Lex V2 sustituirá el valor antes de llamar a Amazon Kendra. Para obtener más información sobre los atributos de solicitud, consulte Definición de los atributos de solicitud. Para obtener más información acerca de los atributos de la sesión, consulte Definición de atributos de la sesión.

A continuación, se muestra un ejemplo de un parámetro queryFilterString que utiliza una cadena para filtrar la consulta de Amazon Kendra.

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

A continuación, se muestra un ejemplo de un parámetro queryFilterString que utiliza un atributo de sesión llamado "SourceURI" para filtrar la consulta de Amazon Kendra.

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

A continuación, se muestra un ejemplo de un parámetro queryFilterString que utiliza un atributo de solicitud llamado "DepartmentName" para filtrar la consulta de Amazon Kendra.

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

Los filtros AMAZON.KendraSearchInteng utilizan el mismo formato que los filtros de búsqueda de Amazon Kendra. Para obtener más información, consulte Usar atributos de documentos para filtrar los resultados de búsqueda en la Guía para desarrolladores de Amazon Kendra.

La cadena de filtro de consultas utilizada con la AMAZON.KendraSearchIntent debe incluir letras minúsculas para la primera letra de cada filtro. Por ejemplo, a continuación se muestra un filtro de consulta válido para la AMAZON.KendraSearchIntent.

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

Uso de la respuesta de búsqueda

Amazon Kendra devuelve la respuesta a una búsqueda en la declaración conclusion de la intención. La intención debe tener una declaración conclusion, a menos que una función de Lambda de cumplimiento genere un mensaje de conclusión.

Amazon Kendra tiene cuatro tipos de respuestas.

  • x-amz-lex:kendra-search-response-question_answer-question-<N>: la pregunta de una sección de preguntas frecuentes que coincide con la búsqueda.

  • x-amz-lex:kendra-search-response-question_answer-answer-<N>: la respuesta de una sección de preguntas frecuentes que coincide con la búsqueda.

  • x-amz-lex:kendra-search-response-document-<N>: un extracto de un documento del índice relacionado con el texto del enunciado.

  • x-amz-lex:kendra-search-response-document-link-<N>: la URL de un documento del índice relacionado con el texto del enunciado.

  • x-amz-lex:kendra-search-response-answer-<N>: un extracto de un documento del índice que responde a la pregunta.

Las respuestas se devuelven en atributos request. Puede haber hasta cinco respuestas para cada atributo, numeradas del 1 al 5. Para obtener más información sobre las respuestas, consulte Tipos de respuesta en la Guía para desarrolladores de Amazon Kendra.

La declaración conclusion debe tener uno o varios grupos de mensajes. Cada grupo contiene uno o varios mensajes. Cada mensaje puede contener una o varias variables de marcador de posición que se reemplazarán con los atributos de solicitud de la respuesta proporcionada por Amazon Kendra. En el grupo de mensajes debe haber al menos un mensaje en el que todas las variables se hayan sustituido por los valores de atributo de solicitud obtenidos de la respuesta en tiempo de ejecución o debe haber un mensaje sin variables de marcador de posición. Los atributos de solicitud se separan con paréntesis dobles («((« »))»). Los siguientes mensajes del grupo coinciden con cualquier respuesta de Amazon Kendra:

  • «Encontré una pregunta frecuente para usted: ((x-amz-lex:kendra-search-response-question_answer-question-1)) y la respuesta es ((x-amz-lex:kendra-search-response-question_answer-answer-1))»

  • «Encontré un extracto en un documento útil: ((x-amz-lex:kendra-search-response-document-1))»

  • «Creo que la respuesta a sus preguntas es ((x-amz-lex:kendra-search-response-answer-1))»

Usar una función de Lambda para administrar la solicitud y la respuesta

La intención AMAZON.KendraSearchIntent puede utilizar el enlace de código de diálogo y el enlace de código de cumplimentación para administrar la solicitud enviada a Amazon Kendra y la respuesta. Utilice la función de Lambda del enlace de código de diálogo cuando desee modificar la consulta que envía a Amazon Kendra, y la función de Lambda de enlace de código de cumplimentación cuando desee modificar la respuesta.

Crear una consulta con el enlace de código de diálogo

Puede utilizar el enlace de código de diálogo para crear una consulta y enviarla a Amazon Kendra. El uso del enlace de código de diálogo es opcional. Si no especifica ningún enlace de código de diálogo, Amazon Lex creará una consulta a partir del enunciado del usuario y utilizará la queryFilterString que se proporcionó al configurar la intención, si se proporcionó alguna.

Puede utilizar dos campos en la respuesta del enlace de código de diálogo para modificar la solicitud que se envía a Amazon Kendra:

  • kendraQueryFilterString: utilice esta cadena para especificar los filtros de atributos para la solicitud de Amazon Kendra. Puede filtrar la consulta utilizando cualquiera de los campos definidos en el índice. Para obtener información sobre la estructura de la cadena de filtro, consulte Usar atributos de documentos para filtrar consultas en la Guía para desarrolladores de Amazon Kendra. Si la cadena de filtro especificada no es válida, aparecerá una excepción InvalidLambdaResponseException. La cadena kendraQueryFilterString invalida cualquier otra cadena de consulta especificada en el campo queryFilterString configurado para la intención.

  • kendraQueryRequestPayload: utilice esta cadena para especificar una consulta de Amazon Kendra. La consulta puede utilizar cualquiera de las características de Amazon Kendra. Si no especifica una consulta válida, aparecerá una excepción InvalidLambdaResponseException. Para obtener más información, consulte Consulta en la Guía para desarrolladores de Amazon Kendra.

Una vez que haya creado el filtro o la cadena de consulta, envíe la respuesta a Amazon Lex con el campo dialogAction de la respuesta establecido en delegate. Amazon Lex envía la consulta a Amazon Kendra y, a continuación, devuelve la respuesta a la consulta al enlace de código de cumplimentación.

Uso del enlace de código de cumplimentación en la respuesta

Una vez que Amazon Lex envía una consulta a Amazon Kendra, la respuesta se devuelve a la función de Lambda de cumplimiento AMAZON.KendraSearchIntent. El evento de entrada del enlace de código contiene la respuesta completa de Amazon Kendra. Los datos de consulta tienen la misma estructura que los datos devueltos por la operación Query de Amazon Kendra. Para obtener más información, consulte Sintaxis de la respuesta a la consulta en la Guía para desarrolladores de Amazon Kendra.

El enlace de código de cumplimentación es opcional. Si no existe o si el enlace de código no devuelve un mensaje en la respuesta, Amazon Lex utilizará la declaración conclusion con las respuestas.