Gestione delle knowledge base

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Una knowledge base rappresenta una raccolta di documenti di conoscenza che fornisci a Dialogflow. I documenti di conoscenza contengono informazioni che possono essere utili durante le conversazioni con gli utenti finali. Alcune funzionalità di Dialogflow utilizzano le knowledge base quando si cerca 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:

  1. Leggi l'articolo Nozioni di base su Dialogflow.
  2. Esegui i passaggi di configurazione.

Creazione di una knowledge base

Gli esempi riportati di seguito mostrano come utilizzare la console di 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 nel tipo KnowledgeBase.

UI web

Utilizza la console di Dialogflow per creare una knowledge base:

  1. Vai alla console di Dialogflow ES
  2. Select an agent
  3. Fai clic su Conoscenza nel menu della barra laterale sinistra
  4. Fai clic su Crea knowledge base
  5. Inserisci un nome Knowledge Base
  6. Fai clic su Salva

REST

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

  • PROJECT_ID: il tuo ID progetto GCP
  • KNOWLEDGE_BASE_DISPLAY_NAME: nome della knowledge base desiderato

Metodo HTTP e URL:

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

Corpo JSON richiesta:

{
  "displayName": "KNOWLEDGE_BASE_DISPLAY_NAME"
}

Per inviare la richiesta, espandi una delle seguenti 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 del percorso dopo knowledgeBases è il tuo nuovo ID della base di conoscenze. Salva questo ID per le richieste riportate di seguito.

Java


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

// 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

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))

Aggiungere un documento alla knowledge base

Al momento, la tua nuova knowledge base non ha documenti, quindi devi aggiungere un documento. Visita la pagina Contenuti supportati di seguito per una descrizione di tutti i contenuti supportati. Per questo esempio, puoi utilizzare il documento delle Domande frequenti su Cloud Storage.

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

UI web

Utilizza la console di Dialogflow per creare un documento di conoscenze:

  1. Se non stai continuando con i passaggi precedenti, vai alle impostazioni della scheda informativa:
    1. Vai alla console di Dialogflow ES
    2. Select an agent
    3. Fai clic su Conoscenza nel menu della barra laterale sinistra
    4. Fai clic sul nome della knowledge base
  2. Fai clic su Nuovo documento o Crea il primo documento.
  3. Inserisci un nome per il documento
  4. Seleziona text/html per Tipo MIME.
  5. Seleziona Domande frequenti per 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, effettua le seguenti sostituzioni:

  • PROJECT_ID: il tuo ID progetto GCP
  • KNOWLEDGE_BASE_ID: il tuo ID knowledge base restituito dalla richiesta precedente
  • DOCUMENT_DISPLAY_NAME: nome del documento di conoscenze desiderato

Metodo HTTP e URL:

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

Corpo JSON richiesta:

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

Per inviare la richiesta, espandi una delle seguenti opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

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

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

