재현성 체크리스트와 Artifact 추적

현재 실험 기록 상태

Minimum Reproducibility Package

Runbook Template

실제 경로와 config는 run마다 바뀐다. 아래는 문서에 남길 명령어 형태다.

# 1. repo root
cd /workspace/landmark-assis/landmark-assistant-model-ver2
source .venv/bin/activate
export PYTHONPATH=$PWD/src:${PYTHONPATH:-}
export DATA_ROOT=/workspace/landmark-assis/Dataset

# 2. dataset split
python -m landmark_candidate.split_data \
  --data-root "$DATA_ROOT" \
  --out "$DATA_ROOT/splits/kfold_seed20260513.json" \
  --seed 20260513 \
  --folds 5 \
  --test-ratio 0.15

# 3. train one fold
torchrun --nproc_per_node=4 -m landmark_candidate.train_multitask \
  --config configs/experiments/{config_name}.yaml \
  --data-root "$DATA_ROOT" \
  --split-file "$DATA_ROOT/splits/kfold_seed20260513.json" \
  --fold 0 \
  --output-dir runs/{run_name}_fold0

# 4. collect metrics
# W&B scalar export 또는 runs/{run_name}/metrics.json을 docs/experiments/paper registry에 반영한다.

Artifact Ledger Schema

모델 파일은 이름만으로 추적하지 않는다. 어떤 데이터와 config에서 나온 파일인지 함께 기록한다.

{
  "artifact_id": "mobileclip2_s4_partial_arcface_hardneg_fold0_best",
  "artifact_type": "pytorch_checkpoint | onnx | int8 | embedding_index",
  "source_run": "",
  "dataset_fingerprint": "",
  "split_manifest": "",
  "config_path": "",
  "git_commit": "",
  "file_path": "",
  "file_size_bytes": null,
  "sha256": "",
  "created_at": "",
  "validation": {
    "pytorch_metric_recorded": false,
    "onnx_parity_checked": false,
    "int8_parity_checked": false,
    "mobile_latency_checked": false
  },
  "notes": []
}

Artifact 검증 단계

1. Checkpoint sanity: class count, embedding dim, config, state_dict load 가능 여부를 확인한다.
2. PyTorch evaluation: validation/test metric과 run folder의 best epoch를 연결한다.
3. ONNX export: 같은 입력 fixture에서 Top-3와 embedding cosine parity를 확인한다.
4. INT8/mobile artifact: Top-3 일치성, 파일 크기, cold/warm latency, memory를 분리 기록한다.
5. Demo regression: 이미지 검색, 자연어 검색, 상세보기, confidence policy, logging을 앱에서 확인한다.

허용 오차와 재검증 기준

재현성 완료 체크리스트

• code commit hash가 기록되어 있다.
• dataset fingerprint와 split manifest가 기록되어 있다.
• config와 실제 run name이 일치한다.
• full/partial/LoRA 이름이 실제 trainable policy와 일치한다.
• W&B run id와 local run folder가 연결되어 있다.
• metrics export 원본이 보관되어 있다.
• checkpoint와 artifact checksum이 기록되어 있다.
• 결과표에 mean/std와 fold별 값이 함께 있다.
• 실패/제외 실험이 삭제되지 않고 사유가 기록되어 있다.
• 최종 모델 선택 전 ONNX/INT8/mobile runtime 검증 계획이 있다.