> 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에 학습하거나 업로드한 모든 버전 관리 모델에 대해 모델 평가가 자동으로 실행됩니다. 이미지가 수백 장인 데이터셋의 경우 평가는 완료되는 데 몇 분이 걸릴 수 있으며, 수천 장 이상의 이미지를 포함한 대규모 데이터셋의 경우 몇 시간이 걸릴 수 있습니다.

혼동 행렬은 테스트 및 검증 세트의 이미지에 대해 학습된 모델을 실행하고, 예측을 주석(정답)과 비교합니다. 이는 올바른 예측, 거짓 양성(잘못된 클래스이거나 객체가 존재하지 않는 경우), 거짓 음성을 보여줍니다. 권장 사항은 이를 기반으로 합니다. 여기에는 거짓 음성이나 거짓 양성이 많은 모델, 자주 혼동되는 클래스, 더 많은 데이터가 필요한 클래스, 너무 작을 수 있는 테스트 또는 검증 세트가 포함됩니다.

### 최적 신뢰도

운영 메트릭 탐색기는 모든 신뢰도 임계값에서 정밀도, 재현율, F1을 계산하고 최적의 신뢰도, 즉 가장 좋은 균형을 가진 임계값을 권장합니다. 평가가 완료되면 해당 임계값이 모델의 추론 요청에 대한 기본값이 됩니다. 클래스별 임계값이 사용 가능한 경우, 그것들도 적용되며, 자체 값이 없는 클래스에 대해서는 전역 임계값이 대체값으로 사용됩니다. 요청에서 이를 덮어쓰려면 `신뢰도` 매개변수를 전달하세요.

### 중앙값 지연 시간

