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

ナレッジベースは、Dialogflow に提供するナレッジドキュメントのコレクションです。ナレッジドキュメントには、エンドユーザーとの会話に役立てることができる情報が含まれています。 Dialogflow の一部の機能では、エンドユーザー表現に対するレスポンスを検索する際に、ナレッジベースを使用します。このガイドでは、ナレッジベースの作成と管理について説明します。

ナレッジベースはエージェントレベルで適用されます。

始める前に

このガイドを読む前に、次の手順を行ってください。

Dialogflow の基本をご覧ください。
手順に沿って設定してください。

ナレッジベースを作成する

以下のサンプルは、Dialogflow コンソール、REST API（コマンドラインを含む）、またはクライアントライブラリを使用してナレッジベースを作成する方法を示しています。API を使用するには、KnowledgeBase タイプの create メソッドを呼び出します。

ウェブ UI

Dialogflow コンソールを使用してナレッジベースを作成します。

Dialogflow ES コンソールに移動します。
エージェントを選択します。
左側のサイドバーメニューで [Knowledge] をクリックします。
[Create Knowledge Base] をクリックします。
ナレッジベース名を入力します。
[保存] をクリックします。

REST

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

PROJECT_ID: GCP プロジェクト ID
KNOWLEDGE_BASE_DISPLAY_NAME: 目的のナレッジベース名

HTTP メソッドと URL:

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

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

{
  "displayName": "KNOWLEDGE_BASE_DISPLAY_NAME"
}

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

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

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/knowledgeBases" | Select-Object -Expand Content

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

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

name フィールドの値をメモしておきます。これが新しいナレッジベースの名前です。knowledgeBases の後のパスセグメントは新しいナレッジベース ID です。この ID を以下のリクエストに保存します。

Java

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


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

ナレッジベースにドキュメントを追加する

作成した新しいナレッジベースには、まだドキュメントがないため、ここで追加します。サポートされるすべてのコンテンツオプションの説明については、以下のサポートされるコンテンツをご覧ください。この例については、Cloud Storage に関するよくある質問をご覧ください。

以下のサンプルは、Dialogflow コンソール、REST API（コマンドラインを含む）、またはクライアントライブラリを使用してナレッジドキュメントを作成する方法を示しています。API を使用するには、Document タイプの create メソッドを呼び出します。

ウェブ UI

Dialogflow コンソールを使用してナレッジドキュメントを作成します。

