kcg-ai-monitoring/prediction/models_core/seeds/README.md

Detection Model Seeds

Phase 2 PoC 모델을 V034 detection_models + detection_model_versions 에 seed 하는 SQL.

현재 seed 대상

파일	모델	tier	모드
v1_dark_suspicion.sql	dark_suspicion (DARK_VESSEL)	3	런타임 override 완성
v1_gear_violation.sql	gear_violation_g01_g06 (GEAR)	4	런타임 override 완성
v1_transshipment.sql	transshipment_5stage (TRANSSHIP)	4	카탈로그 + 관찰
v1_risk_composite.sql	risk_composite (META)	3	카탈로그 + 관찰
v1_pair_trawl.sql	pair_trawl_tier (GEAR)	4	카탈로그 + 관찰
v1_phase2_all.sql	5 모델 일괄	—	\i 로 위 5개 순차 실행

"런타임 override 완성" vs "카탈로그 + 관찰"

• 런타임 override 완성 (dark_suspicion, gear_violation_g01_g06): 알고리즘 함수가 params: dict | None = None 인자를 받고, ACTIVE 버전의 JSONB 를 적용해 실제 가중치·임계값이 교체된다. 운영자가 version 을 ACTIVE 로 승격하면 다음 사이클 결과가 바뀐다.
• 카탈로그 + 관찰 (transshipment_5stage, risk_composite, pair_trawl_tier): 내부 헬퍼 함수들이 모듈 레벨 상수를 직접 참조하여 범위가 큰 리팩토링이 필요. 이번 단계에서는 DEFAULT_PARAMS 를 DB 카탈로그에 노출 + Adapter 로 결과 관찰 수집까지만. 런타임 실제 교체는 후속 리팩토링 PR 에서 헬퍼에 params 전파를 완성하면 활성화된다.

실행 방법

중요: 본 seed 파일들은 BEGIN/COMMIT 을 포함하지 않는다. 호출자가 트랜잭션을 관리한다.

(A) 운영 적용 — 단일 트랜잭션 자동 래핑

PGPASSWORD=... psql -h <host> -U kcg-app -d kcgaidb \
  -v ON_ERROR_STOP=1 -1 \
  -f prediction/models_core/seeds/v1_dark_suspicion.sql

-1 플래그가 파일 전체를 한 트랜잭션으로 묶어 어느 INSERT 실패 시 전부 롤백.

(B) Dry-run — 실제 반영 없이 SQL 검증

PGPASSWORD=... psql -h <host> -U kcg-app -d kcgaidb -v ON_ERROR_STOP=1 <<'SQL'
BEGIN;
\i prediction/models_core/seeds/v1_dark_suspicion.sql
SELECT version, status, params->'tier_thresholds'
  FROM kcg.detection_model_versions WHERE model_id='dark_suspicion';
ROLLBACK;
SQL

⚠️ 사용 금지 패턴

# 절대 금지 — 각 -c/-f 가 별도 세션이라 실제로 INSERT 됨
psql -c 'BEGIN;' -f v1_dark_suspicion.sql -c 'ROLLBACK;'

운영자 승격 절차

1. seed 결과는 status=DRAFT role=NULL → prediction 은 참조하지 않음 (params_loader 는 WHERE status='ACTIVE' AND is_enabled=TRUE).
2. Phase 3 백엔드 API 배포 후 운영자가 다음 중 하나로 승격:
   • POST /api/ai/detection-models/{modelId}/versions/{versionId}/activate?role=SHADOW — 관찰 전용
   • POST /api/ai/detection-models/{modelId}/versions/{versionId}/activate?role=PRIMARY — 운영 반영
   • POST /api/ai/detection-models/{modelId}/versions/{versionId}/promote-primary — SHADOW→PRIMARY 승격 (기존 PRIMARY 자동 ARCHIVED)
3. prediction 은 다음 사이클 시작 시 params_loader TTL(5분) 만료 후 자동 적재.
4. PREDICTION_USE_MODEL_REGISTRY=1 환경변수로 재기동해야 실제 실행 (기본 0 은 구 경로 유지, Phase 2 diff=0 검증 전까지 안전).

동치성 검증

각 모델의 params JSONB 는 Python 소스의 *_DEFAULT_PARAMS 상수와 1:1 일치. 정적 검증은 prediction/tests/test_dark_suspicion_params.py::test_seed_sql_values_match_python_default 가 담당.

런타임 검증(신·구 경로 diff):

1. 같은 모델에 v1.0.0 (DEFAULT) 를 PRIMARY 로 seed
2. (선택) v1.0.0-shadow 를 동일 params 로 SHADOW 로 seed
3. PREDICTION_USE_MODEL_REGISTRY=1 로 5분 사이클 1회 실행
4. kcg.v_detection_model_comparison 뷰에서 PRIMARY↔SHADOW outputs 비교 → 전 입력 동일이어야 함

롤백

-- 한 모델만
DELETE FROM kcg.detection_model_versions WHERE model_id = 'dark_suspicion';
DELETE FROM kcg.detection_models WHERE model_id = 'dark_suspicion';

-- Phase 2 전체 (후속 PR 반영 이후)
DELETE FROM kcg.detection_model_versions WHERE model_id IN (
  'dark_suspicion', 'gear_violation_g01_g06', 'transshipment_5stage',
  'risk_composite', 'pair_trawl_tier'
);
DELETE FROM kcg.detection_models WHERE model_id IN (
  'dark_suspicion', 'gear_violation_g01_g06', 'transshipment_5stage',
  'risk_composite', 'pair_trawl_tier'
);