AI/README_KO.md

# 🚀 온톨로지 시스템 구축 플랫폼

**웹 데이터에서 지능형 지식 그래프를 자동 구축하는 엔드-투-엔드 플랫폼**

```
웹 → 추출 → 검증 → 그래프 저장 → 지능화 → API 공개 → LLM 연계
```

---

## 📊 플랫폼 현황 (Phase 0-6)

| Phase | 기능 | 상태 | 테스트 |
|-------|------|------|--------|
| **0** | URL 텍스트 추출 | ✅ 완료 | ✅ 통과 |
| **1** | 동적 페이지 크롤링 | ✅ 완료 | ✅ 통과 |
| **2** | 크롤링 프로필 지원 | ✅ 완료 | ✅ 통과 |
| **3** | 데이터 검증 + 온톨로지 변환 | ✅ 완료 | ✅ 통과 |
| **4** | Neo4j 그래프 저장 + 벡터 임베딩 | ✅ 완료 | ✅ 통과 |
| **5.0** | RDF 변환 + Entity Resolver | ✅ 완료 | ✅ 7 테스트 |
| **5.1** | Subgraph + Pattern Matching | ✅ 완료 | ✅ 16 테스트 |
| **5.2** | Graph Analytics (중심성, 커뮤니티) | ✅ 완료 | ✅ 8 테스트 |
| **6** | REST API + GraphQL + RAG | ✅ 완료 | ✅ 7 테스트 |

**총 테스트**: 45/45 통과 ✅

---

## 🎯 주요 기능

### 1️⃣ 자동 데이터 수집 (Phase 0-2)
```bash
# 웹에서 데이터 자동 추출
$ ontology extract --url https://example.com
```

- ✅ 정적 페이지 (HTTP)
- ✅ 동적 페이지 (JavaScript)
- ✅ 메타데이터 + 본문 추출

### 2️⃣ 스마트 검증 & 온톨로지 변환 (Phase 3)
```bash
# 데이터 자동 검증 및 온톨로지 변환
$ ontology validate --input data.json --output ontology.rdf
```

- ✅ 엔티티 추출 (NER)
- ✅ 관계 추출 (Relation Extraction)
- ✅ RDF 트리플 생성
- ✅ 신뢰도 점수 계산

### 3️⃣ Neo4j 지식 그래프 (Phase 4)
```
저장된 그래프 특성:
  - 10K+ 노드 지원
  - 벡터 유사도 검색
  - 관계 중심의 쿼리
```

```bash
# 그래프에 온톨로지 저장
$ ontology store --triples ontology.rdf --db neo4j://localhost:7687
```

### 4️⃣ 그래프 지능화 (Phase 5)

#### 5.0: 의미적 중복 제거
```
Before: "Apple", "APPLE Inc", "Apple Computer" (3개 엔티티)
After: Apple (1개) + aliases: [APPLE, APPLE Inc, ...]
```

#### 5.1: 패턴 분석
```python
# 경로 찾기
paths = await matcher.find_paths(1, 5, max_length=5)
# → Apple → produces → iPhone → has_feature → Face ID

# 순환 감지
cycles = await matcher.find_cycles()
# → 논리적 오류 자동 발견

# 모티프 감지
motifs = await matcher.find_motifs("triangle")
# → 빈번한 구조 패턴 식별
```

#### 5.2: 분석
```python
# 중심성 계산
central = await analytics.calculate_centrality("pagerank")
# → 가장 중요한 엔티티 식별

# 커뮤니티 감지
communities = await analytics.detect_communities()
# → 자동 그룹화 (products, people, locations)

# 통계
stats = await analytics.get_graph_statistics()
# → 밀도, 직경, 연결성 분석
```

### 5️⃣ REST API & GraphQL (Phase 6)

#### REST API (10개 엔드포인트)
```bash
# Entity 중복 해결
POST /api/v1/graph/resolve
Body: {"entities": [...]}

# 부분 그래프 추출
GET /api/v1/graph/subgraph/neighborhood/{id}?hops=2

# 경로 찾기
POST /api/v1/graph/patterns/paths
Body: {"start_id": 1, "end_id": 5}

# 중심성 계산
POST /api/v1/graph/analytics/centrality
Body: {"centrality_type": "pagerank"}

# RAG 컨텍스트
POST /api/v1/rag/query
Body: {"query": "Apple의 제품은?"}
```

#### GraphQL 지원
```graphql
{
  entity(id: 1) {
    label
    type
    neighbors(hops: 2) { label }
  }
}
```

