Knowledge API

Knowledge API

Dify 콘솔을 거치지 않고 코드로 지식 베이스를 만들고 운영할 수 있어요. 지식 베이스를 만들고, 문서와 청크를 채우고, 메타데이터와 태그로 정리하고, 검색이나 RAG를 위해 직접 질의할 수 있죠.

출처: 공식문서

API 엔드포인트와 키 얻기

Knowledge에서 오른쪽 위 Service API를 클릭하면 API 설정 패널이 열려요. 여기서:

  • Service API 엔드포인트를 복사하세요. 모든 Knowledge API 요청의 베이스 URL이에요.
  • API Key를 클릭해 키를 만들고 관리해요.
API 키는 서버 쪽에 안전하게 저장하세요. 클라이언트 쪽 코드나 공개 저장소에 노출하면 안 됩니다.

스코프된 API 키

키를 만들 때, 통합이 실제로 작업할 지식 베이스에 스코프하면 돼요. 통합이 지식 베이스를 나열하거나 만들어야 한다면 모든 지식 베이스를 선택하세요.

스코프된 키는 경로에 그 스코프 안에 있는 dataset_id가 포함된 엔드포인트만 호출할 수 있어요. 다른 ID로 호출하거나, 경로에 dataset_id가 없는 호출은 403 forbidden이 나요.

스코프된 키라면 Dify에서 지식 베이스를 열고, 페이지 URL의 /datasets/ 뒤에 있는 ID를 복사하세요. 그 값을 요청 경로의 dataset_id로 쓰면 돼요.

스코프를 바꾸려면 대체 키를 만들어요. 옛 키를 지우기 전에 통합을 새 키로 전환하세요.

지식 베이스를 삭제하면 그 베이스에만 스코프된 키도 함께 삭제됩니다. 다른 지식 베이스도 덮는 키는 남은 것들에 대해서는 계속 동작해요.

지식 베이스의 API 접근 관리

모든 지식 베이스는 기본적으로 API 접근이 켜져 있어요. 특정 베이스를 모든 키에 닫으려면, 베이스를 열고 왼쪽 아래 API Access를 끄면 됩니다.

지식 베이스 만들고 관리하기

문서 추가·업데이트하기

문서 생성은 비동기예요. 문서를 만든 뒤 인덱싱이 끝날 때까지 폴링하면 됩니다:

  1. 지식 베이스 만들기 — Create an Empty Knowledge Base를 호출하거나, 기존 지식 베이스를 쓰세요.

  2. 문서 추가 — Create Document by Text나 Create Document by File을 호출합니다. 둘 다 batch ID를 반환해요.

    지식 베이스를 만들 때 indexing_technique(콘텐츠가 검색을 위해 인덱싱되는 방식)를 설정하지 않았다면, 첫 문서에서 설정하세요. 이후 문서는 그것을 자동으로 상속받아요.

  3. 인덱싱 상태 폴링 — batch ID로 Get Document Indexing Status를 폴링해 indexing_status가 completed나 error에 도달할 때까지 기다려요. 그 사이 waiting, parsing, cleaning, splitting, indexing을 거칩니다.

  • List Documents: 페이지 처리된 목록, 키워드나 인덱싱 상태로 필터할 수 있어요.
  • Get Document: 문서 하나의 인덱싱 상태, 메타데이터, 처리 통계. metadata 쿼리 파라미터로 메타데이터 필드를 포함·제외·오직 반환할 수 있어요.
  • Download Document: 문서가 원래 업로드한 파일에 대한 서명된 URL.
  • Download Documents as ZIP: 최대 100개 업로드 파일 문서를 단일 아카이브로 묶어요.
  • Update Document: 새 파일을 업로드해 문서 콘텐츠를 교체하고 인덱싱을 다시 트리거해요—파일 기반 문서를 업데이트하는 표준 방법이에요.
  • Update Document by Text: 문서의 텍스트 콘텐츠, 이름, 처리 설정을 인라인으로 업데이트하고, 콘텐츠가 바뀌면 인덱싱을 다시 트리거해요.
  • Update Document by File: 대체 파일 업로드용으로 deprecated된 별칭. Update Document를 쓰세요.
  • Update Document Status in Batch: 여러 문서를 한 번에 활성화·비활성화·보관·보관 해제해요.
  • Delete Document: 문서와 그 안의 모든 청크를 영구 제거해요.

청크와 하위 청크 관리하기

  • Create Chunks: 문서에 청크를 손으로 추가해요—업로드한 콘텐츠는 인덱싱이 이미 자동으로 청크로 만듭니다. 각 청크는 content가 필요하고, Q&A 모드 문서는 answer도 필요해요.
  • List Chunks: 페이지 처리된 목록, 키워드나 상태로 필터할 수 있어요.
  • Get Chunk: 청크 하나의 콘텐츠, 키워드, 인덱싱 상태.
  • Update Chunk: 청크의 콘텐츠, 키워드, answer를 바꾸고 그 청크의 인덱싱을 다시 트리거해요.
  • Delete Chunk: 청크를 영구 제거해요.

Parent-child 모드(hierarchical_model) 문서에서는 하위 청크가 상위 청크 아래 중첩돼요. API로 만들거나 업데이트한 하위 청크는 인덱싱 파이프라인이 만드는 automatic과 달리 항상 customized 타입으로 찍힙니다.

메타데이터 필드 관리하기

메타데이터 필드는 문서에 구조화된 정보를 붙여, 검색이 그 위에서 필터할 수 있게 해줘요:

메타데이터는 안정적인 외부 키로도 동작해요. 각 문서에 소스 시스템의 ID를 저장해 두면, 이후 동기화 실행에서 그 위에 필터해 같은 문서를 찾아 업데이트할 수 있어요.

지식 베이스를 태그로 정리하기

태그는 워크스페이스 레벨에 살아 있고, 단일 지식 베이스와 독립적이에요:

사용 가능한 모델 조회하기

  • Get Available Models: 주어진 model_type에 사용 가능한 모델. 지식 베이스 설정 때 임베딩 모델은 text-embedding, 재순위화 모델은 rerank로 질의하면 돼요.

Knowledge 파이프라인 실행하기

Knowledge 파이프라인은 데이터소스에서 데이터를 수집해 문서로 만드는 워크플로예요:

  • Upload Pipeline File: 파이프라인이 처리할 파일을 업로드해요.
  • List Datasource Plugins: 파이프라인에 설정된 데이터소스 노드—기본 게시 버전, 혹은 is_published=false로 초안 버전.
  • Run Datasource Node: 데이터소스 노드 하나를 실행하고 결과를 스트리밍해요. 한 스텝을 단독으로 테스트하기 좋아요.
  • Run Pipeline: streaming 또는 blocking 응답 모드로 전체 파이프라인을 실행해요. is_published로 게시 버전과 현재 초안 중 하나를 선택해요.

더 알아보기 (Learn more)