> 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 버전을 비교하고, 배포 전에 회귀를 확인하는 데 사용하세요.

다음을 따르세요 [모델 비교 튜토리얼](/workflows/ko/tutorials/compare-models-with-workflow-evals.md) bolt-counting Eval을 정의하고 에이전트를 사용해 후보 Workflow를 만들고 비교하는 방법입니다.

## 소개

Eval은 무엇을 확인할지 정의하는 Spec과 Case들의 Dataset을 결합합니다. 각 Case에는 입력과 ground truth가 포함됩니다. 즉, 예상 값 또는 주석입니다. Check는 예측된 박스가 주석과 얼마나 정확히 일치해야 하는지와 같은 설정과 함께 평가자를 선택합니다.

Run은 해당 Case와 Check를 대상으로 하나 이상의 Workflow를 평가합니다. 각 Run은 자체 입력, ground truth, Workflow 정의, 평가 설정을 캡처합니다. Case를 편집하거나 제거하면 이후 Run에만 영향을 주며, 기존 Run의 결과는 변경되지 않습니다.

## 웹 앱

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

1. "Select Workflow": 사용할 Workflow와 추론 서버를 선택합니다.
2. "Upload Ground Truth": "Browse Device", "Pick from Asset Library" 또는 "Use a Dataset test set"으로 이미지를 추가합니다. 확인할 Workflow 출력을 선택합니다.
3. "Label Ground Truth": 예상 값을 입력하고 이미지를 주석 처리합니다. Label Assist 제안을 ground truth로 추가하기 전에 검토하세요. Assist 카드에서 AI 모델 또는 Workflow를 선택해 제안을 생성할 수 있습니다. 이 Eval 또는 해당 Run에서 사용된 어떤 Workflow든 선택할 수 있습니다. 삭제된 Workflow는 "Discarded workflows" 아래에 표시되며 저장된 복사본으로 실행됩니다. 기본적으로 제안은 빈 필드에만 채워집니다. 이미 있는 레이블을 대체하려면 "Existing labels" 아래에서 "Overwrite"를 켜세요. 빈 Case를 열 때 자동으로 레이블을 지정하려면 Assist 카드에서 "Auto-annotate"를 켜세요. 제안을 초안으로 저장하며, 승인하려면 여전히 "Add to Ground Truth"를 클릭해야 합니다.
4. "Define Eval Checks": 요구 사항을 나타내는 평가자와 임계값을 선택합니다. "Add check"를 클릭하고, 출력과 ground truth를 비교하려면 "Output check"를, Case당 시간 제한을 설정하려면 "Latency budget"을 선택하세요. 출력이 ground truth와 같을 때만 Case를 통과시키려면 "Matches ground truth exactly"를 선택하세요. 허용 오차와 같은 사용자 지정 메트릭과 임계값을 설정하려면 "Custom rule"을 선택하세요. 분류 체크는 `상위` 또는 `predicted_classes` 출력과 예상 클래스를 exact match 또는 F1로 비교합니다. "Run preview"를 클릭하여 Run을 시작하지 않고 승인된 Case 하나에서 Check를 테스트하세요.
5. "Run Evaluation": 설정과 크레딧 추정치를 검토한 다음 Run을 시작합니다.

저장된 ground truth를 검토하려면 Eval을 열고 "Browse Ground Truth"를 클릭하세요. 갤러리에는 각 Case 이미지와 주석이 표시되며, "Labeled" 또는 "Needs labels"로 표시됩니다. 전체 화면 편집기에서 ground truth를 수정하려면 Case를 클릭하세요.

Run 이후에는 "Cases"로 개별 실패를 검토하고 "Metrics"로 결과를 비교하세요. Run에 두 개 이상의 Workflow가 있으면 첫 번째 탭은 "Overview"입니다. 각 Workflow의 품질을 지연 시간 또는 크레딧과 비교해 표시하고, 히트맵에는 각 Workflow가 각 Case에서 통과한 Check 수가 표시됩니다. "Vector Analysis"는 이미지 임베딩을 사용해 비슷한 Case를 그룹화하므로 실패 클러스터를 검사할 수 있습니다. 임베딩 생성은 비동기적으로 실행됩니다. 완료될 때까지 기다리거나 해당 탭에서 실패한 생성을 다시 시도하세요.

### 지연 시간

"Latency Avg"는 실패한 요청 중 기록된 지속 시간이 있는 경우를 포함해 Case당 기록된 평균 요청 시간입니다. 네트워크 시간과 러너가 측정한 입력 준비 시간을 포함하고, 평가 대기열 시간과 채점 시간은 제외합니다. 이는 모든 Case 지속 시간의 합도 아니고 모델 추론 시간만의 측정치도 아닙니다.

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

