Agregar preguntas frecuentes (FAQs) a un índice

Puedes añadir las preguntas frecuentes (FAQs) directamente a tu índice mediante la consola o la CreateFaqAPI. La adición FAQs a un índice es una operación asíncrona. Los datos de las preguntas frecuentes se colocan en un archivo que se almacena en un depósito. Amazon Simple Storage Service Puede utilizar archivos CSV o JSON como entrada para las preguntas frecuentes:

Por ejemplo, el siguiente es un archivo CSV básico que proporciona respuestas a preguntas sobre clínicas gratuitas en Spokane, Washington, EE. UU. y Mountain View, Missouri, EE. UU.

How many free clinics are in Spokane WA?, 13
How many free clinics are there in Mountain View Missouri?, 7

Crear campos de índice para un archivo de preguntas frecuentes

Si utilizas un archivo CSV o JSON personalizado como entrada, puedes declarar campos personalizados para tus preguntas frecuentes. Por ejemplo, puede crear un campo personalizado que asigne cada pregunta frecuente a un departamento empresarial. Cuando se devuelve la pregunta frecuente en una respuesta, puede utilizar el departamento como faceta para restringir la búsqueda solo a “RR. HH.” o “Finanzas”, por ejemplo.

Un campo personalizado debe asignarse a un campo de índice. En la consola, utilice la página Facet definition (Definición de faceta) para crear un campo de índice. Al utilizar la API, primero debe crear un campo de índice mediante la API UpdateIndex.

El tipo de campo/atributo del archivo de preguntas frecuentes debe coincidir con el tipo del campo de índice asociado. Por ejemplo, el campo “Departamento” es un campo de tipo STRING_LIST. Por lo tanto, debe proporcionar en el archivo de preguntas frecuentes valores para el campo Departamento como una lista de cadenas. Puede comprobar el tipo de campos de índice utilizando la página Facet Definition (Definición de faceta) en la consola o mediante la API DescribeIndex.

Cuando se crea un campo de índice que se asigna a un atributo personalizado, se puede marcar como visualizable, facetable u ordenable. No se puede hacer que un atributo personalizado se pueda buscar.

Además de los atributos personalizados, también puede definir los campos reservados o comunes de Amazon Kendra en un archivo CSV o JSON personalizado. Para obtener más información, consulte Atributos o campos del documento.

Archivo CSV básico

Usa un archivo CSV básico cuando quieras usar una estructura simple para tu FAQs. En un archivo CSV básico, cada fila tiene dos o tres campos: una pregunta, una respuesta y un URI de origen opcional que apunta a un documento con más información.

El contenido del archivo debe seguir el Formato común RFC 4180 y tipo MIME para archivos de valores separados por comas (CSV).

A continuación se muestra un archivo de preguntas frecuentes en formato CSV básico.

How many free clinics are in Spokane WA?, 13, https://s3.region.company.com/bucket-name/directory/faq.csv
How many free clinics are there in Mountain View Missouri?, 7, https://s3.region.company.com/bucket-name/directory/faq.csv

Archivo CSV personalizado

Utilice un archivo CSV personalizado cuando desee agregar campos/atributos personalizados a sus preguntas frecuentes. Para un archivo CSV personalizado, utilice una fila de encabezado del archivo CSV para definir los atributos adicionales.

El archivo CSV debe contener los dos campos obligatorios siguientes:

El archivo CSV personalizado puede contener tanto campos Amazon Kendra reservados (excepto _faq_id_data_source_id,_document_title, y_file_type) como cualquier campo personalizado.

A continuación se muestra un ejemplo de un archivo CSV personalizado.

_question,_answer,_last_updated_at,custom_string
How many free clinics are in Spokane WA?, 13, 2012-03-25T12:30:10+01:00, Note: Some free clinics require you to meet certain criteria in order to use their services
How many free clinics are there in Mountain View Missouri?, 7, 2012-03-25T12:30:10+01:00, Note: Some free clinics require you to meet certain criteria in order to use their services

El contenido del archivo personalizado debe seguir el Formato común RFC 4180 y tipo MIME para archivos de valores separados por comas (CSV).

A continuación se enumeran los tipos de campos personalizados:

Un archivo CSV personalizado puede contener campos de control de acceso de usuarios. Puede utilizar estos campos para limitar el acceso a las preguntas frecuentes a determinados usuarios y grupos. Para filtrar el contexto de usuario, el usuario debe proporcionar en la consulta información de usuario y grupo. De lo contrario, FAQs se devolverán todos los datos relevantes. Para obtener más información, consulte Filtrado de contexto de usuario.

A continuación se enumeran los filtros de contexto de usuario para FAQs:

Proporcione los valores de las listas de permitir y denegar listas separadas por comas entre comillas (por ejemplo, "user1,user2,user3"). Puede incluir un usuario o un grupo en una lista de permisos o en una lista de denegación, pero no en ambas si el mismo usuario tiene un permiso individual pero forma parte de un grupo denegado. Si incluye un usuario o grupo en ambos, recibirá un error.

A continuación se muestra un ejemplo de un archivo CSV personalizado.

