Gestione delle knowledge base

Una knowledge base rappresenta una raccolta di documenti della conoscenza che fornisci a Dialogflow. I documenti di conoscenza contengono informazioni che potrebbero essere utili durante le conversazioni con gli utenti finali. Alcune funzionalità di Dialogflow utilizzano le knowledge base quando cercano una risposta a un'espressione dell'utente finale. Questa guida descrive come creare e gestire le knowledge base.

Una knowledge base viene applicata a livello di agente.

Prima di iniziare

Prima di leggere questa guida, devi:

  1. Leggi le nozioni di base di Dialogflow.
  2. Esegui i passaggi di configurazione.

Creazione di una knowledge base

Gli esempi riportati di seguito mostrano come utilizzare la console Dialogflow, l'API REST (inclusa la riga di comando) o le librerie client per creare una knowledge base. Per utilizzare l'API, chiama il metodo create sul tipo KnowledgeBase.

UI web

Utilizza la console Dialogflow per creare una knowledge base:

  1. Vai alla console Dialogflow ES
  2. Seleziona un agente
  3. Fai clic su Knowledge nel menu della barra laterale a sinistra.
  4. Fai clic su Crea knowledge base.
  5. Inserisci un nome per la knowledge base
  6. Fai clic su Salva.

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: l'ID del tuo progetto Google Cloud
  • KNOWLEDGE_BASE_DISPLAY_NAME: il nome della knowledge base desiderato

Metodo HTTP e URL: 

POST https://dialogflow.googleapis.com/v2beta1/projects/PROJECT_ID/knowledgeBases

Corpo JSON della richiesta: 

{
  "displayName": "KNOWLEDGE_BASE_DISPLAY_NAME"
}

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

{
  "name": "projects/PROJECT_ID/knowledgeBases/NDA4MTM4NzE2MjMwNDUxMjAwMA",
  "displayName": "KNOWLEDGE_BASE_DISPLAY_NAME"
}

Prendi nota del valore del campo name. Questo è il nome della nuova knowledge base. Il segmento di percorso dopo knowledgeBases è il nuovo ID della knowledge base. Salva questo ID per le richieste riportate di seguito.

Java

Per eseguire l'autenticazione in Dialogflow CX, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 


import com.google.api.gax.rpc.ApiException;
import com.google.cloud.dialogflow.v2.KnowledgeBase;
import com.google.cloud.dialogflow.v2.KnowledgeBasesClient;
import com.google.cloud.dialogflow.v2.LocationName;
import java.io.IOException;

public class KnowledgeBaseManagement {

  public static void main(String[] args) throws ApiException, IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "my-project-id";
    String location = "my-location";

    // Set display name of the new knowledge base
    String knowledgeBaseDisplayName = "my-knowledge-base-display-name";

    // Create a knowledge base
    createKnowledgeBase(projectId, location, knowledgeBaseDisplayName);
  }

  // Create a Knowledge base
  public static void createKnowledgeBase(String projectId, String location, String displayName)
      throws ApiException, IOException {
    // Instantiates a client
    try (KnowledgeBasesClient knowledgeBasesClient = KnowledgeBasesClient.create()) {
      KnowledgeBase targetKnowledgeBase =
          KnowledgeBase.newBuilder().setDisplayName(displayName).build();
      LocationName parent = LocationName.of(projectId, location);
      KnowledgeBase createdKnowledgeBase =
          knowledgeBasesClient.createKnowledgeBase(parent, targetKnowledgeBase);
      System.out.println("====================");
      System.out.format("Knowledgebase created:\n");
      System.out.format("Display Name: %s\n", createdKnowledgeBase.getDisplayName());
      System.out.format("Name: %s\n", createdKnowledgeBase.getName());
    }
  }
}

Node.js

Per eseguire l'autenticazione in Dialogflow CX, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 

// Imports the Dialogflow client library
const dialogflow = require('@google-cloud/dialogflow').v2beta1;

// Instantiate a DialogFlow client.
const client = new dialogflow.KnowledgeBasesClient();

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const projectId = 'ID of GCP project associated with your Dialogflow agent';
// const displayName = `your knowledge base display name, e.g. myKnowledgeBase`;

