Adicionar perguntas frequentes a um índice

Você pode adicionar perguntas frequentes (FAQs) diretamente ao seu índice usando o console ou a CreateFaqAPI. A adição de perguntas frequentes a um índice é uma operação assíncrona. Você coloca os dados das perguntas frequentes em um arquivo que você armazena em um Amazon Simple Storage Service bucket. Você pode usar arquivos CSV ou JSON como entrada para as perguntas frequentes:

• CSV básico: um arquivo CSV em que cada linha contém uma pergunta, uma resposta e um URI de origem opcional.

• CSV personalizado: um arquivo CSV que contém perguntas, respostas e cabeçalhos para campos/atributos personalizados que você pode usar para facetar, exibir ou classificar respostas de perguntas frequentes. Você também pode definir campos de controle de acesso para limitar a resposta das perguntas frequentes a determinados usuários e grupos que têm permissão para ver a resposta das perguntas frequentes.

• JSON: um arquivo JSON que contém perguntas, respostas e cabeçalhos para campos/atributos personalizados que você pode usar para facetar, exibir ou classificar respostas de perguntas frequentes. Você também pode definir campos de controle de acesso para limitar a resposta das perguntas frequentes a determinados usuários e grupos que têm permissão para ver a resposta das perguntas frequentes.

Por exemplo, o seguinte é um arquivo CSV básico que fornece respostas a perguntas sobre clínicas gratuitas em Spokane, Washington, EUA, e Mountain View, Missouri e EUA.

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

nota

O arquivo de perguntas frequentes deve ser um arquivo com codificação UTF-8.

Criação de campos de índice para um arquivo de perguntas frequentes

Ao usar um arquivo CSV ou JSON personalizado para entrada, você pode declarar campos personalizados para suas perguntas de perguntas frequentes. Por exemplo, você pode criar um campo personalizado que atribua cada pergunta a um departamento comercial. Quando as perguntas frequentes são retornadas em uma resposta, você pode usar o departamento como uma faceta para restringir a pesquisa apenas a “RH” ou “Finanças”, por exemplo.

Um campo personalizado deve ser mapeado para um campo de índice. No console, você usa a página de definição de facetas para criar um campo de índice. Ao usar a API, você deve primeiro criar um campo de índice usando a UpdateIndexAPI.

O tipo de campo/atributo no arquivo de perguntas frequentes deve corresponder ao tipo do campo de índice associado. Por exemplo, o campo “Departamento” é um campo de tipo STRING_LIST. Portanto, você deve fornecer valores para o campo do departamento como uma lista de strings no arquivo de perguntas frequentes. Você pode verificar o tipo de campos de índice usando a página de definição de facetas no console ou usando a DescribeIndexAPI.

Ao criar um campo de índice mapeado para um atributo personalizado, você pode marcá-lo como exibível, facetável ou classificável. Não é possível fazer um atributo personalizado pesquisável.

Além dos atributos personalizados, você também pode usar os campos Amazon Kendra reservados ou comuns em um arquivo CSV ou JSON personalizado. Para obter mais informações, consulte Campos ou atributos personalizados.

Arquivo CSV básico

Use um arquivo CSV básico quando quiser usar uma estrutura simples para suas perguntas frequentes. Em um arquivo CSV básico, cada linha tem dois ou três campos: uma pergunta, uma resposta e um URI de origem opcional que aponta para um documento com mais informações.

O conteúdo do arquivo deve seguir o formato comum RFC 4180 e o tipo MIME para arquivos de valores separados por vírgula (CSV).

A seguir está um arquivo de perguntas frequentes no 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

Arquivo CSV personalizado

Use um arquivo CSV personalizado quando quiser adicionar campos/atributos personalizados às suas perguntas de perguntas frequentes. Para um arquivo CSV personalizado, você usa uma linha de cabeçalho no arquivo CSV para definir os atributos adicionais.

O arquivo CSV deve conter os dois campos obrigatórios a seguir:

• _question: perguntas frequentes

• _answer: a resposta para as perguntas frequentes

Seu arquivo pode conter campos Amazon Kendra reservados e campos personalizados. Este é um exemplo de um arquivo .

_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

O conteúdo do arquivo deve seguir o formato comum RFC 4180 e o tipo MIME para arquivos de valores separados por vírgula (CSV).

A seguir, listamos os tipos de campos personalizados:

• Data: valores de data e hora codificados ISO 8601.

  Por exemplo, 2012-03-25T12:30:10+01:00 é o formato de data e hora do ISO 8601 para 25 de março de 2012 às 12h30 (mais 10 segundos) no horário da Europa Central.

• Longos: números, como 1234.

• String: valores de string. Se a string contiver vírgulas, coloque o valor inteiro entre aspas duplas (“) (por exemplo, "custom attribute, and more").

• Lista de strings: uma lista de valores de string. Liste os valores em uma lista separada por virgulas que está entre aspas (“) (por exemplo, "item1, item2, item3"). Se a lista contiver somente uma única entrada, você poderá omitir as aspas (por exemplo, item1).

Um arquivo CSV personalizado pode conter campos de controle de acesso do usuário. Você pode usar esses campos para limitar o acesso às perguntas frequentes a determinados usuários e grupos. Para filtrar o contexto do usuário, o usuário deve fornecer informações do usuário e do grupo na consulta. Caso contrário, todas as perguntas frequentes relevantes serão retornadas. Para obter mais informações, consulte Filtrar o contexto do usuário.

A seguir, são listados os filtros de contexto do usuário para perguntas frequentes:

• _acl_user_allow: os usuários na lista de permissões podem ver as perguntas frequentes na resposta da consulta. A pergunta não é devolvida a outros usuários.