_question, _answer, _acl_user_allow, _acl_user_deny, _acl_group_allow, _acl_group_deny
How many free clinics are in Spokane WA?, 13, "userID6201,userID7552", "userID1001,userID2020", groupBasicPlusRate, groupPremiumRate

Archivo JSON

Puede utilizar un archivo JSON para proporcionar preguntas, respuestas y campos para su índice. Puede añadir cualquiera de los campos Amazon Kendra reservados o campos personalizados a las preguntas frecuentes.

A continuación se muestra el esquema para el archivo JSON.

{
    "SchemaVersion": 1,
    "FaqDocuments": [
        {
            "Question": string,
            "Answer": string,
            "Attributes": {
                string: object
                additional attributes
            },
            "AccessControlList": [
               {
                   "Name": string,
                   "Type": enum( "GROUP" | "USER" ),
                   "Access": enum( "ALLOW" | "DENY" )
               },
               additional user context
            ]
        },
        additional FAQ documents
    ]
}

En el siguiente ejemplo, el archivo JSON muestra dos documentos de preguntas frecuentes. Uno de ellos solo tiene la pregunta y la respuesta requeridas. El otro documento también incluye información adicional sobre el contexto del usuario y los campos o sobre el control de acceso.

{
    "SchemaVersion": 1,
    "FaqDocuments": [
        {
            "Question": "How many free clinics are in Spokane WA?",
            "Answer": "13"
        },
        {
            "Question": "How many free clinics are there in Mountain View Missouri?",
            "Answer": "7",
            "Attributes": {
                "_source_uri": "https://s3.region.company.com/bucket-name/directory/faq.csv",
                "_category": "Charitable Clinics"
            },
            "AccessControlList": [
               {
                   "Name": "user@amazon.com",
                   "Type": "USER",
                   "Access": "ALLOW"
               },
               {
                   "Name": "Admin",
                   "Type": "GROUP",
                   "Access": "ALLOW"
               }
            ]
        }
    ]
}

A continuación se enumeran los tipos de campos personalizados:

Un archivo JSON puede contener campos de control de acceso de usuarios. Puede utilizar estos campos para limitar el acceso a las preguntas frecuentes a determinados usuarios y grupos. Para filtrar el contexto de usuario, el usuario debe proporcionar en la consulta información de usuario y grupo. De lo contrario, FAQs se devuelven todos los datos relevantes. Para obtener más información, consulte Filtrado de contexto de usuario.

Puede incluir un usuario o un grupo en una lista de permisos o en una lista de denegación, pero no en ambas si el mismo usuario tiene un permiso individual pero forma parte de un grupo denegado. Si incluye un usuario o grupo en ambos, recibirá un error.

A continuación se muestra un ejemplo de cómo se incluye el control de acceso de usuarios en una pregunta frecuente de JSON.

"AccessControlList": [
                {
                    "Name": "group or user name",
                    "Type": "GROUP | USER",
                    "Access": "ALLOW | DENY"
                },
                additional user context
            ]
   

Uso del archivo de preguntas frecuentes

Después de almacenar el archivo de entrada de preguntas frecuentes en un bucket de S3, utilice la consola o la API CreateFaq para incluir las preguntas y respuestas en el índice. Si quiere actualizar una pregunta frecuente, elimínela y vuelva a crearla. Utilice la API DeleteFaq para eliminar una pregunta frecuente.

Debe proporcionar un IAM rol que tenga acceso al depósito de S3 que contiene sus archivos fuente. Puede especificar el rol en la consola o en el parámetro RoleArn. A continuación se muestra un ejemplo de adición de un archivo de preguntas frecuentes a un índice.

import boto3

kendra = boto3.client("kendra")

# Provide the index ID
index_id = "index-id"
# Provide the IAM role ARN required to index documents in an S3 bucket
role_arn = "arn:aws:iam::${accountId}:role/${roleName}"

# Provide the S3 bucket path information to the FAQ file
faq_path = {
    "Bucket": "bucket-name",
    "Key": "FreeClinicsUSA.csv"
}

response = kendra.create_faq(
    S3Path =  faq_path,
    Name = "FreeClinicsUSA",
    IndexId = index_id,
    RoleArn = role_arn
)

print(response)

Archivos de preguntas frecuentes en idiomas distintos del inglés

Puede indexar una pregunta frecuente en un idioma compatible. Amazon Kendra indexa FAQs en inglés de forma predeterminada si no especificas un idioma. El código de idioma se especifica al llamar a la CreateFaqoperación o se puede incluir el código de idioma de una pregunta frecuente en los metadatos de las preguntas frecuentes como un campo. Si una pregunta frecuente no contiene un código de idioma en sus metadatos especificado en un campo de metadatos, las preguntas frecuentes se indexan utilizando el código de idioma especificado al llamar a la operación CreateFAQ. Para indexar un documento de preguntas frecuentes en un idioma compatible en la consola, ve a Añadir preguntas frecuentes FAQsy selecciona Añadir preguntas frecuentes. Elija un idioma en el menú desplegable Language (Idioma).