평가는 Serverless Cloud API가 한 요청에 응답하는 데 걸리는 중앙값 시간을 보여주며, 테스트 이미지에서 측정됩니다. 이 값에는 전처리 및 후처리 시간이 포함됩니다. 네트워크 시간은 포함되지 않습니다. 모델 목록과 모델 카드에는 동일한 값이 "지연 시간(Cloud API)"로 표시됩니다. 다음의 지연 시간은 [신경망 아키텍처 탐색](https://docs.roboflow.com/models/ko/train/neural-architecture-search.md) 벤치마크는 다른 방식으로 측정되므로 두 값을 비교하지 마세요.

테스트 이미지의 픽셀 수가 모델 입력의 최소 두 배 이상인 경우, 평가는 캡처 해상도에 대한 권장 사항을 추가합니다. 서버는 모델을 실행하기 전에 모든 이미지를 디코딩하고 크기를 조정하므로, 긴 변의 길이가 모델 입력에 가까운 프레임이 더 빠르게 응답합니다.

사용 [모델 비교](https://docs.roboflow.com/models/ko/evaluate/compare-trained-models.md) 를 사용하여 동일한 데이터셋 버전에서 모델의 테스트 세트 정확도와 지연 시간을 비교하세요.

### 추론용 최적화 중

학습 후 Roboflow는 모델을 Serverless Cloud API가 제공하는 패키지로 컴파일합니다. 이 작업이 진행되는 동안 모델에는 "추론용 최적화 중"이라고 표시되며, 평가는 완료될 때까지 대기합니다. 이렇게 하면 평가가 추론 요청을 제공하는 동일한 패키지를 측정하게 됩니다. 컴파일에는 보통 몇 분이 추가로 걸립니다. 실패하거나 24시간 이상 걸리면 평가는 그대로 시작됩니다.

### 지원되는 프로젝트 유형

모델 평가는 객체 탐지, 인스턴스 분할, 키포인트 탐지, 분류, 의미 분할 프로젝트를 지원합니다.

키포인트 탐지의 경우 mAP는 Object Keypoint Similarity(OKS)를 사용하여 예측된 키포인트를 라벨된 키포인트와 매칭합니다. 평가 이미지 뷰어는 예측된 키포인트는 그리지만 라벨된 키포인트는 그리지 않습니다.

의미 분할의 경우 대표 지표는 mAP 대신 mIoU(mean Intersection-over-Union)입니다. 모든 지표(정밀도, 재현율, F1)는 개별 객체 수준이 아니라 픽셀 수준에서 계산됩니다. 클래스별 세부 내역에는 각 클래스의 IoU, 정밀도, 재현율, F1, 그리고 최적 신뢰도 임계값이 표시됩니다. 혼동 행렬 값은 객체 수가 아니라 픽셀 수를 나타냅니다.

더 최근의 분할 모델 평가는 경계 지표도 보고합니다. Boundary IoU는 각 마스크 가장자리를 따라 좁은 띠를 비교하므로, 마스크 IoU로는 숨겨질 수 있는 가장자리 오류를 보여줍니다. 인스턴스 분할에는 "세부 지표 표시" 아래에 "평균 경계 평균 정밀도" 차트가 표시됩니다. 의미 분할에는 mIoU 옆에 mBIoU가 표시되고, 클래스별 표에는 "Boundary IoU" 열이 표시됩니다.

## 웹 앱

프로젝트에서 "모델"을 열고 학습된 모델을 선택한 다음 "전체 모델 평가 보기"를 클릭하세요.

<figure><img src="https://2225311784-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fcmo9mhfIjYrvFFy1U7dk%2Fuploads%2Fgit-blob-8c6db60420e1905df8d6f3c824f91f0f219e8a76%2FScreenshot%202025-05-14%20at%2014.41.23.png?alt=media" alt=""><figcaption></figcaption></figure>

운영 메트릭 탐색기에서 슬라이더를 드래그하여 모든 신뢰도 임계값에서의 정밀도, 재현율, F1을 확인하세요.

<figure><img src="https://2225311784-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fcmo9mhfIjYrvFFy1U7dk%2Fuploads%2Fgit-blob-cf7be3e1155f28ab47c87709fe072e767b536898%2FScreenshot%202025-07-23%20at%2011.15.02.png?alt=media" alt=""><figcaption></figcaption></figure>

모델 개선 권장 사항에는 정확도를 높이기 위해 무엇을 바꿔야 하는지 나와 있습니다.

<figure><img src="https://2225311784-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fcmo9mhfIjYrvFFy1U7dk%2Fuploads%2Fgit-blob-cb54b251f5e115f9a1eb549b0c03117d5b263b3b%2FScreenshot%202025-07-23%20at%2011.17.09.png?alt=media" alt=""><figcaption></figcaption></figure>

클래스별 성능 차트는 각 클래스에 대해 올바른 예측, 오분류, 거짓 음성, 거짓 양성을 집계합니다. 특정 클래스에 집중하려면 "모든 클래스" 드롭다운을 사용하세요.

<figure><img src="https://2225311784-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fcmo9mhfIjYrvFFy1U7dk%2Fuploads%2Fgit-blob-ffaf491bbb2d955905c575d90aeb04a4fd94f257%2FScreenshot%202025-07-23%20at%2011.18.34.png?alt=media" alt=""><figcaption></figcaption></figure>

혼동 행렬에서 셀을 클릭하면 그 안의 이미지를 볼 수 있습니다(예: "거짓 양성" 열의 셀은 주석에는 없는 객체를 모델이 찾은 이미지를 보여줍니다). 이미지를 클릭한 다음 "정답"과 "모델 예측"을 전환하여 주석과 모델 출력을 비교하세요.

<figure><img src="https://2225311784-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fcmo9mhfIjYrvFFy1U7dk%2Fuploads%2Fgit-blob-cd0af50fa3e0c4158310901798a285245a9d87bc%2FScreenshot%202025-07-23%20at%2011.20.53.png?alt=media" alt=""><figcaption></figcaption></figure>

"벡터 분석"은 테스트 이미지를 시각적 유사도에 따라 배치하고 각 이미지를 F1 점수로 색상 구분합니다. 점, 영역 또는 "식별된 클러스터" 중 하나를 클릭하여 해당 이미지를 확인하면, 모델이 어려워하는 유사한 이미지 그룹을 찾을 수 있습니다.

![산점도에서 두 이미지의 선택된 클러스터가 강조 표시되고 최악의 F1 기준으로 나열된 벡터 분석](https://2225311784-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fcmo9mhfIjYrvFFy1U7dk%2Fuploads%2Fgit-blob-f149c384f7b7dacc4a2816045a6c9e5ab8526dc0%2Fmodel-evaluation-vector-analysis.png?alt=media)

클래스 차트와 혼동 행렬은 최적 신뢰도에서 시작합니다. "신뢰도 임계값" 슬라이더를 움직여 결과, 정밀도, 재현율이 어떻게 변하는지 확인하세요.

"모델 개선"을 클릭하여 [Roboflow 에이전트](https://docs.roboflow.com/agents/roboflow-agent) 로 이 평가에 대해 채팅하세요. 에이전트는 모델이 실패한 이미지와 해당 라벨을 나란히 보여주고, 데이터나 학습에 대한 변경 사항을 제안합니다. 라벨 오류로 보이는 이미지는 하나의 검토 작업으로 묶어, 라벨을 확인하고 수정할 수 있게 합니다. 팀원의 작업에서 이미지를 이동하기 전에 먼저 확인을 요청합니다.

## HTTP API

Model Evaluations API는 앱의 평가 페이지에 표시되는 모든 내용을 반환합니다. 각 패널에는 자체 엔드포인트가 있습니다. Roboflow는 학습이 완료되면 평가를 실행하며, 앱에서 다시 실행할 수도 있습니다. 모든 엔드포인트에는 다음 범위가 포함된 API 키가 필요합니다. `model-eval:read` 범위.

다음으로 시작하세요. [모델 평가 목록](#list-model-evaluations) 에서 `evalId`를 찾은 다음 [모델 평가 가져오기](#get-a-model-evaluation) 를 `상태` 가 `완료`될 때까지 폴링하세요. 패널 엔드포인트는 그때까지 `409` 를 반환합니다. 모든 패널 응답에는 다음이 다시 포함됩니다. `evalId`, `프로젝트`, `versionId`와 `modelId`가 포함되므로, 앱의 다음 주소에서 평가로 연결할 수 있습니다. `https://app.roboflow.com/{workspace}/{project}/evaluation/{versionId}`.

하나의 버전에서 여러 모델을 비교하려면 다음을 참조하세요. [학습된 모델 비교](https://docs.roboflow.com/models/ko/evaluate/compare-trained-models.md#http-api).

### 모델 평가 목록

각 평가에 대한 간단한 레코드를 반환하며, 지표는 포함하지 않습니다. 다음 중 하나로 필터링하세요. `프로젝트`, `버전`또는 `모델`; 여러 개를 보내면 `400`를 반환합니다. 평가를 해당 모델과 매칭하려면 `modelId` 를 추론에 사용하는 모델 ID와 비교하세요.

{% openapi src="/files/1f66ea1713d8bbf053ef4815457d1eb66b73a1d4" path="/{workspace}/model-evals" method="get" %}
[model-evaluations.yaml](https://2225311784-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fcmo9mhfIjYrvFFy1U7dk%2Fuploads%2Fgit-blob-92404e3372138e59de07c239bc165dac2de6cef0%2Fmodel-evaluations.yaml?alt=media)
{% endopenapi %}

### 모델 평가 가져오기

평가 하나를 반환합니다. 한 번 `상태` 가 `완료`가 되면 응답에 `요약` 이 추가되며, 여기에는 주요 지표가 포함됩니다: `mAP` 탐지 작업의 경우, `mIoU` 의미 분할의 경우.

{% openapi src="/files/1f66ea1713d8bbf053ef4815457d1eb66b73a1d4" path="/{workspace}/model-evals/{evaluationId}" method="get" %}
[model-evaluations.yaml](https://2225311784-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fcmo9mhfIjYrvFFy1U7dk%2Fuploads%2Fgit-blob-92404e3372138e59de07c239bc165dac2de6cef0%2Fmodel-evaluations.yaml?alt=media)
{% endopenapi %}

### mAP 결과 가져오기

메트릭을 분할별 패널에 표시된 것처럼 각 분할에 대한 주요 메트릭을 반환합니다. 먼저 `taskType` 를 읽으세요. 분할에 mAP 필드가 있는지, 아니면 mIoU 및 픽셀 수준 필드가 있는지 알려줍니다.

{% openapi src="/files/1f66ea1713d8bbf053ef4815457d1eb66b73a1d4" path="/{workspace}/model-evals/{evaluationId}/map-results" method="get" %}
[model-evaluations.yaml](https://2225311784-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fcmo9mhfIjYrvFFy1U7dk%2Fuploads%2Fgit-blob-92404e3372138e59de07c239bc165dac2de6cef0%2Fmodel-evaluations.yaml?alt=media)
{% endopenapi %}

### 신뢰도 스윕 가져오기

운영 메트릭 탐색기의 기반이 되는 곡선, 즉 각 신뢰도 임계값에서의 정밀도, 재현율, F1과 가장 좋은 F1을 가진 임계값을 반환합니다. 배포에 사용할 신뢰도 임계값을 선택하는 데 사용하세요.

{% openapi src="/files/1f66ea1713d8bbf053ef4815457d1eb66b73a1d4" path="/{workspace}/model-evals/{evaluationId}/confidence-sweep" method="get" %}
[model-evaluations.yaml](https://2225311784-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fcmo9mhfIjYrvFFy1U7dk%2Fuploads%2Fgit-blob-92404e3372138e59de07c239bc165dac2de6cef0%2Fmodel-evaluations.yaml?alt=media)
{% endopenapi %}

### 클래스별 성능 가져오기

한 분할에 대한 클래스별 성능 패널을 반환합니다. 각 클래스는 자체 최적 임계값에서의 정밀도, 재현율, F1을 보고합니다.

{% openapi src="/files/1f66ea1713d8bbf053ef4815457d1eb66b73a1d4" path="/{workspace}/model-evals/{evaluationId}/performance-by-class" method="get" %}
[model-evaluations.yaml](https://2225311784-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fcmo9mhfIjYrvFFy1U7dk%2Fuploads%2Fgit-blob-92404e3372138e59de07c239bc165dac2de6cef0%2Fmodel-evaluations.yaml?alt=media)
{% endopenapi %}

### 혼동 행렬 가져오기

혼동 행렬 패널을 반환합니다. 각 신뢰도 임계값마다 다른 행렬이 생성되므로, 배포에 사용하는 임계값과 맞추려면 `신뢰도` 를 전달하세요.

{% openapi src="/files/1f66ea1713d8bbf053ef4815457d1eb66b73a1d4" path="/{workspace}/model-evals/{evaluationId}/confusion-matrix" method="get" %}
[model-evaluations.yaml](https://2225311784-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fcmo9mhfIjYrvFFy1U7dk%2Fuploads%2Fgit-blob-92404e3372138e59de07c239bc165dac2de6cef0%2Fmodel-evaluations.yaml?alt=media)
{% endopenapi %}

### 벡터 분석 가져오기

벡터 분석 패널을 반환합니다: 시각적 유사도별로 그룹화된 이미지와 각 그룹에 대한 모델의 평균 F1, 정밀도, 재현율이 표시됩니다. 모델이 어려워하는 이미지 종류를 찾으려면 낮은 `f1Mean` 이 있는 클러스터를 찾으세요. 클러스터에 어떤 이미지가 있는지 보려면 [이미지 예측 가져오기](#get-image-predictions).

{% openapi src="/files/1f66ea1713d8bbf053ef4815457d1eb66b73a1d4" path="/{workspace}/model-evals/{evaluationId}/vector-analysis" method="get" %}
[model-evaluations.yaml](https://2225311784-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fcmo9mhfIjYrvFFy1U7dk%2Fuploads%2Fgit-blob-92404e3372138e59de07c239bc165dac2de6cef0%2Fmodel-evaluations.yaml?alt=media)
{% endopenapi %}

### 이미지 예측 가져오기

평가된 이미지마다 하나의 레코드를 반환하며, 그 수, 지표, 클러스터, 혼동 항목을 포함합니다. 결과는 다음으로 페이지 처리됩니다. `limit` 와 `offset`.

이미지 하나를 검사하려면 `imageName` 또는 `evalInputId` 를 `includeGeometry=true`와 함께 전달하세요. 그러면 레코드에 저장된 예측과 정답이 포함되어, 실패가 모델 오류인지 라벨 오류인지 알 수 있습니다.

{% openapi src="/files/1f66ea1713d8bbf053ef4815457d1eb66b73a1d4" path="/{workspace}/model-evals/{evaluationId}/image-predictions" method="get" %}
[model-evaluations.yaml](https://2225311784-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fcmo9mhfIjYrvFFy1U7dk%2Fuploads%2Fgit-blob-92404e3372138e59de07c239bc165dac2de6cef0%2Fmodel-evaluations.yaml?alt=media)
{% endopenapi %}

### 권장 사항 가져오기

모델 개선 권장 사항 패널을 반환합니다. Roboflow는 학습이 완료되면 권장 사항을 생성하며, 이 엔드포인트는 이를 읽기만 합니다. 권장 사항이 없는 완료된 평가는 `200` 를 `generated: false`를 반환하며, 오류가 아닙니다.

{% openapi src="/files/1f66ea1713d8bbf053ef4815457d1eb66b73a1d4" path="/{workspace}/model-evals/{evaluationId}/recommendations" method="get" %}
[model-evaluations.yaml](https://2225311784-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fcmo9mhfIjYrvFFy1U7dk%2Fuploads%2Fgit-blob-92404e3372138e59de07c239bc165dac2de6cef0%2Fmodel-evaluations.yaml?alt=media)
{% endopenapi %}

## MCP 서버

AI 에이전트를 다음에 연결하면 [MCP 서버](https://docs.roboflow.com/agents/mcp-server) 이 도구들로 모델 성능을 검토할 수 있습니다:

<table data-search="false"><thead><tr><th width="290">도구</th><th>설명</th></tr></thead><tbody><tr><td><code>model_evals_list</code></td><td>워크스페이스의 모델 평가를 나열합니다.</td></tr><tr><td><code>model_evals_get</code></td><td>하나의 평가에 대한 최상위 요약을 가져옵니다.</td></tr><tr><td><code>model_evals_get_map_results</code></td><td>분할별 mAP 결과를 가져옵니다.</td></tr><tr><td><code>model_evals_get_confusion_matrix</code></td><td>혼동 행렬을 가져옵니다.</td></tr><tr><td><code>model_evals_get_performance_by_class</code></td><td>하나의 분할에 대한 클래스별 성능 지표를 가져옵니다.</td></tr><tr><td><code>model_evals_get_recommendations</code></td><td>사용 가능한 경우 평가에 대해 생성된 권장 사항을 가져옵니다.</td></tr></tbody></table>
