AMAZON.KendraSearchIntent - Amazon Lex
IAMPolíticaUso de atributos de solicitud y sesión como filtrosUsar la respuesta de búsquedaUsar una función de Lambda para administrar la solicitud y la respuesta

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 V2 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 machine-learning-based búsqueda 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 un FAQ que podría responder a la pregunta

  • Un documento relacionado con la pregunta

Para ver un ejemplo del uso de AMAZON.KendraSearchIntent, consulte Ejemplo: creación de un FAQ bot para un índice de Amazon Kendra.

Si configura una intención AMAZON.KendraSearchIntent para su bot, Amazon Lex V2 la llamará siempre que no pueda determinar el enunciado del usuario en un slot o una intención. Si no hay respuesta de Amazon Kendra, la conversación continuará tal y como está configurada en el bot.

nota

Actualmente, Amazon Lex V2 no admite la AMAZON.KendraSearchIntent durante la obtención del slot. Si Amazon Lex V2 no puede determinar el enunciado del usuario para un slot, llama al AMAZON.FallbackIntent.

Cuando use la AMAZON.KendraSearchIntent con la AMAZON.FallbackIntent en el mismo bot, Amazon Lex V2 utiliza las intenciones de la siguiente manera:

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

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

  3. Si no hay respuesta por parte de Amazon Kendra, Amazon Lex V2 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 V2 reconoce, como llenar un valor de slot 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 V2 reconozca, Amazon Lex V2 hará otra llamada a la operación Query.

  4. Si tras un número establecido de nuevos intentos no hay ninguna respuesta, Amazon Lex V2 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 V2 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 V2 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. 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 utilizando la función de Lambda. Puede crear una solicitud de consulta de Amazon Kendra completa para que Amazon Lex V2 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 V2 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 V2 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 FAQ bot para un índice de Amazon Kendra.

IAMPolítica de Amazon Kendra Search

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

Asociación de permisos

Puede utilizar la consola para asociar permisos que permitan al rol vinculado al servicio de Amazon Lex V2 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 V2 debe tener permisos para administrar políticas de roles. Adjunte la siguiente IAM política a la función de acceso a 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/lexv2.amazonaws.com/AWSServiceRoleForLexBots*"
    },
    {
        "Effect": "Allow",
        "Action": "iam:ListRoles",
        "Resource": "*"
    }
]
}

Especificación de un rol

Puede usar la consola, la o la AWS CLI API para especificar un rol de tiempo de ejecución que se utilizará al llamar a la operación de Amazon KendraQuery.

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 IAMy AWS STS condicione las claves de contexto en la Guía del AWS Identity and Access Management usuario.

{
"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 V2 tiene que usar para llamar a Amazon Kendra debe tener permisos kendra:Query. Si utiliza un IAM rol existente como permiso para llamar a la Query operación de Amazon Kendra, el rol debe tener la siguiente política adjunta.

Puede usar la IAM consola IAMAPI, la o la AWS CLI para crear una política y asociarla a un rol. Estas instrucciones utilizan el AWS CLI 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 IAM política para ejecutar la operación Amazon KendraQuery.

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

  3. Adjunte la política al IAM rol que está utilizando para llamar a la Query operación.

    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 V2 o utilizar el rol que creó al generar la AMAZON.KendraSearchIntent de su bot. El siguiente procedimiento muestra cómo elegir el IAM rol que se va a usar.

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

  1. Inicie sesión en la consola Amazon Lex AWS Management Console y ábrala 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. Para IAMel rol, elija una de las siguientes opciones:

    • Para actualizar el rol vinculado al servicio de Amazon Lex V2 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 Establecer atributos de solicitud. Para obtener más información acerca de los atributos de sesión, consulte Establecer atributos de 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"
            }
        }
    }
]
}

Usar la respuesta de búsqueda

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

Amazon Kendra tiene cinco tipos de respuestas.

  • Las dos respuestas siguientes requieren que se configure una FAQ para su índice de Amazon Kendra. Para obtener más información, consulte Agregar preguntas y respuestas directamente a un índice.

    • x-amz-lex:kendra-search-response-question_answer-question-<N>— La pregunta de a FAQ que coincide con la búsqueda.

    • x-amz-lex:kendra-search-response-question_answer-answer-<N>— La respuesta de una FAQ que coincide con la búsqueda.

  • Las tres respuestas siguientes requieren que se configure un origen de datos para su índice de Amazon Kendra. Para obtener más información, consulte Crear un origen de datos.

    • 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>— El URL de un documento del índice que está 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 closingResponse 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:

  • «He encontrado una FAQ pregunta para ti: ((x-amz-lex: kendra-search-response-question _respuesta-pregunta-1)), y la respuesta es ((: _respuesta-respuesta-1))» x-amz-lex kendra-search-response-question

  • «He encontrado un extracto de un documento útil: ((: -1))» x-amz-lex kendra-search-response-document

  • «Creo que la respuesta a tus 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 V2 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 V2 con el campo dialogAction de la respuesta establecido en delegate. Amazon Lex V2 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.

Usar el enlace de código de cumplimentación en la respuesta

Una vez que Amazon Lex V2 envía una consulta a Amazon Kendra, la respuesta se devuelve a la función de Lambda de cumplimentación 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 V2 utilizará la declaración closingResponse con las respuestas.