버전: Next

Knowledge Builder API

Knowledge Builder는 문서 인덱싱, 청크 관리, 검색 기능을 제공하는 독립 서비스입니다.

별도 서비스

Knowledge Builder API는 Manager API와 별도의 서비스로 운영됩니다. Base URL이 다르므로 주의하세요.

Base URL: /api/v1/knowledger

전체 엔드포인트 요약

그룹	엔드포인트 수	설명
Knowledges	3	Knowledge 삭제, 검색, 인덱싱 프리뷰
Documents	2	Document 삭제, 검색
Indexing	7	웹/문서 인덱싱 시작·상태·삭제, 파일 다운로드
Chunks	6	청크 CRUD, 목록 조회, 일괄 삭제
Settings	4	기본 설정, 임베딩 모델 관리
System	1	헬스 체크

Knowledges

Knowledge 수준의 검색, 인덱싱 프리뷰, 저장소 삭제를 수행합니다.

Method	Path	Description
DELETE	`/knowledges/{kid}`	Knowledge 관련 청크 전체 삭제
POST	`/knowledges/{kid}/search`	Knowledge 내 검색
POST	`/knowledges/{kid}/indexing/preview`	인덱싱 프리뷰 (저장 없이 청킹 시뮬레이션)

DELETE /knowledges/{kid}

해당 Knowledge에 속한 모든 벡터 임베딩과 텍스트 인덱스 데이터를 삭제합니다.

Response

204 No Content

POST /knowledges/{kid}/search

Knowledge 전체 범위에서 청크를 검색합니다.

Request Body

Field	Type	Default	Description
`query`	string	-	검색 쿼리 (1~1000자)
`search_mode`	string	`VECTOR`	검색 모드: `VECTOR`, `TEXT`, `HYBRID`
`top_k`	integer	10	반환 결과 수 (1~100)
`score_threshold`	float	0.0	최소 점수 임계값 (0.0~1.0)

Response

200 OK

{
  "query": "D.Hub 사용법",
  "search_mode": "VECTOR",
  "total_results": 3,
  "results": [
    {
      "chunk_id": "chunk-001",
      "document_id": "knowledge.document-xyz789",
      "content": "D.Hub는 데이터 허브 플랫폼으로...",
      "score": 0.92,
      "highlights": [],
      "metadata": {}
    }
  ]
}

POST /knowledges/{kid}/indexing/preview

파일을 업로드하여 청킹 결과를 미리 확인합니다. 실제 저장은 수행하지 않습니다.

Query Parameters

Parameter	Type	Default	Description
`max_tokens`	integer	512	청크당 최대 토큰 (64~4096)
`max_preview`	integer	10	미리보기 청크 수 (1~50)
`strategy`	string	-	청킹 전략 (`fixed`, `markdown`, `hierarchical`, `hybrid`, `parent_child`)
`overlap_length`	integer	-	오버랩 길이 (0~500)

Request Body

multipart/form-data 형식으로 파일을 업로드합니다. (PDF, DOCX, PPTX, XLSX, HTML, TXT, MD)

Response

200 OK

{
  "total_chunks": 42,
  "preview_chunks": [
    {
      "sequence": 1,
      "content": "첫 번째 청크 내용...",
      "token_count": 128,
      "char_count": 512
    }
  ],
  "truncated": true,
  "file_name": "guide.pdf"
}

Documents

Document 수준의 청크 삭제와 검색을 수행합니다.

Method	Path	Description
DELETE	`/knowledges/{kid}/documents/{did}`	Document 관련 청크 삭제
POST	`/knowledges/{kid}/documents/{did}/search`	Document 내 검색

DELETE /knowledges/{kid}/documents/{did}

해당 Document에 속한 모든 청크를 벡터·텍스트 저장소에서 삭제합니다.

Response

204 No Content

POST /knowledges/{kid}/documents/{did}/search

특정 Document 범위 내에서 청크를 검색합니다. Request/Response 형식은 Knowledge 검색과 동일합니다.

Indexing

