SANGHO JEONG

KAYFABE

WWE 경기 예측 · 데이터 분석 플랫폼

기간
2026.07 – 진행 중
KAYFABE 메인 화면 — WWE DATA & PREDICTION PLATFORM 히어로와 AI 예측 카드

실측

측정한 값만 적었습니다. 측정하지 않은 칸은 비워 둡니다.

API 핸들러
48

apps/kayfabe 기준 · 실측 2026-10-08

테스트
1,349

pytest 수집 기준 · 매 푸시마다 돈다 (2026-10-08)

아키텍처 계약
4

import-linter · 어기면 커밋이 막힌다

커밋
422

저장소 전체 · 실측 2026-10-08

예측 축
3

서사 · 오즈 · 루머 — 둘은 모델, 하나는 코드

코퍼스 청크
1,027

문서 89건 · 도메인 6종 · 2026-10-08

왜 만들었나

경기 결과를 맞히는 서비스는 많습니다. 그런 서비스가 내놓는 적중률을 저는 믿지 못했습니다 — 그 숫자가 무엇을 읽고 나온 것인지가 적혀 있지 않기 때문입니다. 끝난 경기의 문서를 읽고 맞힌 것과 경기 전 자료로 맞힌 것은 같은 숫자여도 다른 일입니다.

그래서 이 플랫폼의 주제는 예측이 아니라 예측의 자격입니다. 세 개의 축이 각본 · 배당 · 소식을 따로 읽어 결론을 내고, 그 결론이 어느 문서의 어느 구절에서 왔는지를 함께 남깁니다. 그러고 나서 시스템이 스스로 묻습니다 — 이 근거를 성적에 세도 되는가.

백엔드부터 프론트, 배포까지 혼자 만들었습니다. 그 과정에서 가장 많은 시간을 쓴 곳은 모델을 고르는 자리가 아니라 모델의 출력을 어디까지 믿을지 정하는 자리였습니다. 언어 모델에게는 데이터를 쓸 권한을 주지 않았습니다 — 모델은 결론과 근거 구절만 주장하고, 반영할지는 서버가 그 인용을 원문과 대조해 판정합니다.

기술 흐름

도면 4장입니다. 왼쪽 세로선을 따라 위에서 아래로 흐르고, 나란한 칸은 동시에 일어나는 일입니다. 빨간 줄이 붙은 칸은 그 자리에서 빠져나가는 길 — 반려·보류·폴백입니다.

  1. 도 01멀티 에이전트 예측 합성
  2. 도 02지식 적재와 누수 판정
  3. 도 03결과 확정 에이전트
  4. 도 04배포 경로
코드
결정론 코드 — 같은 입력이면 같은 출력
모델
언어·비전 모델
저장
저장소
외부
외부 서비스·공개 소스
관문
관문 — 통과 못 하면 빠진다
산출
사람이 보는 산출물

도 01

멀티 에이전트 예측 합성

