ナレッジコネクタ

ナレッジコネクタは、定義済みのインテントを補完します。ナレッジドキュメント（たとえば、よくある質問や記事）を解析して、自動化レスポンス見つけます。ナレッジコネクタを構成するには、ナレッジドキュメントの集合であるナレッジベースを定義します。

ナレッジベースをエージェントに対して有効化すると、すべてのインテント検出リクエストで、そのナレッジベースを使用して自動化レスポンスを見つけることができるようになります。別の方法として、個々のインテント検出リクエストの中でナレッジベースを指定することもできます。

一般的に、ナレッジコネクタを使用するエージェントは定義済みのインテントも使用します。ナレッジコネクタは、レスポンスの精度とコントロールの点でインテントを下回ります。複雑なユーザーリクエストを処理するインテントを定義し、ナレッジコネクタでは単純なリクエストを処理するようにしてください。

サポートされている言語の一覧については、言語のリファレンスのナレッジコネクタの列をご覧ください。

制限事項

ナレッジコネクタ機能は、global リージョンでのみ使用できます。

ベータ版の機能を有効にする

ベータ版の機能が有効になっていることを確認するには、次の手順を実行します。

Dialogflow ES コンソールに移動します。
エージェントを選択します。
エージェント名の横にある設定ボタンをクリックします。
[General] タブが選択されている状態で下にスクロールし、[Beta Features] が有効になっていることを確認します。
変更を加えた場合は、[Save] をクリックします。

ナレッジベースとドキュメントを作成する

ナレッジベースの入門の手順に従って、ナレッジベースとドキュメントを作成します。

ナレッジコネクタの設定

エージェントのナレッジベースを有効または無効にできます。有効なナレッジベースは、ナレッジベースを指定しないすべてのインテント一致リクエストで考慮されます。ナレッジベースを有効または無効にするには、次の手順に従います。

Dialogflow ES コンソールに移動します。
エージェントを選択します。
左側のサイドバーメニューで [Knowledge] をクリックします。
リストからナレッジベースを 1 つ以上選択します。
[Enable] または [Disable] をクリックします。

エンドユーザー表現がインテントとも一致する場合は、ナレッジ検索の精度を指定できます。

[Adjust Knowledge Results Preference] セクションまで下にスクロールします。
スライダーを弱い（インテントへの設定）から強い（ナレッジへの設定）に調整します。詳細については、下記のインテント検出のレスポンスをご覧ください。

レスポンスを構成する

デフォルトでは、ナレッジベースは、一致する最適なナレッジアンサーが入力されたデフォルトのテキストレスポンスで構成されます。このレスポンスを変更して、高度なレスポンスメッセージを追加できます。ナレッジレスポンスには、ナレッジベースごとに最大 3 つの回答が含まれます。これらの回答は、構成済みのレスポンスで参照できます。レスポンスを追加するには、次の手順に従います。

[Knowledge] ページで、ナレッジベース名をクリックします。
下の [Responses] セクションまでスクロールして、必要に応じてレスポンスを追加します。
1. 最初のレスポンスを定義するときは、質問と回答を指定する $Knowledge.Question[1] と $Knowledge.Answer[1] を使用します。
2. $Knowledge.Question と $Knowledge.Answer のインデックスは 1 から始まります。レスポンスを追加する際には、このインデックスの数値を増やします。
編集し終わったら [Save] をクリックします。

レスポンスを定義するときは、次の点を考慮する必要があります。

定義済みのレスポンスの数がナレッジコネクタレスポンス一致の数 N より大きい場合でも、返されるレスポンスは N 個だけです。
明示的に定義されたインテントとの照合に比べて精度が低い可能性があることから、可能であれば、3 つのレスポンスをユーザーに返すことをおすすめします。

例:

ナレッジコネクタ統合のスクリーンショット

ナレッジベースを使用してインテントを検出する

インテント検出リクエストを作成する際に、考えられるレスポンスのナレッジベースを 1 つ以上指定できます。リクエストでナレッジベースを明示的に指定すると、有効および無効なナレッジベースの設定がオーバーライドされます。

以下のサンプルは、Dialogflow コンソール、REST API（コマンドラインを含む）、またはクライアントライブラリを使用してインテントを検出する方法を示しています。API を使用するには、Sessions タイプの detectIntent メソッドを呼び出します。

ウェブ UI

Dialogflow シミュレータを使用して、エージェントと対話してナレッジコネクタのレスポンスを受け取ることが可能です。

上記の手順に従ってナレッジベースを有効にします。
上記の手順に従ってレスポンスを定義します。
シミュレータで、キーボードから「How do I sign up?」と入力します。

REST

Sessions タイプで detectIntent メソッドを呼び出し、queryParams フィールドにナレッジベースを指定します。

リクエストのデータを使用する前に、次のように置き換えます。

PROJECT_ID: GCP プロジェクト ID
KNOWLEDGE_BASE_ID: ナレッジベース ID

HTTP メソッドと URL:

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

リクエストの本文（JSON）:

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

リクエストを送信するには、次のいずれかのオプションを展開します。

curl（Linux、macOS、Cloud Shell）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザーアカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

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）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザーアカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$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

API Explorer（ブラウザ）

リクエスト本文をコピーして、メソッドのリファレンスページを開きます。ページの右側に [API Explorer] パネルが開きます。このツールを操作してリクエストを送信できます。このツールにリクエスト本文を貼り付け、その他の必須フィールドに入力して、[Execute] をクリックします。

次のような JSON レスポンスが返されます。

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

Dialogflow への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。


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

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

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

インテント検出のレスポンス

Sessions タイプの detectIntent メソッドのレスポンスは、DetectIntentResponse のインスタンスです。レスポンスフィールドのデータがどのように入力されるかについては、複数の要素が影響します。

定義済みのインテントとナレッジベースの両方が一致候補の場合は、各候補の一致信頼度とナレッジ結果優先度（ナレッジコネクタの設定をご覧ください）を使用して、どの候補を一致として選択するかを決定します。一致として選択されたものが DetectIntentResponse.queryResult フィールドに入力され、その他の一致候補は .DetectIntentResponse.alternativeQueryResults フィールドに入力されます。これらの両方のフィールドに QueryResult メッセージが含まれます。

ナレッジベースが一致候補の場合:

QueryResult.knowledgeAnswers には、一致の信頼度を降順に並べたナレッジ回答候補のリストが入力されます。
ナレッジベースに対してリッチレスポンスが定義されている場合は、QueryResult.fulfillmentMessages にはリッチレスポンスメッセージが入力されます。

インテント検出リクエストを実行するときに、ナレッジクエリに失敗することも考えられます。このことが起きたときは定義済みのインテントが選択されるので、インテント検出リクエスト全体としては失敗したことにはなりません。ナレッジベースのクエリのエラー情報は、DetectIntentResponse.alternativeQueryResults[i].diagnosticInfo フィールドで確認できます。

ナレッジベースを管理する

ナレッジベースの管理の詳細については、ナレッジベースの管理をご覧ください。

API の操作

トレーニング