# 반도체 ML 검사 화면 · Model Lab

npm 0.17.0부터 제공됩니다.

## 시작

프로젝트 루트에서 `node bin/oscode.js`를 실행한 뒤 입력창 아래 **모델 검사** 버튼을 클릭합니다. 좁은 터미널에서는 **검사**로 표시됩니다. “반도체 검사 화면 열어줘” 또는 “모델 검사 화면 보여주세요”라고 입력해도 열립니다. **작업 시작 → 반도체 ML 모델 검사** 메뉴도 사용할 수 있습니다. `/ml`도 동일하게 브라우저 화면을 엽니다. BUILD 모드에서 기존 브라우저 실행 승인 정책을 따릅니다. 모델 API 키 없이 샘플 체험과 결과 파일 가져오기가 가능합니다.

서버는 임의 포트의 127.0.0.1에만 바인딩됩니다. `/ml close` 또는 CLI 종료 시 닫힙니다. 브라우저를 닫는 것만으로 서버가 종료되지는 않습니다. 탭 새로고침 시 이미지·모델 설정·결과는 초기화됩니다. 필요한 결과는 JSON으로 내보내세요.

## 지원하는 모델 작업

| task | 화면 | predictions 항목 |
|---|---|---|
| classification | 라벨별 점수 막대 | label, score |
| detection | 원본 이미지 위 사각형 | label, score, box: [x,y,width,height] |
| segmentation | 원본 이미지 위 폴리곤 | label, score, polygon: [[x,y],…] |

모델 구조(CNN, ViT, YOLO 등)를 이름으로 추측하지 않습니다. 등록한 task와 명시적인 입출력 규격을 사용합니다. 픽셀 마스크/RLE는 현재 지원하지 않으며 서버에서 폴리곤으로 변환해야 합니다. 센서 시계열·회귀·웨이퍼 다이 행렬은 이번 화면의 지원 범위가 아닙니다.

## 모델 규격 등록

`examples/ml/detection.manifest.json`을 불러오거나 JSON 편집기를 사용합니다. A/B 슬롯에 각각 모델 ID와 버전을 등록합니다. endpoint 없이도 결과 JSON을 가져올 수 있습니다.

```json
{
  "schema": 1,
  "id": "defect-detector",
  "version": "1",
  "task": "detection",
  "labels": ["scratch", "particle", "normal"],
  "input": {
    "type": "image",
    "preprocessingOwner": "server",
    "preprocessing": "서버에서 RGB 변환, 리사이즈, 정규화 후 추론"
  },
  "output": { "coordinates": "original-pixels" },
  "endpoint": "http://127.0.0.1:8000/infer"
}
```

전처리 설명은 실제 서버 동작에 맞게 수정해야 합니다. 클라이언트는 전처리를 실행하지 않으며, 원본 파일을 보냅니다. 서버는 리사이즈/패딩을 역변환해 원본 픽셀 좌표를 반환해야 합니다.

## 검사 순서

1. 합성 샘플로 세 작업 유형을 체험하거나 PNG/JPEG/WebP 이미지(10 MiB·25 MP 이하)를 선택합니다.
2. A/B 모델 규격을 적용합니다. 규격·이미지·유형 변경 시 기존 결과를 초기화합니다.
3. 각 슬롯에 결과 JSON(4 MiB 이하)을 가져오거나 **이미지 전송 · 추론** 버튼을 누릅니다. 표시된 서버 주소에 전송하는 것을 확인해야 요청이 발생합니다.
4. 임계값으로 표시할 결과를 필터링합니다. 이 값은 합격/불합격 판정이나 점수 보정을 하지 않습니다.
5. 비교 결과를 JSON으로 내려받습니다. 파일에는 모델 규격·입력 해시·원본 결과·표시 임계값·데모 여부가 포함됩니다. 이미지 파일은 포함하지 않습니다.

## 추론 서버 계약

브라우저가 endpoint로 `POST multipart/form-data`를 보냅니다.

- `image`: 원본 이미지 파일
- `request`: JSON 문자열 `{schema,modelId,modelVersion,task,image:{sha256,width,height},input,output}`

서버는 요청된 모델·이미지를 실제로 처리한 다음 JSON을 반환해야 합니다.

```json
{
  "schema": 1,
  "modelId": "defect-detector",
  "modelVersion": "1",
  "task": "detection",
  "image": { "sha256": "입력 파일 바이트의 SHA256", "width": 800, "height": 500 },
  "predictions": [{ "label": "scratch", "score": 0.91, "box": [160,150,400,75] }]
}
```

`image.sha256`와 크기는 현재 이미지와 정확히 일치해야 합니다. 라벨은 등록 목록 안에 있어야 하며 score는 0~1, 좌표는 원본 이미지 범위여야 합니다. 최대 결과 2000개, 폴리곤당 꼭짓점 10000개입니다. 빈 결과는 허용되지만 정상 판정을 뜻하지 않습니다.

브라우저 직접 요청이므로 서버의 CORS 설정에서 화면에 표시된 로컬 origin을 허용해야 합니다. 쿠키/인증정보는 보내지 않으며 HTTP 리다이렉트도 따르지 않습니다. API 키 보관·OAuth는 지원하지 않습니다. 필요한 경우 조직의 인증 게이트웨이 또는 로컬 추론 어댑터를 별도로 구성하세요. 요청은 60초 후 취소되고, 사용자가 취소할 수도 있습니다. 서버 측 실행 취소까지 보장하지는 않습니다.

## 결과 해석

합성 샘플은 실제 추론과 구분됩니다. 가져온 JSON의 출처나 실제 모델 실행 여부를 증명하지는 않습니다. 서로 다른 모델 점수는 동일하게 보정된 확률이라고 가정하면 안 됩니다. 현재 A/B 기능은 시각적 비교이며 정답 기반 정확도·정밀도·재현율·IoU 평가나 통계적 실험 기능은 아닙니다.

내보낸 비교 보고서는 두 슬롯을 포함한 보관용 파일입니다. 슬롯의 결과 가져오기는 단일 응답 JSON을 받으므로 재사용하려면 보고서의 `slots.A.result` 또는 `slots.B.result`를 별도 JSON으로 저장하세요.

검증: 스키마/권한/서버 경계 테스트와 Chromium에서 작업 유형 전환·표시 필터·A/B 내보내기·잘못된 이미지 결과 거부·확인 후 전송·모바일 너비를 검사합니다. 추론 연결 테스트는 mock 응답을 사용하며 실제 모델 가중치를 검증하지 않습니다.

## MLflow 연결 (개발 버전)

모델 연결 설정에서 MLflow 로컬/원격 방식을 선택할 수 있습니다. 적용 후 선택한 검사 화면으로 자동 이동합니다. `dataframe_split` 이미지 컬럼 및 `predictions` 응답 계약과 지원 제한은 [MLflow 연동 가이드](mlflow.md)를 참고하세요. npm 0.17.0에는 아직 포함되지 않습니다.