세 축이 같은 경기를 따로 읽고, 합치는 일은 순수 함수가 한다. 사용자가 화면에 들어오는 것으로는 모델이 돌지 않는다.

  1. 관문생성 요청

    • 관리자만 — POST /ple_events/{slug}/ai-predictions
    • 화면 진입(GET)은 저장된 값만 읽는다
  2. 경기별로

    코드경기 문맥 구성

    • 대진·선택지
    • 카드에 적힌 북메이커 호가
  3. 질의

    저장지식 검색

    • pgvector 코사인 거리
    • 경기당 상위 5건

    코퍼스 문서 89건 · 청크 1,027개 (2026-10-08)

  4. 같은 문맥을 셋에게

    모델서사 축

    • 각본 진행·타이틀 명분·푸시
    • 지식이 없으면 부르지 않는다
    • gemini-3.6-flash

    코드오즈 축

    • 북메이커 여럿 → 중앙값 합의
    • 모델을 쓰지 않는다 — 비용도 지연도 없다
    • 분산도 정보다

    모델루머 축

    • 부상·복귀·보도된 푸시
    • 일어날 일만 — 일어난 일은 서사 축
    • gemini-3.5-flash-lite

    셋 다 의견이 없으면

    승률 0.5를 채우지 않고 503으로 끝낸다. 「우열을 가리지 못했다」와 「물어보지 못했다」는 다른 상태다.

  5. 리포트 셋

    코드합성

    • 순수 함수 — 프레임워크·LLM·HTTP를 모른다
    • 기권을 균등분포로 세어 에이전트 수로 나눈다
    • 가중치를 코드에 박지 않았다

    고정 픽스처만으로 테스트가 돈다 (모델 호출 없이)

    에이전트가 죽으면

    북메이커 파생으로 강등하고 그 사실을 응답에 싣는다(source: bookmaker_fallback). 조용히 같은 얼굴로 내보내지 않는다.

  6. 저장

    저장예측 저장

    • pick · 승률 · 에이전트별 리포트 · 산식 판본
    • 승률은 0.0~1.0 float — %는 화면에서 한 번만 만든다
  7. 읽기

    산출예측 카드 · 근거 리포트

    • 어느 축이 무엇을 읽고 그 결론에 왔는지까지 함께 보인다
  • 산식 판본(v1·v2)을 둘 다 남겨 둔다. 지우면 그때의 숫자를 다시 만들 수 없고, 그러면 재현 화면이 근거 없이 「달라졌다」고 말한다.
  • 모델 이름은 환경변수로 덮을 수 있다 — 적힌 것은 기본값이다. 셋이 서로의 예비가 되게 묶어 한 모델이 죽어도 리포트가 통째로 사라지지 않는다.
  • 오즈 축만 모델을 쓰지 않는다. 그래서 세 축 중 유일하게 항상 돌 수 있다.

도 02

지식 적재와 누수 판정

공개 소스만 긁고, 한 문서가 막혀도 나머지는 계속 간다. 쌓인 코퍼스는 그 뒤 「이 근거를 성적에 세도 되는가」를 따로 판정받는다.

  1. 관문허용 도메인 목록

    • 유료 구독 본문은 저장하지 않는다 (제목·링크까지)
    • X 스크래핑·페이월 우회를 하지 않는다

    목록에 없으면

    거절한다. 어디까지 긁을지를 코드가 아니라 목록이 정한다.

  2. 수집

    외부문서 가져오기

    • 공개 위키·공개 배당 페이지·보도
    • 허브(ontology)의 크롤러·스크레이퍼

    한 문서가 실패해도

    나머지를 멈추지 않는다. 20건 중 3건이 막혔다고 17건을 버리면 재실행이 그 17건을 또 받아 온다.

  3. 쪼갠다

    코드청킹

    • 위키 상용구를 걸러 낸다
    • 인물 문서는 앞부분만 — 뒤는 타이틀 이력과 각주다
    • 내용 지문으로 중복을 막는다
  4. 숫자로

    모델임베딩

    • BAAI/bge-m3 · 정규화
    • 인프로세스 — CPU 작업이라 스레드풀로 넘긴다
  5. 색인

    저장pgvector

    • 새 벡터 스토어를 붙이지 않았다 — 이미 돌고 있었다

    문서 89건 · 청크 1,027개 (2026-10-08) · 상용구 오염 0% (2026-10-06 재수집 뒤)

  6. 쌓인 뒤 따로 판정한다

    관문누수 판정 — 규칙 셋

    • self_reference — 경기 이후 판본을 근거로 썼나
    • unverifiable_corpus — 원문을 다시 못 읽나
    • revision_after_prediction — 예측 뒤에 문서가 고쳐졌나

    걸린 근거는 숨기지 않는다

    어느 규칙에 왜 걸렸는지를 화면에 적고, 그 경기를 적중률에서 빼는 판정도 여기서 나온다.

  7. 산출AI LAB

    • 코퍼스 상태·누수 목록·재현 결과를 사람이 볼 수 있게 펼친다
  • 계보의 기준은 수집 시각이다. 문서의 published_at은 경기 뒤 갱신을 못 잡아서 쓰지 않는다.
  • 그래서 대회 전에 수집해야 증거가 된다. 끝난 뒤 긁은 문서는 승자를 이미 알고 있다.
  • 이 판정이 「적중률 자랑」을 막는 자리다. 숫자를 지우는 게 아니라, 그 숫자를 성적에 세도 되는지를 함께 적는다.