const formattedParent = 'projects/' + projectId;
const knowledgeBase = {
  displayName: displayName,
};
const request = {
  parent: formattedParent,
  knowledgeBase: knowledgeBase,
};

const [result] = await client.createKnowledgeBase(request);
console.log(`Name: ${result.name}`);
console.log(`displayName: ${result.displayName}`);

Python

Per eseguire l'autenticazione in Dialogflow CX, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 

def create_knowledge_base(project_id, display_name):
    """Creates a Knowledge base.

    Args:
        project_id: The GCP project linked with the agent.
        display_name: The display name of the Knowledge base."""
    from google.cloud import dialogflow_v2beta1 as dialogflow

    client = dialogflow.KnowledgeBasesClient()
    project_path = client.common_project_path(project_id)

    knowledge_base = dialogflow.KnowledgeBase(display_name=display_name)

    response = client.create_knowledge_base(
        parent=project_path, knowledge_base=knowledge_base
    )

    print("Knowledge Base created:\n")
    print("Display Name: {}\n".format(response.display_name))
    print("Name: {}\n".format(response.name))

Aggiungi un documento alla knowledge base

Al momento la nuova knowledge base non contiene documenti, quindi devi aggiungerne uno. Consulta la sezione Contenuti supportati di seguito per una descrizione di tutte le opzioni di contenuti supportate. Per questo esempio, puoi utilizzare il documento Domande frequenti su Cloud Storage.

Gli esempi riportati di seguito mostrano come utilizzare la console Dialogflow, l'API REST (inclusa la riga di comando) o le librerie client per creare un documento di conoscenza. Per utilizzare l'API, chiama il metodo create sul tipo Document.

UI web

Utilizza la console Dialogflow per creare un documento di conoscenza:

  1. Se non stai continuando dai passaggi precedenti, vai alle impostazioni della knowledge base:
    1. Vai alla console Dialogflow ES
    2. Seleziona un agente
    3. Fai clic su Knowledge nel menu della barra laterale a sinistra.
    4. Fai clic sul nome della knowledge base
  2. Fai clic su Nuovo documento o Crea il primo.
  3. Inserisci un nome del documento
  4. Seleziona text/html per Mime Type (Tipo MIME).
  5. Seleziona FAQ per Knowledge Type (Tipo di conoscenza).
  6. Seleziona URL per Origine dati.
  7. Inserisci https://cloud.google.com/storage/docs/faq nel campo URL.
  8. Fai clic su CREA.

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: l'ID del tuo progetto Google Cloud
  • KNOWLEDGE_BASE_ID: l'ID della knowledge base restituito dalla richiesta precedente
  • DOCUMENT_DISPLAY_NAME: il nome del documento di conoscenza desiderato

Metodo HTTP e URL: 

POST https://dialogflow.googleapis.com/v2beta1/projects/PROJECT_ID/knowledgeBases/KNOWLEDGE_BASE_ID/documents

Corpo JSON della richiesta: 

{
  "displayName": "DOCUMENT_DISPLAY_NAME",
  "mimeType": "text/html",
  "knowledgeTypes": "FAQ",
  "contentUri": "https://cloud.google.com/storage/docs/faq"
}

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

{
  "name": "projects/PROJECT_ID/operations/ks-add_document-MzA5NTY2MTc5Mzg2Mzc5NDY4OA"
}

Il segmento di percorso dopo operations è l'ID operazione.

Java

Per eseguire l'autenticazione in Dialogflow CX, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 