Java


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(180, 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

//   // 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

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, pertanto il suo completamento potrebbe richiedere molto tempo. Puoi inviare un sondaggio sullo stato di questa operazione per vedere se è stata completata. Una volta completata, l'operazione contiene l'ID documento appena creato. Salva questo ID per l'elaborazione futura. Per ulteriori informazioni, consulta la pagina Operazioni a lunga esecuzione.

Gestire i documenti informativi

Aggiornare i contenuti di un documento di conoscenza

Se aggiorni i contenuti a cui viene fatto riferimento in un documento di conoscenza, il documento potrebbe non essere aggiornato automaticamente. I contenuti vengono aggiornati automaticamente solo se sono forniti come URL pubblici e hai selezionato l'opzione Attiva ricarica automatica per il documento.

Per aggiornare manualmente Cloud Storage o i contenuti del documento dell'URL pubblico, chiama il metodo reload nel tipo Document.

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

Elenco documenti di conoscenze

Puoi elencare tutti i documenti relativi alla tua base di conoscenze. Per utilizzare l'API, chiama il metodo list nel tipo Document.

Eliminare i documenti informativi

Puoi eliminare i documenti relativi alla tua base di conoscenze. Per utilizzare l'API, chiama il metodo delete nel tipo Document. Se non hai l'ID, puoi elencare i documenti come descritto sopra.

Contenuti supportati

Sono supportati i seguenti tipi di documenti di conoscenze:

  • Domande frequenti: i contenuti del documento contengono 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 contenere domande nella prima colonna e risposte nella seconda, senza intestazione. A causa di questo formato esplicito, vengono sempre analizzati in modo accurato.
  • QA estratto: documenti per i quali viene estratto testo non strutturato e utilizzati per la risposta alle domande.

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

Conoscenza Tipo \ 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 testo/csv testo/csv testo/csv testo/html
QA estratto testo/normale, testo/html text/plain, text/html, application/pdf text/plain, text/html, application/pdf N/D

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

Informazioni generali

  • I file provenienti dagli URL pubblici devono essere stati sottoposti a scansione dall'indice di ricerca di Google, in modo che esistano nell'indice di ricerca. Puoi verificarlo con Google Search Console. Tieni presente che l'indicizzazione non mantiene i tuoi contenuti aggiornati. Devi aggiornare esplicitamente il documento di conoscenze 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 sia domande frequenti che articoli della knowledge base, il risultato migliore potrebbe non essere sempre il più alto.
  • Dialogflow rimuove i tag HTML dai contenuti durante la creazione delle risposte. Per questo motivo, è meglio evitare i tag HTML e usare testo normale, quando possibile.
  • Le risposte dell'Assistente Google hanno un limite di 640 caratteri per fumetto della chat, pertanto le risposte lunghe vengono troncate quando si esegue l'integrazione con l'Assistente Google.
  • La dimensione massima del documento è 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.

Specifico alle domande frequenti:

  • Il file CSV deve contenere domande nella prima colonna e risposte nella seconda, senza intestazione.
  • Se possibile, utilizza il file CSV perché il file CSV viene analizzato con la massima precisione.
  • I contenuti HTML pubblici con una singola coppia di QA non sono supportati.
  • Il numero di coppie di QA in un documento non deve superare 2000.
  • Non sono supportate domande duplicate con risposte diverse.
  • Puoi utilizzare qualsiasi documento relativo alle domande frequenti. L'analizzatore sintattico di Domande frequenti è in grado di gestire la maggior parte dei formati di domande frequenti.

Note specifiche per il QA estrattivo:

  • Il QA estrattivo è attualmente in fase sperimentale. Si basa su tecnologie simili che sono state comprovate e testate da Google in prodotti come la Ricerca e l'assistente. Inviaci il tuo feedback su come funziona per Dialogflow.
  • I contenuti con testo ad alta densità funzionano meglio. Evita contenuti con molti paragrafi composti da una sola frase.
  • Tabelle ed elenchi non sono supportati.
  • Il numero di paragrafi in un documento non deve superare 2000.
  • Se un articolo è lungo (più di 1000 parole), prova a suddividerlo in più articoli di dimensioni inferiori. Se l'articolo riguarda 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 mantienilo breve.
  • Idealmente, è necessario fornire solo i contenuti principali di un articolo (descrizione e risoluzione del problema). I contenuti aggiuntivi come nome dell'autore, cronologia delle modifiche, link correlati e annunci non sono importanti.
  • Prova a includere una descrizione per i problemi di un articolo o per le query di esempio a cui può rispondere questo articolo.

Utilizzo di Cloud Storage

Se i tuoi contenuti non sono pubblici, ti consigliamo di archiviarli in Cloud Storage. Quando crei documenti della conoscenza, devi fornire gli URL per gli oggetti di Cloud Storage.

Creazione di bucket e oggetti Cloud Storage

Durante la creazione del bucket Cloud Storage:

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

Fornire un oggetto Cloud Storage a un documento di base

Per fornire i tuoi contenuti:

  • Crea una knowledge base come descritto in precedenza.
  • Crea un documento di conoscenze come descritto in precedenza. 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.