管理知识库

知识库是您提供给 Dialogflow 的知识文档的集合。您的知识文档中包含的信息可能有助于与最终用户的对话。在寻找对最终用户表达的响应时,某些 Dialogflow 功能会使用知识库。本指南介绍如何创建和管理知识库。

准备工作

在阅读本指南之前,请先完成以下事项:

  1. 阅读 Dialogflow 基础知识
  2. 执行设置步骤

创建知识库

下面的示例展示您如何使用 Dialogflow 控制台、REST API(包括命令行)或客户端库来创建知识库。如需使用 API,请调用 KnowledgeBase 类型的 create 方法。

Web 界面

使用 Dialogflow 控制台创建知识库的方法如下:

  1. 转到 Dialogflow 控制台
  2. 选择一个代理
  3. 点击左侧边栏菜单上的知识 (Knowledge)
  4. 点击创建知识库 (Create Knowledge Base)
  5. 输入知识库名称
  6. 点击保存 (Save)。

REST 和命令行

在使用下面的请求数据之前,请先进行以下替换:

  • project-id:您的 GCP 项目 ID
  • knowledge-base-display-name:所需的知识库名称

HTTP 方法和网址:

POST https://dialogflow.googleapis.com/v2beta1/projects/project-id/knowledgeBases

请求 JSON 正文:

{
  "displayName": "knowledge-base-display-name"
}

如需发送您的请求,请展开以下选项之一:

您应会收到如下所示的 JSON 响应:

{
  "name": "projects/project-id/knowledgeBases/NDA4MTM4NzE2MjMwNDUxMjAwMA",
  "displayName": "knowledge-base-display-name"
}

记下 name 字段的值。这是您的新知识库的名称。 knowledgeBases 后面的路径段是您的新知识库 ID。 请保存好此 ID,以供后续请求使用。

Java


import com.google.api.gax.rpc.ApiException;
import com.google.cloud.dialogflow.v2beta1.KnowledgeBase;
import com.google.cloud.dialogflow.v2beta1.KnowledgeBasesClient;
import com.google.cloud.dialogflow.v2beta1.ProjectName;
import java.io.IOException;

public class KnowledgeBaseManagement {

