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

0.24.0 기능 기준입니다. npm 게시 여부와 사용 가능한 기능은 설치·게시된 패키지 버전을 별도로 확인하세요.

## 실행

웹 CLI의 **작업실 → 반도체 모델 비교 → 검사 실패 사례 모으기**에서 가상 검사 환경을 새 탭으로 엽니다. 작업실의 **가상 생산라인** 패널에도 같은 링크가 있습니다. 기존 **모델 검사** 버튼 → Model Lab → **가상 검사 환경 열기** 경로도 사용할 수 있습니다. 시나리오를 설정한 뒤 **검사 시작**을 누릅니다.

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 전체 이미지의 서버 전송을 확인합니다. 동일 시드·조건·임계값으로 모델 버전을 바꿔 반복할 수 있습니다. 발견한 오류의 PNG를 그대로 비교하려면 아래 회귀 세트를 사용하세요. 버전은 사용자 지정 메타데이터이며 서버의 실제 배포 모델 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는 정상 응답 케이스의 클라이언트 처리 시간에 최근접 순위 방식을 적용합니다. 이미지 인코딩·해시·전송·서버·응답 처리를 포함합니다. 케이스 간 대기 시간은 제외합니다. 순수 모델 추론 시간이나 공장 처리량 지표가 아닙니다.

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

## 오류 사례를 회귀 검사로 재사용

**검사 회귀 작업실**은 이전 검사에서 발견한 오류를 다음 모델에서도 같은 입력으로 확인하는 기능입니다.

1. LOT 검사를 실행하고 다이 목록에서 과검출·미검출 사례를 선택합니다.
2. 회귀 세트 이름(1~80자)을 입력합니다. 기존 세트를 비우고 새로 시작할 때는 **새 회귀 세트**를 누릅니다.
3. 필요하면 정답 JSON을 수정하고 **정답을 검수했습니다**를 체크합니다.
4. **선택한 실패 저장**으로 선택한 다이를 세트에 추가합니다. 처음 저장한 사례의 검사 당시 점수 임계값·IoU가 세트에 고정됩니다.
5. **회귀 세트 저장**으로 JSON을 내려받습니다. 다음에는 **회귀 세트 열기**로 이어서 사용합니다.

정상 응답을 받은 다이 중 FP 또는 FN이 있는 사례만 추가합니다. 통신 실패·취소·미실행은 예측 오류 사례로 추가하지 않습니다. 최대 48개 사례, 개별 PNG는 1 MiB, PNG 원본 파일 바이트 합계는 12 MiB입니다. 이후 추가하는 사례도 같은 점수 임계값·IoU로 검사한 결과여야 합니다.

추가한 사례에는 **실제 요청에 사용한 PNG**, LOT·웨이퍼·다이 정보, 정답 사각형, 기준 예측과 실행기 종류를 보존합니다. 재실행은 생성기나 시드를 다시 그리는 대신 저장한 PNG를 사용합니다. 같은 이미지와 같은 정답은 중복 추가하지 않으며, 같은 이미지에 다른 검수 정답을 적용하면 별도 사례가 됩니다.

기본 정답은 생성기가 만든 합성 참조 정답입니다. 정답 입력란에 사람이 확인한 사각형 목록을 JSON으로 입력하고 **정답을 검수했습니다**를 체크하면 사용자 검수 정답으로 기록합니다.

```json
[
  {"label":"scratch","box":[20,30,45,6]},
  {"label":"particle","box":[120,80,12,12]}
]
```

좌표는 384×256 원본 이미지의 `[x,y,width,height]`이며 라벨은 scratch·particle입니다. 결함이 없다는 검수 결과는 `[]`로 입력합니다. 검수 정답을 적용하면 저장된 기준 예측을 세트의 임계값·IoU로 다시 평가합니다. 이때 FP와 FN이 모두 0이 되면 오류 사례 추가 대상에서 제외됩니다. 검수 표시는 사용자가 확인했다고 기록한 것이며 외부 검수나 라벨 정확도를 인증하지 않습니다.

### 저장과 다시 열기

회귀 세트를 JSON으로 내려받아 보관하고 다음 검사 화면에서 가져올 수 있습니다. base64 이미지와 기록을 포함한 JSON 파일은 최대 18 MiB입니다. 가져오기는 PNG 형식·크기·사각형·사례 수·용량과 SHA-256 지문을 검사하고, 저장된 기준 예측의 평가와 집계를 다시 계산합니다. 파일의 일부만 바꾸고 예전 지문을 유지한 경우 가져오기를 거절합니다.

사례 지문은 정확한 PNG 파일과 정답을 연결하고 세트 지문은 기준 예측을 포함한 전체 세트를 연결합니다. 지문은 내용 일치 확인용입니다. 파일 작성자·실제 서버 모델 버전·검수자의 신원이나 결과의 진위를 보증하지 않습니다. 가져온 세트는 합성 데이터라는 표시와 원래 모의 실행 여부를 유지합니다. 세트와 실행 결과는 브라우저 메모리에만 있으므로 새로고침 전에 저장하세요.

### 같은 이미지로 다음 모델 확인

**내 MLflow 모델**을 선택하고 기존 detection / records 규격으로 모델을 설정한 뒤 **새 모델로 회귀 검사**를 누릅니다. 전송 대상과 사례 수를 확인하고 저장한 PNG만 보냅니다. 정답·기준 예측은 추론 요청에 포함하지 않습니다. 현재 설정에서는 모델·실행기만 사용하며 점수 임계값·IoU는 세트에 고정된 값을 사용합니다. LOT 생성 설정을 변경해도 세트의 이미지와 평가 기준은 바뀌지 않습니다.

기준·후보 예측을 같은 점수 임계값과 IoU로 평가해 사례별 FP·FN 변화와 **기존 오류 감소·잔존·악화**를 확인합니다. 전체 합계가 줄어도 한 사례의 FP 또는 FN이 늘면 통과하지 않습니다.

통과에는 다음 조건이 모두 필요합니다.

- 모든 사례에 저장된 이미지와 연결된 정상 응답이 있어야 합니다. 누락·중복·이미지 불일치·형식 오류·통신 실패·취소는 미완료입니다.
- 기준과 후보에 같은 점수 임계값·IoU를 사용하고, 각 사례의 FP와 FN이 기준보다 늘지 않아야 합니다.
- 설정한 전체 FP·FN 허용 개수 이하여야 합니다. 기본값은 각각 0개입니다.

진행 중 또는 일부 실패한 실행을 통과로 표시하지 않습니다. 모의 실행 결과는 정답을 참조하는 시연으로 계속 구분하며, MLflow 모델의 id/version도 사용자 설정값으로 기록합니다. **회귀 검사 중단**은 현재 요청을 취소하고 이후 사례를 보내지 않습니다. **검사 결과 저장**으로 회귀 결과와 세트 지문을 내려받아 보관하세요.

오류 사례만 모은 표본의 통과는 **그 사례들에서 정한 기준을 충족했다는 뜻**입니다. 정상 사례는 이 세트에 포함하지 않으므로 전체 데이터에서 발생하는 새 오류를 검사했다고 볼 수 없습니다. 전체 정상률·일반화 성능·실제 생산 성능·통계적 유의성 또는 배포 승인을 뜻하지 않습니다. 실제 모델을 연결한 회귀 실행도 합성 이미지에 대한 확인이며 실제 현장 데이터의 검증을 대신하지 않습니다.

## 중단과 내보내기

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

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

## 검증 범위

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