Aggiungere domande frequenti (FAQs) a un indice

Puoi aggiungere le domande frequenti (FAQs) direttamente al tuo indice utilizzando la console o l'CreateFaqAPI. L'aggiunta FAQs a un indice è un'operazione asincrona. I dati per le domande frequenti vengono inseriti in un file archiviato in un bucket. Amazon Simple Storage Service Puoi usare file CSV o JSON come input per le tue FAQ:

Ad esempio, quello che segue è un file CSV di base che fornisce risposte a domande sulle cliniche gratuite a Spokane, Washington USA e Mountain View, Missouri, USA.

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

Creazione di campi indice per un file di domande frequenti

Quando utilizzi un file CSV o JSON personalizzato per l'input, puoi dichiarare campi personalizzati per le tue domande frequenti. Ad esempio, puoi creare un campo personalizzato che assegna a ogni domanda FAQ un reparto aziendale. Quando le domande frequenti vengono restituite in una risposta, puoi utilizzare il reparto come sfaccettatura per restringere la ricerca solo a «Risorse Umane» o «Finanze», ad esempio.

Un campo personalizzato deve essere mappato a un campo indice. Nella console, si utilizza la pagina di definizione di Facet per creare un campo indice. Quando si utilizza l'API, è necessario innanzitutto creare un campo indice utilizzando l'UpdateIndexAPI.

Il tipo di campo/attributo nel file FAQ deve corrispondere al tipo del campo indice associato. Ad esempio, il campo «Dipartimento» è un campo STRING_LIST di tipo. Pertanto, è necessario fornire i valori per il campo department come elenco di stringhe nel file delle domande frequenti. Puoi controllare il tipo di campi indice utilizzando la pagina di definizione di Facet nella console o utilizzando l'DescribeIndexAPI.

Quando crei un campo indice mappato a un attributo personalizzato, puoi contrassegnarlo come visualizzabile, sfaccettato o ordinabile. Non puoi rendere ricercabile un attributo personalizzato.

Oltre agli attributi personalizzati, puoi anche utilizzare i campi Amazon Kendra riservati o comuni in un file CSV o JSON personalizzato. Per ulteriori informazioni, consulta Attributi o campi del documento.

File CSV di base

Usa un file CSV di base quando desideri utilizzare una struttura semplice per il tuo. FAQs In un file CSV di base, ogni riga contiene due o tre campi: una domanda, una risposta e un URI di origine opzionale che rimanda a un documento con ulteriori informazioni.

Il contenuto del file deve essere conforme al formato comune RFC 4180 e al tipo MIME per i file CSV (Comma-Separated Values).

Di seguito è riportato un file di domande frequenti nel formato CSV di base.

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

File CSV personalizzato

Utilizza un file CSV personalizzato per aggiungere campi/attributi personalizzati alle domande frequenti. Per un file CSV personalizzato, usi una riga di intestazione nel file CSV per definire gli attributi aggiuntivi.

Il file CSV deve contenere i seguenti due campi obbligatori:

Il file CSV personalizzato può contenere sia campi Amazon Kendra riservati (tranne_faq_id, _data_source_id_document_title, e_file_type) sia qualsiasi campo personalizzato.

Di seguito è riportato un esempio di file CSV personalizzato.

_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

Il contenuto del file personalizzato deve essere conforme al formato comune RFC 4180 e al tipo MIME per i file CSV (Comma-Separated Values).

Di seguito sono elencati i tipi di campi personalizzati:

Un file CSV personalizzato può contenere campi di controllo dell'accesso degli utenti. Puoi utilizzare questi campi per limitare l'accesso alle domande frequenti a determinati utenti e gruppi. Per filtrare in base al contesto dell'utente, l'utente deve fornire informazioni sull'utente e sul gruppo nella query. In caso contrario, FAQs vengono restituiti tutti i dati pertinenti. Per ulteriori informazioni, consulta Filtraggio del contesto utente.

Di seguito sono elencati i filtri del contesto utente per FAQs:

Fornisci i valori per gli elenchi di autorizzazione e rifiuto in elenchi separati da virgole racchiusi tra virgolette (ad esempio,). "user1,user2,user3" È possibile includere un utente o un gruppo in un elenco di utenti consentiti o in un elenco di utenti non autorizzati, ma non entrambi quando lo stesso utente è autorizzato individualmente ma anche in un gruppo negato. Se includi un utente o un gruppo in entrambi, riceverai un errore.

Di seguito è riportato un esempio di file CSV personalizzato con informazioni sul contesto dell'utente.

_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

File JSON

Puoi utilizzare un file JSON per fornire domande, risposte e campi per il tuo indice. Puoi aggiungere qualsiasi campo Amazon Kendra riservato o campo personalizzato alle domande frequenti.

Di seguito è riportato lo schema per il file 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
    ]
}

Il seguente file JSON di esempio mostra due documenti di domande frequenti. Uno dei documenti contiene solo la domanda e la risposta richieste. L'altro documento include anche informazioni aggiuntive sul campo e sul contesto utente o sul controllo degli accessi.

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

Di seguito sono elencati i tipi di campi personalizzati:

Un file JSON può contenere campi di controllo dell'accesso degli utenti. Puoi utilizzare questi campi per limitare l'accesso alle domande frequenti a determinati utenti e gruppi. Per filtrare in base al contesto dell'utente, l'utente deve fornire informazioni sull'utente e sul gruppo nella query. In caso contrario, FAQs vengono restituiti tutti i dati pertinenti. Per ulteriori informazioni, consulta Filtraggio del contesto utente.

È possibile includere un utente o un gruppo in un elenco consentito o in un elenco negato, ma non entrambi se lo stesso utente è autorizzato individualmente, ma anche se lo stesso utente è negato al gruppo. Se includi un utente o un gruppo in entrambi, riceverai un errore.

Di seguito è riportato un esempio di inclusione del controllo dell'accesso degli utenti in una domanda frequente su JSON.

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

Utilizzo del file delle domande frequenti

Dopo aver archiviato il file di input delle FAQ in un bucket S3, usi la console o l'CreateFaqAPI per inserire le domande e le risposte nel tuo indice. Se desideri aggiornare una FAQ, elimina la FAQ e creala di nuovo. Utilizzi l'DeleteFaqAPI per eliminare una FAQ.

Devi fornire un IAM ruolo che abbia accesso al bucket S3 che contiene i tuoi file sorgente. Specificate il ruolo nella console o nel RoleArn parametro. Di seguito è riportato un esempio di aggiunta di un file di domande frequenti a un indice.

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)

File di domande frequenti in lingue diverse dall'inglese

Puoi indicizzare una FAQ in una lingua supportata. Amazon Kendra gli indici sono FAQs in inglese per impostazione predefinita se non si specifica una lingua. È possibile specificare il codice della lingua quando si richiama l'CreateFaqoperazione oppure è possibile includere il codice della lingua per una FAQ nei metadati delle domande frequenti come campo. Se una FAQ non ha un codice di lingua nei metadati specificati in un campo di metadati, le domande frequenti vengono indicizzate utilizzando il codice della lingua specificato al momento della chiamata dell'operazione. CreateFAQ Per indicizzare un documento di domande frequenti in una lingua supportata nella console, vai a FAQse seleziona Aggiungi domande frequenti. Scegli una lingua dal menu a discesa Lingua.