ShockFlow AI

🔗 라이브 데모 — https://ai-pro-project-1.vercel.app

설치 없이 운영자 화면 전체(관제탑, 운영 통계, 재배치, 요금)를 바로 볼 수 있습니다. API는 무료 호스팅(Render free tier)이라 한동안 요청이 없으면 잠들고, 깨어나는 첫 접속에 30~60초가 걸립니다 (cold start). 그 뒤에는 빠르게 응답합니다. 설치해서 실행하거나 수치를 재현하는 방법은 아래 빠른 확인 안내에 있습니다.

---

한 줄 요약

시간 정보가 붙은 도시 이벤트를 feature로 만들어, 정형 데이터만으로는 놓치는 공유 자전거 수요 급변을 예측하고, 그 예측을 재배치와 요금 결정으로 연결한 end-to-end 시스템입니다. Citi Bike 2,491만 건과 NYC 허가 이벤트 63,070건으로 백테스트했고, 측정된 결과는 모두 reports/에 artifact로 커밋해 두었습니다.

Citi Bike 수요 이력 + 시간 정보가 붙은 뉴스 / 이벤트 + 현재 station 재고
→ LLM 이벤트 추출 → Neo4j 이벤트 graph → as-of numeric graph feature
→ H3 Zone-시간 수요 예측 → 설명 및 시나리오 비교 → 실행 가능한 재배치 계획

문제 정의

공유 자전거 수요는 출퇴근, 요일, 날씨 같은 정형 패턴을 대부분 따르지만, 축제나 도로 통제, 대형 행사처럼 특정 시각과 특정 지역에 몰리는 이벤트가 생기면 그 구간에서 크게 벗어납니다. 수요 이력과 캘린더 feature만 쓰는 모델은 이런 급변을 사후에야 따라잡습니다. 부족(자전거가 없어 못 탐)은 초과(빈 거치대)보다 운영상 더 아픈데, 대칭 손실로 학습한 모델은 둘을 똑같이 취급합니다. 이 프로젝트는 (1) 이벤트를 feature로 넣으면 예측이 실제로 좋아지는지를 누수 없이 검증하고, (2) 부족을 더 무겁게 다루도록 손실함수를 바꾸며, (3) 예측을 제약을 만족하는 재배치 계획으로 연결하는 것을 목표로 합니다.

데이터

소스	규모	용도
Citi Bike 트립 이력 (NYC, 2026-01~07)	24,914,442건	수요 label (H3 zone × local hour 집계)
NYC 허가 이벤트 (permitted events)	63,070건	이벤트 feature (시각, 위치, 유형)
GDELT 뉴스 → LLM 구조화 이벤트	23건	LLM 뉴스 feature (유형, 심각도, 영향 방향)
NOAA 날씨 (Central Park)	일 단위	날씨 feature (도시 전역 shock)

트립 원본(약 3GB)은 저장소에 넣지 않습니다(§7.1). make download-citibike로 내려받아 재현합니다. 승격 모델은 leakage 검증이 끝난 Citi Bike Jersey City 패널(2026-01~07, 226,953행 / 219 zone)로 학습했습니다.

라이브 재고는 Supabase 안에서 주기 수집합니다. 외부 러너나 키 없이 Postgres의 pg_cron이 10분마다 pg_net으로 Citi Bike GBFS를 받아 정류장 2,520개의 재고 스냅숏을 쌓고, 매시 station × hour로 집계한 뒤 원본은 7일만 보관합니다. 모든 행에 fetched_at, source_last_updated, payload_hash, mode=live가 붙고 같은 payload의 재발행은 duplicate로 기록되어 적재가 idempotent합니다. 구성 SQL은 supabase/migrations/, 운영 메모는 supabase/README.md에 있습니다. 데모 fixture와 라이브 데이터는 테이블과 mode 값으로 분리되어 fixture가 라이브로 표시되는 일이 없습니다.

핵심 결과

숫자마다 측정 조건을 함께 적었습니다. 안 된 것(뉴스 피처의 조건부 실패, 철회한 permit lift)도 그대로 둡니다.

