lasta/AI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs

Browse Source
This commit is contained in:
LASTA_DEV01\lasta
2026-05-19 20:31:52 +09:00
parent 00407e7a08
commit e260e5f218
104 changed files with 12898 additions and 1709 deletions
Download Patch File Download Diff File Expand all files Collapse all files

301
README.md
View File

@@ -1,234 +1,81 @@
# Ontology Platform
# Ontology Platform
온톨로지 플랫폼은 웹에서 구조화된 지식(엔티티/관계)을 자동 추출, 검증, 저장하는 고속 시스템입니다.
본 프로젝트는 여러 검증된 오픈소스 기반 엔진들을 조합하여 구축된 온톨로지 구축 플랫폼이다.
**Phase 0-4** 전체 구현 완료 | 추출(10초) → 검증(<100ms) → 그래프 저장 → 벡터 검색
목표는 기존 엔진을 폐기하거나 새로 만드는 것이 아니라:
## 🚀 빠른 시작
- 기존 엔진을 최대한 유지하면서
- 부족한 플랫폼 기능을 확장하고
- 온톨로지 구축 워크플로우를 강화하며
- 상용화 가능한 구조로 발전시키는 것이다.
### 1. 설치
```bash
# 기본 설치 (Phase 0-1: 추출)
pip install fastapi uvicorn pydantic trafilatura httpx
# Phase 2 추가 (동적 페이지)
pip install crawl4ai
# Phase 4 추가 (Neo4j)
pip install neo4j sentence-transformers
```
### 2. Phase 0-1만 사용 (가장 간단)
```bash
# API 서버 시작
python -m uvicorn ontology_platform.ont_platform.api.phase0_app:app --reload
# URL에서 추출
curl -X POST "http://localhost:8000/api/v1/extract/url?url=https://example.com"
```
### 3. Phase 4 (그래프 검색) 포함
```bash
# Neo4j 시작
docker-compose -f docker-compose.neo4j.yml up -d
# API 서버 시작
python -m uvicorn ontology_platform.ont_platform.api.phase0_app:app --reload
# 추출 → 수집 → 검색
curl -X POST "http://localhost:8000/api/v1/extract/url?url=https://example.com"
curl -X POST "http://localhost:8000/api/v1/search/ingest" -d '{"entities": [...], "relations": [...]}'
curl "http://localhost:8000/api/v1/search/vector?query=machine+learning"
```
## 📋 Phase별 기능
| Phase | 기능 | 시간 | 상태 |
|-------|------|------|------|
| 0-1 | HTML 추출 (Trafilatura) | 10-15초 | ✅ |
| 2 | 동적 페이지 (Crawl4AI) | 20-30초 | ✅ |
| 3A | 경량 검증 (Pydantic) | <100ms | ✅ |
| 3B | SPARQL 검증 | <500ms | ✅ |
| 4 | Neo4j + 벡터 검색 | 50-200ms | ✅ |
## 🎯 사용 예시
### 예시 1: 기본 추출 (10초)
```bash
curl -X POST "http://localhost:8000/api/v1/extract/url?url=https://wikipedia.org/wiki/Python"
```
응답:
```json
{
"url": "https://wikipedia.org/wiki/Python",
"title": "Python - Wikipedia",
"entities": [
{
"id": "E_1",
"label": "Python",
"type": "ProgrammingLanguage",
"confidence": 0.95
}
],
"relations": [...],
"extraction_time_sec": 9.5,
"validation_passed": true
}
```
### 예시 2: 동적 페이지 (25초)
```bash
curl -X POST "http://localhost:8000/api/v1/extract/url?url=https://app.example.com&profile=dynamic_page"
```
### 예시 3: 그래프 수집 + 검색
```bash
# 1. 추출
RESULT=$(curl -s -X POST "http://localhost:8000/api/v1/extract/url?url=https://example.com")
# 2. Neo4j에 수집
curl -X POST "http://localhost:8000/api/v1/search/ingest" \
-H "Content-Type: application/json" \
-d "{\"entities\": $(echo $RESULT | jq '.entities'), \"relations\": $(echo $RESULT | jq '.relations')}"
# 3. 벡터 검색
curl "http://localhost:8000/api/v1/search/vector?query=programming&limit=10"
# 4. 그래프 통계
curl "http://localhost:8000/api/v1/search/stats"
# 5. 엔티티 이웃
curl "http://localhost:8000/api/v1/search/entity/E_1?depth=1"
```
## 🔧 설정
### Phase 선택 (validators.py)
```python
# 경량 검증 (기본)
guard = OntologyGuard(validator_type="lightweight")
# SPARQL 검증
guard = OntologyGuard(validator_type="ontocast")
```
### Neo4j 연결 (neo4j_adapter.py)
```python
# 기본값
config = Neo4jConfig() # localhost:7687
# 커스텀
config = Neo4jConfig(
uri="bolt://custom-host:7687",
username="user",
password="pass",
database="mydb"
)
adapter = Neo4jAdapter(config=config)
```
## 📊 API 문서
서버 시작 후:
- **Swagger UI**: http://localhost:8000/docs
- **ReDoc**: http://localhost:8000/redoc
### 주요 엔드포인트
```
POST /api/v1/extract/url 추출
GET /api/v1/search/stats 통계
POST /api/v1/search/vector 벡터 검색
GET /api/v1/search/entity/{id} 이웃 탐색
POST /api/v1/search/ingest 그래프 수집
```
## 🧪 테스트
```bash
# Phase 0-1
python test_phase0_extraction.py
# Phase 2
python test_phase2_crawl.py
# Phase 3A
python test_phase3_validation.py
# Phase 3B
python test_phase3_option_b.py
# Phase 4
python test_phase4_integration.py
```
## 📦 의존성
- **FastAPI**: API 프레임워크
- **Trafilatura**: HTML 추출
- **Crawl4AI**: 동적 크롤링 (선택)
- **Pydantic**: 데이터 검증
- **Neo4j**: 그래프 DB (선택)
- **SentenceTransformers**: 벡터 임베딩 (선택)
## 🐳 Docker
```bash
# Neo4j만
docker-compose -f docker-compose.neo4j.yml up -d
# 전체 스택 (향후)
docker-compose up -d
```
## 📚 상세 문서
- [구현 요약](IMPLEMENTATION_SUMMARY.md) - Phase 0-4 전체 개요
- [Phase 2](PHASE2_COMPLETION.md) - Crawl4AI 동적 크롤링
- [Phase 3A](PHASE3_COMPLETION.md) - 경량 검증
- [Phase 3B](PHASE3_OPTION_B.md) - SPARQL 검증
- [Phase 4](PHASE4_COMPLETION.md) - Neo4j 그래프 + 벡터 검색
## 🎓 설계 원칙
1. **Phase-gated**: 각 Phase는 선택사항
2. **Pluggable**: 여러 검증 방식 지원
3. **Async**: 높은 동시성
4. **Resilient**: 의존성 부재 시에도 동작
## 💡 다음 단계
### Phase 5: GraphRAG (선택)
- RDF ↔ Property Graph 변환
- Entity Resolver
- Subgraph retrieval
### Advanced Features
- Critic loop (자동 수정)
- Few-shot learning
- Zero-shot 분류
## 🔗 관련 링크
- [Neo4j 문서](https://neo4j.com/docs/)
- [SentenceTransformers](https://www.sbert.net/)
- [Trafilatura](https://trafilatura.python-engineering.com/)
- [FastAPI](https://fastapi.tiangolo.com/)
## 📝 라이센스
MIT License
기존 엔진은 이미 검증된 기반 자산으로 간주한다.
---
**Version**: 0.4.0 (Phase 0-4 완료)
**Updated**: 2026-05-14
# CORE DEVELOPMENT PRINCIPLES
## 기존 엔진 재사용 원칙
현재 시스템은 다음과 같은 검증된 오픈소스 기반 구조들을 포함한다.
- 웹 크롤링 엔진
- HTML 정제 시스템
- 엔티티 추출 구조
- 클레임 생성 구조
- 데이터 저장 구조
- 기존 분석 파이프라인
따라서:
- 기존 엔진을 임의로 교체하지 않는다.
- 없는 기능만 확장한다.
- 구조적 문제가 확인된 경우에만 수정 검토한다.
- 승인 없는 대규모 리팩토링을 금지한다.
- 전체 구조 재설계를 금지한다.
---
# TASK EXECUTION MODES
프로젝트 작업 모드는 세 가지로 구분된다.
---
## 1. PHASE WORKFLOW MODE
로드맵 기반 작업 수행 모드.
다음 명령이 포함될 때만 활성화.
- ^(다음 )?(페이즈|PHASE|phase)( \d+(-\d+)?)? 진행$
이 경우에만
PHASE_WORKFLOW.MD 를 읽고 작업을 진행한다.
---
## 2. PLANNING MODE
설계 및 roadmap 생성 모드.
다음 명령이 포함될 때만 활성화.
- ^(페이즈|PHASE|phase)( \d+(-\d+)?)? (생성|계획)$
이 경우에만
PHASE_PLANNING.md 를 읽고 작업을 진행한다.
---
# PROJECT STRUCTURE
```text
README.md
/docs/phases
PHASE_WORKFLOW.md
PHASE_PLANNING.md
PHASE_INDEX.md
/phase_01
/phase_02
/phase_03