Sprint 1 Gap Analysis 2026-05-16

결론

Sprint 1의 핵심 시연 흐름은 이미 성립했다. 학습된 MobileCLIP2-S4는 13-class 내부 locked test에서 top-1 0.9910, top-3 0.9985, macro F1 0.9876을 기록했고, 로컬 데모앱은 이미지 검색, 자연어 검색, 이름 검색, 상세 페이지, 로그 저장까지 동작했다.

남은 핵심은 모델 교체가 아니라 신뢰도 정책과 검증 구조다. 현재 데모앱은 closed-set ranker에 가깝고, top1 < 0.25만으로 reject를 결정한다. 그래서 화면 캡처, 범위 밖 유사 이미지, 40/30/20처럼 애매한 결과, 저화질 입력이 서로 구분되지 않는다. 시연 전에는 matched, ambiguous, out_of_scope, low_quality 4상태 정책과 회귀 테스트 세트를 먼저 고정하는 것이 가장 현실적이다.

사용한 근거

근거	확인 내용	해석
13-class W&B export	`C:\Users\hi\Downloads\종설_작업중\mobileclip2_s4_fold0_20260514_081351`. test_count 669, top-1 0.9910, top-3 0.9985, macro F1 0.9876.	내부 split에서는 매우 강하지만, negative/OOD와 실제 사용자 사진 일반화는 별도 검증이 필요하다.
데모 raw log	`landmark-demo-app/logs/demo.jsonl` 24건. 이미지 19건, 텍스트 5건, 현 threshold 기준 below_threshold 0건.	성공 케이스와 애매한 케이스가 함께 확인됐다. 현재 threshold 0.25는 너무 느슨하다.
1차 데모 테스트 문서	청와대, 종묘, 낙산공원 대표 케이스는 pass. 화면 캡처, art gallery, 돌담있는곳, 경복궁 전경은 calibration 또는 metadata 보강 필요.	데모는 작동하지만, 사용자 신뢰를 위해 low-confidence UI와 로그 사유 코드가 필요하다.
서브에이전트 리뷰	analyst는 checkpoint/문서 정합성, test-engineer는 수동/자동 test matrix, architect는 4상태 policy와 negative dataset 구조를 제안했다.	세 관점 모두 model보다 data/policy/test gap이 더 급하다는 결론으로 수렴했다.
기존 결정 문서	ADR-0003, ADR-0004, ADR-0005, Dataset Contract, Scope Audit.	자연어 검색, 모델 후보, 학습 설정은 정리됐지만, reject와 bohyunsanshingak 범위 결정이 아직 흔들린다.

A. Sprint 1 Gap Analysis

영역	현재 상태	Sprint 1 기준 판단	다음 액션
모델 학습	MobileCLIP2-S4 13-class fold0 test top-1 0.9910, top-3 0.9985.	충분. 시연 모델 후보로는 강하다.	checkpoint가 데모앱 `best.pt`와 동일한 run인지 명시하고 문서화한다.
데모 기능	이미지, 자연어, 이름 검색과 상세 페이지가 Streamlit에서 동작한다.	충분. 앱 형태가 완전하지 않아도 기술 시현은 가능하다.	PC에서 서버를 열고 스마트폰 브라우저로 접속하는 runbook을 추가한다.
신뢰도 정책	`reject_threshold=0.25`와 `below_threshold` 하나만 사용한다.	부족. 실제 사용자 신뢰를 떨어뜨릴 수 있다.	top-1, margin, 품질, scope를 이용한 4상태 정책을 도입한다.
Out-of-scope 처리	negative 데이터와 OOD test set이 얕고, 화면 캡처도 통과했다.	부족. 시연 질문에서 바로 지적될 가능성이 높다.	screenshot, non-landmark, similar landmark negative를 최소 regression set으로 고정한다.
자연어 검색	명확한 alias는 좋지만 `art gallery`, `돌담있는곳`이 실패했다.	부분 충족. 부가 기능으로는 좋지만 metadata 보강이 필요하다.	영문 alias/tag와 한국어 동의어를 보강하고, compound query 처리를 개선한다.
데이터 범위	`bohyunsanshingak`이 13-class catalog에 있으나 종로 범위와 충돌한다.	미결정. 설명 없이 두면 프로젝트 범위가 흐려진다.	Sprint 1은 임시 포함 또는 negative 전환 중 하나를 문서로 결정한다. 권장은 negative 전환이다.
테스트 구조	수동 smoke test는 있으나 자동 regression은 없다.	부족. 수정 후 성능이 깨졌는지 추적하기 어렵다.	demo-regression-v1과 pytest/Streamlit AppTest 기반 최소 자동 검사를 만든다.
문서 정합성	모델/데모/배포 문서는 많지만 checkpoint, policy, demo 구조의 연결이 약하다.	부분 충족. 팀원이 따라가기에는 보강이 필요하다.	문서 hub, demo app guide, serving contract, ADR을 같은 policy 단어로 맞춘다.

B. 문제점별 개선 계획

