# MLflow → OSCODE 검사 화면

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

## 버튼으로 연결하고 검사 화면으로 이동

1. OSCODE 입력창의 **모델 검사** 버튼을 클릭합니다.
2. 이미지와 작업 유형을 선택한 뒤 **모델 연결 설정**을 펼칩니다.
3. A/B 슬롯을 선택하고 **연결 방식 → MLflow · 로컬 서버**를 선택합니다.
4. `http://127.0.0.1:5000/invocations`와 모델의 이미지 컬럼명, 응답 형식을 입력합니다. JSON 영역에서 id, version, labels와 전처리 설명을 실제 모델에 맞게 수정합니다.
5. **MLflow 연결 적용**을 누르면 설정 영역을 접고 선택한 모델의 검사 카드로 자동 이동합니다. 이는 설정 적용이며 서버 접속 성공을 의미하지 않습니다.
6. **이미지 전송 · 추론**을 누르고 대상 주소를 확인하면 서버 호출 후 결과를 표시합니다. 연결 적용만으로 이미지를 보내지는 않습니다.

여기서 자동 이동은 OSCODE 검사 화면으로의 스크롤·포커스 이동입니다. 원격 웹사이트로 이동하거나 HTTP 리다이렉트를 허용하는 기능은 아닙니다. HTTP 리다이렉트 응답은 차단합니다.

## 지원 범위

이미지 분류, 결함 탐지, 폴리곤 분할을 지원합니다. 현재 입력은 `dataframe_split`의 **이미지 base64 단일 컬럼, 단일 행**입니다. 모델이 해당 컬럼을 받도록 signature와 pyfunc의 입력 처리를 구성해야 합니다. 모든 MLflow 모델이 이미지 base64를 바로 받는 것은 아닙니다. 텐서·표·시계열 입력, 범용 응답 필드 매핑, Databricks 인증·API 키 저장은 아직 지원하지 않습니다.

```json
{
  "dataframe_split": {
    "columns": ["image_base64"],
    "data": [["이미지 파일 바이트의 base64 문자열"]]
  }
}
```

문자열 컬럼이면 모델 내부에서 base64를 디코딩합니다. binary signature를 선언하면 MLflow가 디코딩한 바이트를 모델에 전달할 수 있으므로 실제 signature에 맞춰 처리해야 합니다. 리사이즈·정규화와 좌표 역변환은 서버의 책임입니다.

## 응답 형식

**label·score 레코드 목록**:

```json
{"predictions":[{"label":"scratch","score":0.91}]}
```

탐지는 각 레코드에 `box: [x,y,width,height]`, 분할은 `polygon: [[x,y],…]`를 추가합니다. 좌표는 원본 이미지 픽셀입니다. 세 작업 예제 규격은 `examples/mlflow/`에 있습니다.

**분류 점수 배열**은 분류에서만 사용하며 labels와 순서·개수가 같아야 합니다:

```json
{"predictions":[[0.91,0.06,0.03]]}
```

점수는 0~1 범위이며 통계적으로 보정된 확률을 보증하지 않습니다. 클래스 번호만 반환하는 모델은 label·score 응답을 반환하는 별도 어댑터가 필요합니다. 점수를 임의로 만들어 넣지 않습니다.

MLflow 응답에는 보통 요청 이미지 해시나 모델 버전이 없으므로, OSCODE는 요청 시점의 이미지·설정과 응답을 연결합니다. 내보낸 결과의 `association: client-request`, `modelIdentityVerified: false`가 이를 나타냅니다. 실제 배포된 모델 버전을 검증했다는 의미는 아닙니다.

## 로컬과 원격

- **로컬**: CLI가 동일 컴퓨터의 `http://127.0.0.1:포트/invocations`로 중계합니다. localhost와 IPv6 루프백도 허용합니다. 원격 주소·다른 경로·자격증명·쿼리·리다이렉트는 거부합니다. 브라우저 CORS 설정이 필요하지 않습니다.
- **원격**: 브라우저에서 설정된 endpoint로 직접 JSON을 전송합니다. 서버의 CORS 허용이 필요하며 쿠키나 인증 헤더를 보내지 않습니다. 인증이 필요한 엔드포인트에는 별도 게이트웨이가 필요합니다.
- 이미지 10 MiB, 요청 중계 15 MiB, 응답 4 MiB, 60초 시간 제한입니다. 취소가 서버의 모델 실행 중단까지 보장하지는 않습니다.

## 실제 모델 배포

이미 등록한 모델 URI를 사용합니다:

```bash
mlflow models serve -m "models:/YOUR_MODEL/1" -p 5000
```

Tracking UI 주소가 아니라 **추론 서버의 /invocations 주소**를 입력하세요. HTTP 오류는 모델 입력 컬럼과 signature를 확인하고, 형식 오류는 위 predictions 계약과 라벨·좌표를 확인하세요.

검증에는 MLflow 규격을 흉내 낸 로컬 HTTP 서버와 Chromium을 사용했습니다. 사용자 MLflow 모델·가중치·실제 엔드포인트에 대한 추론 검증은 주소와 입력·응답 예제가 있어야 가능합니다.

공식 참고: [MLflow 로컬 모델 배포 및 요청 규격](https://mlflow.org/docs/latest/ml/deployment/deploy-model-locally/).