README.md

metadata

title: IntentFinder API
emoji: 🔎
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false

HuggingFace Space 배포 메모

• SDK: Docker (위 메타). 진입점 api:app, 포트 7860.
• Space Settings → Secrets 에 입력(코드/레포엔 두지 않음): NAVER_CLIENT_ID, NAVER_CLIENT_SECRET, NAVER_API_KEY, NAVER_SECRET_KEY, NAVER_CUSTOMER_ID, ANTHROPIC_API_KEY, SUPABASE_URL, SUPABASE_SERVICE_KEY
• 배포 보호 시크릿(권장): ALLOWED_ORIGINS(대시보드 도메인), DT_API_KEY(대시보드와 공유), RATE_MAX_PER_MIN
• 헬스체크: GET /health · 분석: GET /analyze?keyword=... (DT_API_KEY 설정 시 X-DT-Key 헤더 필요)

IntentFinder — 검색 인텐트 분석 대시보드

키워드를 입력하면 네이버 실시간 검색 데이터 + AI 클러스터링으로 검색 의도·타깃·연관 경로를 분석하는 SMB용 대시보드.

구성

[dashboard.html]  React 단일 파일 프론트 (빌드 불필요)
      │  fetch /analyze?keyword=
      ▼
[api.py]  FastAPI 백엔드 (포트 8000)
      ├─ naver_collector.py   네이버 검색광고 키워드도구 (검색량·경쟁)
      ├─ clusterer.py         관련성 필터 + S-BERT→UMAP→HDBSCAN 클러스터링
      ├─ analyzer.py          Overview 카드 집계
      ├─ intent_classifier.py Claude Haiku 의도분류·테마명·마케팅 제안
      ├─ autocomplete.py      네이버 자동완성 기반 검색 경로
      ├─ search_path.py       임베딩 기반 검색 경로(폴백)
      ├─ datalab.py           데이터랩 성별×연령 추정 비중
      ├─ cache.py             SQLite 빠른 재조회 캐시
      └─ supabase_store.py    Supabase 적재(통합 BI 저장소)

설치 및 실행

# 1. 의존성 설치 (torch 포함, 수백 MB)
pip install -r requirements.txt

# 2. 자격증명 설정: .env.example을 .env로 복사 후 값 채우기
#    - 네이버 검색광고 (searchad.naver.com > 도구 > API)
#    - ANTHROPIC_API_KEY (platform.claude.com)
#    - 네이버 데이터랩 (developers.naver.com)
#    - SUPABASE_URL / SUPABASE_SERVICE_KEY (Supabase > Settings > API)

# 3. Supabase 테이블 생성: supabase_schema.sql을 SQL Editor에 붙여 Run

# 4. 실행
python -m uvicorn api:app --port 8000      # 백엔드
python -m http.server 5500                 # 프론트
#  → http://127.0.0.1:5500/dashboard.html

자격증명 키 (.env)

변수	발급처	용도
NAVER_API_KEY / NAVER_SECRET_KEY / NAVER_CUSTOMER_ID	searchad.naver.com	검색량·경쟁
ANTHROPIC_API_KEY	platform.claude.com	의도분류·마케팅 제안
NAVER_CLIENT_ID / NAVER_CLIENT_SECRET	developers.naver.com	인구통계
SUPABASE_URL / SUPABASE_SERVICE_KEY	Supabase	통합 저장소 적재

키가 없는 기능은 자동으로 비활성(placeholder)되고 나머지는 정상 동작한다.

주의

• .env(실제 키)는 절대 공유·커밋 금지. 공유는 .env.example만.
• service_role 키는 RLS 우회 키 → 서버에서만 사용, 프론트 노출 금지.
• 네이버 자동완성·데이터랩은 비공식/상대지수 기반 → "추정" 라벨 유지.
• CDN(Babel·Tailwind)은 데모용 → 실서비스는 Vite 빌드 권장.

진행 기록

• checklist.md — 단계별 완료 현황
• context-notes.md — 설계 결정과 근거
• data-requirements.md — 데이터 소스·한계 분석