Upload README.md with huggingface_hub

README.md

@@ -1,10 +1,96 @@
 ---
-title: Youtube Segment Summary
-emoji: 🐨
+title: YouTube Video Analyzer
+emoji: 🎥
 colorFrom: blue
-colorTo: yellow
+colorTo: purple
 sdk: docker
 pinned: false
+license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🎥 YouTube Video Analyzer
+
+유튜브 영상의 자막을 주제별로 분리하고 AI로 요약하는 서비스입니다.
+
+## 🚀 주요 기능
+
+### 1. 세그먼트 분리
+- **ruptures PELT 알고리즘**: 통계적 변화점 탐지로 대주제 분리
+- **의미 유사도 분석**: Sentence Transformers로 소주제 정밀 분할
+- **타임스탬프 매핑**: 각 세그먼트의 영상 시작 시간 제공
+
+### 2. AI 요약
+- **Gemini 2.0 Flash Lite**: Google의 최신 경량 AI 모델 사용
+- **주제 라벨링**: 2-5단어로 핵심 주제 추출
+- **스마트 필터링**: 의미 없는 짧은 리액션 자동 제외
+
+## 📚 API 문서
+
+이 스페이스가 실행되면 자동으로 Swagger UI가 제공됩니다:
+- **API 문서**: `/docs`
+- **헬스 체크**: `/health`
+- **API 정보**: `/info`
+
+## 🎯 사용 방법
+
+### GET 요청 예시
+```
+/process?youtube_url=https://youtube.com/watch?v=VIDEO_ID&mode=summary&penalty=5.0&threshold=90&gemini_api_key=YOUR_KEY
+```
+
+### POST 요청 예시
+```json
+{
+  "youtube_url": "https://youtube.com/watch?v=VIDEO_ID",
+  "mode": "summary",
+  "penalty": 5.0,
+  "threshold": 90,
+  "gemini_api_key": "your_gemini_api_key"
+}
+```
+
+## ⚙️ 파라미터 가이드
+
+### Penalty (대주제 분리)
+- **1.0-3.0**: 매우 세밀한 분리 (많은 주제)
+- **5.0**: 균형잡힌 분리 (기본값)
+- **7.0-10.0**: 큰 주제 단위 분리
+- **15.0-30.0**: 매우 큰 덩어리로 분리
+
+### Threshold (소주제 분리)
+- **70-80**: 세밀한 분리
+- **85-92**: 균형잡힌 분리 (권장)
+- **90**: 기본값
+- **95-98**: 큰 덩어리 분리
+
+## 🔧 기술 스택
+
+- **youtube-transcript-api**: 자막 추출
+- **ruptures**: 통계적 변화점 탐지
+- **sentence-transformers**: 문장 임베딩
+- **google-generativeai**: AI 요약
+- **FastAPI**: REST API 서버
+
+## 🔧 문제 해결
+
+### DNS/네트워크 오류
+허깅페이스 스페이스 환경에서 외부 네트워크 접근에 제한이 있을 수 있습니다. 이 경우:
+
+1. **재시도 로직**: 코드에 자동 재시도 기능이 내장되어 있습니다 (최대 3회)
+2. **타임아웃**: 각 시도마다 대기 시간이 증가합니다 (2초, 4초, 6초)
+3. **대안**: 로컬에서 Docker를 실행하거나, 다른 클라우드 환경 사용
+
+### 로컬 실행 방법
+```bash
+# Docker로 실행
+docker build -t youtube-analyzer .
+docker run -p 7860:7860 youtube-analyzer
+
+# 또는 직접 실행
+pip install -r requirements.txt
+uvicorn app:app --host 0.0.0.0 --port 7860
+```
+
+## 📝 라이선스
+
+MIT License