버전: v0.1.0

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