前の手順からの続きではない場合は、ナレッジベースの設定画面に移動します。
1. Dialogflow ES コンソールに移動します。
2. エージェントを選択します。
3. 左側のサイドバーメニューで [Knowledge] をクリックします。
4. ナレッジベース名をクリックします。
[New Document] または [Create the first one] をクリックします。
ドキュメント名を入力します。
[Mime Type] で [text/html] を選択します。
ナレッジタイプのよくある質問を選択します。
データソースの URL を選択します。
[https://cloud.google.com/storage/docs/faq] フィールドに「https://cloud.google.com/storage/docs/faq」と入力します。
[CREATE] をクリックします。

REST

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

PROJECT_ID: GCP プロジェクト ID
KNOWLEDGE_BASE_ID: 前回のリクエストから返されたナレッジベース ID
DOCUMENT_DISPLAY_NAME: 目的のナレッジドキュメント名

HTTP メソッドと URL:

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

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

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

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

curl（Linux、macOS、Cloud Shell）

リクエスト本文を 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/knowledgeBases/KNOWLEDGE_BASE_ID/documents"

PowerShell（Windows）

リクエスト本文を 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/knowledgeBases/KNOWLEDGE_BASE_ID/documents" | Select-Object -Expand Content

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

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

operations の後のパスセグメントは、オペレーション ID です。

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

ドキュメントの作成は長時間実行されるオペレーションであるため、完了までにかなりの時間がかかることがあります。このオペレーションのステータスをポーリングして、完了したかどうかを確認できます。完了すると、オペレーションに新たに作成されたドキュメント ID が含まれます。今後の処理に備えてこの ID を保存してください。詳しくは、長時間実行オペレーションをご覧ください。

ナレッジドキュメントを管理する

ナレッジドキュメントのコンテンツを更新する

ナレッジドキュメントが参照するコンテンツを更新した場合、ナレッジドキュメントは、自動的に更新されない場合があります。コンテンツが公開 URL として提供されていて、ドキュメントの [自動再読み込みを有効にする] オプションがオンになっている場合にのみ、コンテンツは自動的に更新されます。

Cloud Storage やパブリック URL のドキュメントコンテンツを手動で更新するには、Document 型の reload メソッドを呼び出します。

アップロードした未加工のコンテンツを手動で更新するには、Document 型の delete メソッドと create メソッドを使用してドキュメントを再作成します。

ナレッジドキュメントを一覧表示する

ナレッジベースのすべてのナレッジドキュメントを一覧表示できます。API を使用するには、Document タイプの list メソッドを呼び出します。

ナレッジドキュメントを削除する

ナレッジベースのナレッジドキュメントを削除できます。API を使用するには、Document タイプの delete メソッドを呼び出します。ドキュメント ID がない場合は、前述のようにドキュメントを一覧表示できます。

サポートされるコンテンツ

サポートされているナレッジドキュメントタイプは、次のとおりです。

よくある質問: HTML または CSV のいずれかの形式の質問と回答のペアがドキュメントコンテンツに含まれています。よくある質問の一般的な HTML 形式は正確に解析されますが、通常とは異なる形式は解析できない可能性があります。CSV では、最初の列に質問、2 番目の列に回答を入れます。ヘッダーは付けないでください。この明示的な形式のため、常に正確に解析されます。
抽出に関する QA: 非構造化テキストが抽出され、質問の回答に使用されるドキュメント。

次の表は、サポートされている MIME タイプをナレッジタイプとソースごとにまとめたものです。

ナレッジタイプ / ソース	アップロードされるファイル（Document.content、非推奨）	アップロードされるファイル（Document.raw_content、推奨）	Cloud Storage からのファイル（Document.contentUri）	公開 URL からのファイル（Document.contentUri）
よくある質問	text/csv	text/csv	text/csv	text/html
抽出に関する QA	text/plain、text/html	text/plain、text/html、application/pdf	text/plain、text/html、application/pdf	なし

ドキュメントのコンテンツに関しては、次の既知の問題点、制限事項、おすすめの方法があります。

全般:

公開 URL からのファイルは、検索インデックスに存在するように、Google 検索インデクサによってクロールされている必要があります。これは Google Search Console で確認できます。このインデクサはコンテンツを最新の状態には保たないことに注意してください。ソースコンテンツが変更された場合は、ナレッジドキュメントを明示的に更新する必要があります。
CSV ファイルでは、区切り文字としてカンマを使用する必要があります。
信頼度スコアはまだ、よくある質問とナレッジベース記事との間で調整されていないため、よくある質問とナレッジベース記事の両方を使用する場合に最良の結果が最高になるとは限りません。
Dialogflow によってレスポンスが作成されるときに、コンテンツから HTML タグが削除されます。したがって、可能であれば HTML タグを避けて書式なしテキストを使用することをおすすめします。
Google アシスタントのレスポンスでは、チャットバブルあたり 640 文字という上限があるため、長い回答は Google アシスタントとの統合時に切り捨てられます。
ドキュメントの最大サイズは 50 MB です。
Cloud Storage のファイルを使用するときは、ユーザーアカウントまたはサービスアカウントからアクセスできるパブリック URI またはプライベート URI を使用してください。

よくある質問に固有の事項:

CSV では、最初の列に質問、2 番目の列に回答を入れます。ヘッダーは付けないでください。
CSV が最も正確に解析されることから、可能な限り CSV を使用してください。
パブリック HTML コンテンツの QA ペアが 1 つだけというケースはサポートされません。
1 つのドキュメント内の QA ペアの数が 2,000 を超えてはなりません。
重複する質問の回答がそれぞれ異なるというケースはサポートされません。
どのよくある質問ドキュメントでも使用できます。よくある質問パーサーは、ほとんどのよくある質問形式を処理できるためです。

抽出に関する QA に固有の事項:

現在、抽出に関する QA は試験運用版です。このベースとなっているのは、Google の検索とアシスタントなどのプロダクトですでに試用されテストされた、類似のテクノロジーです。Dialogflow でどのように機能しているかについて、フィードバックをお寄せください。
コンテンツのテキストが高密度の場合に、最も良好に動作します。単一センテンスの段落が多数あるコンテンツは避けてください。
表とリストはサポートされていません。
1 つのドキュメントの中の段落数が 2,000 を超えないようにしてください。
記事が長すぎる場合は、複数の小さな記事に分割します。記事が複数の問題を扱っている場合は、個々の問題をより短い記事に分割できます。記事に 1 つの問題のみを記載している場合は、問題の説明に焦点を当てて解決してください。
記事の中核となる内容（問題の説明および解決策）のみを提供するのが理想的です。著者名、変更履歴、関連リンク、広告などの追加コンテンツは重要ではありません。
記事が役立つ問題や、この記事で解説するクエリの例を含めるようにしてください。

Cloud Storage の使用

コンテンツが公開されていない場合は、Cloud Storage にコンテンツを保存することをおすすめします。ナレッジドキュメントを作成するときは、Cloud Storage オブジェクトの URL を指定します。

Cloud Storage バケットとオブジェクトの作成

Cloud Storage バケットを作成する場合は、次の手順を行います。

Dialogflow で使用する GCP プロジェクトが選択されていることを確認します。
Dialogflow API へのアクセスに通常使用するユーザーアカウントやサービスアカウントに、バケットオブジェクトに対する読み取り権限があることを確認します。
Standard Storage クラスを使用します。
バケットのロケーションを現在地に最も近い場所に設定します。ロケーション ID（例: us-west1）が必要となる API 呼び出しもあるため、選択した ID をメモしておきます。

Cloud Storage クイックスタートの手順に沿って、バケットを作成し、ファイルをアップロードします。

ナレッジベースドキュメントへの Cloud Storage オブジェクトの提供

コンテンツを提供するには、次の手順を行います。

ナレッジベースを上記に従って作成します。
ナレッジドキュメントを上記に従って作成します。Document タイプの create メソッドを呼び出す場合は、Cloud Storage ドキュメントの URL に contentUri フィールドを設定します。この URL の形式は gs://bucket-name/object-name です。

API でインテントを管理する

FieldMask を使用してデータを更新する

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

始める前に

ナレッジベースを作成する

ウェブ UI

REST

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

Java

Node.js

Python

ナレッジベースにドキュメントを追加する

ウェブ UI

REST

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

Java

Node.js

Python

ナレッジ ドキュメントを管理する

ナレッジ ドキュメントのコンテンツを更新する

ナレッジ ドキュメントを一覧表示する

ナレッジ ドキュメントを削除する

サポートされるコンテンツ

Cloud Storage の使用

Cloud Storage バケットとオブジェクトの作成

ナレッジベース ドキュメントへの Cloud Storage オブジェクトの提供

ナレッジドキュメントを管理する

ナレッジドキュメントのコンテンツを更新する

ナレッジドキュメントを一覧表示する

ナレッジドキュメントを削除する

ナレッジベースドキュメントへの Cloud Storage オブジェクトの提供