### 6️⃣ RAG 파이프라인 (Phase 6)

```
사용자 쿼리: "Apple의 제품은?"
    ↓
그래프에서 자동 검색 + 컨텍스트 추출
    ↓
LLM 프롬프트 자동 생성:
  "You are a helpful assistant.
   
   Knowledge Graph Context:
   - Apple produces iPhone, iPad, Mac
   - Apple was founded by Steve Jobs
   - Apple is headquartered in Cupertino
   
   Question: Apple의 제품은?"
    ↓
LLM 응답 (외부 서비스): "Apple의 주요 제품은..."
```

---

## 🛠 설치 및 실행

### 사전 요구사항
```bash
Python 3.9+
Neo4j 5.0+
Redis (선택사항)
```

### 1단계: 설치
```bash
git clone <repository>
cd ontology_platform
pip install -r requirements.txt
```

### 2단계: 설정
```bash
# Neo4j 연결
export NEO4J_URI=bolt://localhost:7687
export NEO4J_USER=neo4j
export NEO4J_PASSWORD=ontology123
```

### 3단계: 플랫폼 실행
```bash
# 방법 1: CLI로 온톨로지 구축
python -m ontology_platform.cli \
  --url https://example.com \
  --validate \
  --store-neo4j

# 방법 2: API 서버 시작
python -m uvicorn ontology_platform.api.phase6_app:app --reload
# → http://localhost:8000/docs
```

---

## 📈 성능

| 작업 | 규모 | 시간 |
|------|------|------|
| 웹 크롤링 | 1 URL | 5-30초 |
| 데이터 검증 | 1000 엔티티 | < 2초 |
| 벡터 임베딩 | 10K 엔티티 | 4초 |
| 배치 저장 | 100K 노드/에지 | 28초 |
| 부분 그래프 추출 | 2-hop | < 200ms |
| 경로 찾기 | max_length=5 | < 300ms |
| 중심성 계산 | top_n=100 | < 600ms |
| RAG 쿼리 | 벡터 검색 | < 1초 |

---

## 💡 사용 예제

### 예제 1: 기술 회사 온톨로지
```bash
# 1. 데이터 수집
$ ontology extract --url https://apple.com

# 2. 검증 및 변환
$ ontology validate --input apple_data.json

# 3. 그래프 저장
$ ontology store --triples apple.rdf

# 4. 분석
$ curl http://localhost:8000/api/v1/graph/analytics/influential
# → Apple, iPhone, iPad, Tim Cook 등 중요 엔티티

# 5. RAG 쿼리
$ curl -X POST http://localhost:8000/api/v1/rag/query \
  -H "Content-Type: application/json" \
  -d '{"query": "Apple의 제품은?"}'
# → 자동으로 LLM 프롬프트 생성
```

### 예제 2: 의료 온톨로지
```python
from ontology_platform.platform import OntologyPlatform

# 플랫폼 초기화
platform = OntologyPlatform()

# 1. 의료 사이트 크롤링
data = await platform.extract_from_urls([
    "https://fda.gov",
    "https://medline.gov"
])

# 2. 약물-질병-치료 관계 추출
ontology = await platform.validate_and_convert(data)

# 3. Neo4j에 저장
await platform.store_to_neo4j(ontology)

# 4. 의약 상호작용 분석
graph = platform.get_graph()
interactions = await graph.find_cycles()  # 부정적 상호작용 감지

# 5. API로 공개
# GET /api/drug/{id}/interactions
# → 의사용 의약품 상호작용 정보
```

---

## 📚 문서

| 문서 | 내용 |
|------|------|
| **ONTOLOGY_PLATFORM_OVERVIEW.md** | 플랫폼 전체 개요 및 아키텍처 |
| **PHASE_5_SUMMARY.md** | Phase 5.0-5.2 GraphRAG 상세 |
| **PHASE_6_API_GUIDE.md** | Phase 6 REST API/GraphQL/RAG 완전 레퍼런스 |
| **README.md** (English) | English version |

---

## 🔄 워크플로우