### 크레딧

Eval에서 승인된 Workflow 실행 1회당 비용은 크레딧의 1/10,000이며, 로컬에서 실행하든 Serverless에서 실행하든 동일합니다. 100개의 Case에 대해 3개의 Workflow를 평가하면 평가 비용으로 크레딧의 3/10,000이 들며, 여기에 추가 추론 요금이 더해집니다.

Serverless Workflow 추론과 Label Assist는 별도 요금이 부과됩니다. 새 Replay 또는 Rescore는 새로 과금되는 평가 실행을 생성합니다. 원래의 idempotency key로 같은 생성 요청을 다시 시도하면 과금되지 않습니다. 임베딩 생성은 평가 크레딧을 소모하지 않습니다. ground truth를 레이블링할 때의 Smart Select는 주석 편집기와 동일한 AI Labeling 크레딧을 사용합니다.

## HTTP API

API를 사용해 Eval, Spec, Dataset, Case, Run, 결과, export, 임베딩을 관리하세요. 네임스페이스는 `https://api.roboflow.com/workspaces/{workspace}/workflow-evals`이며, `workspace` 는 Workspace 슬러그입니다.

개인 Workspace API 키 또는 OAuth 액세스 토큰으로 `Authorization: Bearer` 헤더에서 인증하세요. 폴더 제한 자격 증명은 지원되지 않습니다. OAuth 액세스는 사용자의 Workspace 권한과 소스 이미지, 데이터세트 또는 Workflow를 읽는 데 필요한 권한도 따릅니다.

Workflow Evals에는 서로 독립적인 4개의 OAuth 범위가 있습니다:

* `workflow-evals:read`: Evals를 읽고 평가자와 스키마를 확인합니다.
* `workflow-evals:write`: 평가 리소스를 생성하고 편집합니다.
* `workflow-evals:run`: Run을 시작하고 제어합니다.
* `workflow-evals:export`: 결과를 내보냅니다.

통합에 필요한 모든 범위를 요청하세요. 한 범위가 다른 범위를 부여하지는 않습니다.  [OAuth 인증](https://docs.roboflow.com/reference/authentication/authentication/oauth) 을 참고해 애플리케이션을 연결하세요.

### 평가기 찾기

Check를 만들기 전에 평가자 카탈로그를 가져오세요. 설치된 엔진에 대한 평가자 유형과 설정 스키마를 반환합니다.

{% 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 관리

Spec으로 Check를 정의하고, Dataset으로 Case를 보관하며, binding으로 Workflow 출력을 Spec에 매핑하세요. Run을 시작하기 전에 Spec과 binding을 검증하세요. 목록 응답은 `items` 를 사용하며, 결과가 더 있으면 `nextCursor`.

를 사용합니다. 작업에서 `Idempotency-Key`가 필요하면 UUID v4를 보내고 같은 요청을 다시 시도할 때는 그 키를 유지하세요. 작업에서 `If-Match`가 필요하면 다른 편집 내용을 덮어쓰지 않도록 리소스의 현재 개정본을 보내세요. Run, import, export는 비동기적으로 처리됩니다. 완료될 때까지 상태를 폴링하고, Run을 취소하려면 명시적인 취소 작업을 사용하세요.

실패했거나 부분적으로 완료되어 아직 다시 시도할 Case가 남아 있는 Run은 내보낼 수 없습니다. 현재 상태 그대로 내보내려면 `allowPendingRetries: true` 를 export 요청에 보내세요. 활성 Run은 내보낼 수 없습니다.

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

## Python SDK

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

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

Workspace의 Workflow Evals 클라이언트를 사용해 평가자를 찾고 Eval을 나열하세요:

```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을 시작하기 전에  `openapi()` 와 `list_evaluators()`.

## CLI

Roboflow 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` 를 확인해 리소스와 Run 명령을 보세요. 이 명령 그룹은 Workflow를 평가하며, 모델 평가 명령과는 별개입니다.

## MCP

다음을 [Roboflow MCP Server](https://docs.roboflow.com/agents/mcp-server) 에 에이전트에 연결하세요. 만들기 전에 `workflow_evals_agent_manifest` 와 Workflow Evals 가이드를 로드하도록 요청하세요. 이 도구들은 같은 공개 API를 통해 평가자 검색, Spec 검증, 작성, Run, 결과를 지원합니다.

예를 들어, 이렇게 요청할 수 있습니다: "이 Workflow에 대해 이 테스트 이미지를 사용하여 Workflow Eval을 만들어 주세요. ground truth와 Check를 정의하고, 설정을 검증한 뒤, Run을 시작하기 전에 크레딧 추정치를 보여주세요."