`, `include_tables`
- 처리: row/cell 구조 변환, header cell role 지정, colspan span 계산
- 출력: XML tree의 `table/row/cell`
- 실패: table 옵션 off이면 제외
- 수용 기준: ontology relation 후보 생성 단계에서 행/열 구조를 읽을 수 있어야 한다.
### F-006 링크/이미지 보존
- 입력: HTML anchor/img, base URL
- 처리: 상대 URL 절대화, 내부 `ref`/`graphic` 태그 변환
- 출력: XML tree 내 `target`, image attribute
- 실패: 옵션 off이면 텍스트만 남거나 제거
- 수용 기준: source graph edge와 media evidence로 저장 가능해야 한다.
### F-007 메타데이터 추출
- 입력: HTML tree, 입력 URL, date params, blacklist
- 처리: OpenGraph, Twitter, meta, JSON-LD, canonical, heading, htmldate
- 출력: `Document` metadata fields
- 실패: 후보 없음 시 None
- 수용 기준: `only_with_metadata=True`에서 `date/title/url` 필수 조건을 적용해야 한다.
### F-008 언어 필터
- 입력: HTML lang 또는 추출 텍스트, target language
- 처리: HTML lang quick check 또는 `py3langid` 판별
- 출력: pass/fail, `Document.language`
- 실패: target 불일치 시 문서 폐기
- 수용 기준: 언어 판별 패키지가 없을 때는 HTML lang 기반 검사로 degrade해야 한다.
### F-009 Feed URL 발견
- 입력: 홈페이지/feed URL, target_lang, external
- 처리: feed 직접 파싱, HTML feed link discovery, Google News fallback
- 출력: 기사 URL 목록
- 실패: 다운로드 실패, feed 없음
- 수용 기준: 중복 제거와 도메인 유사도 필터가 적용되어야 한다.
### F-010 Sitemap URL 발견
- 입력: 홈페이지/sitemap URL, target_lang, external, max_sitemaps
- 처리: robots.txt sitemap, sitemap guess, nested sitemap, XML/TXT parsing, hreflang
- 출력: 페이지 URL 목록
- 실패: base URL unreachable, invalid sitemap
- 수용 기준: sitemap index가 깊어도 `max_sitemaps` 제한을 지켜야 한다.
### F-011 Focused crawling
- 입력: homepage, max_seen_urls, max_known_urls, todo, known_links, lang
- 처리: robots.txt, crawl delay, navigation URL 우선순위, URL store update
- 출력: 다음 방문 URL 목록, 알려진 URL 목록
- 실패: 시작 URL invalid, frontier 고갈
- 수용 기준: 작업 재개를 위해 `todo`, `known_links`를 저장/재주입할 수 있어야 한다.
### F-012 중복 제거
- 입력: XML element 또는 문서 텍스트
- 처리: LRU exact segment count, SimHash fingerprint
- 출력: duplicate bool 또는 fingerprint
- 실패: 짧은 텍스트는 중복 검사 bypass
- 수용 기준: 문서 fingerprint가 DB unique/near-duplicate 정책과 연결되어야 한다.
### F-013 출력 변환
- 입력: `Document`, `Extractor.format`
- 처리: XML cleanup, JSON/CSV/HTML/TXT/Markdown/XML/TEI 변환
- 출력: 문자열
- 실패: unsupported format이면 AttributeError/ValueError
- 수용 기준: 동일 문서에서 최소 TXT, JSON, XML 출력을 생성할 수 있어야 한다.
### F-014 설정 관리
- 입력: `settings.cfg`, `Extractor`, 함수 인자
- 처리: config parse, 옵션 병합
- 출력: 실행 시 옵션 객체
- 실패: config 파일 없음, 필수 key 없음
- 수용 기준: 플랫폼 source profile에서 추출 설정을 생성할 수 있어야 한다.
### F-015 cache reset
- 입력: 없음
- 처리: module-level cache clear
- 출력: 없음
- 실패: 없음
- 수용 기준: 장시간 batch 또는 tenant 전환 시 cache를 초기화할 수 있어야 한다.
## 15. 품질 및 테스트 자산
테스트 구성:
- `tests/unit_tests.py`: 기본 추출/유틸 단위 테스트
- `tests/metadata_tests.py`: 메타데이터 추출
- `tests/json_metadata_tests.py`: JSON-LD 메타
- `tests/downloads_tests.py`: 다운로드
- `tests/feeds_tests.py`: feed
- `tests/sitemaps_tests.py`: sitemap
- `tests/spider_tests.py`: crawler
- `tests/deduplication_tests.py`: 중복 제거
- `tests/xml_tei_tests.py`: XML/TEI
- `tests/eval/`, `tests/cache/`: 실제 웹 페이지 평가 corpus
플랫폼 통합 테스트로 추가해야 할 것:
- 한국어 뉴스/블로그/쇼핑/위키/공공기관 샘플
- JS-heavy 사이트에서 raw HTML 한계 확인
- HTML table -> relation candidate 변환 테스트
- `bare_extraction` 결과의 provenance field completeness 테스트
- 동일 URL/동일 본문/near duplicate 처리 테스트
- source profile별 precision/recall 옵션 비교 테스트
## 16. 위험 요소와 대응
| 위험 | 설명 | 대응 |
|---|---|---|
| JS 렌더링 미지원 | 정적 HTML 기반 추출 | Playwright/Crawl4AI 등으로 렌더링 후 HTML을 Trafilatura에 입력 |
| 전역 상태 | HTTP pool, URL_STORE, LRU cache | 작업 단위 프로세스 격리 또는 reset |
| 사이트별 메타 노이즈 | tags/category/author가 부정확할 수 있음 | confidence와 source별 rule 적용 |
| 언어 판별 선택 의존성 | `py3langid` 없으면 제한적 | optional dependency 설치 또는 별도 언어 판별기 연결 |
| 표/이미지 실험적 옵션 | 모든 출력 형식에서 완전 보존되지 않음 | `output_format="python"` 또는 XML tree 직접 사용 |
| robots/정책 준수 | downloader 직접 사용 시 정책 책임 필요 | 플랫폼 crawler policy layer에서 관리 |
| 날짜 추출 recall/precision | `EXTENSIVE_DATE_SEARCH`에 따라 오탐 가능 | source별 date extraction profile 운영 |
## 17. 구현 권장 래퍼 인터페이스
```python
from dataclasses import dataclass
from typing import Optional
from trafilatura import bare_extraction
from trafilatura.settings import Extractor
@dataclass
class ExtractedWebDocument:
url: str
title: Optional[str]
author: Optional[str]
date: Optional[str]
sitename: Optional[str]
description: Optional[str]
text: str
body_xml: object
metadata: dict
fingerprint: Optional[str]
def extract_for_ontology(html: str, url: str, lang: Optional[str] = None) -> Optional[ExtractedWebDocument]:
options = Extractor(
output_format="python",
url=url,
with_metadata=True,
comments=False,
tables=True,
formatting=True,
links=True,
images=True,
dedup=True,
lang=lang,
)
doc = bare_extraction(html, options=options)
if not doc or not doc.text:
return None
return ExtractedWebDocument(
url=doc.url or url,
title=doc.title,
author=doc.author,
date=doc.date,
sitename=doc.sitename,
description=doc.description,
text=doc.text,
body_xml=doc.body,
metadata=doc.as_dict(),
fingerprint=doc.fingerprint,
)
```
## 18. 채택 우선순위
1. `bare_extraction()` 기반 ContentExtractionService 구현
2. `Document` metadata를 프로젝트 DB schema에 매핑
3. `Document.body` XML tree 기반 chunker 구현
4. `content_fingerprint()` 기반 중복 문서 정책 추가
5. `sitemap_search()`와 `find_feed_urls()`를 source discovery에 연결
6. 필요한 경우 `focused_crawler()`는 전역 상태 격리 후 채택
7. JS rendering 결과 HTML을 Trafilatura에 넣는 hybrid extractor 구성
## 19. 최종 판단
Trafilatura는 범용 온톨로지 구축 플랫폼에서 “웹 문서를 ontology-ready document로 정제하는 핵심 엔진”으로 채택할 가치가 높다. 본문 추출 알고리즘, 메타데이터 추출, 링크 발견, 중복 제거, 구조 출력이 이미 모듈화되어 있으며 Apache-2.0 라이선스라 기본 소스 활용에도 적합하다.
가장 좋은 통합 방향은 원본 코드를 크게 변형하지 않고, 플랫폼 내부에 얇은 adapter layer를 두는 것이다. Adapter layer는 source profile, 작업 격리, provenance 저장, 품질 점수, 온톨로지 후보 생성만 담당하고 Trafilatura의 본문/메타/URL 발견 로직은 원형에 가깝게 유지하는 편이 안정적이다.