1. LLM 뉴스 피처는 이벤트가 국지적일 때만 예측을 개선합니다 — 조건부 결과. 6월 홀드아웃(이벤트 평균 2.0개 borough)에서 borough 시간당 예측 오차가 평균 1.24대 감소(상대 0.69%), 95% CI [0.83, 1.64]대(0 제외, 시드 10개 앙상블). 이벤트가 도시 전역일수록 기여가 단조 감소해 부호가 바뀝니다(평균 4.2개 −0.96 → 3.7개 −0.86 → 2.3개 −0.76 → 2.0개 +1.24). 원인: 전역 이벤트는 feature를 모든 zone에서 동시에 켜 공간 대비를 못 주고 캘린더 feature와 중복됩니다. (reports/v2/llm_value/news_feature_conditions.json)
2. 허가 이벤트 피처(permit)의 단일 분할 +2.69% 개선은 재현되지 않아 철회했습니다. 월별 rolling origin으로 창마다 재학습하면 유의한 양수가 사라집니다(inconclusive). 과장하지 않기 위해 원본 artifact와 재현 실패를 나란히 남겼습니다. (reports/v2/llm_value/rolling_origin_ablation.json)
3. 비대칭 비용 최적화 — 0.667분위(뉴스벤더 q*) 회귀로 품절 26%, 운영비용(OCS) 3.4% 감소. 3개 홀드아웃 창 전부에서 q=0.667이 최적이며, 대가로 WAPE는 8.4% 나빠집니다(트레이드오프를 함께 보고). 예측을 실행 전에 artifact에 기록했습니다. (reports/v2/holdout/quantile_cost.json)
4. MPC 재배치로 부족 73% 감소(무대응 대비, 단일 MILP는 42%), 총비용 36% 감소(greedy 대비) — 시뮬레이션. ledger total_cost: 무대응 1127 / greedy 1155 / MILP 1087 / MPC 740 / Oracle 719. MPC가 best feasible(regret 21.6). 금액은 assumption에 조건부라 simulated 라벨입니다. (reports/v2/mpc/)

A/B/C 실험 — 이벤트 피처가 실제로 효과가 있나

핵심 질문("이벤트 feature를 넣으면 예측이 좋아지는가")을 A/B/C 실험으로 검증했습니다. 세 arm은 같은 모델, 같은 cutoff, 같은 분할을 쓰고 입력 feature만 다릅니다.

arm	feature	역할
A (대조군)	수요 이력 + 캘린더 (32개)	baseline
B (처치 1)	A + 허가 이벤트 (permitted)	구조화 이벤트 피드
C (처치 2)	B + LLM 뉴스 이벤트	LLM이 뉴스에서 뽑은 이벤트

통계 방법. arm 간 차이가 우연인지 가리려고 paired day-block bootstrap을 씁니다. 지표는 짝지은 gain = loss(대조) − loss(처치)이고, 행이 아니라 날짜 블록을 2,000회 복원추출(seed 42)해 95% 신뢰구간을 percentile로 잡습니다(같은 날 시간대의 상관을 깨지 않으려는 것). 판정 규칙은 실행 전에 고정했습니다 — CI가 전부 0보다 크면 개선, 전부 작으면 악화, 0을 포함하면 보류, 이벤트 커버리지가 임계 미만이면 blocked. Diebold-Mariano 계열의 예측 정확도 비교입니다. 단일 분할이 아니라 월별 rolling-origin 6창에서 창마다 재학습해, 한 분할이 놓치는 학습 변동까지 담았습니다.

창(held-out)	A WAPE	B WAPE	C WAPE	B−A gain(대, borough 시간당) [95% CI]	판정	C−B gain(대, borough 시간당) [95% CI]	판정
2026-02	0.1469	0.1458	0.1478	+0.52 [−0.40, 1.47]	보류	−0.96 [−1.53, −0.42]	악화
2026-03	0.1467	0.1488	0.1496	−2.06 [−3.47, −0.63]	악화	−0.86 [−1.40, −0.28]	악화
2026-04	0.1085	0.1091	0.1097	−0.83 [−2.77, 1.04]	보류	−0.82 [−1.93, 0.34]	blocked
2026-05	0.0903	0.0900	0.0904	+0.42 [−2.00, 2.71]	보류	−0.58 [−1.72, 0.59]	보류
2026-06	0.0978	0.0968	0.0956	+1.91 [−0.24, 3.92]	보류	+2.23 [1.10, 3.35]	개선
2026-07	0.1030	0.1033	0.1036	−0.38 [−3.46, 2.61]	blocked	−0.51 [−2.04, 1.02]	blocked

스코어보드 (창 6개 기준).

대조	개선	악화	보류	blocked	cross-origin 판정
B vs A (허가 이벤트)	0	1	4	1	mixed_with_inconclusive
C vs B (LLM 뉴스)	1	2	1	2	sign_flips

해석. 한 창의 유의성(예: 6월 C−B가 0을 넘음)만으로 "효과 있다"고 말하지 않습니다. 6창을 모아 보면 B(허가 이벤트)는 origin에 따라 흔들려 방향을 확정할 수 없고(그래서 핵심 결과 2에서 단일 분할 +2.69% 주장을 철회), C(LLM 뉴스)는 부호가 뒤집힙니다. C가 어느 창에서 이기는지를 추가로 파고든 결과가 조건부 결과(핵심 결과 1)입니다 — 이벤트가 국지적일 때만 기여가 양수이고, 시드 10개 앙상블로 6월 창을 다시 재면 **borough 시간당 오차 1.24대 감소(상대 0.69%, CI [0.83, 1.64]대)**로 좁혀집니다. 위 표의 단일 시드 +2.23대보다 보수적인 값이며, 이 프로젝트가 대표로 인용하는 숫자입니다.

재현: make v2-llm-value-rolling(측정) → make v2-abc-plot(그림), make v2-news-conditions(조건부 시드 앙상블). 원본 artifact는 reports/v2/llm_value/rolling_origin_ablation.json.

This is the beginning of the README. Read the rest at the original. Read the full README ↗