> 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/workflows/ko/evaluate/workflow-evals.md).

# 워크플로우 평가

웹 앱, HTTP API, Python SDK, CLI 또는 MCP를 통해 레이블이 지정된 사례와 비교하여 워크플로우를 평가하고 비교합니다.

Workflow Evals는 예제 집합을 사용해 Workflow가 요구 사항을 충족하는지 확인합니다. 이를 통해 실패 사례를 찾고, Workflow 버전을 비교하고, 배포 전에 회귀를 확인할 수 있습니다.

다음 [모델 비교 튜토리얼](https://docs.roboflow.com/workflows/ko/tutorials/compare-models-with-workflow-evals.md) 을 따라 볼트 개수 세기 Eval을 정의하고 에이전트를 사용해 후보 Workflow를 만들고 비교해 보세요.

## 소개

Eval은 검사할 항목을 정의하는 Spec과 Cases로 구성된 Dataset을 결합합니다. 각 Case에는 입력과 정답, 즉 예상 값이나 주석이 포함됩니다. Check는 평가기와 설정을 선택합니다. 예를 들어 예측된 상자가 주석과 얼마나 일치해야 하는지 지정할 수 있습니다.

Run은 하나 이상의 Workflow를 해당 Cases 및 Checks와 대조해 평가합니다. 각 Run에는 자체 입력, 정답, Workflow 정의 및 평가 설정이 기록됩니다. Case를 수정하거나 삭제하면 이후 Run에 영향을 주지만, 기존 Run의 결과는 변경되지 않습니다. 정답이 완전하지 않은 Case는 건너뛰고, 건너뛴 Case의 수도 표시합니다.

Check에는 두 가지 유형이 있습니다. "출력 검사"는 Workflow 출력을 정답과 비교하고, "지연 시간 한도"는 Case별 시간 제한을 설정합니다. 비율 지표(예: precision, recall, F1, mAP)의 임계값은 0\~1 사이의 소수이므로 80%를 입력하려면 0.8을 입력하세요. 분류 검사는 `top` 또는 `predicted_classes` 출력을 예상 클래스와 비교하며, 정확히 일치하는지 또는 F1 점수를 기준으로 검사합니다. 키포인트 검사는 모든 Case를 통합해 COCO AP 및 AR, 그리고 평균 OKS 임계값에서의 F1로 예측된 점수를 라벨링된 점과 비교합니다.

Dataset 테스트 세트에서 정답을 가져올 수 있습니다. 가져오기는 Dataset Version의 전처리되거나 증강된 이미지가 아니라 원본 이미지의 현재 주석을 사용합니다. 상자, 분류, 세그멘테이션을 지원합니다. 키포인트 Dataset에서는 이미지만 가져옵니다. 가져온 라벨은 검토할 때까지 승인되지 않은 상태로 유지됩니다.

### 지연 시간

"Latency Avg"는 기록된 요청 시간이 있는 실패 요청을 포함해 Case별로 기록된 요청 시간의 평균입니다. 네트워크 시간과 러너가 시간을 측정하는 입력 준비 과정이 포함되며, 평가 대기열에서 기다리는 시간과 점수 산정 시간은 제외됩니다. 모든 Case의 소요 시간을 합산한 값도 아니며 모델 추론 시간만을 측정한 값도 아닙니다.

"Latency budget" Check가 포함된 Run은 모든 Case를 다시 실행하므로 캐시된 결과를 재사용하지 않습니다. 이전 Run에 지연 시간 Check를 추가하려면 새 Run을 시작하세요. Rescore로는 지연 시간을 측정할 수 없습니다.

### 크레딧

Eval에서 허용된 Workflow 실행 1회당 1/10,000 크레딧이 청구됩니다. 로컬에서 실행하든 Serverless에서 실행하든 동일합니다. 100개 Case에서 Workflow 3개를 평가하면 평가에 3/10,000 크레딧이 들며, 여기에 추론 비용이 추가됩니다.

Serverless Workflow 추론과 Label Assist에는 별도의 요금이 부과됩니다. 새 Replay 또는 Rescore를 실행하면 요금이 부과되는 평가 실행이 새로 생성됩니다. 단, 원래의 멱등성 키를 사용해 동일한 생성 요청을 재시도하는 경우는 제외됩니다. 임베딩 생성에는 평가 크레딧이 사용되지 않습니다. 정답에 라벨을 지정하는 동안 Smart Select를 사용하면 주석 편집기와 마찬가지로 AI Labeling 크레딧이 사용됩니다.

## 웹 앱

Workspace에서 "Workflows"를 열고 "Evals"를 선택한 다음 "Create Eval"을 클릭하세요. 다음 단계를 따르세요.

1. "Select Workflow": Workflow를 선택합니다. 단계 헤더의 서버 칩을 클릭하면 추론 서버를 전환할 수 있습니다.
2. "Upload Ground Truth": 기기, Asset Library 또는 Dataset 테스트 세트에서 이미지를 추가한 다음 검사할 Workflow 출력을 선택합니다.
3. "Label Ground Truth": 예상 값을 입력하고 이미지에 주석을 답니다. "Assist" 카드를 사용해 모델이나 Workflow의 제안을 받거나, "Auto-annotate"를 켜서 Case를 열 때마다 라벨을 지정할 수 있습니다. 상자, 마스크 또는 키포인트 출력에 해당하는 객체가 이미지에 없으면 그 출력 옆의 빈 집합 아이콘을 클릭해 객체가 없음을 표시합니다. "Add N to the Eval and Continue"를 클릭하면 라벨이 지정된 이미지를 한꺼번에 모두 추가합니다. 라벨을 지정하지 않고 나간 이미지는 초안으로 남습니다. 키포인트 라벨 지정에는 Workflow의 키포인트 모델에 저장된 스켈레톤이 사용됩니다. 모델에 스켈레톤이 없으면 "Create With AI" 또는 "Create Manually"를 클릭해 Eval용 스켈레톤을 만드세요. 점 이름은 Workflow의 점 이름과 일치해야 합니다. Label Assist는 신뢰도가 0.5 미만인 점을 배치하지 않습니다.
4. "Define Eval Checks": "Add check"를 클릭하고 임계값을 설정합니다. "Run preview"를 클릭해 Case 하나에서 Checks를 테스트합니다.
5. "Run Evaluation": 설정과 크레딧 예상치를 확인한 다음 Run을 시작합니다.

Eval 페이지에는 정답 및 Checks와 함께 해당 Eval의 Runs가 표시됩니다. 여기서 정답을 열어 수정할 수 있습니다. 수정 내용은 진행 중에 자동 저장됩니다. 가져온 라벨이나 초안 라벨을 그대로 승인하려면 "Approve Labels"를 클릭합니다. Case를 찾으려면 "Search saved ground truth"에 입력해 정답(예: 클래스, 개수, 완성도) 또는 원본 이미지(예: 파일 이름, 태그, 시맨틱 검색)를 기준으로 필터링하세요.

![품질, 지연 시간 및 실패한 Check 추이, 네 개의 Run, 정답 이미지, 두 개의 Check가 표시된 Eval 페이지](https://3843302164-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoO0Ceoy9R0lHDZATcPyh%2Fuploads%2Fgit-blob-c9b38e2d3b29b8a9419e5780fc673efa923b122e%2Fworkflow-evals-eval-page.png?alt=media)

Run을 열어 결과를 확인합니다. Workflow가 두 개 이상인 경우 "Overview"에는 각 Workflow의 품질과 지연 시간 또는 크레딧의 관계가 표시되고, Case별 통과 Check를 히트맵으로 볼 수 있습니다. "Metrics"에서는 Check별 결과를 비교하고, "Vector Analysis"에서는 유사한 Case를 그룹화해 실패 사례의 군집을 찾을 수 있습니다.

![여섯 개 Workflow의 통과 Check 수와 지연 시간을 표시한 Overview 탭 및 Case별 통과 Check 히트맵](https://3843302164-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoO0Ceoy9R0lHDZATcPyh%2Fuploads%2Fgit-blob-9a7612903ca0ae3e2043d0bc43c710a0ef9594da%2Fworkflow-evals-results-overview.png?alt=media)

### 배포 게이트

배포 게이트는 Eval을 통과할 때까지 Workflow 버전의 라이브 배포를 차단합니다. 설정하려면 Workflow를 열고 "Publish" 옆의 드롭다운을 클릭하세요. "Publishing Requirements"에서 "Require an Eval to pass"를 선택합니다. Eval을 선택하고 각 Check의 최소 통과율(기본값 100%)을 설정한 다음 "Save Checks"를 클릭합니다. 목록에는 해당 Workflow가 조건을 충족하지만 아직 참여하지 않은, 사용 가능한 Eval도 표시됩니다. 이를 선택하면 저장 시 Workflow가 해당 Eval에 추가됩니다. 이 작업에는 Workflow Evals 관리 및 실행 권한이 필요합니다.

"Run Checks"를 클릭해 마지막으로 저장된 버전에서 Eval을 실행합니다. 모든 Check를 통과하면 "Publish"를 클릭하세요. "Auto-Publish" 모드에서는 저장할 때마다 검사가 실행되며, 통과하면 버전이 자동으로 게시됩니다.

새 버전마다 별도의 통과 Run이 필요합니다. Eval을 수정하면 이전에 통과한 버전도 Checks를 다시 실행해야 합니다. 게이트를 설정하거나 제거하려면 Workflow 배포 게이트 관리 권한이 필요합니다.

각 버전을 사람이 승인하도록 하려면 "Publishing Requirements"에서 "Require approval"을 선택하고 승인할 수 있는 사용자나 역할을 지정합니다. 승인자에게는 Workflow 관리 권한이 필요합니다. 승인자 중 한 명이 승인하면 버전을 게시할 수 있으며, 한 명이라도 거부하면 게시가 차단됩니다. 자신이 저장한 버전은 승인할 수 없습니다. 새 버전마다 별도의 승인이 필요합니다. 검토를 요청하려면 "Publish"를 클릭하고 "Request Review"를 사용하세요. 승인자는 "Approve" 또는 "Reject"를 클릭합니다. Workflow에 Eval 게이트도 설정되어 있다면 버전은 두 조건을 모두 통과해야 합니다.

## HTTP API

API를 사용해 Evals, Specs, Datasets, Cases, Runs, 결과, 내보내기 및 임베딩을 관리할 수 있습니다. 네임스페이스는 `https://api.roboflow.com/workspaces/{workspace}/workflow-evals`이며, 여기서 `workspace` 는 Workspace 슬러그입니다.

비공개 Workspace API 키 또는 OAuth 액세스 토큰을 다음 `Authorization: Bearer` 헤더에 넣어 인증하세요. 폴더 제한이 적용된 자격 증명은 지원되지 않습니다. OAuth 액세스에는 사용자의 Workspace 권한과 원본 이미지, Dataset 또는 Workflow를 읽는 데 필요한 권한도 적용됩니다.

Workflow Evals에는 서로 독립적인 OAuth 범위가 네 가지 있습니다.

* `workflow-evals:read`: Evals를 읽고 평가기와 스키마를 찾습니다.
* `workflow-evals:write`: 평가 리소스를 만들고 수정합니다.
* `workflow-evals:run`: Run을 시작하고 제어합니다.
* `workflow-evals:export`: 결과를 내보냅니다.

통합에 필요한 모든 스코프를 요청하세요. 하나의 스코프를 부여받아도 다른 스코프가 부여되는 것은 아닙니다. 애플리케이션 연결에 대한 자세한 내용은 [OAuth 인증](https://docs.roboflow.com/reference/authentication/authentication/oauth) 을 참조하세요.

### 평가자 탐색

Checks를 만들기 전에 평가자 카탈로그를 가져오세요. 설치된 엔진의 평가자 유형과 구성 스키마가 반환됩니다.

{% openapi src="/files/af1fe4b26520fa2c4523f90185c4e8851c86db61" path="/workspaces/{workspace}/workflow-evals/evaluators" method="get" %}
[workflow-evals-discovery.openapi.json](https://3843302164-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoO0Ceoy9R0lHDZATcPyh%2Fuploads%2Fgit-blob-2928c95a7448a440bb1fffe80e25051dc965410d%2Fworkflow-evals-discovery.openapi.json?alt=media)
{% endopenapi %}

### API 계약 확인

전체 작업 목록, 요청 스키마, 필수 스코프 및 헤더를 확인하려면 Workspace의 OpenAPI 문서를 가져오세요. 출력 유형이나 평가자 설정을 추측하지 말고, 평가자 카탈로그와 함께 사용하세요.

{% openapi src="/files/af1fe4b26520fa2c4523f90185c4e8851c86db61" path="/workspaces/{workspace}/workflow-evals/openapi.json" method="get" %}
[workflow-evals-discovery.openapi.json](https://3843302164-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoO0Ceoy9R0lHDZATcPyh%2Fuploads%2Fgit-blob-2928c95a7448a440bb1fffe80e25051dc965410d%2Fworkflow-evals-discovery.openapi.json?alt=media)
{% endopenapi %}

### 리소스 및 Run 관리

Specs로 Checks를 정의하고, Datasets에 Cases를 저장하고, 바인딩을 사용해 Workflow 출력을 Spec에 매핑하세요. Run을 시작하기 전에 Spec과 바인딩을 검증하세요. 목록 응답에는 `items` 가 포함되며, 결과가 더 있는 경우에는 `nextCursor`.

가 포함됩니다. 작업에 `Idempotency-Key`가 필요한 경우 UUID v4를 보내고, 같은 요청을 재시도할 때도 해당 키를 유지하세요. 작업에 `If-Match`가 필요한 경우 다른 편집 내용을 덮어쓰지 않도록 리소스의 현재 리비전을 보내세요. Run, 가져오기 및 내보내기는 비동기 작업입니다. 완료될 때까지 상태를 폴링하고, Run을 취소하려면 명시적 취소 작업을 사용하세요.

Dataset의 Cases를 검색하려면 다음을 보내세요. `POST /workspaces/{workspace}/workflow-evals/eval-datasets/{evalDatasetId}/search`. 소스 이미지 필터와 시맨틱 검색에는 `image:read` 스코프도 필요합니다. 빈 페이지를 받은 경우에도 `nextCursor` 가 더 이상 반환되지 않을 때까지 계속 보내세요.

재시도가 필요한 Cases가 남아 있는 실패했거나 일부만 완료된 Run은 내보낼 수 없습니다. 현재 상태 그대로 내보내려면 내보내기 요청에 `allowPendingRetries: true` 를 포함하세요. 활성 상태인 Run은 내보낼 수 없습니다.

{% hint style="info" %}
클라우드 백엔드는 사용자 컴퓨터의 `localhost`에 연결할 수 없습니다. 로컬 Run에서는 클라이언트 러너가 Workflow를 실행하고 채점을 위해 출력을 제출합니다. API를 통해 Run을 생성해도 클라우드에서 로컬 서버에 접근할 수 있게 되는 것은 아닙니다.
{% endhint %}

### Eval 삭제

삭제는 두 단계로 진행됩니다. 먼저 영향을 미리 확인한 다음 반환된 `deletionKey`를 사용해 삭제를 확정합니다. Eval이 배포 게이트를 지원하는 경우 `impact.deployGates` 에 영향을 받는 Workflows가 표시됩니다. 삭제를 확정하면 해당 게이트가 제거되고 대기 중인 배포 검사가 취소됩니다. 게이트가 설정된 Eval을 삭제하려면 `workflow:update` 스코프와 Workflow 배포 게이트를 관리할 권한도 필요합니다. 게이트가 설정되지 않은 Eval에는 이러한 추가 권한이 필요하지 않습니다. 반환된 삭제 작업이 완료될 때까지 폴링하세요.

## Python SDK

Workflow Evals를 사용하려면 [Roboflow Python SDK](https://docs.roboflow.com/reference/platform/python-sdk)버전 1.7.0 이상이 필요합니다. 설치하거나 업데이트하세요.

```bash
pip install --upgrade roboflow
```

Workspace의 Workflow Evals 클라이언트를 사용해 평가자를 확인하고 Evals를 나열하세요.

```python
import os

from roboflow import Roboflow

rf = Roboflow(api_key=os.environ["ROBOFLOW_API_KEY"])
evals = rf.workspace("your-workspace").workflow_evals()

catalog = evals.list_evaluators()
page = evals.list(limit=20)

for evaluation in page["items"]:
    print(evaluation["id"], evaluation["name"])
```

동일한 클라이언트에서 다음도 사용할 수 있습니다. `create`, `start_run`, `get_run`, `wait_for_run`, 그리고 `openapi`. Run을 시작하기 전에 Spec, Dataset, 바인딩을 만들고, 다음의 스키마를 사용하세요 `openapi()` 그리고 `list_evaluators()`.

## CLI

다음 [Roboflow CLI](https://docs.roboflow.com/reference/platform/cli/install-and-set-up-the-cli) 에는 다음이 포함됩니다 `workflow-eval` 명령 그룹입니다. 비공개 API 키로 인증하고 Workspace를 선택하세요:

```bash
export ROBOFLOW_API_KEY="your-private-api-key"
roboflow --workspace your-workspace --json workflow-eval list
roboflow --workspace your-workspace --json workflow-eval evaluator list
roboflow --workspace your-workspace --json workflow-eval run list --eval your-eval-id
```

리소스 및 실행 명령을 확인하려면 `roboflow workflow-eval --help` 를 사용하세요. 이 명령 그룹은 Workflows를 평가하며, 모델 평가 명령과는 별개입니다.

## MCP

연결하세요 [Roboflow MCP Server](https://docs.roboflow.com/agents/mcp-server) 에이전트에 연결한 다음, 다음을 로드하도록 요청하세요: `workflow_evals_agent_manifest` 그리고 Eval을 만들기 전에 Workflow Evals 안내를 확인하도록 요청하세요. 도구를 사용하면 동일한 공개 API를 통해 평가기 검색, Spec 검증, 작성, Runs 및 결과를 처리할 수 있습니다. 다음을 사용하세요: `workflow_evals_datasets_search` 정답 또는 소스 이미지 필터를 기준으로 Cases를 찾으세요. 소스 이미지 및 시맨틱 검색에는 다음 권한도 필요합니다: `image:read`.

예를 들어 다음과 같이 요청하세요. "이 Workflow와 다음 테스트 이미지를 사용해 Workflow Eval을 만들어 주세요. 정답과 Checks를 정의하고 설정을 검증한 다음, Run을 시작하기 전에 크레딧 예상치를 보여 주세요."
