Cette page a été traduite par l'API Cloud Translation.

Gérer les bases de connaissances

Une base de connaissances représente une collection de documents de base de connaissances que vous fournissez à Dialogflow. Vos documents de base de connaissances contiennent des informations qui peuvent être utiles lors des conversations avec les utilisateurs finaux. Certaines fonctionnalités de Dialogflow utilisent des bases de connaissances lors de la recherche d'une réponse à une expression d'utilisateur final. Ce guide explique comment créer et gérer des bases de connaissances.

Une base de connaissances est appliquée au niveau de l'agent.

Avant de commencer

Avant de lire ce guide, procédez comme suit :

Consultez la section Principes de base de Dialogflow.
Effectuez la procédure de configuration.

Créer une base de connaissances

Les exemples ci-dessous vous montrent comment créer une base de connaissances avec la console Dialogflow, l'API REST (y compris la ligne de commande) ou les bibliothèques clientes. Pour utiliser l'API, appelez la méthode create sur le type KnowledgeBase.

UI Web

Utilisez la console Dialogflow pour créer une base de connaissances :

Accédez à la console Dialogflow ES.
Sélectionnez un agent.
Cliquez sur Connaissances dans le menu de la barre latérale gauche.
Cliquez sur Créer une base de connaissances.
Saisissez un nom de base de connaissances.
Cliquez sur Enregistrer.

REST

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

PROJECT_ID : ID de votre projet GCP
KNOWLEDGE_BASE_DISPLAY_NAME : nom de base de connaissances souhaité

Méthode HTTP et URL :

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

Corps JSON de la requête :

{
  "displayName": "KNOWLEDGE_BASE_DISPLAY_NAME"
}

Pour envoyer votre requête, développez l'une des options suivantes :

curl (Linux, macOS ou Cloud Shell)

Remarque : La commande suivante suppose que vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login, ou en utilisant Cloud Shell, qui vous connecte automatiquement à la CLI gcloud. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: PROJECT_ID" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://dialogflow.googleapis.com/v2beta1/projects/PROJECT_ID/knowledgeBases"

PowerShell (Windows)

Remarque : La commande suivante suppose que vous vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://dialogflow.googleapis.com/v2beta1/projects/PROJECT_ID/knowledgeBases" | Select-Object -Expand Content

Vous devriez recevoir une réponse JSON de ce type :

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

Notez la valeur du champ name. C'est le nom de votre nouvelle base de connaissances. Le segment de chemin d'accès indiqué après knowledgeBases correspond au nouvel ID de votre base de connaissances. Enregistrez cet ID pour les requêtes suivantes.

Java

Pour vous authentifier auprès de Dialogflow, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.


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

Ajouter un document à la base de connaissances

Votre nouvelle base de connaissances ne contient actuellement aucun document. Vous devez donc en ajouter un. Consultez la section Contenus pris en charge ci-dessous pour obtenir une description de toutes les options de contenu disponibles. Vous pouvez utiliser le document Questions fréquentes sur Cloud Storage pour cet exemple.

Les exemples ci-dessous vous montrent comment créer un document de base de connaissances avec la console Dialogflow, l'API REST (y compris la ligne de commande) ou les bibliothèques clientes. Pour utiliser l'API, appelez la méthode create sur le type Document.

UI Web

Utilisez la console Dialogflow pour créer un document de base de connaissances :

Si vous ne suivez pas les étapes ci-dessus, accédez aux paramètres de votre base de connaissances :
1. Accédez à la console Dialogflow ES.
2. Sélectionnez un agent.
3. Cliquez sur Connaissances dans le menu de la barre latérale gauche.
4. Cliquez sur le nom de votre base de connaissances.
Cliquez sur Nouveau document ou sur Créer un premier document.
Saisissez un nom de document.
Sélectionnez text/html pour le type MIME.
Sélectionnez Questions fréquentes dans le champ Type de connaissance.
Sélectionnez URL comme Source de données.
Saisissez https://cloud.google.com/storage/docs/faq dans le champ URL.
Cliquez sur CRÉER.

REST

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

PROJECT_ID : ID de votre projet GCP
KNOWLEDGE_BASE_ID : ID de votre base de connaissances, renvoyé par une requête précédente
DOCUMENT_DISPLAY_NAME : nom de document de base de connaissances souhaité