도 03

결과 확정 에이전트

이쪽은 워크플로가 아니라 에이전트다 — 몇 걸음이 필요한지 미리 모른다. 대신 모델에게 쓰기 도구를 주지 않았다.

  1. 코드끝난 경기 선별

    • 대회 문서 제목은 사람이 전수 실측한 표에서 준다
    • 이름 맞히기를 모델에게 시키지 않는다
  2. 도구를 쥐여 준다

    모델에이전트 루프

    • 도구는 읽기 둘뿐 — 문서 찾기 · 절 읽기
    • 어느 절을 읽을지·더 읽을지는 모델이 정한다
    • 쓰기 도구가 없어 DB에 닿는 경로가 구조적으로 없다

    걸음 수와 도구 호출 수에 각각 상한이 있다 · 넘으면 보류로 끝낸다(보류는 정상 종료다)

  3. 마지막에 한 번

    모델주장

    • 승자 이름 + 근거 구절
    • 모델이 할 수 있는 일은 여기까지다
  4. 쓸지 말지는 코드가 정한다

    코드관문 다섯

    • ① 주장이 있는가 — 침묵을 승자로 바꾸지 않는다
    • ② 인용이 우리가 건넨 본문에 실제로 있는가
    • ③ 이름이 선택지 정확히 하나에 걸리는가
    • ④ 카드의 이름이 인용 안에서 보이는가
    • ⑤ 인용이 그 사람을 패자로 적고 있지 않은가

    ②와 ④가 양방향을 만든다 — 한쪽만 걸면 각각 뚫린다

    하나라도 못 넘으면 보류

    ⑤는 진실을 증명하지 않고 모순만 잡는다. 승패 관계를 못 알아보면 통과시킨다 — 그래서 이름이 「모순 검출」이지 「승자 판정」이 아니다.

  5. 통과한 것만

    코드결과 기록

    • 쓰는 것은 인터랙터다
  6. 산출예측 채점

    • 맞았으면 맞았다고, 틀렸으면 틀렸다고 담백하게
  • 예측 생성과 다른 모델을 쓴다. 무료 등급 한도가 모델 단위라 서로 침범하지 않게 한 것이다. 같은 이유로 호출 간격을 벌린다.
  • ⑤를 넣게 된 계기는 실측이다 — `Liv Morgan (c) defeated Iyo Sky by pinfall`을 정직하게 인용한 채 승자를 Iyo Sky라고 주장하면 관문 넷을 전부 통과한다.
  • 끝난 대회만 대상이다. 안 끝난 대회를 읽히면 그게 곧 누수다(도 02).

도 04

배포 경로

화면과 서버가 다른 데 산다. 상태를 가진 것은 하나도 내 클러스터 안에 두지 않았다.

  1. 코드git push

    • 작업 브랜치에 커밋하고 기본 브랜치를 fast-forward로 맞춘다
  2. 밀면 바로 돈다

    관문GitHub Actions 게이트

    • ruff · 아키텍처 계약 · pytest
    • 프론트는 ESLint · TypeScript strict
    • 앱 사이 의존 방향과 레이어 순서를 계약으로 검사한다

    계약 4건 · 테스트 1,349건 (2026-10-08)

    통과 못 하면 거기서 멈춘다

    규칙을 문서가 아니라 게이트로 지킨다. 문서는 안 읽히고 게이트는 막는다.

  3. 둘로 갈린다

    외부Vercel

    • Next.js 한 벌 · 배포는 하나고 도메인만 셋이다
    • 호스트로 첫 화면을 가른다 — 포트폴리오 · KAYFABE · 데모

    외부AWS EC2

    • FastAPI · 인증 게이트웨이
    • Cloudflare Tunnel로 내보낸다 — 서버 문을 바깥에 직접 열지 않는다
  4. 둘 다 같은 DB를 본다

    저장Supabase

    • PostgreSQL + pgvector
    • pooler 주소 · 포트 5432(session)
    • 대시보드가 주는 direct 주소는 IPv6 전용이라 EC2에서 안 닿는다
  • 로컬 개발은 k3s인데 앱만 올린다. 상태를 가진 것은 외부 관리형 서비스에 둔다 — 그래서 로컬에 DB 컨테이너가 없다.
  • 포트 6543(transaction)은 prepared statement를 못 써서 ORM과 마이그레이션이 깨진다. 포트 하나가 설정 문제가 아니라 동작 문제인 자리다.
  • DB는 2026-09-22에 EC2 안의 컨테이너에서 Supabase로 나갔다. 되돌릴 수 있게 옛 설정과 볼륨을 남겨 뒀다.

