> 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/deployment/ko/monitoring-and-analytics/vision-events/use-cases.md).

# 사용 사례

사용 목적별로 Vision Event를 사용 사례로 그룹화합니다.

## 정보

사용 사례는 [Vision Events를 그룹화합니다](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events.md) 공통 목적과 사용자 지정 메타데이터 구조를 공유하며, 각 이벤트는 정확히 하나의 사용 사례에 속합니다. 이벤트를 이런 방식으로 정리하면 동일한 필드를 보고하는 카메라, 기기, 위치 전반의 데이터를 쉽게 필터링하고 비교할 수 있습니다.

서로 다른 위치, 카메라 또는 기기에서 발생하더라도 사용자 지정 메타데이터 필드를 공유하는 이벤트는 같은 사용 사례에 넣으세요. 예를 들어 "Defect Detection" 사용 사례는 여러 공장에서 발생한 이벤트를 받을 수 있으며, 이 이벤트에는 모두 `line_id`, `shift`및 `part_number`가 포함됩니다. 메타데이터 구조가 다르면 별도의 사용 사례를 만드세요:

* 조립 라인 품질 보증: `line_id`, `shift`, `part_number`
* 창고 재고: `aisle`, `shelf`, `item_type`
* 건설 현장 안전: `zone`, `alert_type`, `contractor`

이벤트가 도착하면 Roboflow는 확인된 필드와 값 유형을 기반으로 사용자 지정 메타데이터 스키마를 추론합니다. 이를 확인하려면 다음을 호출하세요. [사용자 지정 메타데이터 스키마 가져오기](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/get-custom-metadata-schema.md).