Méthode HTTP et URL :

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

Corps JSON de la requête :

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

Pour envoyer votre requête, développez l'une des options suivantes :

curl (Linux, macOS ou Cloud Shell)

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: PROJECT_ID" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://dialogflow.googleapis.com/v2beta1/projects/PROJECT_ID/knowledgeBases/KNOWLEDGE_BASE_ID/documents"

PowerShell (Windows)

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://dialogflow.googleapis.com/v2beta1/projects/PROJECT_ID/knowledgeBases/KNOWLEDGE_BASE_ID/documents" | Select-Object -Expand Content

Vous devriez recevoir une réponse JSON de ce type :

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

Le segment de chemin d'accès indiqué après operations correspond à l'ID de votre opération.

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

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

Créer un document est une opération longue, qui peut prendre un temps considérable. Vous pouvez interroger l'état de cette opération pour voir si elle est terminée. Une fois terminée, l'opération contient l'ID du document que vous venez de créer. Enregistrez cet ID pour un traitement ultérieur. Pour en savoir plus, consultez la page Opérations de longue durée.

Gérer les documents de base de connaissances

Mettre à jour le contenu d'un document de base de connaissances

Si vous mettez à jour le contenu référencé par un document de base de connaissances, celui-ci pourrait ne pas s'actualiser automatiquement. Votre contenu n'est actualisé automatiquement que s'il est fourni en tant qu'URL publique et que vous avez coché l'option Activer l'actualisation automatique pour le document.

Pour actualiser manuellement le contenu d'un document d'URL publique ou Cloud Storage, appelez la méthode reload sur le type Document.

Pour actualiser manuellement le contenu brut importé, utilisez les méthodes delete et create sur le type Document pour recréer votre document.

Répertorier les documents de base de connaissances

Vous pouvez répertorier tous les documents de votre base de connaissances. Pour utiliser l'API, appelez la méthode list sur le type Document.

Supprimer des documents de base de connaissances

Vous pouvez supprimer des documents de votre base de connaissances. Pour utiliser l'API, appelez la méthode delete sur le type Document. Si vous ne disposez pas des ID des documents, vous pouvez répertorier les documents comme décrit ci-dessus.

Contenus pris en charge

Les types de documents de base de connaissances suivants sont pris en charge :

Questions fréquentes : le document contient des paires de questions et de réponses au format HTML ou CSV. Les formats de questions fréquentes HTML standards sont analysés avec précision, mais l'analyse de formats inhabituels peut échouer. Dans les fichiers CSV, les questions doivent se trouver dans la première colonne et les réponses dans la seconde, sans en-tête. En raison de ce format explicite, ces fichiers sont toujours analysés avec précision.
Questions-réponses extractives : documents pour lesquels un texte non structuré est extrait et utilisé pour répondre aux questions.

Le tableau suivant présente les types MIME pris en charge par type de connaissance et source.

Type/source de la base de connaissances	Fichier importé (Document.content, NON recommandé)	Fichier importé (Document.raw_content, recommandé)	Fichier de Cloud Storage (Document.contentUri)	Fichier d'URL publique (Document.contentUri)
Questions fréquentes	texte/csv	texte/csv	texte/csv	texte/html
Questions-réponses extractives	texte/brut, texte/html	texte/brut, texte/html, application/pdf	texte/brut, texte/html, application/pdf	ND

Voici les problèmes connus, les limitations et les bonnes pratiques pour le contenu des documents :

Paramètres généraux :

