기술 자료 관리

기술 자료는 Dialogflow에 제공하는 기술 문서 모음을 나타냅니다. 기술 문서에는 최종 사용자와의 대화에 유용한 정보가 포함되어 있습니다. 일부 Dialogflow 기능은 최종 사용자 표현에 대한 응답을 찾을 때 기술 자료를 사용합니다. 이 가이드에서는 기술 자료를 만들고 관리하는 방법을 설명합니다.

기술 자료는 에이전트 수준에서 적용됩니다.

시작하기 전에

이 가이드를 읽기 전에 다음을 수행해야 합니다.

Dialogflow 기본사항 읽기
설정 단계 수행

기술 자료 만들기

아래 샘플에서는 Dialogflow 콘솔, REST API(명령줄 포함), 클라이언트 라이브러리를 사용하여 기술 자료를 만드는 방법을 보여줍니다. API를 사용하려면 KnowledgeBase 유형의 create 메서드를 호출합니다.

웹 UI

Dialogflow 콘솔을 사용하여 기술 자료를 만듭니다.

Dialogflow ES 콘솔로 이동합니다.
에이전트를 선택합니다.
왼쪽 사이드바 메뉴에서 지식을 클릭합니다.
기술 자료 만들기를 클릭합니다.
기술 자료 이름을 입력합니다.
저장을 클릭합니다.

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

CTS에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.


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

CTS에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.

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

CTS에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.

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 FAQ 문서를 사용할 수 있습니다.

아래 샘플에서는 Dialogflow 콘솔, REST API(명령줄 포함), 클라이언트 라이브러리를 사용하여 기술 문서를 만드는 방법을 보여줍니다. API를 사용하려면 Document 유형의 create 메서드를 호출합니다.

웹 UI

Dialogflow 콘솔을 사용하여 기술 문서를 만듭니다.

위의 단계에 이어서 진행하는 것이 아니라면 기술 자료 설정으로 이동합니다.
1. Dialogflow ES 콘솔로 이동합니다.
2. 에이전트를 선택합니다.
3. 왼쪽 사이드바 메뉴에서 지식을 클릭합니다.
4. 기술 자료 이름을 클릭합니다.
새 문서 또는 첫 번째 문서 만들기를 클릭합니다.
문서 이름을 입력합니다.
Mime 유형으로 text/html을 선택합니다.
지식 유형에 FAQ를 선택합니다.
데이터 소스에 URL을 선택합니다.
https://cloud.google.com/storage/docs/faq 필드에 https://cloud.google.com/storage/docs/faq를 입력합니다.
만들기를 클릭합니다.

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

CTS에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.


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

CTS에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.

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

CTS에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.

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가 없는 경우 위에서 설명한 대로 문서를 나열할 수 있습니다.

지원 콘텐츠

지원되는 기술 문서 유형은 다음과 같습니다.

FAQ: 문서 콘텐츠에 질문 및 답변 쌍이 HTML 또는 CSV 형식으로 포함되어 있습니다. 일반적인 FAQ HTML 형식은 정확하게 파싱되지만 특수한 형식은 파싱되지 않을 수 있습니다. CSV의 첫 번째 열에 질문이 있어야 하고 두 번째 열에 헤더가 없는 답변이 있어야 합니다. 이러한 명시적인 형식 덕분에 항상 정확하게 파싱됩니다.
추출 QA: 구조화되지 않은 텍스트를 추출하여 질문 응답에 사용하는 문서입니다.

다음 표에는 지식 유형 및 소스별로 지원되는 MIME 유형이 나와 있습니다.

지식 유형 \ 소스	업로드된 파일(Document.content 권장하지 않음)	업로드된 파일(Document.raw_content 권장)	Cloud Storage의 파일(Document.contentUri)	공개 URL의 파일(Document.contentUri)
FAQ	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 파일은 구분자로 쉼표를 사용해야 합니다.
FAQ와 기술 자료 문서의 신뢰도 점수는 비교 보정을 거치지 않았으므로 FAQ와 기술 자료 문서를 모두 사용하는 경우 점수가 가장 높은 쪽이 항상 최선의 결과를 가져오는 것은 아닙니다.
Dialogflow는 응답을 생성할 때 콘텐츠에서 HTML 태그를 삭제합니다. 따라서 가능하다면 HTML 태그 사용을 지양하고 일반 텍스트를 사용하는 것이 가장 좋습니다.
Google 어시스턴트 응답에는 말풍선당 640자의 글자 수 제한이 적용되므로 Google 어시스턴트로 의사 소통할 때 길게 답변하면 잘리게 됩니다.
최대 문서 크기는 50MB입니다.
Cloud Storage 파일을 사용할 때에는 공개 URI 또는 사용자 계정이나 서비스 계정에 액세스 권한이 있는 비공개 URI를 사용해야 합니다.

