287 lines
8.0 KiB
Markdown
287 lines
8.0 KiB
Markdown
# Ontology Crawler Platform
|
|
|
|
향수 구독 플랫폼을 첫 사용 사례로 삼되, 차, 커피, 캔들, 디퓨저, 영양제, 선물, 패션 소품 같은 개인화 구독 추천 서비스에 재사용할 수 있는 범용 크롤러/온톨로지 기반 지식 DB MVP입니다.
|
|
|
|
## 핵심 아이디어
|
|
|
|
이 시스템은 웹에서 가져온 문장을 곧바로 사실로 저장하지 않습니다. 모든 정보는 `Claim`으로 저장됩니다.
|
|
|
|
```yaml
|
|
subject: Product A
|
|
predicate: hasTopNote
|
|
object: Bergamot
|
|
source: OfficialSite
|
|
evidence_text: Top notes: Bergamot, Neroli
|
|
confidence: 0.95
|
|
```
|
|
|
|
추천 시스템은 원문 복제가 아니라, 출처, 근거, 신뢰도, 갱신일을 가진 온톨로지 매핑 지식을 사용합니다.
|
|
|
|
## 아키텍처
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
A["URL Discovery"] --> B["Page Fetch"]
|
|
B --> C["HTML Clean"]
|
|
C --> D["Site Parser Plugin"]
|
|
D --> E["Extractor Provider"]
|
|
E --> F["Ontology Mapping"]
|
|
F --> G["Deduplication"]
|
|
G --> H["Confidence Scoring"]
|
|
H --> I["Knowledge DB"]
|
|
I --> J["Recommendation API"]
|
|
I --> K["Update Scheduling"]
|
|
```
|
|
|
|
구성 단위:
|
|
|
|
- `Project`: 향수 구독, 차 구독, 선물 추천 같은 프로젝트 단위 설정
|
|
- `Source`: 공식몰, 마켓플레이스, 리뷰 사이트 같은 데이터 출처
|
|
- `Page`: 수집된 URL과 정제 텍스트 요약
|
|
- `Entity`: 상품, 브랜드, 노트, 무드, 계절, 상황 등 의미 객체
|
|
- `Claim`: 출처가 주장한 정보 단위
|
|
- `Evidence`: Claim의 근거 문장
|
|
- `Relation`: Entity 간 집계 관계
|
|
- `ExtractionLog`: 추출 방식, Provider, 로그
|
|
|
|
## 폴더 구조
|
|
|
|
```text
|
|
crawler_platform/
|
|
app/
|
|
main.py
|
|
config/
|
|
core/
|
|
crawler/
|
|
extractor/
|
|
ontology/
|
|
database/
|
|
recommendation/
|
|
scheduler/
|
|
domains/
|
|
perfume/
|
|
tea/
|
|
coffee/
|
|
candle/
|
|
supplement/
|
|
gift/
|
|
api/
|
|
cli/
|
|
configs/
|
|
perfume_subscription.yaml
|
|
tests/
|
|
README.md
|
|
```
|
|
|
|
## DB 스키마
|
|
|
|
초기 MVP는 SQLAlchemy ORM으로 SQLite와 PostgreSQL을 모두 지원합니다.
|
|
|
|
필수 테이블:
|
|
|
|
- `projects`: 프로젝트 이름, 도메인, JSON 설정
|
|
- `sources`: 출처 타입, 신뢰도, robots 정책, rate limit
|
|
- `pages`: URL, fetch 상태, content hash, 정제 텍스트 요약
|
|
- `entities`: 범용 의미 객체
|
|
- `attributes`: Entity 속성
|
|
- `relations`: Entity 간 집계 관계
|
|
- `claims`: 출처가 주장한 subject-predicate-object 정보
|
|
- `evidence`: Claim 근거 텍스트
|
|
- `extraction_logs`: 추출 Provider와 로그
|
|
- `crawl_jobs`: 예약 수집 작업
|
|
- `user_profiles`: 추천 사용자
|
|
- `user_preferences`: 취향 구조
|
|
- `feedback_logs`: 추천 피드백
|
|
|
|
## 설치
|
|
|
|
```bash
|
|
pip install -r requirements.txt
|
|
playwright install chromium
|
|
```
|
|
|
|
정적 페이지는 `requests + BeautifulSoup`로 처리합니다. 동적 페이지가 필요하면 config에서 `fetcher: playwright`로 바꾸면 됩니다.
|
|
|
|
## CLI 사용
|
|
|
|
DB 초기화:
|
|
|
|
```bash
|
|
python -m crawler_platform.app.cli.main --db sqlite:///crawler_platform.db init-db
|
|
```
|
|
|
|
향수 프로젝트 생성:
|
|
|
|
```bash
|
|
python -m crawler_platform.app.cli.main --db sqlite:///crawler_platform.db create-project --config configs/perfume_subscription.yaml
|
|
```
|
|
|
|
온톨로지 조회:
|
|
|
|
```bash
|
|
python -m crawler_platform.app.cli.main ontology --domain perfume
|
|
```
|
|
|
|
단일 URL 수집:
|
|
|
|
```bash
|
|
python -m crawler_platform.app.cli.main --db sqlite:///crawler_platform.db crawl-url \
|
|
--config configs/perfume_subscription.yaml \
|
|
--source official_brand_site \
|
|
--url https://example.com/perfume/product-page
|
|
```
|
|
|
|
네트워크 없이 로컬 샘플 HTML로 파이프라인을 확인할 수도 있습니다.
|
|
|
|
```bash
|
|
python -m crawler_platform.app.cli.main --db sqlite:///crawler_platform.db crawl-url \
|
|
--config configs/perfume_subscription.yaml \
|
|
--source official_brand_site \
|
|
--url tests/fixtures/sample_perfume.html
|
|
```
|
|
|
|
분석기 Provider를 바꿀 수도 있습니다. 기본값은 규칙 기반이며, AI Provider는 모델/API 키 또는 로컬 서버 설정이 필요합니다.
|
|
|
|
```bash
|
|
python -m crawler_platform.app.cli.main --db sqlite:///crawler_platform.db crawl-url \
|
|
--config configs/perfume_subscription.yaml \
|
|
--source official_brand_site \
|
|
--url tests/fixtures/sample_perfume.html \
|
|
--extractor-provider ollama \
|
|
--extractor-model llama3.1
|
|
```
|
|
|
|
지원 Provider:
|
|
|
|
- `rule_based`: 정규식/키워드 기반 기본 분석기
|
|
- `openai`: OpenAI 호환 Chat Completions API, `OPENAI_API_KEY`와 모델 필요
|
|
- `ollama`: 로컬 Ollama, 기본 URL `http://localhost:11434/api/chat`
|
|
- `lm_studio`: LM Studio OpenAI 호환 서버, 기본 URL `http://localhost:1234/v1/chat/completions`
|
|
|
|
LM Studio 사용 순서:
|
|
|
|
1. LM Studio에서 `Developer` 또는 Local Server 화면을 엽니다.
|
|
2. OpenAI Compatible Server를 켭니다.
|
|
3. 서버 주소가 보통 `http://localhost:1234/v1`인지 확인합니다.
|
|
4. 웹 UI의 Analyzer에서 `LM Studio`를 선택합니다.
|
|
5. Base URL은 비워두거나 `http://localhost:1234/v1`을 넣습니다.
|
|
6. `연결 테스트`로 모델 목록을 불러옵니다.
|
|
7. 모델이 자동 입력되면 `수집 실행`을 누릅니다.
|
|
|
|
Claim 확인:
|
|
|
|
```bash
|
|
python -m crawler_platform.app.cli.main --db sqlite:///crawler_platform.db claims --project perfume_subscription
|
|
```
|
|
|
|
추천 예시:
|
|
|
|
```bash
|
|
python -m crawler_platform.app.cli.main --db sqlite:///crawler_platform.db recommend \
|
|
--project perfume_subscription \
|
|
--target-type Perfume \
|
|
--preferences-json "{\"preferred_notes\":[\"Bergamot\",\"Musk\"],\"preferred_moods\":[\"Fresh\"],\"season_context\":\"Summer\"}"
|
|
```
|
|
|
|
## FastAPI 실행
|
|
|
|
```bash
|
|
uvicorn crawler_platform.app.main:app --reload
|
|
```
|
|
|
|
브라우저에서 관리자 UI를 열 수 있습니다.
|
|
|
|
```text
|
|
http://127.0.0.1:8000/
|
|
```
|
|
|
|
관리자 UI에서 가능한 작업:
|
|
|
|
- 프로젝트 config 경로로 프로젝트 생성
|
|
- Source 선택 후 URL 또는 로컬 HTML 샘플 수집
|
|
- 분석기 Provider 선택: Rule-based, OpenAI, Ollama, LM Studio
|
|
- 도메인 온톨로지, Entity, Claim 조회
|
|
- Claim 신뢰도와 사유 수동 수정
|
|
- Entity ID 기준 병합
|
|
- 추천용 태그 확인
|
|
- 사용자 취향 입력 후 추천 결과 테스트
|
|
|
|
주요 엔드포인트:
|
|
|
|
- `GET /health`
|
|
- `GET /`
|
|
- `GET /projects`
|
|
- `POST /projects`
|
|
- `GET /ontology/{domain}`
|
|
- `POST /crawl`
|
|
- `GET /projects/{project_name}/entities`
|
|
- `GET /projects/{project_name}/claims`
|
|
- `PATCH /claims/{claim_id}/confidence`
|
|
- `POST /entities/merge`
|
|
- `GET /projects/{project_name}/recommendation-tags`
|
|
- `POST /recommend`
|
|
|
|
## 향수 도메인 MVP
|
|
|
|
기본 엔티티:
|
|
|
|
- `Perfume`
|
|
- `Brand`
|
|
- `Note`
|
|
- `Accord`
|
|
- `Mood`
|
|
- `Season`
|
|
- `Occasion`
|
|
- `Review`
|
|
- `Price`
|
|
- `ProductPage`
|
|
|
|
기본 관계:
|
|
|
|
- `hasBrand`
|
|
- `hasTopNote`
|
|
- `hasMiddleNote`
|
|
- `hasBaseNote`
|
|
- `hasAccord`
|
|
- `evokesMood`
|
|
- `suitableForSeason`
|
|
- `suitableForOccasion`
|
|
- `similarTo`
|
|
- `soldBy`
|
|
- `hasPrice`
|
|
- `hasReviewKeyword`
|
|
|
|
규칙 기반 추출기는 `Top notes`, `Middle notes`, `Base notes`, 가격, 무드, 계절, 사용 상황, 리뷰 키워드를 우선 추출합니다.
|
|
|
|
## 확장 방법
|
|
|
|
새 도메인을 추가할 때는 다음을 추가하면 됩니다.
|
|
|
|
1. `configs/{project}.yaml`에 `domain`, `target_entities`, `fields`, `sources`, `ontology` 정의
|
|
2. `crawler_platform/app/core/ontology/definitions.py`에 도메인 온톨로지 추가
|
|
3. 필요하면 `crawler_platform/app/domains/{domain}/extractor.py`에 도메인별 Extractor 구현
|
|
4. 사이트별 HTML 구조가 특수하면 `SiteParser`를 구현하고 `ParserRegistry`에 등록
|
|
5. OpenAI, Ollama, LM Studio 등 AI 추출은 `AIExtractor`를 상속하는 Provider로 추가
|
|
|
|
## 컴플라이언스 설계
|
|
|
|
- `robots.txt` 확인 구조 포함
|
|
- Source별 rate limit과 User-Agent 적용
|
|
- retry, timeout 고려
|
|
- 원문 전체 저장 대신 `evidence_text`와 정제 요약 중심 저장
|
|
- 상품 설명은 복제 저장보다 Claim, 태그, 요약, 근거 중심으로 사용
|
|
|
|
## 테스트
|
|
|
|
```bash
|
|
pytest
|
|
```
|
|
|
|
외부 테스트 러너가 없을 때는 기본 `unittest` 스모크 테스트를 실행할 수 있습니다.
|
|
|
|
```bash
|
|
python -m unittest tests.test_smoke_unittest -v
|
|
```
|
|
|
|
현재 테스트는 향수 규칙 기반 추출, config 로더, 로컬 HTML fetch 경로를 검증합니다.
|