Les fichiers provenant d'URL publiques doivent avoir été explorés par le plug-in d'indexation de recherche Google, de sorte qu'ils existent dans l'index de recherche. Vous pouvez vérifier cela à l'aide de la Google Search Console. Notez que le plug-in d'indexation ne maintient pas votre contenu à jour. Vous devez explicitement mettre à jour votre document de base de connaissances lorsque le contenu source est modifié.
Les fichiers CSV doivent utiliser des virgules comme délimiteurs.
Les scores de confiance ne sont pas encore calibrés entre les questions fréquentes et les articles de la base de connaissances. Par conséquent, si vous utilisez à la fois les questions fréquentes et les articles de la base de connaissances, le meilleur résultat ne sera pas toujours celui dont le score est le plus élevé.
Dialogflow supprime les balises HTML du contenu lors de la création des réponses. Il est donc préférable d'éviter les balises HTML et d'utiliser du texte brut lorsque cela est possible.
Les réponses de l'Assistant Google ont une limite de 640 caractères par bulle de conversation. Les réponses longues sont donc tronquées lors de l'intégration à l'Assistant Google.
La taille maximale du document est de 50 Mo.
Lorsque vous employez des fichiers Cloud Storage, vous devez utiliser des URI publics ou des URI privés auxquels votre compte utilisateur ou votre compte de service a accès.

Spécifique aux questions fréquentes :

Dans les fichiers CSV, les questions doivent se trouver dans la première colonne et les réponses dans la seconde, sans en-tête.
Utilisez le format CSV aussi souvent que possible, car celui-ci est le plus précisément analysé.
Le contenu HTML public avec une seule paire de question/réponse (Q/R) n'est pas accepté.
Le nombre de paires de Q/R dans un document ne doit pas dépasser 2000.
Les questions en double avec des réponses différentes ne sont pas acceptées.
Vous pouvez utiliser n'importe quel document de questions fréquentes. L'analyseur de questions fréquentes est capable de gérer la plupart des formats.

Spécifique aux questions-réponses extractives :

Les questions-réponses extractives sont actuellement en phase expérimentale. Elles sont basées sur des technologies semblables à celles qui ont été expérimentées et testées chez Google sur des produits tels que la Recherche et l'Assistant. Envoyez-nous vos commentaires sur son efficacité dans Dialogflow.
Les contenus avec du texte dense fonctionnent mieux. Évitez les contenus avec de nombreux paragraphes d'une seule phrase.
Les tableaux et les listes ne sont pas acceptés.
Le nombre de paragraphes dans un document ne doit pas dépasser 2 000.
Si un article est long (> 1 000 mots), essayez de le décomposer en plusieurs articles plus petits. Si l'article aborde plusieurs problèmes, il peut être divisé en articles plus courts traitant de chaque problème. Si l'article ne porte que sur un seul problème, focalisez-vous sur sa description et présentez brièvement la manière de le résoudre.
Dans l'idéal, seul le contenu principal d'un article doit être fourni (description et résolution du problème). Les contenus supplémentaires, tels que le nom de l'auteur, l'historique des modifications, les liens associés et les annonces, ne sont pas importants.
Essayez d'inclure une description des problèmes qu'un article peut aider à résoudre et/ou des exemples de requêtes auxquels cet article peut répondre.

Utiliser Cloud Storage

Si votre contenu n'est pas public, nous vous recommandons de le stocker dans Cloud Storage. Lorsque vous créez des documents de base de connaissances, vous fournissez les URL de vos objets Cloud Storage.

Créer des buckets et des objets Cloud Storage

Lors de la création d'un bucket Cloud Storage :

Assurez-vous d'avoir sélectionné le projet GCP que vous utilisez pour Dialogflow.
Assurez-vous que le compte utilisateur ou le compte de service que vous utilisez normalement pour accéder à l'API Dialogflow dispose d'autorisations de lecture sur les objets de bucket.
Utilisez la classe Stockage standard.
Définissez l'emplacement du bucket sur l'emplacement le plus proche du vôtre. Pour certains appels d'API, vous aurez besoin de l'ID d'emplacement, par exemple us-west1. Veillez donc à prendre note de votre choix.

Suivez les instructions de la page Démarrage rapide de Cloud Storage pour créer un bucket et importer des fichiers.

Fournir un objet Cloud Storage dans un document de base de connaissances

Pour fournir votre contenu, procédez comme suit :

Créez une base de connaissances en suivant les instructions décrites ci-dessus.
Créez un document de base de connaissances en suivant les instructions décrites ci-dessus. Lorsque vous appelez la méthode create sur le type Document, définissez le champ contentUri sur l'URL de votre document Cloud Storage. Le format de cette URL est gs://bucket-name/object-name.

Gérer des intents avec l'API

Mettre à jour les données avec un FieldMask