Connettori di conoscenza

I connettori di conoscenza integrano gli intent definiti. Analizzano i documenti della knowledge base (ad esempio, domande frequenti o articoli) per trovare risposte automatiche. Per configurarle, definisci una o più knowledge base, che sono raccolte di documenti di conoscenza.

Puoi attivare le knowledge base per il tuo agente, in modo che tutte le richieste di rilevamento dell'intent possano trovare risposte automatiche utilizzando le tue knowledge base. In alternativa, puoi specificare una o più knowledge base nelle singole richieste di rilevamento dell'intent.

È comune che un agente che utilizza i connettori di conoscenza utilizzi anche intent definiti. I connettori di conoscenza offrono meno precisione e controllo delle risposte rispetto agli intent. Devi definire gli intent per gestire le richieste complesse degli utenti e lasciare che i connettori di conoscenza gestiscano le richieste semplici.

Per un elenco delle lingue supportate, consulta la colonna Knowledge Connectors nel riferimento alle lingue.

Limitazioni

La funzionalità dei connettori della conoscenza è disponibile solo per la global regione.

Abilitare le funzionalità beta

Assicurati che le funzionalità beta siano attivate:

  1. Vai alla console Dialogflow ES.
  2. Seleziona un agente.
  3. Fai clic sul pulsante delle impostazioni accanto al nome dell'agente.
  4. Scorri verso il basso nella scheda Generali e assicurati che l'opzione Funzionalità beta sia attivata.
  5. Se hai apportato modifiche, fai clic su Salva.

Creare una knowledge base e un documento

Segui le istruzioni riportate nella guida alle knowledge base per creare una knowledge base e un documento.

Impostazioni per i connettori di conoscenza

Puoi attivare o disattivare le knowledge base per il tuo agente. Le knowledge base abilitate verranno prese in considerazione per tutte le richieste di corrispondenza degli intent che non specificano knowledge base. Per attivare o disattivare le 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. Seleziona una o più knowledge base dall'elenco.
  5. Fai clic su Attiva o Disattiva.

Quando un'espressione dell'utente finale corrisponde anche a un intent, puoi specificare il livello di preferenza per i risultati della knowledge base:

  1. Scorri verso il basso fino alla sezione Modifica preferenza risultati di Knowledge.
  2. Regola il cursore da più debole (preferenza data all'intent) a più forte (preferenza data alla conoscenza). Per maggiori informazioni, vedi Rilevare le risposte di intent di seguito.

Configurare le risposte

Per impostazione predefinita, una knowledge base è configurata con una singola risposta di testo predefinita compilata con la risposta della knowledge base più pertinente. Puoi modificare questa risposta e aggiungere messaggi di risposta avanzata. Le risposte della knowledge base possono contenere fino a tre risposte per knowledge base e puoi farvi riferimento nelle risposte configurate. Per aggiungere risposte:

  1. Nella pagina Knowledge, fai clic sul nome della knowledge base.
  2. Scorri verso il basso fino alla sezione Risposte e aggiungi le risposte che preferisci:
    1. Quando definisci la prima risposta, utilizza $Knowledge.Question[1] e $Knowledge.Answer[1] dove vuoi che vengano inserite la domanda e la risposta.
    2. L'indice per $Knowledge.Question e $Knowledge.Answer inizia da 1, quindi aumenta questo indice quando aggiungi altre risposte.
  3. Al termine delle modifiche, fai clic su Salva.

Quando definisci le risposte, devi considerare questi punti:

  • Se il numero di risposte definite è maggiore del numero N di corrispondenze delle risposte del connettore della conoscenza, verranno restituite solo N risposte.
  • Poiché l'accuratezza potrebbe essere inferiore rispetto alla corrispondenza con intent definiti in modo esplicito, ti consigliamo di restituire tre risposte agli utenti, se possibile.

Esempio:

Screenshot dell'integrazione del connettore di conoscenza

Rilevamento dell'intent con la knowledge base

Quando effettui una richiesta di rilevamento dell'intent, puoi specificare una o più knowledge base per una possibile risposta. Fornire esplicitamente le knowledge base in una richiesta esegue l'override delle impostazioni per le knowledge base abilitate e disabilitate.

Gli esempi riportati di seguito mostrano come utilizzare la console Dialogflow, l'API REST (inclusa la riga di comando) o le librerie client per rilevare l'intent. Per utilizzare l'API, chiama il metodo detectIntent sul tipo Sessions.

UI web

Puoi interagire con l'agente e ricevere risposte del connettore di conoscenza tramite il simulatore di Dialogflow:

  1. Segui i passaggi precedenti per attivare una knowledge base.
  2. Segui i passaggi precedenti per definire le risposte.
  3. Digita "Come faccio a registrarmi?" nel simulatore.

REST

Chiama il metodo detectIntent sul tipo Sessions e specifica la knowledge base nel campo queryParams.

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

  • PROJECT_ID: il tuo ID progetto Google Cloud
  • KNOWLEDGE_BASE_ID: l'ID della knowledge base

Metodo HTTP e URL:

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

Corpo JSON della richiesta:

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

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

{
  ...
  "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

Per eseguire l'autenticazione in Dialogflow, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.


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

Per eseguire l'autenticazione in Dialogflow, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi 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 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

Per eseguire l'autenticazione in Dialogflow, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.

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

Rilevare le risposte di intent

La risposta per il metodo Sessions di tipo detectIntent è un DetectIntentResponse. Il modo in cui vengono compilati i campi di risposta dipende da diversi fattori.

Se un intento definito e una knowledge base sono entrambi potenziali corrispondenze, la confidenza della corrispondenza di ciascuno e la preferenza per i risultati della knowledge base (vedi Impostazioni per i connettori della knowledge base) vengono utilizzate per determinare quale corrispondenza viene selezionata. La corrispondenza selezionata viene inserita nel campo DetectIntentResponse.queryResult, mentre le altre potenziali corrispondenze vengono inserite nel campo DetectIntentResponse.alternativeQueryResults. Entrambi questi campi contengono messaggi QueryResult.

Se una knowledge base fornisce una potenziale corrispondenza:

  • QueryResult.knowledgeAnswers viene compilato con un elenco di potenziali risposte della knowledge ordinate in base alla probabilità di corrispondenza decrescente.
  • Se sono state definite risposte avanzate per la knowledge base, QueryResult.fulfillmentMessages viene compilato con messaggi di risposta avanzati.

Quando esegui una richiesta di rilevamento dell'intent, è possibile che la query di conoscenza non vada a buon fine. In questo caso, verranno selezionati gli intent definiti, in modo che la richiesta di rilevamento dell'intent complessiva non vada in errore. Puoi trovare informazioni sugli errori delle query di Knowledge nel campo DetectIntentResponse.alternativeQueryResults[i].diagnosticInfo.

Gestione delle knowledge base

Per scoprire di più sulla gestione delle knowledge base, consulta Gestire le knowledge base.