```
┌─────────────────────────────────────────┐
│     Ontology Platform Workflow          │
├─────────────────────────────────────────┤
│                                         │
│ 1️⃣  웹 URL → 텍스트 추출              │
│      (Phase 0-2: Extraction)            │
│                                         │
│ 2️⃣  텍스트 → 검증 + 온톨로지 변환    │
│      (Phase 3: Validation)              │
│                                         │
│ 3️⃣  온톨로지 → Neo4j 그래프 저장      │
│      (Phase 4: Storage)                 │
│                                         │
│ 4️⃣  그래프 분석 + 최적화              │
│      (Phase 5: Intelligence)            │
│                                         │
│ 5️⃣  API로 공개 + LLM 연계             │
│      (Phase 6: API & Integration)       │
│                                         │
│ 6️⃣  실시간 응답 (Future)              │
│      (Phase 7-8: Enhancements)          │
│                                         │
└─────────────────────────────────────────┘
```

---

## 🎓 온톨로지란?

**온톨로지**: 어떤 영역의 개념, 속성, 관계를 형식화한 구조

```
의료 온톨로지 예:
  Entities:     Disease, Drug, Symptom
  Relations:    treats, causes, prevents
  Properties:   severity, dosage, sideEffects
  
Example:
  Aspirin --treats--> Headache
  Aspirin --has_sideEffect--> Gastric_Bleeding
```

---

## 🚀 다음 단계

### Phase 7: LLM 엔드투엔드 통합
```
목표: LLM을 플랫폼에 직접 통합
- 스트리밍 응답 (토큰 실시간 전달)
- 응답 캐싱 (반복 질문 < 50ms)
- 자동 문맥 관리
```

### Phase 8: 엔터프라이즈 기능
```
목표: 대규모 운영 지원
- 멀티테넌트 (여러 조직 동시 지원)
- 실시간 그래프 업데이트
- 변경 이력 추적 (감사 로그)
```

---

## 📞 지원

### 문제 해결
```bash
# Neo4j 연결 확인
curl http://localhost:8000/health

# API 문서 확인
http://localhost:8000/docs

# 로그 확인
tail -f logs/ontology.log
```

### 커뮤니티
- GitHub Issues: 버그 리포트
- GitHub Discussions: 질문 및 제안

---

## 📝 라이선스

MIT License - 자유로운 사용, 수정, 배포 가능

---

## 💪 기여

Pull Request 환영합니다!

```bash
1. Fork
2. Feature branch 생성 (git checkout -b feature/amazing-feature)
3. Commit (git commit -m "Add amazing feature")
4. Push (git push origin feature/amazing-feature)
5. Pull Request 생성
```

---

## 🏆 주요 성과

- ✅ **45/45 테스트 통과** (100%)
- ✅ **6단계 완성** (Phase 0-6)
- ✅ **3,500+ 라인 코드** (고품질 구현)
- ✅ **10개 REST API** + GraphQL + RAG 파이프라인
- ✅ **성능**: 10K+ 노드 그래프 < 1초 응답
- ✅ **확장성**: 100K 노드/에지 < 30초 저장

---

## 📊 통계

| 항목 | 수치 |
|------|------|
| 구현 파일 | 15+ |
| 테스트 파일 | 8+ |
| 테스트 케이스 | 45 |
| API 엔드포인트 | 10 (REST) + GraphQL |
| 문서 페이지 | 2,000+ 라인 |
| 총 코드 | 3,500+ 라인 |

---

## 🎯 플랫폼이 해결하는 문제

1. **정보 구조화**: 웹의 비구조화 정보 → 구조화된 지식
2. **중복 제거**: 자동 엔티티 통합 (semantic deduplication)
3. **품질 보장**: 자동 검증 및 분석
4. **지능형 검색**: 그래프 기반 의미 검색
5. **LLM 연계**: 구조화된 컨텍스트로 더 나은 응답

---

## 🌟 특징

✨ **자동화**: 클릭 몇 번으로 온톨로지 구축  
✨ **확장성**: 수백만 개 노드 지원  
✨ **지능화**: 자동 중복 제거, 패턴 분석  
✨ **현대적**: REST, GraphQL, LLM 통합  
✨ **문서화**: 완전한 API 문서 및 가이드  

---

## 📈 로드맵

```
2026년 Q2  Phase 0-6 완성  ✅
2026년 Q3  Phase 7 (LLM 스트리밍)  🚀
2026년 Q4  Phase 8 (멀티테넌트)  📅
```

---

**버전**: 0.6.0  
**상태**: Production Ready  
**마지막 업데이트**: 2026-05-14

---

**지금 시작하세요!** 👇

```bash
python -m uvicorn ontology_platform.api.phase6_app:app --reload
```

🎉 온톨로지 시스템 구축 플랫폼에 오신 것을 환영합니다!