웹 URL과 문서 파일에 대한 인덱싱(청킹 → 임베딩 → 저장)을 관리합니다.

모든 인덱싱 엔드포인트는 /knowledges/{kid}/documents/{did}/indexing 하위에 있습니다.

웹 인덱싱

Method	Path	Description
POST	`.../indexing/web`	웹 인덱싱 시작
GET	`.../indexing/web`	웹 인덱싱 상태 조회
DELETE	`.../indexing/web`	웹 인덱싱 삭제

POST .../indexing/web

웹 URL 크롤링 및 인덱싱을 시작합니다. Document의 options.url에 설정된 URL을 크롤링합니다.

Response: 202 Accepted

{
  "message": "Web indexing started"
}

GET .../indexing/web

현재 웹 인덱싱 상태를 조회합니다.

Response: 200 OK

{
  "status": "READY"
}

문서 파일 인덱싱

Method	Path	Description
POST	`.../indexing/doc`	문서 파일 인덱싱 시작
GET	`.../indexing/doc`	문서 인덱싱 상태 조회
DELETE	`.../indexing/doc`	문서 인덱싱 삭제
GET	`.../indexing/doc/file`	원본 파일 다운로드

POST .../indexing/doc

문서 파일을 업로드하여 인덱싱을 시작합니다. 파일을 생략하면 이전에 저장된 파일을 재사용합니다.

Request Body: multipart/form-data (file 필드, 선택적)

Response: 202 Accepted

{
  "message": "Document indexing started"
}

GET .../indexing/doc/file

인덱싱에 사용된 원본 파일을 다운로드합니다.

Response: 파일 스트림 (Content-Disposition: attachment)

Chunks

Document 하위의 청크를 직접 관리합니다. MANUAL 타입 문서에서 청크의 생성·수정·삭제가 가능합니다.

모든 엔드포인트는 /knowledges/{kid}/documents/{did}/chunks 하위에 있습니다.

Method	Path	Description
POST	`/chunks`	청크 생성
GET	`/chunks`	청크 목록 조회 (페이지네이션)
GET	`/chunks/{id}`	청크 상세 조회
PATCH	`/chunks/{id}`	청크 수정
DELETE	`/chunks/{id}`	청크 삭제
DELETE	`/chunks`	청크 일괄 삭제

POST /chunks

새로운 청크를 생성합니다. VECTOR 타겟이 활성화된 경우 임베딩이 자동 생성됩니다.

Request Body

{
  "content": "청크 텍스트 내용",
  "metadata": {"source": "manual", "page": 1}
}

Response

201 Created

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "content": "청크 텍스트 내용",
  "metadata": {"source": "manual", "page": 1},
  "created_at": "2024-06-15T10:30:00Z"
}

GET /chunks

페이지네이션으로 청크 목록을 조회합니다.

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	페이지 번호 (1부터)
`page_size`	integer	20	페이지당 항목 수 (1~100)

Response

200 OK

{
  "data": [
    {
      "id": "550e8400-...",
      "type": "TEXT",
      "content": "청크 내용...",
      "metadata": {},
      "storages": ["TEXT", "VECTOR"],
      "created_at": "2024-06-15T10:30:00Z",
      "updated_at": null
    }
  ],
  "meta": {
    "total": 42,
    "page": 1,
    "page_size": 20,
    "total_pages": 3
  }
}

PATCH /chunks/{id}

기존 청크의 내용이나 메타데이터를 수정합니다. 내용이 변경되면 임베딩이 재생성됩니다.

Request Body

{
  "content": "수정된 청크 내용",
  "metadata": {"reviewed": true}
}

Settings

Knowledge Builder 서비스의 전역 설정을 관리합니다.

Method	Path	Description
GET	`/settings/defaults`	기본 처리 옵션 조회
PUT	`/settings/defaults`	기본 처리 옵션 수정
GET	`/settings/embedding-model`	현재 임베딩 모델 정보
GET	`/settings/embedding-models`	사용 가능한 임베딩 모델 목록

GET /settings/embedding-model

현재 설정된 임베딩 모델의 상세 정보를 조회합니다.