문제	관측 증거	가능한 원인	개선 방향
학습 점수는 높은데 데모가 애매함	13-class test top-1은 0.9910이나, 실제 demo log에서는 0.326, 0.351 같은 통과 케이스가 있다.	test split은 positive closed-set이고, 데모 입력은 negative/OOD/유사 전경을 포함한다.	학습 성능과 데모 신뢰도 평가를 분리한다. 모델 accuracy와 reject calibration을 별도 지표로 둔다.
40/30/20처럼 애매한 결과	`12341.jpg`는 청와대 0.351, 광화문 0.257, 청계천 0.213 수준으로 반복됐다.	top-1만 보고 matched로 처리해서 score spread가 낮은 상황을 구분하지 못한다.	top-1과 margin을 함께 보고 `ambiguous` 상태로 분기한다.
DB에 없는 이미지 input	화면 캡처 PNG가 MMCA 0.326으로 통과했다.	negative detector와 screenshot/non-landmark calibration set이 없다.	out_of_scope regression set을 만들고, 낮은 top-1 또는 낮은 margin은 Top-3 대신 안내 문구를 우선한다.
저화질 입력 처리 부재	현재 검사는 주로 확장자, 크기, decode 가능 여부에 가깝다.	blur, dark, tiny crop, occlusion 같은 품질 신호가 policy에 없다.	시연 전에는 수동 케이스를 고정하고, 이후 blur/brightness/min-side heuristic을 추가한다.
영어 일반 질의 실패	`art gallery`가 MMCA가 아니라 보현산 신각 0.325로 나왔다.	MMCA metadata에 art gallery, art museum, modern art museum 같은 영문 표현이 부족하다.	`landmark_info.json`과 text index에 영문 alias/tag를 보강한다.
한국어 compound query 실패	`돌담있는곳`이 낙산공원이 아니라 보현산 신각 0.511로 나왔다.	공백 없는 한국어 표현, 돌담/성곽/성벽/한양도성 동의어 처리가 약하다.	metadata를 먼저 보강하고, 이후 query normalization 또는 char n-gram keyword score를 검토한다.
bohyunsanshingak 범위 혼선	catalog에는 포함돼 있지만 종로 landmark demo 범위와 어긋난다.	데이터 수집 과정에서 유사 전통건축 positive와 hard negative의 경계가 섞였다.	권장은 `similar_landmark` negative 전환이다. 시연상 유지한다면 임시 포함이라고 명시한다.

C. 데모/테스트 구조

시연 환경 목표

Sprint 1 시연은 실제 모바일 앱이 아니어도 된다. 다만 사용자가 스마트폰에서 앱을 쓰는 것처럼 보여주려면 Windows 노트북에서 Streamlit 서버를 띄우고 같은 Wi-Fi의 스마트폰 브라우저로 접속하는 구성이 가장 빠르다.

cd C:\Users\hi\Downloads\종설_작업중\landmark-demo-app
streamlit run src/landmark_demo/app.py --server.address 0.0.0.0 --server.port 8501

# 스마트폰에서 접속
http://<PC_IP>:8501

위 명령은 데모 앱의 실제 entrypoint를 확인한 뒤 runbook에 고정해야 한다. 방화벽에서 Python 또는 8501 포트 허용이 필요할 수 있다.

테스트 묶음	입력 예시	확인할 것
정상 이미지	청와대, 종묘, 낙산공원, 청계천 대표 이미지	Top-1 정답, top-1/margin 충분, 상세 페이지 이동.
유사 landmark	광화문, 경복궁 근정문, 전통 건축물 전경	정답 또는 `ambiguous`가 나오는지. 잘못된 확정 문구가 없는지.
범위 밖 입력	음식, 실내, 앱 화면 캡처, 종로 외 관광지	`out_of_scope`와 안내 문구. 내부 로그에는 raw top-3가 남는지.
저품질 입력	흐림, 어두움, 너무 작은 crop, 과도한 확대	`low_quality` 또는 `ambiguous`로 과신하지 않는지.
자연어	미술관, Royal Ancestral Shrine, art gallery, 돌담있는곳	영문 alias, 한국어 동의어, 실패 query의 회귀 여부.
이름 검색	청와대, Jongmyo, MMCA, Naksan	metadata 기반 검색과 상세 페이지 라우팅.
로그	각 검색 수행 후 `logs/demo.jsonl`	status, reason_codes, top1/top2/margin, elapsed_ms, model_version 기록.

자동화 우선순위

1순위는 모델을 매번 로드하지 않는 deterministic regression이다. keyword/name/detail/logging/threshold policy는 mock bundle로 빠르게 검사한다. 2순위는 실제 best.pt를 쓰는 slow smoke test다. 이 테스트는 시연 전 또는 모델 교체 후에만 돌린다.

D. 데이터셋 개선 제안

