# 반도체 외관 검사 가상환경

개발 버전 기능입니다. npm 0.17.0에는 아직 포함되지 않았습니다.

## 실행

OSCODE의 **모델 검사** 버튼 → 브라우저 상단 **가상 검사 환경 열기** → **검사 시작**.

API 키 없이 모의 실행기로 체험할 수 있습니다. 12/24/48개의 합성 다이를 LOT·웨이퍼·다이 ID와 순서대로 처리합니다. 목록은 논리적 검사 순서이며 원형 웨이퍼상의 실제 물리 위치를 뜻하지 않습니다.

## 가상 검사 데이터

- 기하학적 패턴 위에 스크래치(scratch), 파티클(particle)과 정상 케이스를 생성합니다.
- 정답은 라벨과 원본 이미지의 사각형 좌표입니다. 이미지 크기는 384×256입니다.
- 재현 시드를 고정하면 결함 위치와 목록이 같습니다. 기준·밝기 저하·흐림·노이즈를 바꿔도 정답 좌표는 유지합니다.
- 밝기 저하: 검은색 50% 오버레이. 흐림: 브라우저 blur 2px. 노이즈: 고정 시드의 균일 난수로 RGB를 변화시킵니다.
- **이미지·정답 내려받기**는 base64 PNG, 좌표, 시드, 조건, 생성기 버전을 JSON으로 저장합니다. 브라우저별 PNG 인코딩과 blur 렌더링 차이가 있으므로 바이트 단위 재현이 필요하면 저장한 이미지를 사용하세요.

실제 현미경 영상·광학계·재료 물성·생산 장비를 물리적으로 시뮬레이션하지 않습니다. 실제 검사 환경의 오염·조명·렌즈·공정 분포를 보증하지 않습니다. 이 데이터에 잘 맞는 모델이 실제 불량을 잘 찾는다는 뜻은 아닙니다.

## 모의 실행과 실제 모델

**UI 시연용 모의 실행기**는 정답을 읽어 일부 결함을 누락하거나 가짜 예측을 추가합니다. 미검출·과검출·정상 상태를 확인하는 테스트 도구이며 학습 모델이 아닙니다. 처리 시간을 실제 모델 속도와 비교하지 마세요.

**내 MLflow 모델**을 선택하면 모델 규격 입력란이 열립니다. 기본 연결 예시를 본인 모델의 id/version/endpoint에 맞게 변경합니다. detection + records 응답을 사용하고 scratch·particle 라벨을 포함해야 합니다. 모델이 다른 결함 taxonomy를 사용한다면 이 합성 데이터와 평가 라벨을 맞추는 작업이 먼저 필요합니다.

이미지 파일만 dataframe_split의 base64 컬럼으로 보냅니다. 정답 라벨이나 좌표를 추론 요청에 넣지 않습니다. 자세한 서버 규격은 [MLflow 가이드](mlflow.md)를 참고하세요. 현재 가상환경의 정답 평가 대상은 **사각형 결함 탐지**입니다. 분류·분할 UI는 일반 Model Lab에서 사용할 수 있지만 이 시뮬레이터의 평가에는 아직 포함되지 않습니다.

실행 전 LOT 전체 이미지의 서버 전송을 확인합니다. 동일 시드·조건·임계값으로 모델 버전을 바꿔 반복하고 각 보고서를 저장하면 비교할 수 있습니다. 버전은 사용자 지정 메타데이터이며 서버의 실제 배포 모델 ID를 검증하지 않습니다.

## 결과 판정

점수 임계값 이상 예측을 점수 내림차순으로 정렬하고, 같은 라벨의 아직 매칭되지 않은 정답 중 IoU가 가장 큰 항목과 1:1 매칭합니다. IoU 기준 이상만 TP입니다. 중복 예측은 추가 TP가 되지 않습니다.

- TP: 정답과 매칭한 예측
- FP: 정답과 매칭되지 않은 예측(과검출)
- FN: 예측과 매칭되지 않은 정답(미검출)
- Precision = TP/(TP+FP), recall = TP/(TP+FN). 분모가 0이면 null입니다.
- 응답 형식 오류·HTTP 실패·시간 초과는 오류로 분리합니다. 실패·취소는 TP/FP/FN 계산에서 제외하므로 반드시 완료 비율도 함께 확인해야 합니다.
- P95는 정상 응답 케이스의 클라이언트 처리 시간에 최근접 순위 방식을 적용합니다. 이미지 인코딩·해시·전송·서버·응답 처리를 포함합니다. 케이스 간 대기 시간은 제외합니다. 순수 모델 추론 시간이나 공장 처리량 지표가 아닙니다.

정답 표시를 끄면 이미지와 예측만 볼 수 있습니다. 목록 필터로 미검출·과검출·오류 케이스를 따로 검토할 수 있습니다.

## 중단과 내보내기

중단하면 현재 요청을 취소하고 이후 다이를 보내지 않습니다. 서버 내부 모델 실행까지 취소된다는 보장은 없습니다. 다시 시작하면 전체 LOT를 처음부터 검사합니다. 실행 중 시나리오와 모델 설정은 잠깁니다.

보고서에는 합성 데이터 표시, 시나리오, 실행기 종류, 모델 설정, 평가 임계값, 케이스별 응답·이미지 해시·오류·집계가 담깁니다. 새로고침이나 새 검사 전에 내려받으세요. 실제 공정 성능 판정에는 현장 데이터와 정답 검수가 별도로 필요합니다.

## 검증 범위

자동 테스트는 시나리오 재현성, 라벨별 1:1 IoU 매칭, 오류 제외 집계, Chromium의 재생·필터·파일 내보내기·모바일 레이아웃, HTTP 모의 서버 연결·503 오류·요청 취소를 확인합니다. 사용자 MLflow 서버나 학습된 가중치에 대한 검증은 아직 수행하지 않았습니다.