웹 크롤링
D.Hub Knowledge의 웹 크롤링 기능은 지정된 URL을 시작점으로 웹사이트의 콘텐츠를 자동으로 수집하고, 이를 청크 단위로 분할하여 Knowledge 저장소에 인덱싱합니다. 기술 문서 사이트, 블로그, 위키 등 다양한 웹 소스에서 지식을 구축할 때 유용합니다.
크롤링 엔진은 정적 HTML 페이지는 물론 JavaScript로 렌더링되는 동적 페이지(SPA)까지 처리합니다. 수집된 콘텐츠는 설정된 청킹 전략에 따라 분할된 후, 선택한 저장소(Vector·Text)에 인덱싱됩니다.
새 웹 크롤링 작업 생성
Knowledge 상세 화면의 문서 (Documents) 탭에서 Web 소스를 선택하면 웹 크롤링 작업 생성 페이지(/knowledge/:knowledgeId/documents/web/new)로 이동합니다.
기본 정보
| 항목 | 필수 | 설명 |
|---|---|---|
| 시작 URL | 필수 | 크롤링을 시작할 웹페이지의 URL (https://docs.example.com) |
| 문서 제목 | 선택 | 미입력 시 페이지 타이틀에서 자동 감지 |
| 설명 | 선택 | 크롤링 작업에 대한 메모 |
크롤링 옵션
기본 정보 입력 후, Crawl Options 섹션을 펼쳐 크롤링 동작을 세부 조정할 수 있습니다.
크롤링 전략
| 전략 | 설명 | 적합한 상황 |
|---|---|---|
| 너비 우선 (BFS) | 같은 깊이의 페이지를 먼저 수집한 후 다음 깊이로 이동 | 사이트의 전체 구조를 고르게 수집할 때 (기본값) |
| 깊이 우선 (DFS) | 한 경로를 끝까지 탐색한 후 다음 경로로 이동 | 특정 하위 섹션을 집중적으로 수집할 때 |
| 최적 우선 (BEST_FIRST) | 링크 중요도 점수를 기반으로 관련성 높은 페이지 우선 수집 | 관련 콘텐츠를 효율적으로 수집할 때 |
탐색 범위
| 옵션 | 기본값 | 범위 | 설명 |
|---|---|---|---|
| 최대 깊이 | 3 | 1~10 | 시작 URL로부터의 링크 탐색 깊이 |
| 최대 페이지 | 100 | 1~10,000 | 수집할 최대 페이지 수 |
최대 페이지 수를 설정하지 않으면 크롤링이 매우 오래 걸릴 수 있습니다. 대규모 사이트를 크롤링할 때는 반드시 적절한 한도를 설정하세요.
추가 옵션
| 옵션 | 기본값 | 설명 |
|---|---|---|
| Sitemap 사용 | 활성화 | sitemap.xml을 활용하여 URL 목록을 빠르게 수집 |
| robots.txt 준수 | 활성화 | robots.txt 규칙을 확인하고 차단된 경로를 건너뜀 |
| 외부 링크 제외 | 활성화 | 시작 URL과 다른 도메인의 링크를 무시 |
콘텐츠 추출
크롤링된 웹 페이지에서 본문 콘텐츠를 추출하는 처리(불필요한 영역 제거, 동적 렌더링 처리 등)는 백엔드에서 자동으로 수행됩니다. 크롤링 작업 생성 화면에는 위의 크롤링 전략·탐색 범위·추가 옵션만 노출되며, 콘텐츠 추출 세부 파라미터를 직접 설정하는 입력란은 제공되지 않습니다.
인덱싱 옵션
수집된 콘텐츠가 저장될 검색 모드를 선택합니다.
| 검색 모드 | 설명 |
|---|---|
| 시맨틱 전용 (VECTOR) | 임베딩 벡터 기반 의미 유사도 검색만 사용 |
| 키워드 전용 (TEXT) | BM25 기반 키워드 전문 검색만 사용 |
| 하이브리드 (HYBRID) | Vector + Text를 결합한 하이브리드 검색 (RRF 기반 병합) |
대부분의 경우 하이브리드 (HYBRID) 모드가 가장 효과적입니다. 의미 기반 검색과 키워드 검색의 장점을 모두 활용할 수 있습니다.
청킹 옵션
크롤링된 콘텐츠를 검색에 적합한 크기로 분할하는 설정입니다. Chunking Options 섹션에서 조정할 수 있습니다.
| 옵션 | 기본값 | 범위 | 설명 |
|---|---|---|---|
| 청킹 전략 | 마크다운 (markdown) | - | 분할 방식 선택 (하이브리드 · 마크다운 · 계층적 · 고정 크기 · 상위-하위 · 문장 · 시맨틱 · 에이전틱) |
| 최대 청크 길이 | 500 | 100~4,000 | 하나의 청크에 포함되는 최대 토큰 수 |
| 오버랩 길이 | 50 | 0~500 | 인접 청크 간 겹치는 토큰 수 |
웹 크롤링의 기본 청킹 전략은 markdown으로 설정되어 있어, HTML에서 변환된 마크다운 구조(제목, 목록 등)를 기준으로 자연스럽게 분할됩니다. 전략별 상세 옵션은 청킹 및 옵션 문서를 참고하세요.
오버랩 길이는 최대 청크 길이의 10~25% 를 권장합니다. 예를 들어 최대 청크 길이가 500이면 오버랩은 50~125 사이가 적절합니다.
크롤링 작업 모니터링
크롤링 작업이 시작되면 작업 상세 페이지(/knowledge/:knowledgeId/documents/web/:jobId)에서 진행 상황을 실시간으로 모니터링할 수 있습니다.
작업 상태
| 상태 | 설명 |
|---|---|
| 처리 중 (PROCESSING) | 크롤링이 진행 중 |
| 일시 정지 (PAUSED) | 사용자에 의해 일시 정지됨 |
| 완료 (COMPLETED) | 크롤링 및 인덱싱이 성공적으로 완료됨 |
| 실패 (FAILED) | 오류로 인해 크롤링이 실패함 |
| 취소됨 (CANCELLED) | 사용자에 의해 취소됨 |
상태별 제어 버튼
작업 상태에 따라 헤더 영역에 다른 제어 버튼이 표시됩니다.
| 현재 상태 | 사용 가능한 버튼 | 동작 |
|---|---|---|
| 처리 중 (PROCESSING) | 일시정지 / 취소 | 진행 중인 크롤링을 일시정지하거나 즉시 중단 |
| 일시 정지 (PAUSED) | 재개 / 취소 | 일시정지된 크롤링을 재개하거나 취소 |
| 완료 (COMPLETED) | 재크롤링 | 동일한 설정으로 크롤링을 다시 시작 |
| 실패 (FAILED) | 재크롤링 | 실패한 크롤링을 다시 시도 |
| 취소됨 (CANCELLED) | 재크롤링 | 취소된 크롤링을 다시 시작 |
진행 상황 표시
크롤링이 진행 중일 때 상세 페이지 상단에 인덱싱 상태 카드가 표시됩니다. 이 카드에는 현재 상태와 진행 메시지가 포함되며, 5초 간격으로 자동 갱신됩니다.
크롤링이 완료되면 상태 카드를 닫을 수 있으며, 생성된 청크 목록이 테이블 형태로 표시됩니다.
청크 목록
크롤링 완료 후 생성된 청크는 페이지네이션된 테이블로 확인할 수 있습니다.
| 컬럼 | 설명 |
|---|---|
| # | 청크 순번 |
| Type | 청크 유형 (TEXT, IMAGE) |
| Content | 청크 내용 미리보기 (2줄) |
테이블의 행을 클릭하면 청크 상세 드로어가 열리며, 전체 내용을 확인하고 이전/다음 청크로 탐색할 수 있습니다.
문서 관리
작업 상세 페이지에서는 크롤링 결과 문서에 대해 다음 작업을 수행할 수 있습니다.
- 설명 편집: 문서에 대한 설명을 추가하거나 수정
- 문서 삭제: 문서와 관련된 모든 청크 및 임베딩을 영구 삭제
문서를 삭제하면 해당 문서의 모든 청크와 임베딩 데이터가 영구적으로 제거됩니다. 이 작업은 되돌릴 수 없습니다.
크롤링 전체 워크플로우
- Knowledge 상세 → 문서 (Documents) 탭 → Web 소스 선택
- 시작 URL 입력 및 크롤링 옵션 설정
- 필요 시 청킹/인덱싱 옵션 조정
- 크롤링 시작 버튼 클릭
- 작업 상세 페이지에서 진행 상황 모니터링
- 완료 후 생성된 청크 확인 및 검색 테스트로 품질 검증
- 기술 문서 사이트: 너비 우선 (BFS) 전략, 최대 깊이 3~5, 외부 링크 제외 활성화
- 블로그/위키: 최적 우선 (BEST_FIRST) 전략, 최대 페이지 수 제한, Sitemap 활용
- 대규모 사이트: 최대 페이지 수를 적절히 제한하여 과도한 수집 방지