> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/models/ko/evaluate/evaluate-trained-models.md).
# 학습된 모델 평가
## 소개
모델 평가는 다음을 보여줍니다:
1. 프로덕션 메트릭 탐색기, 모델을 실행할 최적의 신뢰도 임계값을 찾는 데 도움이 됩니다;
2. 모델 개선 권장 사항, 모델 정확도를 높이는 방법에 대한 제안을 제공합니다;
3. 클래스별 성능, 모델이 서로 다른 클래스를 얼마나 잘 식별하는지 보여줍니다;
4. 혼동 행렬, 모델이 강점을 보이고 어려움을 겪는 특정 클래스를 찾는 데 사용할 수 있으며,
5. 모델이 잘하거나 못하는 이미지 클러스터를 식별할 수 있는 대화형 벡터 탐색기;
모델 평가를 사용하면 모델의 개선 영역을 식별할 수 있습니다.
유료 사용자가 Roboflow에서 학습했거나 업로드한 모든 버전 관리 모델에 대해 모델 평가는 자동으로 실행됩니다. 수백 장의 이미지로 구성된 데이터셋의 평가에는 몇 분이 걸릴 수 있으며, 수천 장 이상의 이미지가 있는 대규모 데이터셋의 경우 몇 시간이 걸릴 수 있습니다.
### 지원되는 프로젝트 유형
모델 평가는 객체 탐지, 인스턴스 분할, 분류, 시맨틱 분할 프로젝트를 지원합니다.
시맨틱 분할의 경우, 주요 지표는 **mIoU** (평균 Intersection-over-Union)이며 mAP 대신 사용됩니다. 모든 지표(정밀도, 재현율, F1)는 인스턴스별이 아니라 픽셀 수준에서 계산됩니다. 클래스별 세부 내역에는 각 클래스의 IoU, 정밀도, 재현율, F1 및 최적 신뢰도 임계값이 표시됩니다. 혼동 행렬 값은 객체 수가 아니라 픽셀 수를 나타냅니다.
## 웹 앱
### 모델 평가 열기
모델의 혼동 행렬과 벡터 탐색기를 찾으려면 프로젝트에서 학습된 모델을 엽니다. 그런 다음 "평가 보기" 버튼을 클릭하세요:
혼동 행렬과 벡터 분석을 볼 수 있는 창이 열립니다.
### 프로덕션 메트릭 탐색기
프로덕션 메트릭 탐색기는 가능한 모든 신뢰도 임계값에서 모델의 정밀도, 재현율, F1 점수를 보여줍니다. 이 정보는 그래프로 표시됩니다.
이 통계를 바탕으로 프로덕션 메트릭 탐색기는 "최적 신뢰도"를 추천합니다. 이는 정밀도/재현율/F1 점수의 최적 균형을 제공하는 임계값입니다.
모델 평가가 완료되면 최적 신뢰도 임계값이 모델 추론 요청의 기본값으로 자동 적용됩니다. 클래스별 임계값이 있으면 그것도 적용되며, 자체 값이 없는 클래스에는 전역 임계값이 대체값으로 사용됩니다.
개별 추론 요청에서 다음을 전달하여 신뢰도 임계값을 계속 재정의할 수 있습니다: `신뢰도` 매개변수를 명시적으로.
슬라이더를 드래그하여 서로 다른 신뢰도 임계값에서 F1/정밀도/재현율 값을 볼 수 있습니다:
### 모델 개선 권장 사항
모델 평가의 모델 개선 권장 사항 섹션에는 모델 정확도를 높이는 방법에 대한 제안이 나열됩니다. 이러한 개선 사항은 모델로 계산한 혼동 행렬 결과를 기반으로 합니다. (이 페이지의 뒤쪽에서 혼동 행렬에 대한 자세한 정보를 확인하세요).
모델 개선 권장 사항 기능은 다음과 관련된 제안을 할 수 있습니다:
* 많은 거짓 음성을 예측하는 모델을 개선하는 방법.
* 많은 거짓 양성을 예측하는 모델을 개선하는 방법.
* 어떤 클래스가 자주 혼동되는지(잘못 식별되는지).
* 정확도를 높이기 위해 더 많은 데이터가 필요한 클래스.
* 테스트 또는 검증 세트가 너무 작을 수 있는 경우.
* 그 외에도.
### 클래스별 성능
클래스별 성능 차트는 데이터셋의 모든 클래스에 걸쳐 올바른 예측, 오분류, 거짓 음성, 거짓 양성이 각각 몇 개인지 보여줍니다.
이 정보를 사용하면 한눈에 모델이 잘 식별하는 클래스와 모델이 식별하는 데 어려움을 겪는 클래스를 확인할 수 있습니다.
데이터셋에 클래스가 많다면 "모든 클래스" 드롭다운을 열고 강조할 클래스를 선택하여 차트를 특정 클래스에 집중시킬 수 있습니다:
신뢰도 임계값 슬라이더를 움직여 서로 다른 신뢰도 임계값에서 이 차트가 어떻게 변하는지도 볼 수 있습니다:
기본적으로 이 차트는 우리가 추천하는 최적 신뢰도 임계값을 사용합니다.
### 혼동 행렬
혼동 행렬은 모델이 서로 다른 클래스에서 얼마나 잘 수행하는지 보여줍니다.
혼동 행렬은 학습된 모델로 테스트 및 검증 세트의 이미지를 실행하여 계산됩니다. 그런 다음 모델 결과를 데이터셋 주석의 "ground truth"와 비교합니다.
혼동 행렬 도구를 사용하면 다음을 식별할 수 있습니다:
* 모델이 잘 수행하는 클래스.
* 모델이 객체에 대해 잘못된 클래스를 식별하는 클래스(거짓 양성).
* 실제로는 아무것도 없는데 모델이 객체를 식별하는 사례(거짓 음성).
혼동 행렬 예시는 다음과 같습니다:
모델이 많은 클래스를 감지하면 혼동 행렬을 탐색할 수 있는 스크롤 바가 나타납니다.
기본적으로 혼동 행렬은 모델에 대해 계산된 최적 임계값에서 실행했을 때 모델이 얼마나 잘 수행하는지 보여줍니다.
신뢰도 임계값 슬라이더를 사용하여 신뢰도 임계값을 조정할 수 있습니다. 슬라이더를 조정하면 혼동 행렬, 정밀도, 재현율이 업데이트됩니다:
혼동 행렬의 각 상자를 클릭하면 해당 범주에 어떤 이미지가 표시되는지 볼 수 있습니다.
예를 들어 "거짓 양성" 열의 아무 상자나 클릭하면 ground truth 데이터에 객체가 없는데도 객체가 식별된 이미지를 확인할 수 있습니다.
개별 이미지를 클릭하면 ground truth(주석)와 모델 예측을 전환할 수 있는 대화형 보기로 들어갈 수 있습니다:
주석을 보려면 "Ground Truth"를, 모델이 반환한 내용을 보려면 "Model Predictions"를 클릭하세요.
## HTTP API
모델 평가는 버전의 테스트 분할에서 모델이 어떻게 작동하는지 포착합니다. 여기에는 클래스별 지표, 신뢰도 임계값 곡선, 이미지 임베딩 클러스터링, 이미지별 예측, 개선 권장 사항이 포함됩니다. 객체 탐지 및 인스턴스 분할의 주요 지표는 mAP이며, 시맨틱 분할의 주요 지표는 mIoU입니다. 평가는 학습이 완료되면 자동으로 생성되며 앱에서 수동으로 다시 실행할 수 있습니다.
모델 평가 API를 사용하면 앱의 평가 페이지에 표시되는 모든 내용을 읽을 수 있습니다. UI의 각 패널은 전용 엔드포인트에 매핑됩니다:
* [작업공간의 모델 평가 목록 가져오기](#list-model-evaluations)
* [하나의 평가 메타데이터와 주요 지표 가져오기](#get-a-model-evaluation)
* [분할별 전체 지표 세부 정보 가져오기(mAP 또는 mIoU)](#map-results)
* [신뢰도 임계값 스윕과 F1 최적 임계값 가져오기](#confidence-sweep)
* [한 분할의 클래스별 성능 가져오기](#performance-by-class-1)
* [혼동 행렬 가져오기](#confusion-matrix-1)
* [이미지 임베딩 클러스터링(벡터 분석) 가져오기](#vector-analysis)
* [이미지별 예측 가져오기](#per-image-predictions)
* [모델 개선 권장 사항 가져오기](#recommendations)
### 인증
모든 엔드포인트에는 다음 범위의 API 키가 필요합니다: `model-eval:read` 범위. 이를 쿼리 매개변수로 전달하거나 `Bearer` 토큰으로 `Authorization` 헤더에 전달하세요.
### 일반적인 오류
| 상태 | 오류 코드 | 발생 시 |
| ----- | ---------------------- | --------------------------------------- |
| `401` | 인증되지 않음 | API 키가 없거나 유효하지 않음 |
| `404` | `model_eval_not_found` | 평가가 존재하지 않거나 다른 작업공간에 속함 |
| `409` | `model_eval_not_done` | 평가가 완료되지 않았습니다. 패널 데이터는 아직 사용할 수 없습니다 |
| `400` | `invalid_confidence` | `신뢰도` 쿼리 매개변수가 정수가 아닙니다: `[0, 100]` |
| `400` | `invalid_split` | `분할` 쿼리 매개변수가 엔드포인트에서 허용되는 값 중 하나가 아닙니다 |
### 모델 평가 목록 가져오기
작업공간의 모델 평가를 나열합니다. 간략한 형태로 반환됩니다. 특정 평가의 주요 지표는 다음을 통해 확인하세요: [모델 평가 가져오기](#get-a-model-evaluation).
```url
https://api.roboflow.com/:workspace/model-evals
```
```bash
curl "https://api.roboflow.com/my-workspace/model-evals?api_key=$ROBOFLOW_API_KEY&status=done&limit=10"
```
#### 쿼리 매개변수
| 매개변수 | 유형 | 설명 |
| -------------------------- | --- | ------------------------------------------------------------ |
| `project` | 문자열 | 프로젝트를 URL 슬러그로 필터링합니다(예: `chess-pieces-fmhpz`) |
| `version` (별칭 `versionId`) | 문자열 | 특정 버전으로 필터링합니다(예: `"4"`) |
| `model` (별칭 `modelId`) | 문자열 | 특정 모델 ID의 평가로 필터링합니다 |
| `status` | 열거형 | 다음 중 하나: `running`, `done`, `failed`. 알 수 없는 값은 반환됩니다 `400`. |
| `limit` | 정수 | 페이지 크기; 기본값 `50`, 최대 `200` |
최대 하나의 `project` / `version` / `model` 각 호출당 설정할 수 있습니다(가장 구체적인 값이 우선합니다: `model` > `version` > `project`). 조합은 다음과 함께 거부됩니다 `400 invalid_filter_combination` 저장 인덱스가 제한 범위 내에 있도록 하기 위해.
#### 응답
```json
{
"evals": [
{
"evalId": "huUF720inUcymARwqAGK",
"status": "done",
"project": "chess-pieces-fmhpz",
"versionId": "4",
"modelId": null,
"createdAt": "2026-04-27T20:04:10.904Z"
}
]
}
```
`project` 프로젝트의 URL 슬러그입니다. REST API가 URL 경로에서 사용하는 것과 동일한 식별자입니다(`/:workspace/:project/...`). 평가 UI로 딥링크하려면: `https://app.roboflow.com/{workspace}/{project}/evaluation/{versionId}`.
### 모델 평가 가져오기
ID로 단일 모델 평가를 가져옵니다. 완료된 평가의 응답에는 다음이 포함됩니다: `요약` 주요 지표가 포함된 객체입니다. 실행 중이거나 실패한 평가는 간략한 형태만 반환합니다. 어떤 주요 지표가 채워지는지는 작업 유형에 따라 다릅니다 - `mAP` 탐지 유형 작업의 경우, `mIoU` 시맨틱 분할의 경우.
```url
https://api.roboflow.com/:workspace/model-evals/:evalId
```
```bash
curl "https://api.roboflow.com/my-workspace/model-evals/huUF720inUcymARwqAGK?api_key=$ROBOFLOW_API_KEY"
```
#### 응답(완료된 평가)
```json
{
"evalId": "huUF720inUcymARwqAGK",
"status": "done",
"project": "chess-pieces-fmhpz",
"versionId": "4",
"modelId": null,
"createdAt": "2026-04-27T20:04:10.904Z",
"summary": {
"mAP": 0.9239650566041828,
"mIoU": null,
"precision": 0.85,
"recall": 0.85
}
}
```
#### 응답(실행 중 또는 실패)
다음 없이 동일한 필드 `요약` 블록.
```json
{
"evalId": "fNyWx6PC74rCc18IuZ3M",
"status": "running",
"project": "hard-hat-detection",
"versionId": "1",
"modelId": null,
"createdAt": "2026-03-19T21:02:07.918Z"
}
```
#### 참고
* `mAP` IoU 0.5에서의 mean Average Precision입니다(`map50`). 이는 `null` 탐지가 아닌 평가 작업(예: 분류, 시맨틱 분할)에서는 해당되지 않습니다.
* `mIoU` 전경 클래스의 매크로 평균 Intersection-over-Union입니다. 시맨틱 분할 평가에서만 채워집니다. `null` 그렇지 않으면 null입니다.
* `정밀도` 및 `재현율` 테스트 분할의 F1 최적 신뢰도 임계값에서 보고됩니다.
* `evalId` 는 모든 패널 응답에 포함된 동일한 식별자입니다. - `modelEvals.get` 페이로드는 구조적으로 모든 패널 페이로드의 상위 집합이므로 `요약`-이 추가된 `modelEvals.get` 그리고 `getMapResults` 응답은 동일한 클라이언트 코드 경로를 통해 렌더링할 수 있습니다.
* `project` 프로젝트의 URL 슬러그입니다. REST API가 URL 경로에서 사용하는 것과 동일한 식별자입니다. 평가 UI로 딥링크하려면: `https://app.roboflow.com/{workspace}/{project}/evaluation/{versionId}`. `project` 는 `null` 프로젝트가 삭제된 경우입니다.
### mAP 결과
평가의 주요 지표 세부 정보를 반환합니다. 응답 형식은 작업 유형에 따라 다릅니다:
* **객체 탐지 / 인스턴스 분할** - 분할별 IoU 0.5 / 0.5-0.95 / 0.75에서의 mAP이며, 객체 크기 및 클래스별로 세분화됩니다.
* **시맨틱 분할** - 분할별 mIoU, 정밀도, 재현율, F1(픽셀 수준)이며, 클래스별 IoU와 최적 신뢰도 임계값이 포함됩니다.
이 `taskType` 필드는 응답의 형식을 나타냅니다. 파싱하기 전에 항상 확인하세요. `"object-detection-like"` 또는 `"semantic-segmentation"`.
이는 다음이 읽는 데이터입니다: **분할별 지표** 앱의 패널이 읽습니다.
```url
https://api.roboflow.com/:workspace/model-evals/:evalId/map-results
```
```bash
curl "https://api.roboflow.com/my-workspace/model-evals/$EVAL_ID/map-results?api_key=$ROBOFLOW_API_KEY"
```
#### 응답(객체 탐지 / 인스턴스 분할)
```json
{
"taskType": "object-detection-like",
"splits": {
"test": {
"map50": 0.9239650566041828,
"map50_95": 0.7555258345429926,
"map75": 0.9239650566041828,
"byObjectSize": {
"small": {
"map50": 0.9038189533239035,
"map50_95": 0.6478143732740621,
"map75": 0.9038189533239035
},
"medium": {
"map50": 0.9913366336633663,
"map50_95": 0.8572608399609195,
"map75": 0.9913366336633663
},
"large": null
},
"perClass": {
"Car-rims": {
"map50": 0.9239650566041828,
"map50_95": 0.7555258345429926,
"map75": 0.9239650566041828,
"byObjectSize": {
"small": { "map50": 0.9, "map50_95": 0.65, "map75": 0.85 },
"medium": { "map50": 0.99, "map50_95": 0.85, "map75": 0.99 },
"large": null
}
}
}
},
"valid": { "...": "동일한 형식" },
"train": { "...": "동일한 형식" }
}
}
```
#### 응답(시맨틱 분할)
```json
{
"taskType": "semantic-segmentation",
"splits": {
"test": {
"miou": 0.816,
"precision": 0.938,
"recall": 0.862,
"f1": 0.898,
"perClass": [
{
"classID": 3,
"className": "multi",
"iou": 0.816,
"precision": 0.938,
"recall": 0.862,
"f1": 0.898,
"optimalThreshold": 0.0
}
]
},
"valid": { "...": "동일한 형식" },
"train": { "...": "동일한 형식" }
}
}
```
#### 참고
* 이 `taskType` 필드는 응답 형식을 구분합니다. 분할 내용을 파싱하기 전에 항상 확인하세요.
* **탐지:** `map50_95` 는 IoU 임계값 0.5부터 0.95까지 0.05 간격으로 평균한 mAP입니다(COCO 표준). 객체 크기 버킷은 `null` 해당 크기의 인스턴스가 분할에 없을 때는 null입니다. 클래스별 항목은 다음 아래에 표시됩니다: `perClass`, 클래스 이름을 키로 합니다.
* **시맨틱 분할:** 모든 지표는 전경 클래스(배경 제외)에 대한 픽셀 수준 매크로 평균입니다. `miou` 는 평균 Intersection-over-Union입니다. `optimalThreshold` 는 클래스별 F1 최적 신뢰도 임계값입니다. 값이 `0.0` 이면 유효하며, 모델이 argmax에서 최고값을 갖는다는 뜻입니다.
### 신뢰도 스윕
신뢰도 임계값별 지표 곡선과 분할별(및 클래스별) F1 최적 임계값을 반환합니다. 정밀도/재현율 간 균형을 시각화하고 배포 시 임계값을 선택하는 데 유용합니다.
이는 다음이 읽는 데이터입니다: **프로덕션 메트릭 탐색기** 앱의 패널이 읽습니다.
```url
https://api.roboflow.com/:workspace/model-evals/:evalId/confidence-sweep
```
```bash
curl "https://api.roboflow.com/my-workspace/model-evals/$EVAL_ID/confidence-sweep?api_key=$ROBOFLOW_API_KEY"
```
#### 응답
```json
{
"splits": {
"test": {
"perThreshold": {
"0.00": { "precision": 0.02, "recall": 1.0, "f1": 0.039 },
"0.20": { "precision": 0.45, "recall": 0.92, "f1": 0.605 },
"0.37": { "precision": 0.85, "recall": 0.85, "f1": 0.85 },
"0.50": { "precision": 0.91, "recall": 0.78, "f1": 0.84 }
},
"optimalThreshold": 0.37,
"optimalMetrics": {
"precision": 0.85,
"recall": 0.85,
"f1": 0.85
},
"perClass": {
"Car-rims": {
"perThreshold": { "0.37": { "precision": 0.85, "recall": 0.85, "f1": 0.85 } },
"optimalThreshold": 0.37,
"optimalMetrics": { "precision": 0.85, "recall": 0.85, "f1": 0.85 }
}
}
},
"valid": { "...": "동일한 형식" },
"train": { "...": "동일한 형식" }
}
}
```
#### 참고
* `perThreshold` 키는 소수 문자열로 된 신뢰도 임계값이며, 일반적으로 `0.01` 에서 `0.00` 까지 `0.99`.
* `optimalThreshold` 는 해당 분할에서 F1을 최대화하는 임계값입니다.
* 분할의 내부에 있는 클래스별 항목은 `perClass` 중첩된 항목을 제외하고 동일한 형식을 가집니다 `perClass`.
### 클래스별 성능
한 분할의 클래스별 주요 지표를 반환합니다. 응답 형식은 평가의 작업 유형에 따라 다릅니다:
* **객체 탐지 / 인스턴스 분할** - 클래스별 `map50`, `map50_95`, `map75`, 정밀도, 재현율, F1 및 최적 임계값.
* **시맨틱 분할** - 클래스별 `iou`, 정밀도, 재현율, F1 및 최적 임계값(픽셀 수준).
이 `taskType` 응답의 필드는 어떤 형식을 예상해야 하는지 나타냅니다.
이는 다음이 읽는 데이터입니다: **클래스별 성능** 앱의 패널이 읽습니다.
```url
https://api.roboflow.com/:workspace/model-evals/:evalId/performance-by-class
```
```bash
curl "https://api.roboflow.com/my-workspace/model-evals/$EVAL_ID/performance-by-class?api_key=$ROBOFLOW_API_KEY&split=test"
```
#### 쿼리 매개변수
| 매개변수 | 유형 | 설명 |
| ---- | --- | -------------------------------------------------------------------------------------------------------- |
| `분할` | 열거형 | 다음 중 하나: `train`, `valid`, `test`. 기본값 `test`. `all` 는 **아님** 여기서는 유효하지 않습니다. 클래스별 지표는 분할 간에 집계할 수 없습니다. |
#### 응답(객체 탐지 / 인스턴스 분할)
```json
{
"taskType": "object-detection-like",
"split": "test",
"classes": [
{
"className": "Car-rims",
"map50": 0.9239650566041828,
"map50_95": 0.7555258345429926,
"map75": 0.9239650566041828,
"precision": 0.85,
"recall": 0.85,
"f1": 0.85,
"optimalThreshold": 0.37
},
{
"className": "music-note",
"map50": null,
"map50_95": null,
"map75": null,
"precision": 0,
"recall": 0,
"f1": 0,
"optimalThreshold": 0.5
}
]
}
```
#### 응답(시맨틱 분할)
```json
{
"taskType": "semantic-segmentation",
"split": "test",
"classes": [
{
"classID": 3,
"className": "multi",
"iou": 0.816,
"precision": 0.938,
"recall": 0.862,
"f1": 0.898,
"optimalThreshold": 0.0
}
]
}
```
#### 참고
* `taskType` 클래스별 필드 세트를 구분합니다. 탐지 클래스에는 `map50`/`map50_95`/`map75`; 시맨틱 분할 클래스에는 `iou` 및 `클래스 ID` 대신입니다.
* `optimalThreshold` 는 confidence sweep에서 클래스별 F1 최적 신뢰도 임계값입니다.
* `정밀도`, `재현율`, 그리고 `f1` 은 해당 클래스별 최적 임계값에서 보고됩니다.
* 탐지의 경우 mAP 필드는 `null` 해당 분할에 그 클래스의 인스턴스가 없을 때입니다.
* 시맨틱 분할의 경우 모든 메트릭은 픽셀 수준입니다. 하나의 `optimalThreshold` 의 `0.0` 는 유효합니다.
### 혼동 행렬
이미지별 예측에서 파생된 집계 혼동 행렬을 반환합니다. 각 셀은 `matrix[actual][predicted]` 은 실제 정답 클래스가 `실제` 이고 모델이 예측한 `예측`. 시맨틱 분할 평가에서는 값이 인스턴스 수가 아니라 픽셀 수를 나타냅니다.
이는 다음이 읽는 데이터입니다: **혼동 행렬** 앱의 패널이 읽습니다.
```url
https://api.roboflow.com/:workspace/model-evals/:evalId/confusion-matrix
```
```bash
curl "https://api.roboflow.com/my-workspace/model-evals/$EVAL_ID/confusion-matrix?api_key=$ROBOFLOW_API_KEY&split=test"
```
#### 쿼리 매개변수
| 매개변수 | 유형 | 설명 |
| ----- | --- | -------------------------------------------------------- |
| `분할` | 열거형 | 다음 중 하나: `train`, `valid`, `test`, 또는 `all`. 기본값 `test`. |
| `신뢰도` | 정수 | 신뢰도 임계값 퍼센트는 `[0, 100]`. 기본값은 canonical 파일(일반적으로 `20`). |
#### 응답
```json
{
"split": "test",
"confidenceThreshold": 0.2,
"classes": ["Car-rims", "music-note", "background"],
"matrix": [
[20, 0, 0],
[ 0, 0, 0],
[80, 0, 0]
]
}
```
위 예시에서 신뢰도 임계값 0.2에서:
* 의 모든 20개 인스턴스가 `Car-rims` 가 올바르게 분류되었습니다 (`matrix[0][0] = 20`)
* 모델이 80개의 거짓 양성을 생성했습니다 - `Car-rims` 실제 클래스가 `background` (`matrix[2][0] = 80`)
* 테스트 분할에는 `music-note` 인스턴스가 없습니다
#### 참고
* `신뢰도` 집계할 보고서의 기반이 되는 신뢰도별 변형을 선택합니다. 임계값이 다르면 서로 다른 행렬이 생성됩니다.
* `split=all` train, valid, test 전반의 원시 개수를 집계합니다.
### 벡터 분석
평가의 이미지 임베딩 클러스터링 출력을 반환합니다 - HDBSCAN으로 클러스터링한 UMAP 투영 임베딩과, 클러스터별 집계 메트릭을 제공합니다. 모델이 특정 이미지 그룹에서 체계적으로 더 잘 작동하거나 더 나쁘게 작동하는지를 파악하는 데 유용합니다.
이는 다음이 읽는 데이터입니다: **벡터 분석** 앱의 패널이 읽습니다.
```url
https://api.roboflow.com/:workspace/model-evals/:evalId/vector-analysis
```
```bash
curl "https://api.roboflow.com/my-workspace/model-evals/$EVAL_ID/vector-analysis?api_key=$ROBOFLOW_API_KEY"
```
#### 쿼리 매개변수
| 매개변수 | 유형 | 설명 |
| ----- | -- | ------------------------------------------------ |
| `신뢰도` | 정수 | 신뢰도 임계값 퍼센트는 `[0, 100]` (기본값은 canonical 보고서입니다). |
#### 응답
```json
{
"clustering": {
"method": "hdbscan",
"nClusters": 54,
"metrics": {
"noiseRatio": 0.078125,
"silhouetteScore": 0.48925095796585083
},
"parameters": {
"min_cluster_size": 2,
"min_samples": 1,
"cluster_selection_method": "eom",
"metric": "euclidean"
},
"processingTimeSeconds": 8.36
},
"preprocessing": {
"method": "umap",
"originalDimensions": 768,
"targetDimensions": 10,
"nNeighbors": 30,
"minDistance": 0.05
},
"clusters": [
{
"id": -1,
"numImages": 15,
"splitDistribution": { "train": 12, "valid": 2, "test": 1 },
"metrics": {
"f1Mean": 0.462,
"f1Std": 0.219,
"f1Min": 0.129,
"f1Max": 0.8,
"precisionMean": 0.330,
"recallMean": 0.952
},
"sampleImages": ["img1.jpg", "img2.jpg"]
},
{
"id": 0,
"numImages": 3,
"splitDistribution": { "train": 2, "valid": 1 },
"metrics": {
"f1Mean": 0.889,
"f1Std": 0.157,
"f1Min": 0.667,
"f1Max": 1.0,
"precisionMean": 1.0,
"recallMean": 0.833
},
"sampleImages": ["img3.jpg", "img4.jpg", "img5.jpg"]
}
]
}
```
#### 참고
* 클러스터 ID `-1` 는 노이즈/비클러스터 버킷(HDBSCAN 관례)입니다 - 어떤 밀집 영역에도 맞지 않는 이미지입니다.
* `정밀도 평균` 및 `재현율 평균` 는 클러스터의 모든 이미지에 대해 평균됩니다.
* 이미지별 임베딩과 클러스터 할당은 다음을 통해 제공됩니다: [이미지별 예측](#per-image-predictions).
### 이미지별 예측
이미지별 예측 레코드를 반환합니다 - TP/FP/FN 개수, 이미지별 precision/recall/F1, 이미지의 클러스터 ID와 2D 임베딩, 그리고 원시 혼동 항목을 제공합니다. 페이지네이션 적용됨.
이는 다음이 읽는 데이터입니다: **이미지별 예측** 앱의 패널이 읽습니다.
```url
https://api.roboflow.com/:workspace/model-evals/:evalId/image-predictions
```
```bash
curl "https://api.roboflow.com/my-workspace/model-evals/$EVAL_ID/image-predictions?api_key=$ROBOFLOW_API_KEY&split=test&limit=50"
```
#### 쿼리 매개변수
| 매개변수 | 유형 | 설명 |
| ------- | --- | ------------------------------------------------------- |
| `분할` | 열거형 | 다음 중 하나: `train`, `valid`, `test`, 또는 `all`. 기본값 `all`. |
| `신뢰도` | 정수 | 신뢰도 임계값 퍼센트는 `[0, 100]` (읽을 신뢰도별 보고서 변형을 선택합니다). |
| `limit` | 정수 | 페이지 크기; 기본값 `200`, 최대 `1000`. |
| `오프셋` | 정수 | 반환하기 전에 이 개수만큼 레코드를 건너뜁니다. 기본값 `0`. |
#### 응답
```json
{
"split": "test",
"confidenceThreshold": 0.2,
"totalImages": 192,
"offset": 0,
"limit": 50,
"images": [
{
"imageId": "1QKLCUsfAzFiCIb6YCJj",
"imageName": "abc.jpg",
"split": "test",
"augmentations": 2,
"cluster": {
"id": 4,
"embedding2D": [7.494518280029297, -5.143994331359863]
},
"stats": {
"truePositives": 2,
"falsePositives": 7,
"falseNegatives": 0,
"precision": 0.222,
"recall": 1.0,
"f1": 0.364
},
"confusion": [
[0, 0, 2],
[2, 0, 7]
]
}
]
}
```
#### 참고
* `이미지 ID` 는 Roboflow 원본 이미지 ID입니다 - 다른 Roboflow API와 교차 참조하는 데 유용합니다.
* `혼동` 항목은 `[actualClassIdx, predictedClassIdx, count]` 세트입니다; 클래스 인덱스는 다음과 같은 배열을 참조합니다: [혼동 행렬](#confusion-matrix-1)의 `클래스`.
* `2D 임베딩` 는 다음에서 사용되는 UMAP 투영 2D 좌표입니다. [벡터 분석](#vector-analysis) 플롯입니다.
* 서로 다른 `신뢰도` 값은 서로 다른 통계를 반환합니다 - 예측은 임계값에 따라 달라집니다. 임의의 `신뢰도` 값을 조회하려면 eval 파이프라인이 실제로 생성한 임계값에 대해서만 성공합니다; 생성되지 않은 변형은 `404 report_not_found`.
* **페이지네이션 비용**: 각 페이지는 전체 `model_eval_results.json` 파일을 스토리지에서 다시 읽고 서버 측에서 잘라냅니다. 매우 큰 `이미지 결과` 배열이 있는 eval의 경우, 더 큰 `limit` 값(최대 `1000`)을 많은 작은 페이지보다 우선하여 페이지당 고정 비용을 최소화하세요.
### 추천 사항
완료된 평가에서 생성된 모델 개선 추천 사항을 반환합니다 - 클래스 불균형 경고, 놓친 탐지 패턴, 그리고 데이터셋에 추가할 항목이나 재학습 방법에 대한 기타 실행 가능한 제안을 포함합니다.
이는 다음이 읽는 데이터입니다: **모델 개선 추천 사항** 앱의 패널이 읽습니다.
이 엔드포인트는 **읽기 전용**. 추천 사항은 학습 완료의 부작용으로 생성됩니다(또는 기존 앱 내 "추천 새로고침" 작업을 통해 생성됩니다). 아직 생성되지 않았다면 응답은 `200 {"generated": false}` - 이것은 **아님** 하나의 `409 EVAL_NOT_DONE`. 평가는 *는* 완료된 상태입니다. 단지 선택적 추천 부가 출력이 없을 뿐입니다. 다른 패널 엔드포인트(`map-results`, `confidence-sweep`, 등)은 반환합니다 `409 EVAL_NOT_DONE` 기반 데이터가 누락되었을 때도 그 데이터가 평가의 본질적인 일부이기 때문에 반환합니다; 추천 사항은 그렇지 않습니다.
```url
https://api.roboflow.com/:workspace/model-evals/:evalId/recommendations
```
```bash
curl "https://api.roboflow.com/my-workspace/model-evals/$EVAL_ID/recommendations?api_key=$ROBOFLOW_API_KEY"
```
#### 응답(추천 사항 사용 가능)
```json
{
"generated": true,
"generatedAt": "2026-04-27T20:05:37.512Z",
"recommendations": {
"summary": {
"confidenceThreshold": 37,
"split": "test",
"generatedAt": "2026-04-27T20:05:37.512Z",
"count": 3,
"f1": 0.85,
"precision": 0.85,
"recall": 0.85
},
"items": [
{
"id": "56bcd423-38ff-45f9-b3e0-662a71ce44e6",
"type": "missed_detection",
"analysis": {
"affected_class": "Car-rims",
"count": 3
}
},
{
"id": "150e49a8-3a61-479a-9e18-3eb751494a70",
"type": "class_imbalance",
"analysis": {
"affected_class": "Car-rims",
"current_count": 20,
"total_gt_instances": 20,
"median_count": 10
}
}
]
}
}
```
#### 응답(아직 생성되지 않음)
```json
{
"generated": false
}
```