import com.google.api.gax.longrunning.OperationFuture;
import com.google.api.gax.rpc.ApiException;
import com.google.cloud.dialogflow.v2.CreateDocumentRequest;
import com.google.cloud.dialogflow.v2.Document;
import com.google.cloud.dialogflow.v2.Document.KnowledgeType;
import com.google.cloud.dialogflow.v2.DocumentsClient;
import com.google.cloud.dialogflow.v2.KnowledgeOperationMetadata;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class DocumentManagement {

  public static void createDocument(
      String knowledgeBaseName,
      String displayName,
      String mimeType,
      String knowledgeType,
      String contentUri)
      throws IOException, ApiException, InterruptedException, ExecutionException, TimeoutException {
    // Instantiates a client
    try (DocumentsClient documentsClient = DocumentsClient.create()) {
      Document document =
          Document.newBuilder()
              .setDisplayName(displayName)
              .setContentUri(contentUri)
              .setMimeType(mimeType)
              .addKnowledgeTypes(KnowledgeType.valueOf(knowledgeType))
              .build();
      CreateDocumentRequest createDocumentRequest =
          CreateDocumentRequest.newBuilder()
              .setDocument(document)
              .setParent(knowledgeBaseName)
              .build();
      OperationFuture<Document, KnowledgeOperationMetadata> response =
          documentsClient.createDocumentAsync(createDocumentRequest);
      Document createdDocument = response.get(300, TimeUnit.SECONDS);
      System.out.format("Created Document:\n");
      System.out.format(" - Display Name: %s\n", createdDocument.getDisplayName());
      System.out.format(" - Document Name: %s\n", createdDocument.getName());
      System.out.format(" - MIME Type: %s\n", createdDocument.getMimeType());
      System.out.format(" - Knowledge Types:\n");
      for (KnowledgeType knowledgeTypeId : document.getKnowledgeTypesList()) {
        System.out.format("  - %s \n", knowledgeTypeId.getValueDescriptor());
      }
      System.out.format(" - Source: %s \n", document.getContentUri());
    }
  }
}

Node.js

Per eseguire l'autenticazione in Dialogflow CX, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 

//   // Imports the Dialogflow client library
//   const dialogflow = require('@google-cloud/dialogflow').v2beta1;

//   // Instantiate a DialogFlow Documents client.
//   const client = new dialogflow.DocumentsClient({
//     projectId: projectId,
//   });

//   /**
//    * TODO(developer): Uncomment the following lines before running the sample.
//    */
//   // const projectId = 'ID of GCP project associated with your Dialogflow agent';
//   // const knowledgeBaseFullName = `the full path of your knowledge base, e.g my-Gcloud-project/myKnowledgeBase`;
//   // const documentPath = `path of the document you'd like to add, e.g. https://dialogflow.com/docs/knowledge-connectors`;
//   // const documentName = `displayed name of your document in knowledge base, e.g. myDoc`;
//   // const knowledgeTypes = `The Knowledge type of the Document. e.g. FAQ`;
//   // const mimeType = `The mime_type of the Document. e.g. text/csv, text/html,text/plain, text/pdf etc.`;

//   const request = {
//     parent: knowledgeBaseFullName,
//     document: {
//       knowledgeTypes: [knowledgeTypes],
//       displayName: documentName,
//       contentUri: documentPath,
//       source: 'contentUri',
//       mimeType: mimeType,
//     },
//   };

//   const [operation] = await client.createDocument(request);
//   const [response] = await operation.promise();

//   console.log('Document created');
//   console.log(`Content URI...${response.contentUri}`);
//   console.log(`displayName...${response.displayName}`);
//   console.log(`mimeType...${response.mimeType}`);
//   console.log(`name...${response.name}`);
//   console.log(`source...${response.source}`);

Python

Per eseguire l'autenticazione in Dialogflow CX, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 

