웹 크롤링
D.Hub Knowledge의 웹 크롤링 기능은 지정된 URL을 시작점으로 웹사이트의 콘텐츠를 자동으로 수집하고, 이를 청크 단위로 분할하여 Knowledge 저장소에 인덱싱합니다. 기술 문서 사이트, 블로그, 위키 등 다양한 웹 소스에서 지식을 구축할 때 유용합니다.
크롤링 엔진은 AI 기반 웹 크롤러를 통해 동작하며, 정적 HTML 페이지는 물론 JavaScript로 렌더링되는 동적 페이지(SPA)까지 지원합니다. 수집된 콘텐츠는 설정된 청킹 전략에 따라 분할된 후, 벡터 DB, 텍스트 검색 DB, 그래프 DB 중 선택한 저장소에 인덱싱됩니다.
새 웹 크롤링 작업 생성
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과 다른 도메인의 링크를 무시 |
콘텐츠 처리 옵션
크롤링된 웹 페이지에서 유용한 콘텐츠만 추출하기 위한 옵션입니다. 이 옵션들은 옵션 레퍼런스의 콘텐츠 옵션에 해당하며, 실제 UI에서는 고급 설정으로 제공됩니다.
| 옵션 | 설명 | 기본값 |
|---|---|---|
JS 실행 (execute_js) | JavaScript를 실행하여 동적으로 렌더링되는 페이지의 콘텐츠를 수집 | 활성화 |
콘텐츠 필터 (content_filter) | BM25 또는 Pruning 알고리즘으로 불필요한 콘텐츠를 자동 필터링 | PRUNING |
CSS 선택자 (css_selector) | 페이지에서 특정 요소만 추출 (예: main, article, .content) | 미설정 |
제외 태그 (excluded_tags) | 추출에서 제외할 HTML 태그 목록 (예: nav, footer, aside) | 미설정 |
JS 실행 옵션은 SPA나 동적 콘텐츠가 있는 사이트에서만 활성화하세요. 정적 사이트에서는 불필요한 리소스를 소모합니다.
인덱싱 옵션
수집된 콘텐츠가 저장될 검색 모드를 선택합니다.
| 검색 모드 | 설명 |
|---|---|
| VECTOR (Semantic Only) | 임베딩 벡터 기반 의미 유사도 검색만 사용 |
| TEXT (Keyword Only) | BM25 기반 키워드 전문 검색만 사용 |
| HYBRID (권장) | Vector + Text를 결합한 하이브리드 검색 (RRF 기반 병합) |
대부분의 경우 HYBRID 모드가 가장 효과적입니다. 의미 기반 검색과 키워드 검색의 장점을 모두 활용할 수 있습니다.
청킹 옵션
크롤링된 콘텐츠를 검색에 적합한 크기로 분할하는 설정입니다. Chunking Options 섹션에서 조정할 수 있습니다.
| 옵션 | 기본값 | 범위 | 설명 |
|---|---|---|---|
| 청킹 전략 | markdown | - | 분할 방식 선택 (hybrid, markdown, hierarchical, fixed, parent_child) |
| 최대 청크 길이 | 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 | 취소 | 진행 중인 크롤링을 즉시 중단 |
| COMPLETED | 재크롤링 | 동일한 설정으로 크롤링을 다시 시작 |
| FAILED | 재크롤링 | 실패한 크롤링을 다시 시도 |
진행 상황 표시
크롤링이 진행 중일 때 상세 페이지 상단에 인덱싱 상태 카드가 표시됩니다. 이 카드에는 현재 상태와 진행 메시지가 포함되며, 5초 간격으로 자동 갱신됩니다.
크롤링이 완료되면 상태 카드를 닫을 수 있으며, 생성된 청크 목록이 테이블 형태로 표시됩니다.
청크 목록
크롤링 완료 후 생성된 청크는 페이지네이션된 테이블로 확인할 수 있습니다.
| 컬럼 | 설명 |
|---|---|
| # | 청크 순번 |
| Type | 청크 유형 (TEXT, IMAGE) |
| Content | 청크 내용 미리보기 (2줄) |
테이블의 행을 클릭하면 청크 상세 드로어가 열리며, 전체 내용을 확인하고 이전/다음 청크로 탐색할 수 있습니다.
문서 관리
작업 상세 페이지에서는 크롤링 결과 문서에 대해 다음 작업을 수행할 수 있습니다.
- 설명 편집: 문서에 대한 설명을 추가하거나 수정
- 문서 삭제: 문서와 관련된 모든 청크 및 임베딩을 영구 삭제
문서를 삭제하면 해당 문서의 모든 청크와 임베딩 데이터가 영구적으로 제거됩니다. 이 작업은 되돌릴 수 없습니다.
크롤링 전체 워크플로우
- Knowledge 상세 → Documents 탭 → Web 소스 선택
- 시작 URL 입력 및 크롤링 옵션 설정
- 필요 시 청킹/인덱싱 옵션 조정
- Start Crawl 클릭하여 크롤링 시작
- 작업 상세 페이지에서 진행 상황 모니터링
- 완료 후 생성된 청크 확인 및 검색 테스트로 품질 검증
- 기술 문서 사이트: BFS 전략, 최대 깊이 3~5, 외부 링크 제외 활성화
- 블로그/위키: BEST_FIRST 전략, 최대 페이지 수 제한, CSS 선택자로 본문 영역 지정
- SPA (React/Vue 기반): JS 실행 활성화, 무한 스크롤 처리 고려