  // Create a Knowledge base
  public static KnowledgeBase createKnowledgeBase(String projectId, String displayName)
      throws ApiException, IOException {
    // Instantiates a client
    try (KnowledgeBasesClient knowledgeBasesClient = KnowledgeBasesClient.create()) {
      KnowledgeBase knowledgeBase = KnowledgeBase.newBuilder().setDisplayName(displayName).build();
      ProjectName projectName = ProjectName.of(projectId);
      KnowledgeBase response = knowledgeBasesClient.createKnowledgeBase(projectName, knowledgeBase);
      System.out.format("Knowledgebase created:\n");
      System.out.format("Display Name: %s \n", response.getDisplayName());
      System.out.format("Knowledge ID: %s \n", response.getName());

      return response;
    }
  }
}

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."""
    import dialogflow_v2beta1 as dialogflow
    client = dialogflow.KnowledgeBasesClient()
    project_path = client.project_path(project_id)

    knowledge_base = dialogflow.types.KnowledgeBase(
        display_name=display_name)

    response = client.create_knowledge_base(project_path, knowledge_base)

    print('Knowledge Base created:\n')
    print('Display Name: {}\n'.format(response.display_name))
    print('Knowledge ID: {}\n'.format(response.name))

为知识库添加文档

您的新知识库目前没有文档,因此您应该向其中添加文档。如需了解所有受支持内容选项的说明,请参阅下文支持的内容部分。您可在此示例中使用Cloud Storage 常见问题解答文档。

下面的示例展示您如何使用 Dialogflow 控制台、REST API(包括命令行)或客户端库来创建知识文档。如需使用 API,请调用 Document 类型的 create 方法。

Web 界面

使用 Dialogflow 控制台创建知识文档的方法如下:

  1. 如果您并非按照上文所述步骤继续执行操作,请前往您的知识库设置:
    1. 转到 Dialogflow 控制台
    2. 选择一个代理
    3. 点击左侧边栏菜单上的知识 (Knowledge)
    4. 点击您的知识库名称
  2. 点击新建文档 (New Document) 或创建第一个文档 (Create the first one)
  3. 输入文档名称
  4. 对于 Mime 类型 (Mime Type),选择 text/html
  5. 对于知识库类型 (Knowledge Type),选择常见问题解答 (FAQ)
  6. 对于数据源 (Data Source),选择网址 (URL)
  7. 网址 (URL) 字段中输入 https://cloud.google.com/storage/docs/faq
  8. 点击创建 (CREATE)

REST 和命令行

在使用下面的请求数据之前,请先进行以下替换:

  • project-id:您的 GCP 项目 ID
  • knowledge-base-id:上一项请求返回的您的知识库 ID
  • document-display-name:所需的知识文档名称

HTTP 方法和网址:

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"
}

如需发送您的请求,请展开以下选项之一:

您应会收到如下所示的 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.v2beta1.CreateDocumentRequest;
import com.google.cloud.dialogflow.v2beta1.Document;
import com.google.cloud.dialogflow.v2beta1.Document.KnowledgeType;
import com.google.cloud.dialogflow.v2beta1.DocumentsClient;
import com.google.cloud.dialogflow.v2beta1.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 Document 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(180, TimeUnit.SECONDS);
      System.out.format("Created Document:\n");
      System.out.format(" - Display Name: %s\n", createdDocument.getDisplayName());
      System.out.format(" - Knowledge ID: %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());
      return createdDocument;
    }
  }
}

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."""
    import dialogflow_v2beta1 as dialogflow
    client = dialogflow.DocumentsClient()
    knowledge_base_path = client.knowledge_base_path(project_id,
                                                     knowledge_base_id)

    document = dialogflow.types.Document(
        display_name=display_name, mime_type=mime_type,
        content_uri=content_uri)

    document.knowledge_types.append(
        dialogflow.types.Document.KnowledgeType.Value(knowledge_type))

    response = client.create_document(knowledge_base_path, 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 供日后处理。 如需了解详情,请参阅长时间运行的操作

管理知识文档

更新知识文档内容

如果您更新了由知识文档引用的内容,知识文档将不会自动刷新。

如需刷新 Cloud Storage 或公开 URI 文档内容,请调用 Document 类型的 reload 方法。

如需刷新上传的原始内容,请在 Document 类型上使用 deletecreate 方法重新创建文档。

列出知识文档

您可以列出知识库中的所有知识文档。 如需使用 API,请调用 Document 类型的 list 方法。

删除知识文档

您可以删除知识库中的知识文档。 如需使用 API,请调用 Document 类型的 delete 方法。 如果您没有文档 ID,则可以按照上述说明列出文档。

支持的内容

支持以下知识文档类型:

  • 常见问题解答:文档内容包含问题和答案对,可以采用 HTML 或 CSV 格式。系统可以对典型的常见问题解答 HTML 格式进行准确解析,但可能无法解析某些不常见的格式。CSV 的第一列必须是问题,第二列必须是答案,并且没有标题行。由于这种格式十分明确,因此总能得到准确解析。
  • 抽样质量检查:提取非结构化文本并用于问题解答的文档。

下表按知识类型和来源展示了支持的 MIME 类型

知识类型\来源 上传的文件 (Document.content)(不推荐使用) 上传的文件 (Document.raw_content)(推荐使用) 来自 Cloud Storage 的文件 (Document.contentUri) 来自公开网址的文件 (Document.contentUri)
常见问题解答 文本/csv 文本/csv 文本/csv 文本/html
抽样质量检查 文本/纯文本、文本/html 文本/纯文本、文本/html、应用/pdf 文本/纯文本、文本/html、应用/pdf 不适用

对于文档内容,存在以下已知问题、限制和最佳做法:

一般注意事项:

  • 来自公共网址的文件必须已被 Google 搜索索引器抓取,因此存在于搜索索引中。您可以使用 Google Search Console 检查是否满足此项要求。请注意,索引器不会及时更新您的内容。 当源内容发生变化时,您必须明确更新您的知识文档。
  • CSV 文件必须使用逗号作为分隔符。
  • 常见问题解答和知识库文章的置信度分数尚未采用统一标准,因此如果同时使用常见问题解答和知识库文章,最佳结果并不一定是得分最高的答案。
  • Dialogflow 在创建响应时从内容中删除 HTML 标记。 因此,最好避免使用 HTML 标记并尽可能使用纯文本。
  • Google 助理响应的每个聊天气泡内容长度限制为 640 个字符,因此在集成 Google 助理时,系统会截短超过此限制的答案。
  • 文档大小上限取决于您的版本
    • Standard:50 MB
    • Essentials:50 MB
    • Plus:无限制
  • 使用 Cloud Storage 文件时,您应该使用自己的用户帐号或服务帐号可以访问的公开 URI 或私有 URI。

常见问题解答特定注意事项:

  • CSV 的第一列必须是问题,第二列必须是答案,并且没有标题行。
  • 尽可能使用 CSV,因为 CSV 解析最准确。
  • 不支持具有单个 QA 对的公开 HTML 内容。
  • 一个文档中的 QA 对数量不应超过 2000。
  • 不支持具有不同答案的重复问题。
  • 您可以使用任何常见问题解答文档,知识库的 FAQ 解析器可以处理大多数常见问题解答格式。

抽样质量检查特定注意事项:

  • 抽样质量检查目前处于实验阶段。 它基于在 Google 的搜索和智能助理等产品中试用并测试的类似技术。请向我们发送反馈,反映 Dialogflow 的工作表现。
  • 具有密集文字的内容效果最佳。请避免使用有许多单句段落的内容。
  • 不支持表格和列表。
  • 一个文档中的段落数不应超过 2000。
  • 如果文章很长(大于 1000 个字词),请尝试将其分为多篇小文章。 如果文章涵盖了多个问题,可以将其分为涵盖各个问题的简短文章。 如果文章只涵盖一个问题,请将文章的重点放在问题说明上,并尽量让问题的解决方法保持简短。
  • 理想情况下,应只提供文章的核心内容(问题说明和解决方法)。 作者姓名、修改历史记录、相关链接和广告等其他内容并不重要。
  • 请尝试描述文章可以帮助解决的问题和/或添加此文章可以回答的示例提问。

使用 Cloud Storage

如果您的内容不是公开的,建议您将内容存储在 Cloud Storage 中。创建知识文档时,请为 Cloud Storage 对象提供网址。

创建 Cloud Storage 存储分区和对象

创建 Cloud Storage 存储分区时,请注意以下几点:

  • 务必选择用于 Dialogflow 的 GCP 项目。
  • 使用 Standard 存储类别
  • 存储分区位置设置为离您最近的位置。 您需要为某些 API 调用提供位置 ID(例如 us-west1),因此请记下您的选择。

按照 Cloud Storage 快速入门中的说明创建存储分区并上传文件。

为知识库文档提供 Cloud Storage 对象

要提供您的内容,请执行以下操作:

  • 按照上文所述创建知识库。
  • 按照上文所述创建知识文档。 调用 Document 类型的 create 方法时,请将 contentUri 字段设置为 Cloud Storage 文档的网址。 此网址的格式为 gs://bucket-name/object-name