PlotPath 데이터 파이프라인 최종 정리

개요

PlotPath의 데이터베이스를 구축하고 최신으로 유지하기 위해, 각기 다른 역할을 수행하는 4개의 Python 스크립트로 구성된 데이터 파이프라인을 구축했다. 이 파이프라인은 1차적인 대량 데이터 수집부터, 2차 전문 데이터 수집 및 교정, 3/4차 LLM을 이용한 지능적인 데이터 분류 및 보강까지, 체계적인 4단계로 구성된다.

---

단계별 로직 설명

[1단계] tmdb_collector.py : 1차 대량 수집 (영화 & 실사 작품)

• 역할: TMDB의 방대한 데이터를 활용하여, 영화와 실사 드라마 등 광범위한 작품의 기본 정보를 빠르게 DB에 채워 넣는 것을 목표로 한다.
• 상세 로직:
  1. 사용자는 python tmdb_collector.py --type movie --pages 5 와 같이 명령줄 인수를 통해 수집 대상(movie/tv)과 규모(pages)를 지정하여 스크립트를 실행한다.
  2. 스크립트는 TMDB API에서 인기/평점순 목록을 조회한다.
  3. 가져온 작품이 애니메이션 TV 시리즈일 경우 (media_type='tv' & 장르='애니메이션'), anilist_collector에서 더 전문적으로 처리하도록 건너뛴다(Skip).
  4. work_identifier 테이블을 통해 DB에 이미 존재하는 작품인지 확인하고, 신규일 경우 INSERT, 기존 작품일 경우 UPDATE를 수행한다.
  5. 이 과정에서 작품의 타입을 API가 제공하는 장르 정보를 바탕으로 한 규칙 기반(Rule-based)으로 결정하여 work_type_mapping 테이블에 저장한다. (예: 영화 + 애니메이션 장르 → 'Movie', 'Animation' 타입 모두 저장)
  6. 예고편 URL을 포함한 모든 정형 데이터를 수집하여 저장한다.

[2단계] anilist_collector.py : 2차 전문 수집 및 정제 (애니메이션)

• 역할: 애니메이션 전문 DB인 AniList를 'Source of Truth'로 삼아, 모든 애니메이션 데이터를 수집, 교정, 보강한다. 1단계에서 TMDB를 통해 잘못 들어온 데이터를 바로잡는 핵심적인 역할을 수행한다.
• 상세 로직:
  1. 사용자는 python anilist_collector.py --pages 3 과 같이 실행하여 처리할 페이지 수를 지정한다.
  2. AniList API에서 인기 애니메이션 목록을 가져온 뒤, 이미 처리한 ID는 건너뛴다.
  3. 각 애니메이션 ID에 대해 data_reconciler.py의 메인 함수(process_series_from_entry_point)를 호출한다.
  4. 호출된 함수는 AniList API의 relations 정보를 분석하여, 관련된 모든 시즌(속편) 정보를 한 번에 파악한다.
  5. 대표 제목으로 series 테이블을 조회하여 기존 시리즈를 찾거나, 없으면 새로 생성한다.
  6. 시리즈에 속한 각 시즌(작품)별로 DB에 이미 존재하는지(work_identifier 확인) 검사한다.
     • 존재할 경우 (UPDATE): TMDB에서 수집된 기존 work 정보를 더 정확한 AniList의 데이터(줄거리, 에피소드 수 등)로 덮어쓰고, 올바른 seriesId를 다시 연결해준다.
     • 존재하지 않을 경우 (INSERT): 새로운 work로 DB에 추가하고, seriesId를 연결한다.
  7. 이 과정에서 작품의 타입은 AniList의 format(MOVIE, TV 등) 정보를 바탕으로 한 규칙 기반으로 결정된다.

[3단계] type_fixer.py : 3차 데이터 클린업 (드라마 타입 교정)

• 역할: 1, 2단계를 거친 데이터 중, '드라마' 타입 분류가 모호한 작품들을 대상으로 LLM의 지능을 이용해 최종 교정한다.
• 상세 로직:
  1. 사용자가 python type_fixer.py 를 실행한다. (내부적으로 처리량 조절 가능)
  2. DB에서 'Drama' 타입이 아직 부여되지 않은 작품들을 조회한다.
  3. 각 작품의 제목과 줄거리를 Gemini(LLM)에게 보내 "이 작품은 '아케인'처럼 서사가 중심인 드라마인가?" 라고 질문한다.
  4. Gemini가 'Drama'라고 답변하면, work_type_mapping 테이블에 'Drama' 타입을 추가하여 데이터의 깊이를 더한다.

[4단계] llm_enricher.py : 4차 데이터 보강 (정보 채우기)

• 목적: 데이터의 종류는 맞지만 내용이 부실한(한글 제목, 썸네일, 줄거리 등) 작품들의 빈틈을 LLM으로 채워 데이터의 완성도를 높인다.
• 상세 로직:
  1. 사용자가 python llm_enricher.py 를 실행한다. (내부적으로 처리량 조절 가능)
  2. DB에서 한글 제목이 없거나(titleKr = titleOriginal), 썸네일 또는 줄거리가 비어있는 작품을 찾는다.
  3. 각 작품에 대해, Gemini(LLM)에게 "이 작품의 한국어 제목, 고화질 포스터 주소, 스포일러 없는 한국어 줄거리를 찾아줘" 라고 요청한다.
  4. Gemini가 찾아준 양질의 정보로 work 테이블의 해당 필드들을 UPDATE한다.

---

API 차단 방지 및 안전성

모든 스크립트는 외부 API의 과도한 사용으로 인한 차단을 방지하기 위해 안전장치를 포함하고 있다.

• TMDB: 각 작품 처리 시 0.5초의 지연(time.sleep(0.5))을 주어, TMDB의 공식 요청 제한을 준수한다.
• AniList & Gemini:
  • anilist_collector는 각 시리즈를 처리하는 사이에 2초의 지연을 준다.
  • (추가) data_reconciler는 한 시리즈 내의 여러 시즌 상세 정보를 조회할 때, 각 시즌 사이에 1초의 추가 지연을 주어, 짧은 순간에 요청이 몰려 429 Too Many Requests 오류가 발생하는 문제를 해결했다.
  • 이러한 다중 딜레이 로직을 통해 모든 API 요청 횟수를 각 서비스의 제한(AniList 분당 90회, Gemini 분당 60회)보다 훨씬 낮은 수준으로 안정적으로 유지한다.