def create_document(
    project_id, knowledge_base_id, display_name, mime_type, knowledge_type, content_uri
):
    """Creates a Document.

    Args:
        project_id: The GCP project linked with the agent.
        knowledge_base_id: Id of the Knowledge base.
        display_name: The display name of the Document.
        mime_type: The mime_type of the Document. e.g. text/csv, text/html,
            text/plain, text/pdf etc.
        knowledge_type: The Knowledge type of the Document. e.g. FAQ,
            EXTRACTIVE_QA.
        content_uri: Uri of the document, e.g. gs://path/mydoc.csv,
            http://mypage.com/faq.html."""
    from google.cloud import dialogflow_v2beta1 as dialogflow

    client = dialogflow.DocumentsClient()
    knowledge_base_path = dialogflow.KnowledgeBasesClient.knowledge_base_path(
        project_id, knowledge_base_id
    )

    document = dialogflow.Document(
        display_name=display_name, mime_type=mime_type, content_uri=content_uri
    )

    document.knowledge_types.append(
        getattr(dialogflow.Document.KnowledgeType, knowledge_type)
    )

    response = client.create_document(parent=knowledge_base_path, document=document)
    print("Waiting for results...")
    document = response.result(timeout=120)
    print("Created Document:")
    print(" - Display Name: {}".format(document.display_name))
    print(" - Knowledge ID: {}".format(document.name))
    print(" - MIME Type: {}".format(document.mime_type))
    print(" - Knowledge Types:")
    for knowledge_type in document.knowledge_types:
        print("    - {}".format(KNOWLEDGE_TYPES[knowledge_type]))
    print(" - Source: {}\n".format(document.content_uri))

La creazione di un documento è un'operazione a lunga esecuzione, quindi potrebbe essere necessario un periodo di tempo considerevole per completarla. Puoi eseguire il polling dello stato di questa operazione per vedere se è stata completata. Al termine, l'operazione contiene l'ID del documento appena creato. Salva questo ID per l'elaborazione futura. Per saperne di più, consulta Operazioni a lunga esecuzione.

Gestisci i documenti della knowledge base

Aggiorna i contenuti del documento della knowledge base

Se aggiorni i contenuti a cui fa riferimento un documento di conoscenza, quest'ultimo potrebbe non aggiornarsi automaticamente. I contenuti vengono aggiornati automaticamente solo se vengono forniti come URL pubblico e se hai selezionato l'opzione Attiva ricaricamento automatico per il documento.

Per aggiornare manualmente i contenuti dei documenti di Cloud Storage o degli URL pubblici, chiama il metodo reload sul tipo Document.

Per aggiornare manualmente i contenuti non elaborati caricati, utilizza i metodi delete e create sul tipo Document per ricreare il documento.

Elenca i documenti della Knowledge Base

Puoi elencare tutti i documenti della knowledge base. Per utilizzare l'API, chiama il metodo list sul tipo Document.

Elimina i documenti della Knowledge Base

Puoi eliminare i documenti della knowledge base. Per utilizzare l'API, chiama il metodo delete sul tipo Document. Se non hai l'ID documento, puoi elencare i documenti come descritto sopra.

Contenuti supportati

Sono supportati i seguenti tipi di documenti di conoscenza:

  • FAQ: il contenuto del documento contiene coppie di domande e risposte in formato HTML o CSV. I formati HTML tipici delle domande frequenti vengono analizzati con precisione, ma i formati insoliti potrebbero non essere analizzati. Il file CSV deve includere le domande nella prima colonna e le risposte nella seconda, senza intestazione. Grazie a questo formato esplicito, vengono sempre analizzati con precisione.
  • QA estrattiva: documenti da cui viene estratto il testo non strutturato e utilizzato per rispondere alle domande.

La tabella seguente mostra i tipi MIME supportati per Tipo di conoscenza e Origine.

Tipo di conoscenza \ Origine File caricato (Document.content) (NON consigliato) File caricato (Document.raw_content) (consigliato) File da Cloud Storage (Document.contentUri) File da URL pubblico (Document.contentUri)
Domande frequenti text/csv text/csv text/csv text/html
QA estrattiva text/plain, text/html text/plain, text/html, application/pdf text/plain, text/html, application/pdf N/D

I contenuti dei documenti presentano i seguenti problemi noti, limitazioni e best practice:

