Connecteurs de connaissances

Bêta

Ce produit ou cette fonctionnalité est soumis aux "Conditions des offres de pré-DG" dans la section "Conditions d'utilisation générales" des Conditions spécifiques au service. Les produits et fonctionnalités pré-DG sont disponibles "en l'état" et peuvent bénéficier d'une assistance limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Les connecteurs de connaissances complètent les intents définis. Ils analysent des documents de base de connaissances (par exemple, des questions fréquentes ou des articles) pour trouver des réponses automatisées. Pour les configurer, définissez une ou plusieurs bases de connaissances, qui sont des collections de documents de base de connaissances.

Vous pouvez activer des bases de connaissances pour votre agent afin que toutes les requêtes de détection d'intents puissent y trouver des réponses automatisées. Vous pouvez également spécifier une ou plusieurs bases de connaissances dans vos requêtes de détection d'intents individuelles.

Il est courant qu'un agent utilisant des connecteurs de connaissances utilise également des intents définis. Les connecteurs de connaissances offrent moins de précision et de contrôle dans les réponses que les intents. Vous devez définir vos intents de sorte qu'ils gèrent les requêtes utilisateur complexes, et laisser les connecteurs de connaissances gérer les requêtes simples.

Pour obtenir la liste des langues disponibles, consultez la colonne Connecteurs de connaissances dans la documentation de référence sur les langues.

Limites

La fonctionnalité de connecteurs de connaissances n'est disponible que pour la région global.

Activer les fonctionnalités en version bêta

Assurez-vous que les fonctionnalités bêta sont activées:

1. Accédez à la console Dialogflow ES.
2. Sélectionnez un agent.
3. Cliquez sur le bouton des paramètres () à côté du nom de l'agent.
4. Faites défiler l'onglet Général et assurez-vous que l'option Fonctionnalités en version bêta est activée.
5. Si vous avez apporté des modifications, cliquez sur Enregistrer.

Créer une base de connaissances et un document

Suivez les instructions du guide d'utilisation des bases de connaissances pour créer une base de connaissances et un document.

Paramètres pour les connecteurs de connaissances

Attention :Actuellement, les paramètres du connecteur de connaissances ne sont pas inclus lors de l'exportation, l'importation ou la restauration des agents.

Vous pouvez activer ou désactiver les bases de connaissances pour votre agent. Les bases de connaissances activées sont prises en compte pour toutes les requêtes de détection d'intents qui ne spécifient pas de bases de connaissances. Pour activer ou désactiver les bases de connaissances, procédez comme suit :

1. Accédez à la console Dialogflow ES.
2. Sélectionnez un agent.
3. Cliquez sur Connaissances dans le menu de la barre latérale de gauche.
4. Sélectionnez une ou plusieurs bases de connaissances dans la liste.
5. Cliquez sur Activer ou Désactiver.

Lorsqu'une expression d'utilisateur final correspond également à un intent, vous pouvez indiquer votre degré de préférence des résultats de connaissances :