다음 [Roboflow Agent](https://docs.roboflow.com/agents/roboflow-agent) 는 Vision Events를 사용해 Workflow를 만들 때 Use Case를 생성합니다. 적합한 기존 Use Case가 있으면 이를 재사용합니다. Agent에 Use Case 설정을 요청할 수도 있습니다.

Use Case를 보관하면 기본 보기에서 숨겨집니다. 이벤트는 보존되며, 보관을 해제할 수 있습니다. 보관된 Use Case로 전송한 이벤트도 저장되지만, 각 이벤트는 경고를 반환합니다.

### 이벤트 값

Use Case의 가치를 추적할 수 있도록 이벤트에 금전적 가치를 지정하세요(예: 적발된 결함 하나당 비용). Use Case에 기본값과 통화를 설정합니다. 자체 값을 보내지 않는 새 이벤트에는 기본값이 적용되며, 이미 전송한 이벤트의 값은 그대로 유지됩니다.

이벤트는 자체 값을 다음 항목에 보낼 수도 있습니다. `valueBaseUnits` (참조: [비전 이벤트 만들기](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/create-a-vision-event.md#http-api)). 값은 항상 사용 사례 통화로 표시됩니다. 값 합계는 약 5분마다 업데이트됩니다.

### 체크리스트

체크리스트는 한 장치가 스테이션에서 통과해야 하는 단계(예: 보드에 나사 4개 고정)를 추적합니다. 각 체크리스트에는 이름과 항목 목록이 있습니다. 하나의 사용 사례에 최대 20개의 체크리스트를 만들 수 있으며, 각 체크리스트에는 최대 50개의 항목을 포함할 수 있습니다. Roboflow는 다음 이벤트에서 체크리스트 상태를 읽습니다: `quality_check` 별도의 상태를 저장하지는 않습니다.

각 장치에는 하나의 시간 창이 할당됩니다. 다음 항목을 전송하세요. `customMetadata` 각 항목의 키 `quality_check` 해당 단위의 이벤트:

* `checklistId`체크리스트의 ID입니다.
* `checklistWindowId`단위마다 하나의 ID(예: 일련번호)를 사용합니다. 해당 단위의 모든 이벤트에서 같은 ID를 사용합니다.
* `checklistRole`: `window_open`, `item`, 또는 `window_close`.
* `checklistItemId`: 결과가 적용되는 항목입니다. 이 값은 `item` 이벤트에만 전송하세요.

다음 `item` 이벤트에서는 다음을 설정하세요 `eventData.result` 를 `pass` 또는 `fail`. 각 이벤트에 고유한 `eventId`. 동일한 `eventId`, `timestamp`, 그리고 `useCaseId` 이전 항목을 대체합니다.

순서대로 항목을 통과하게 하려면 "Require Order"를 켜세요(`ordered` (API에서는). 그러면 이전 항목이 모두 통과한 경우에만 항목 통과로 계산되며, 실패가 발생하면 해당 항목과 그 이후의 모든 항목이 초기화됩니다. 이 옵션을 끄면 항목은 순서와 상관없이 통과할 수 있고, 이후 항목이 실패해도 이미 통과한 항목은 초기화되지 않습니다.

## 웹 앱

Workspace의 왼쪽 사이드바에서 "Vision Events"를 열고 "+ Create Use Case"를 클릭하세요.

<figure><img src="https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-e940058d52aa94761417871f65f91eaf3772b31e%2Fimage%20(456).png?alt=media" alt="" width="375"><figcaption></figcaption></figure>

Use Cases 표에는 각 Use Case의 이벤트 수, 마지막 이벤트 시간, 이벤트 유형, 누적 값이 표시됩니다. Use Case의 개요에는 "Value Created" 타일에 해당 Use Case의 값이 표시됩니다.

기본값을 설정하려면 [이벤트 값](#event-value)에서 Use Case 메뉴를 열고 "Update Settings"를 클릭한 다음 "Default Event Value"와 "Currency"를 입력하세요.

추가하려면 [체크리스트를](#checklists)사용 사례 메뉴를 열고 "체크리스트 편집"을 클릭한 다음 "체크리스트 추가"를 클릭하세요. 변경 사항을 저장하려면 "체크리스트 저장"을 클릭하세요. 각 유닛의 진행 상황을 보려면 사용 사례를 열고 "체크리스트" 탭을 클릭하세요. Connect Guide에서 체크리스트 ID가 포함된 샘플 체크리스트 이벤트를 확인할 수 있습니다.

대시보드에서 사용 사례를 보관할 수 있습니다. 보관된 사용 사례를 보려면 표 하단의 "보관된 사용 사례 보기"를 클릭하세요.

<figure><img src="https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-a19e941a3d1c11eebe09fc1426edc618aef53913%2FDashboard%20view%20for%20solution%20nine%20status.png?alt=media" alt=""><figcaption></figcaption></figure>

## HTTP API

제한 없는 워크스페이스 API 키에는 기본적으로 `vision-events:manage` 범위가 포함됩니다.

### 사용 사례 만들기

워크스페이스에 새 사용 사례를 만드세요. 사용 사례를 활용하면 배포 컨텍스트(예: "제조 라인 1", "창고 재고")별로 비전 이벤트를 정리할 수 있습니다.

**필수 범위:** `vision-events:manage`

{% openapi src="/files/07bb573a8b2a5a268b550bc4e2d87e5feae31c5d" path="/vision-events/use-cases" method="post" %}
[openapi.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-0988c6c6c600d725f72d1ecfe0cbeba9b717363f%2Fopenapi.yaml?alt=media)
{% endopenapi %}

#### 참고

* 새 사용 사례는 기본적으로 `active` 상태로 생성됩니다.
* 사용 사례를 생성한 후에는 해당 사용 사례의 `id` 를 `useCaseId` 로 참조할 수 있습니다. [비전 이벤트 생성](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/create-a-vision-event.md#http-api).

### 사용 사례 업데이트

기존 사용 사례의 이름, 상태, 기본 이벤트 값 또는 체크리스트를 업데이트합니다.  `checklists` 를 전송하면 사용 사례의 체크리스트가 모두 대체됩니다.

**필수 범위:** `vision-events:manage`

{% openapi src="/files/07bb573a8b2a5a268b550bc4e2d87e5feae31c5d" path="/vision-events/use-cases/{useCaseId}" method="put" %}
[openapi.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-0988c6c6c600d725f72d1ecfe0cbeba9b717363f%2Fopenapi.yaml?alt=media)
{% endopenapi %}

### 사용 사례 목록 조회

워크스페이스의 사용 사례를 나열합니다. 사용 사례를 만들고 관리하는 방법은  [사용 사례 문서](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/use-cases.md).

**필수 권한 범위:** `vision-events:read` 또는 `device:read`

{% openapi src="/files/07bb573a8b2a5a268b550bc4e2d87e5feae31c5d" path="/vision-events/use-cases" method="get" %}
[openapi.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-0988c6c6c600d725f72d1ecfe0cbeba9b717363f%2Fopenapi.yaml?alt=media)
{% endopenapi %}

### 사용 사례 보관

사용 사례의 상태를 다음 값으로 설정하여 보관합니다:  `inactive`. 보관된 사용 사례는 기본적으로 목록에서 숨겨집니다. 보관된 사용 사례로 전송된 이벤트는 계속 저장되며,  `entity_not_found`  경고가 표시됩니다.

**필수 범위:** `vision-events:manage`

{% openapi src="/files/07bb573a8b2a5a268b550bc4e2d87e5feae31c5d" path="/vision-events/use-cases/{useCaseId}/archive" method="post" %}
[openapi.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-0988c6c6c600d725f72d1ecfe0cbeba9b717363f%2Fopenapi.yaml?alt=media)
{% endopenapi %}

#### 참고

* 보관은 소프트 삭제입니다. 사용 사례와 이벤트는 보존되지만 활성 목록에서는 숨겨집니다.
* 보관된 사용 사례를 보려면  [사용 사례 목록 조회](#http-api) 엔드포인트에  `status=inactive`.
* 를 지정합니다. 보관된 사용 사례는  [사용 사례 보관 해제](#http-api) 엔드포인트를 사용하여 복원할 수 있습니다.

### 사용 사례 보관 해제

이전에 보관된 사용 사례의 상태를 다시 다음 값으로 설정하여 복원합니다:  `active`.

**필수 범위:** `vision-events:manage`

{% openapi src="/files/07bb573a8b2a5a268b550bc4e2d87e5feae31c5d" path="/vision-events/use-cases/{useCaseId}/unarchive" method="post" %}
[openapi.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-0988c6c6c600d725f72d1ecfe0cbeba9b717363f%2Fopenapi.yaml?alt=media)
{% endopenapi %}

#### 참고

* 상태가  `inactive` 인 사용 사례만 보관 해제할 수 있습니다.
* 보관 해제하면 사용 사례가 활성 목록에 다시 표시되며, 새 이벤트에는 더 이상 경고가 반환되지 않습니다.

## Python SDK

각 비전 이벤트는 사용 사례와 연결됩니다. Python SDK는 사용 사례 생성, 목록 조회, 이름 변경, 보관 및 보관 해제를 위한 메서드를 제공합니다.

### 사용 사례 목록 조회

```python
import roboflow

roboflow.login()

rf = roboflow.Roboflow()
ws = rf.workspace()

result = ws.list_vision_event_use_cases()

for uc in result["useCases"]:
    print(uc["id"], uc["name"], uc.get("status"))
```

상태로 필터링할 수 있습니다:

```python
# 활성 사용 사례만 나열
result = ws.list_vision_event_use_cases(status="active")
```

### 사용 사례 만들기

```python
result = ws.create_vision_event_use_case("manufacturing-qa")
use_case_id = result["id"]
print(f"Created use case: {use_case_id}")
```

### 사용 사례 이름 변경

```python
ws.rename_vision_event_use_case("a1b3c8e1", "updated-name")
```

### 사용 사례 보관

```python
ws.archive_vision_event_use_case("a1b3c8e1")
```

### 사용 사례 보관 해제

```python
ws.unarchive_vision_event_use_case("a1b3c8e1")
```

사용 사례 관리에 관한 자세한 내용은 다음을 참조하세요. [REST API 참조](#http-api).

## 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>vision_events_use_cases_list</code></td><td>워크스페이스의 비전 이벤트 사용 사례를 나열합니다.</td></tr><tr><td><code>vision_events_use_case_create</code></td><td>새 비전 이벤트 사용 사례를 만듭니다.</td></tr><tr><td><code>vision_events_use_case_rename</code></td><td>기존 사용 사례의 이름을 변경합니다.</td></tr><tr><td><code>vision_events_use_case_archive</code></td><td>사용 사례를 보관합니다.</td></tr><tr><td><code>vision_events_use_case_unarchive</code></td><td>이전에 보관한 사용 사례를 복원합니다.</td></tr></tbody></table>