• _acl_user_deny: os usuários na lista de bloqueios não podem ver as perguntas frequentes na resposta da consulta. A pergunta é devolvida a todos os outros usuários quando é relevante para a consulta.

• _acl_group_allow: os usuários que são membros de um grupo permitido podem ver as perguntas frequentes na resposta da consulta. As perguntas frequentes não são devolvidas aos usuários que são membros de outro grupo.

• _acl_group_deny: os usuários que são membros de um grupo permitido podem ver as perguntas frequentes na resposta da consulta. A pergunta é devolvida a todos os outros usuários quando é relevante para a consulta.

Forneça os valores para as listas de permissão e negação em listas separadas por vírgulas entre aspas (por exemplo, "user1,user2,user3"). Você pode incluir um usuário ou um grupo em uma lista de permissões ou negações, mas não em ambas, quando o mesmo usuário é permitido individualmente, mas também em um grupo negado. Se você incluir um usuário ou grupo em ambos, receberá um erro.

Este é um exemplo de um arquivo .

_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

Arquivo JSON

Você pode usar um arquivo JSON para fornecer perguntas, respostas e campos para seu índice. Você pode adicionar qualquer um dos campos Amazon Kendra reservados ou personalizados às perguntas frequentes.

O seguinte é o esquema para o arquivo 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
    ]
}

O exemplo de arquivo JSON a seguir mostra dois documentos de perguntas frequentes. Um dos documentos contém apenas as perguntas e respostas necessárias. O outro documento também inclui informações adicionais de campo e contexto do usuário ou controle de acesso.

{
    "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": "[e-mail]",
                   "Type": "USER",
                   "Access": "ALLOW"
               },
               {
                   "Name": "Admin",
                   "Type": "GROUP",
                   "Access": "ALLOW"
               }
            ]
        }
    ]
}

A seguir, listamos os tipos de campos personalizados:

• Data: um valor de string JSON com valores de data e hora codificados em ISO 8601. Por exemplo, 2012-03-25T12:30:10+01:00 é o formato de data e hora do ISO 8601 para 25 de março de 2012 às 12h30 (mais 10 segundos) no horário da Europa Central.

• Longo: um valor numérico JSON, como 1234.

• String: um valor de string JSON (por exemplo, "custom attribute").

• Lista de strins: uma matriz JSON de valores de string (por exemplo, ["item1,item2,item3"]).

Um arquivo JSON pode conter campos de controle de acesso do usuário. Você pode usar esses campos para limitar o acesso às perguntas frequentes a determinados usuários e grupos. Para filtrar o contexto do usuário, o usuário deve fornecer informações do usuário e do grupo na consulta. Caso contrário, todas as perguntas frequentes relevantes serão retornadas. Para obter mais informações, consulte Filtrar o contexto do usuário.

Você pode incluir um usuário ou um grupo em uma lista de permissões ou negações, mas não em ambas, quando o mesmo usuário é permitido individualmente, mas também em um grupo negado. Se você incluir um usuário ou grupo em ambos, receberá um erro.

Veja a seguir um exemplo de como incluir controle de acesso do usuário em uma pergunta frequente JSON.

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

Usando seu arquivo de perguntas frequentes

Depois de armazenar seu arquivo de entrada de perguntas frequentes em um bucket do S3, você use console ou a API CreateFaqpara colocar as perguntas e respostas no índice. Se você quiser atualizar uma pergunta frequente, exclua ela e crie-a novamente. Use a API DeleteFaq para excluir uma FAQ.

Você deve fornecer uma IAM função que tenha acesso ao bucket do S3 que contém seus arquivos de origem. Você especifica a função no console ou no parâmetro RoleArn. Veja a seguir um exemplo de como adicionar um arquivo de pergunta frequente a um índice.

Python

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)

Java

package com.amazonaws.kendra;

import software.amazon.awssdk.services.kendra.KendraClient;
import software.amazon.awssdk.services.kendra.model.CreateFaqRequest;
import software.amazon.awssdk.services.kendra.model.CreateFaqResponse;
import software.amazon.awssdk.services.kendra.model.S3Path;

public class AddFaqExample {
    public static void main(String[] args) {
        KendraClient kendra = KendraClient.builder().build();

        String indexId = "yourIndexId";
        String roleArn = "your role for accessing S3 files";

        CreateFaqRequest createFaqRequest = CreateFaqRequest
            .builder()
            .indexId(indexId)
            .name("FreeClinicsUSA")
            .roleArn(roleArn)
            .s3Path(
                S3Path
                    .builder()
                    .bucket("an-aws-kendra-test-bucket")
                    .key("FreeClinicsUSA.csv")
                    .build())
            .build();

        CreateFaqResponse response = kendra.createFaq(createFaqRequest);

        System.out.println(String.format("The result of creating FAQ: %s", response));

    }
}

Arquivos de perguntas frequentes em idiomas diferentes do inglês

Você pode indexar uma FAQ em um idioma compatível. Amazon Kendra indexa as perguntas frequentes em inglês por padrão se você não especificar um idioma. Você especifica o código do idioma ao chamar a CreateFaqoperação ou pode incluir o código do idioma de uma FAQ nos metadados da FAQ como um campo. Se uma pergunta frequente não tiver um código de idioma em seus metadados especificado em um campo de metadados, a pergunta frequente será indexada usando o código de idioma especificado quando você chama a operação CreateFAQ. Para indexar um documento de perguntas frequentes em um idioma compatível no console, acesse Perguntas frequentes e selecione Adicionar perguntas frequentes. Você escolhe um idioma no menu suspenso Idioma.