정한 것과 거부한 것

만든 것보다 안 만든 것이 설계입니다. 왜 그렇게 정했는지를 함께 적었습니다.

  1. 01

    적중률을 자랑하지 않는다

    적중률은 쉽게 만들 수 있는 숫자입니다. 끝난 경기의 문서를 읽히면 거의 다 맞습니다. 그래서 이 화면은 숫자를 크게 세우는 대신 그 숫자가 통과한 판정을 함께 적습니다 — 어느 근거가 경기 이후 판본이었나, 원문을 다시 읽을 수 있나, 예측한 뒤에 문서가 고쳐졌나.

  2. 02

    언어 모델에게 쓰기 권한을 주지 않는다

    결과 확정 에이전트가 쥔 도구는 읽기 둘뿐입니다 — 문서 찾기와 절 읽기. 모델은 「승자는 이 사람이고 근거는 이 구절」이라고 주장하는 것까지 할 수 있고, 그 주장을 쓸지는 순수 함수가 관문 다섯으로 정합니다. 모델이 DB에 닿는 경로가 구조적으로 없습니다.

  3. 03

    에이전트 가중치를 코드에 박지 않았다

    서사·오즈·루머 중 무엇을 더 믿어야 하는지는 아직 정할 근거가 없습니다. 그래서 합성 함수에 기본 가중치를 넣지 않고, 리포트가 실어 온 값을 분포로 펴서 평균합니다. 근거 없는 숫자를 코드에 남기면 그 숫자가 나중에 사실처럼 읽힙니다.

  4. 04

    표본이 모자란 지표는 0%로 채우지 않는다

    지표를 낼 수 없을 때 화면은 0%를 그리지 않고 무엇이 모자란지를 적습니다. 작은 표본으로 낼 때는 분모를 함께 세웁니다 — 「적중률 100% (12/12)」. 분모 없는 백분율은 과장입니다.

  5. 05

    새 벡터 DB를 붙이지 않았다

    RAG를 붙이라는 지시서는 Pinecone이나 Chroma를 말했지만, 이 저장소에는 pgvector와 bge-m3가 이미 돌고 있었습니다. 요청받지 않은 의존성을 더하는 대신 같은 차원의 테이블을 하나 늘렸습니다.

  6. 06

    규칙은 문서가 아니라 게이트로 지킨다

    앱 사이 의존 방향(허브 하나, 스포크 여럿)과 레이어 순서를 CI가 계약으로 검사합니다. 어기면 커밋이 막힙니다. 문서에 적어 둔 규칙은 안 읽히고, 게이트는 막습니다.

이 프로젝트에서 쓴 것

실제로 돌아가는 것만 적었습니다. 각 기술이 어디에 쓰이는지는 위 도면이 말합니다.

백엔드
Python 3.13FastAPISQLAlchemy 2.0 asyncSQLModelAlembicPydanticpytestruffUvicornuv
프론트엔드
TypeScriptNext.js 16React 19Tailwind CSSRadix UIRecharts
데이터
PostgreSQLpgvectorNeo4jRedisSupabaseSQL
AI
Google GeminiRAGBAAI/bge-m3Kiwi 형태소
인프라
Dockerk3sAWS EC2VercelCloudflare TunnelGitHub Actionsimport-linterpre-commit

아직 못 한 것

다른 프로젝트