Informazioni generali:

  • I file provenienti da URL pubblici devono essere stati sottoposti a scansione dall'indicizzatore della Ricerca Google, in modo che esistano nell'indice della Ricerca. Puoi verificarlo con Google Search Console. Tieni presente che l'indicizzatore non mantiene aggiornati i tuoi contenuti. Devi aggiornare esplicitamente il documento di conoscenza quando i contenuti di origine cambiano.
  • I file CSV devono utilizzare le virgole come delimitatori.
  • I punteggi di affidabilità non sono ancora calibrati tra le domande frequenti e gli articoli della Knowledge Base, quindi se utilizzi entrambi, il risultato migliore potrebbe non essere sempre quello più alto.
  • Dialogflow rimuove i tag HTML dai contenuti durante la creazione delle risposte. Per questo motivo, è meglio evitare i tag HTML e utilizzare il testo normale, se possibile.
  • Le risposte dell'Assistente Google hanno un limite di 640 caratteri per fumetto della chat, pertanto le risposte lunghe vengono troncate durante l'integrazione con l'Assistente Google.
  • La dimensione massima del documento è di 50 MB.
  • Quando utilizzi i file di Cloud Storage, devi utilizzare URI pubblici o URI privati a cui il tuo account utente o account di servizio ha accesso.

Specifiche per le domande frequenti:

  • Il file CSV deve includere le domande nella prima colonna e le risposte nella seconda, senza intestazione.
  • Se possibile, utilizza il formato CSV, perché viene analizzato con maggiore precisione.
  • I contenuti HTML pubblici con una singola coppia di domande e risposte non sono supportati.
  • Il numero di coppie di domande e risposte in un documento non deve superare 2000.
  • Le domande duplicate con risposte diverse non sono supportate.
  • Puoi utilizzare qualsiasi documento di domande frequenti; il parser delle domande frequenti è in grado di gestire la maggior parte dei formati di domande frequenti.

Specifico per QA estrattiva:

  • La funzionalità di domande e risposte estrattive è attualmente sperimentale. Si basa su tecnologie simili che sono state provate e testate da Google in prodotti come la Ricerca e l'assistente. Inviaci il tuo feedback sul funzionamento di questa funzionalità per Dialogflow.
  • I contenuti con testo fitto funzionano meglio. Evita contenuti con molti paragrafi di una sola frase.
  • Tabelle ed elenchi non sono supportati.
  • Il numero di paragrafi in un documento non deve superare i 2000.
  • Se un articolo è lungo (> 1000 parole), prova a suddividerlo in più articoli più piccoli. Se l'articolo tratta più problemi, può essere suddiviso in articoli più brevi che trattano i singoli problemi. Se l'articolo riguarda un solo problema, concentrati sulla descrizione del problema e mantieni breve la risoluzione.
  • Idealmente, dovrebbero essere forniti solo i contenuti principali di un articolo (descrizione e risoluzione del problema). I contenuti aggiuntivi come il nome dell'autore, la cronologia delle modifiche, i link correlati e gli annunci non sono importanti.
  • Prova a includere una descrizione dei problemi che un articolo può aiutare a risolvere e/o query di esempio a cui questo articolo può rispondere.

Utilizzo di Cloud Storage

Se i tuoi contenuti non sono pubblici, l'opzione consigliata è archiviarli in Cloud Storage. Quando crei documenti della Knowledge Base, fornisci gli URL degli oggetti Cloud Storage.

Creazione di bucket Cloud Storage e oggetti

Quando crei il bucket Cloud Storage:

  • Assicurati di aver selezionato il progetto GCP che utilizzi per Dialogflow.
  • Assicurati che l'account utente o il account di servizio che utilizzi normalmente per accedere all'API Dialogflow disponga delle autorizzazioni in lettura per gli oggetti del bucket.
  • Utilizza la classe Standard Storage.
  • Imposta la località del bucket sulla località più vicina alla tua. Per alcune chiamate API, avrai bisogno dell'ID località (ad esempio, us-west1), quindi prendi nota della tua scelta.

Segui le istruzioni della guida rapida di Cloud Storage per creare un bucket e caricare i file.

Fornitura di un oggetto Cloud Storage a un documento della knowledge base

Per fornire i tuoi contenuti:

  • Crea una knowledge base come descritto sopra.
  • Crea un documento di conoscenza come descritto sopra. Quando chiami il metodo create sul tipo Document, imposta il campo contentUri sull'URL del documento Cloud Storage. Il formato di questo URL è gs://bucket-name/object-name.
Indietro
Gestione degli intenti con l'API
Avanti
Aggiornamento dei dati con una FieldMask