제안	Sprint 1 적용	이후 확장
현재 폴더 구조 유지	`Dataset/<landmark_id>/{labels.json,images/}`는 유지한다.	수집이 계속 늘어날 수 있으므로 manifest와 fingerprint로 버전을 추적한다.
역할 라벨 추가	`label_status`, `quality_status`, `negative_type`를 실제로 채운다.	`scope_status=in_scope\|out_of_scope_similar\|out_of_scope_other`를 추가한다.
bohyunsanshingak 정리	권장안은 지원 class에서 제외하고 `similar_landmark` negative로 이동.	유사 전통 건축물 reject 성능 평가에 사용한다.
negative set 확보	screenshot, non-landmark, similar landmark를 demo-regression-v1에 소량 고정.	버킷당 30-50장 이상으로 늘려 threshold calibration을 한다.
hard positive 보강	cheonggyecheon, gwanghwamun, gyeongbokgung_geunjeongmun 소수 class부터 확인.	시점, 계절, 거리, 야간, 부분 crop 기준으로 view_type을 태깅한다.
text metadata 보강	MMCA와 낙산공원 영문/한국어 일반 표현을 즉시 추가한다.	각 landmark별 `captions`, `keywords_en`, `keywords_ko`를 별도 검수한다.

E. 신뢰도/거절 정책

아래 수치는 24건 demo smoke test를 기반으로 한 seed threshold다. calibrated probability가 아니며, negative set이 늘어나면 반드시 재보정해야 한다.

상태	초기 판단 기준	사용자 문구	로그 사유 코드 예시
`matched`	이미지 top1 ≥ 0.60 또는 top1 ≥ 0.45 and margin ≥ 0.12. 텍스트는 alias/keyword hit와 margin을 함께 요구.	가장 가능성이 높은 장소는 `{name}`입니다.	`top1_high`, `margin_high`, `alias_hit`
`ambiguous`	top1은 낮지 않지만 margin이 낮거나, 0.25-0.60 구간에서 확정하기 어려운 경우.	한 곳으로 확정하기 어렵습니다. 가까운 후보를 함께 보여드립니다.	`top1_mid`, `margin_low`, `generic_query`
`out_of_scope`	top1 < 0.25, screenshot/non-landmark 판정, 또는 text keyword hit 없음 and top1 < 0.35.	지원 범위의 종로 랜드마크로 확인되지 않았습니다.	`top1_low`, `screenshot_like`, `keyword_miss`
`low_quality`	decode는 되지만 blur, dark, min-side, extreme crop 같은 품질 신호가 낮은 경우.	사진 품질이 낮아 판별하기 어렵습니다. 더 밝고 선명한 사진으로 다시 시도해 주세요.	`blur_detected`, `dark_detected`, `too_small`

로그 스키마 v1

{
  "policy_version": "sprint1-reliability-v1",
  "decision": "ambiguous",
  "reason_codes": ["top1_mid", "margin_low"],
  "input_kind": "image",
  "input_id": "12341.jpg",
  "model_version": "mobileclip2_s4_fold0_20260514_081351",
  "checkpoint_source": "best.pt",
  "top1_score": 0.351,
  "top2_score": 0.257,
  "margin": 0.094,
  "thresholds": {
    "match_top1": 0.45,
    "match_margin": 0.12,
    "reject_top1": 0.25
  },
  "top3": [
    {"landmark_id": "cheongwadae", "score": 0.351},
    {"landmark_id": "gwanghwamun", "score": 0.257},
    {"landmark_id": "cheonggyecheon", "score": 0.213}
  ],
  "elapsed_ms": 557,
  "ui_message_key": "ambiguous_candidates"
}

화면에는 과신 문구를 줄이고, 로그에는 raw score와 reason code를 충분히 남긴다. 이렇게 해야 시연 후 어떤 케이스가 정책 문제인지, 데이터 문제인지, 모델 문제인지 분해할 수 있다.

F. 문서화 개선 TODO

우선순위	문서	수정 내용
P0	Demo App Guide	PC LAN 스마트폰 접속 runbook, 방화벽 체크, demo-regression-v1 실행법을 추가한다.
P0	Serving Contract	`ambiguous`, `low_quality` 상태와 reason_codes, margin 필드를 계약에 추가한다.
P0	Scope Audit	Sprint 1에서 임시 포함인지, negative 전환인지 최종 결정을 표시한다.
P1	ADR-0004	13-class fold0 W&B export 수치와 checkpoint identity를 반영한다.
P1	ADR-0003	runtime text encoder와 build-time text embedding 사용 범위를 데모앱 기준으로 정리한다.
P1	Dataset Contract	`scope_status`, negative bucket, demo_regression tag를 추가한다.
P1	Demo Test Result	24건 raw log 요약과 “score는 probability가 아님” 문구를 유지하고, 새 policy 적용 후 재테스트 결과를 추가한다.

검증된 것과 아직 검증되지 않은 것

검증된 것: 13-class fold0 내부 test 성능, 로컬 Streamlit 데모의 핵심 흐름, 일부 성공/실패 demo log, Vercel 문서 배포 구조.

아직 검증되지 않은 것: 5-fold 평균 성능, 실제 smartphone native inference, ONNX export, negative/OOD calibrated threshold, bohyunsanshingak 최종 scope, 데모앱의 best.pt와 W&B run의 완전한 artifact 동일성.