FAQ에만 해당되는 내용:

CSV의 첫 번째 열에 질문이 있어야 하고 두 번째 열에 헤더가 없는 답변이 있어야 합니다.
CSV가 가장 정확하게 파싱되므로 가능하다면 CSV를 사용하세요.
QA 조합이 하나만 있는 공용 HTML 콘텐츠는 지원되지 않습니다.
문서 1개당 QA 조합 개수는 2,000개를 넘을 수 없습니다.
답변이 다른 중복 질문은 지원되지 않습니다.
FAQ 파서가 대부분의 FAQ 형식을 처리할 수 있으므로 어떤 FAQ 문서든 사용할 수 있습니다.

추출 QA에만 해당되는 내용:

추출 QA는 현재 실험용입니다. 검색 또는 어시스턴트와 같은 Google 제품에서 체험과 테스트 과정을 거친 유사한 기술을 기반으로 합니다. Dialogflow에서 어떻게 작동하는지에 대한 의견을 보내주세요.
콘텐츠의 텍스트가 조밀할 때 가장 좋은 결과가 나옵니다. 콘텐츠를 한 문장씩 여러 단락으로 나누지 마세요.
표와 목록은 지원되지 않습니다.
문서 1개당 단락 수는 2,000개를 넘을 수 없습니다.
자료가 긴 경우(1,000단어 초과) 여러 개의 작은 자료로 나누어보세요. 문서에서 여러 가지 문제를 다루는 경우 개별 문제를 다루는 보다 짧은 문서로 나눌 수 있습니다. 문서에서 한 가지 문제만 다루는 경우 문서를 문제 설명에 집중시키고 문제 해결을 간결하게 유지하세요.
자료의 핵심 콘텐츠만 제공하는 것이 좋습니다(문제 설명 및 해결). 작성자 이름, 수정 내역, 관련 링크, 광고와 같은 부가적인 콘텐츠는 중요하지 않습니다.
유용할 수 있는 문제 설명 또는 이 문서에서 답변할 수 있는 샘플 쿼리를 문서에 포함해보세요.

Cloud Storage 사용

공개된 콘텐츠가 아닌 경우 Cloud Storage에 콘텐츠를 저장하는 것이 좋습니다. 기술 문서를 만들 때 Cloud Storage 객체의 URL을 제공합니다.

Cloud Storage 버킷 및 객체 만들기

Cloud Storage 버킷을 만들려면 다음을 수행합니다.

Dialogflow에 사용할 GCP 프로젝트를 선택했는지 확인합니다.
평소에 Dialogflow API에 액세스하는 데 사용하는 사용자 계정 또는 서비스 계정에 버킷 객체에 대한 읽기 권한이 있는지 확인합니다.
표준 스토리지 클래스를 사용합니다.
버킷 위치를 자신과 가장 가까운 위치로 설정합니다. 일부 API 호출에는 위치 ID(예: us-west1)가 필요하므로 선택한 위치 ID를 기록합니다.

Cloud Storage 빠른 시작의 안내를 따라 버킷을 만들고 파일을 업로드합니다.

기술 자료 문서에 Cloud Storage 객체 제공

콘텐츠를 제공하려면 다음 안내를 따르세요.

위 설명대로 기술 자료를 만듭니다.
위 설명대로 기술 문서를 만듭니다. Document 유형의 create 메서드를 호출할 경우 contentUri 필드를 Cloud Storage 문서의 URL로 설정합니다. 이 URL 형식은 gs://bucket-name/object-name입니다.

API로 인텐트 관리

FieldMask로 데이터 업데이트