Response

200 OK

{
  "model_name": "BAAI/bge-m3",
  "model_version": null,
  "dimensions": 1024,
  "max_tokens": 8192
}

GET /settings/embedding-models

사용 가능한 모든 임베딩 모델을 조회합니다.

Response

200 OK

{
  "models": [
    {
      "id": "BAAI/bge-m3",
      "name": "BAAI/bge-m3",
      "provider": "local",
      "dimensions": 1024,
      "max_tokens": 8192,
      "supports_image": false,
      "is_default": true
    }
  ]
}

System

GET /system/health

Knowledge Builder 서비스의 상태를 확인합니다.

Response

200 OK

{
  "status": "healthy",
  "timestamp": "2024-06-15T10:30:00Z",
  "components": {}
}

사용 예시

cURL

# Knowledge 내 검색
curl -X POST https://api.dhub.io/api/v1/knowledger/knowledges/knowledge-abc123/search \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "데이터 파이프라인 설정 방법",
    "search_mode": "HYBRID",
    "top_k": 5
  }'

# 문서 파일 인덱싱 시작
curl -X POST https://api.dhub.io/api/v1/knowledger/knowledges/knowledge-abc123/documents/doc-xyz/indexing/doc \
  -H "Authorization: Bearer <access_token>" \
  -F "file=@guide.pdf"

# 청크 목록 조회
curl "https://api.dhub.io/api/v1/knowledger/knowledges/knowledge-abc123/documents/doc-xyz/chunks?page=1&page_size=20" \
  -H "Authorization: Bearer <access_token>"

# 수동 청크 생성
curl -X POST https://api.dhub.io/api/v1/knowledger/knowledges/knowledge-abc123/documents/doc-xyz/chunks \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "수동으로 추가하는 청크 내용입니다.",
    "metadata": {"source": "manual"}
  }'

# 임베딩 모델 목록 조회
curl https://api.dhub.io/api/v1/knowledger/settings/embedding-models \
  -H "Authorization: Bearer <access_token>"

Manager API와의 관계

Knowledge와 Document의 메타데이터(이름, 태그 등)는 Knowledge API를 통해 Manager에서 관리합니다. Knowledge Builder는 인덱싱, 청크, 검색 등 AI/RAG 관련 기능만을 담당합니다.

전체 엔드포인트 요약​

Knowledges​

DELETE /knowledges/{kid}​

Response​

POST /knowledges/{kid}/search​

Request Body​

Response​

POST /knowledges/{kid}/indexing/preview​

Query Parameters​

Request Body​

Response​

Documents​

DELETE /knowledges/{kid}/documents/{did}​

Response​

POST /knowledges/{kid}/documents/{did}/search​

Indexing​

웹 인덱싱​

POST .../indexing/web​

GET .../indexing/web​

문서 파일 인덱싱​

POST .../indexing/doc​

GET .../indexing/doc/file​

Chunks​

POST /chunks​

Request Body​

Response​

GET /chunks​

Query Parameters​

Response​

PATCH /chunks/{id}​

Request Body​

Settings​

GET /settings/embedding-model​

Response​

GET /settings/embedding-models​

Response​

System​

GET /system/health​

Response​

사용 예시​

cURL​

전체 엔드포인트 요약

Knowledges

DELETE /knowledges/{kid}

Response

POST /knowledges/{kid}/search

Request Body

Response

POST /knowledges/{kid}/indexing/preview

Query Parameters

Request Body

Response

Documents

DELETE /knowledges/{kid}/documents/{did}

Response

POST /knowledges/{kid}/documents/{did}/search

Indexing

웹 인덱싱

POST .../indexing/web

GET .../indexing/web

문서 파일 인덱싱

POST .../indexing/doc

GET .../indexing/doc/file

Chunks

POST /chunks

Request Body

Response

GET /chunks

Query Parameters

Response

PATCH /chunks/{id}

Request Body

Settings

GET /settings/embedding-model

Response

GET /settings/embedding-models

Response

System

GET /system/health

Response

사용 예시

cURL