1. Faites défiler la page jusqu'à la section Régler les préférences de résultats de connaissances.
2. Faites passer le curseur de la valeur la plus faible (préférence attribuée à l'intent) à la plus forte (préférence attribuée aux connaissances). Pour en savoir plus, consultez la section Réponses de détection d'intent ci-dessous.

Configurer des réponses

Par défaut, une base de connaissances est configurée avec une seule réponse textuelle par défaut, renseignée avec la réponse de connaissances la plus pertinente. Vous pouvez modifier cette réponse et ajouter des messages de réponses enrichies. Les réponses de connaissances peuvent contenir jusqu'à trois réponses par base de connaissances, et vous pouvez les référencer dans vos réponses configurées. Pour ajouter des réponses :

1. Sur la page Connaissances, cliquez sur le nom de votre base de connaissances.
2. Faites défiler la page jusqu'à la section Responses (Réponses) et ajoutez les réponses souhaitées :
   1. Lorsque vous définissez la première réponse, utilisez $Knowledge.Question[1] et $Knowledge.Answer[1] à l'endroit où la question et la réponse doivent être fournies.
   2. L'index pour $Knowledge.Question et $Knowledge.Answer commence à 1. Vous devez donc augmenter cet index lors de l'ajout de réponses.
3. Une fois vos modifications terminées, cliquez sur Enregistrer.

Lorsque vous définissez des réponses, vous devez prendre en compte ces points :

• Si le nombre de réponses définies est supérieur au nombre N de correspondances de réponses du connecteur de connaissances, seules N réponses seront renvoyées.
• Étant donné que la précision peut être inférieure à une correspondance explicite avec des intents définis, nous vous recommandons de renvoyer trois réponses à vos utilisateurs lorsque cela est possible.

Attention : Le comportement actuel lors de la définition de plusieurs variantes de réponse est un problème connu. Une fois corrigé, le comportement sera le suivant :

• Si plusieurs variantes de réponse sont définies dans une seule zone de réponse texte ou de réponse simple de l'Assistant Google, Dialogflow en choisit une au hasard.
• Si plusieurs zones de réponse enrichie sont définies, Dialogflow choisit une variante de réponse dans chaque zone.

Exemple :

Détecter un intent avec la base de connaissances

Lorsque vous effectuez une requête de détection d'intent, vous pouvez spécifier une ou plusieurs bases de connaissances pour une réponse possible. Le fait de fournir explicitement des bases de connaissances dans une requête remplace les paramètres des bases de connaissances activées et désactivées.

Les exemples ci-dessous vous montrent comment détecter un intent 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 detectIntent sur le type Sessions.

UI Web

Vous pouvez interagir avec l'agent et recevoir les réponses du connecteur de connaissances via le simulateur Dialogflow:

1. Suivez la procédure ci-dessus pour activer une base de connaissances.
2. Suivez la procédure ci-dessus pour définir des réponses.
3. Saisissez "Comment m'inscrire ?" dans le simulateur.

REST

Appelez la méthode detectIntent sur le type Sessions et spécifiez la base de connaissances dans le champ queryParams.

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

• PROJECT_ID : ID de votre projet GCP
• KNOWLEDGE_BASE_ID : ID de votre base de connaissances

Méthode HTTP et URL :

POST https://dialogflow.googleapis.com/v2beta1/projects/PROJECT_ID/agent/sessions/123456789:detectIntent

Corps JSON de la requête :

{
 "queryInput": {
   "text": {
     "text": "How do I sign up?",
     "languageCode": "en-US"
   }
 },
 "queryParams": {
   "knowledgeBaseNames": ["projects/PROJECT_ID/knowledgeBases/KNOWLEDGE_BASE_ID"]
 }
}

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 gcloud auth list pour vérifier le compte actuellement actif.

Enregistrez le corps de la requête dans un fichier nommé request.json et 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/agent/sessions/123456789:detectIntent"

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 gcloud auth list pour vérifier le compte actuellement actif.

Enregistrez le corps de la requête dans un fichier nommé request.json et 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/agent/sessions/123456789:detectIntent" | Select-Object -Expand Content

APIs Explorer (navigateur)

Copiez le corps de la requête et ouvrez la page de référence de la méthode. Le panneau APIs Explorer s'ouvre dans la partie droite de la page. Vous pouvez interagir avec cet outil pour envoyer des requêtes. Collez le corps de la requête dans cet outil, renseignez tous les champs obligatoires, puis cliquez sur Execute (Exécuter).

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

{
  ...
  "queryResult": {
    "queryText": "How do I sign up?",
    "parameters": {},
    "allRequiredParamsPresent": true,
    "fulfillmentText": "Sign up for Cloud Storage by turning on the Cloud Storage service in the Google Cloud Platform Console.",
    "intent": {
      "name": "projects/my-gcp-project/agent/intents/487c7242-a769-408a-a339-47b95e10dac4",
      "displayName": "Knowledge.KnowledgeBase.MzkzNTAyMDE3NDQxNDk3MDg4MA"
    },
    "intentDetectionConfidence": 0.99371547,
    "languageCode": "en-us",
    "knowledgeAnswers": {
      "answers": [
        {
          "answer": "Sign up for Cloud Storage by turning on the Cloud Storage service in the Google Cloud Platform Console.",
          "matchConfidenceLevel": "HIGH",
          "matchConfidence": 0.99371547
        },
        {
          "answer": "Certain types of content are not allowed on this service; please refer to the Terms of Services and Platform Policies for details. If you believe a piece of content is in violation of our policies, report it here (select See more products, then Google Cloud Storage and Cloud Bigtable).",
          "matchConfidenceLevel": "LOW",
          "matchConfidence": 0.0012244871
        },
        {
          "answer": "From the Cloud Storage documentation click \"Send feedback\" near the top right of the page. This will open a feedback form. Your comments will be reviewed by the Cloud Storage team.",
          "matchConfidenceLevel": "LOW",
          "matchConfidence": 0.0011537358
        }
      ]
    }
  }
}

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.v2beta1.DetectIntentRequest;
import com.google.cloud.dialogflow.v2beta1.DetectIntentResponse;
import com.google.cloud.dialogflow.v2beta1.KnowledgeAnswers;
import com.google.cloud.dialogflow.v2beta1.KnowledgeAnswers.Answer;
import com.google.cloud.dialogflow.v2beta1.QueryInput;
import com.google.cloud.dialogflow.v2beta1.QueryParameters;
import com.google.cloud.dialogflow.v2beta1.QueryResult;
import com.google.cloud.dialogflow.v2beta1.SessionName;
import com.google.cloud.dialogflow.v2beta1.SessionsClient;
import com.google.cloud.dialogflow.v2beta1.TextInput;
import com.google.common.collect.Maps;
import java.io.IOException;
import java.util.List;
import java.util.Map;

public class DetectIntentKnowledge {

  // DialogFlow API Detect Intent sample with querying knowledge connector.
  public static Map<String, KnowledgeAnswers> detectIntentKnowledge(
      String projectId,
      String knowledgeBaseName,
      String sessionId,
      String languageCode,
      List<String> texts)
      throws IOException, ApiException {
    // Instantiates a client
    Map<String, KnowledgeAnswers> allKnowledgeAnswers = Maps.newHashMap();
    try (SessionsClient sessionsClient = SessionsClient.create()) {
      // Set the session name using the sessionId (UUID) and projectID (my-project-id)
      SessionName session = SessionName.of(projectId, sessionId);
      System.out.println("Session Path: " + session.toString());

      // Detect intents for each text input
      for (String text : texts) {
        // Set the text and language code (en-US) for the query
        TextInput.Builder textInput =
            TextInput.newBuilder().setText(text).setLanguageCode(languageCode);
        // Build the query with the TextInput
        QueryInput queryInput = QueryInput.newBuilder().setText(textInput).build();

        QueryParameters queryParameters =
            QueryParameters.newBuilder().addKnowledgeBaseNames(knowledgeBaseName).build();

        DetectIntentRequest detectIntentRequest =
            DetectIntentRequest.newBuilder()
                .setSession(session.toString())
                .setQueryInput(queryInput)
                .setQueryParams(queryParameters)
                .build();
        // Performs the detect intent request
        DetectIntentResponse response = sessionsClient.detectIntent(detectIntentRequest);

        // Display the query result
        QueryResult queryResult = response.getQueryResult();

        System.out.format("Knowledge results:\n");
        System.out.format("====================\n");
        System.out.format("Query Text: '%s'\n", queryResult.getQueryText());
        System.out.format(
            "Detected Intent: %s (confidence: %f)\n",
            queryResult.getIntent().getDisplayName(), queryResult.getIntentDetectionConfidence());
        System.out.format(
            "Fulfillment Text: '%s'\n",
            queryResult.getFulfillmentMessagesCount() > 0
                ? queryResult.getFulfillmentMessages(0).getText()
                : "Triggered Default Fallback Intent");
        KnowledgeAnswers knowledgeAnswers = queryResult.getKnowledgeAnswers();
        for (Answer answer : knowledgeAnswers.getAnswersList()) {
          System.out.format(" - Answer: '%s'\n", answer.getAnswer());
          System.out.format(" - Confidence: '%s'\n", answer.getMatchConfidence());
        }

        KnowledgeAnswers answers = queryResult.getKnowledgeAnswers();
        allKnowledgeAnswers.put(text, answers);
      }
    }
    return allKnowledgeAnswers;
  }
}

Node.js

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.

// Imports the Dialogflow client library
const dialogflow = require('@google-cloud/dialogflow').v2beta1;
// Instantiate a DialogFlow client.
const sessionClient = new dialogflow.SessionsClient();

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const projectId = 'ID of GCP project associated with your Dialogflow agent';
// const sessionId = `user specific ID of session, e.g. 12345`;
// const languageCode = 'BCP-47 language code, e.g. en-US';
// const knowledgeBaseId = `the ID of your KnowledgeBase`;
// const query = `phrase(s) to pass to detect, e.g. I'd like to reserve a room for six people`;

// Define session path
const sessionPath = sessionClient.projectAgentSessionPath(
  projectId,
  sessionId
);
const knowledgeBasePath =
  'projects/' + projectId + '/knowledgeBases/' + knowledgeBaseId + '';

// The audio query request
const request = {
  session: sessionPath,
  queryInput: {
    text: {
      text: query,
      languageCode: languageCode,
    },
  },
  queryParams: {
    knowledgeBaseNames: [knowledgeBasePath],
  },
};

const responses = await sessionClient.detectIntent(request);
const result = responses[0].queryResult;
console.log(`Query text: ${result.queryText}`);
console.log(`Detected Intent: ${result.intent.displayName}`);
console.log(`Confidence: ${result.intentDetectionConfidence}`);
console.log(`Query Result: ${result.fulfillmentText}`);
if (result.knowledgeAnswers && result.knowledgeAnswers.answers) {
  const answers = result.knowledgeAnswers.answers;
  console.log(`There are ${answers.length} answer(s);`);
  answers.forEach(a => {
    console.log(`   answer: ${a.answer}`);
    console.log(`   confidence: ${a.matchConfidence}`);
    console.log(`   match confidence level: ${a.matchConfidenceLevel}`);
  });
}

Python

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.

def detect_intent_knowledge(
    project_id, session_id, language_code, knowledge_base_id, texts
):
    """Returns the result of detect intent with querying Knowledge Connector.

    Args:
    project_id: The GCP project linked with the agent you are going to query.
    session_id: Id of the session, using the same `session_id` between requests
              allows continuation of the conversation.
    language_code: Language of the queries.
    knowledge_base_id: The Knowledge base's id to query against.
    texts: A list of text queries to send.
    """
    from google.cloud import dialogflow_v2beta1 as dialogflow

    session_client = dialogflow.SessionsClient()

    session_path = session_client.session_path(project_id, session_id)
    print("Session path: {}\n".format(session_path))

    for text in texts:
        text_input = dialogflow.TextInput(text=text, language_code=language_code)

        query_input = dialogflow.QueryInput(text=text_input)

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

        query_params = dialogflow.QueryParameters(
            knowledge_base_names=[knowledge_base_path]
        )

        request = dialogflow.DetectIntentRequest(
            session=session_path, query_input=query_input, query_params=query_params
        )
        response = session_client.detect_intent(request=request)

        print("=" * 20)
        print("Query text: {}".format(response.query_result.query_text))
        print(
            "Detected intent: {} (confidence: {})\n".format(
                response.query_result.intent.display_name,
                response.query_result.intent_detection_confidence,
            )
        )
        print("Fulfillment text: {}\n".format(response.query_result.fulfillment_text))
        print("Knowledge results:")
        knowledge_answers = response.query_result.knowledge_answers
        for answers in knowledge_answers.answers:
            print(" - Answer: {}".format(answers.answer))
            print(" - Confidence: {}".format(answers.match_confidence))

Réponses de détection d'intent

La réponse de la méthode detectIntent pour le type Sessions est DetectIntentResponse. Plusieurs facteurs affectent la manière dont les champs de réponse sont renseignés.

Si un intent défini et une base de connaissances sont tous deux des correspondances potentielles, la correspondance proposée sera choisie en fonction de l'indice de confiance de chacun et de la préférence de résultats de connaissances définie (consultez la section Paramètres pour les connecteurs de connaissances). La correspondance sélectionnée est renseignée dans le champ DetectIntentResponse.queryResult et les autres correspondances potentielles sont renseignées dans le champ DetectIntentResponse.alternativeQueryResults. Ces deux champs contiennent des messages de type QueryResult.

Si une base de connaissances fournit une correspondance potentielle :

• Le champ QueryResult.knowledgeAnswers est renseigné avec une liste de réponses potentielles classées en fonction de la fiabilité des correspondances (par ordre décroissant).
• Si des réponses enrichies ont été définies pour la base de connaissances, le champ QueryResult.fulfillmentMessages est renseigné avec ces messages de réponses enrichies.

Lorsque vous effectuez une requête de détection d'intent, il est possible que la requête de connaissances échoue. Dans ce cas, les intents définis sont sélectionnés, afin que la requête globale de détection d'intent ne soit pas interrompue. Les informations d'erreur de la requête de connaissances sont affichées dans le champ DetectIntentResponse.alternativeQueryResults[i].diagnosticInfo.

Gérer les bases de connaissances

Pour en savoir plus sur la gestion des bases de connaissances, consultez la page Gérer les bases de connaissances.