> 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.md).

# Vision Events

## 소개

### 개요

Vision Events는 배포된 컴퓨터 비전 모델에서 얻은 시각 정보와 함께 불량 감지나 재고 수량 집계와 같은 중요한 이벤트를 캡처할 수 있는 Roboflow 데이터 저장소입니다. 이를 통해 운영 환경에서 비전 시스템이 관찰한 모든 것에 대한 검색 가능하고 필터링 가능한 기록을 얻을 수 있습니다.

### 비전 이벤트란 무엇인가요?

비전 이벤트는 모델이 이미지를 처리할 때 생성되는 타임스탬프가 포함된 기록입니다. 각 이벤트는 선택적으로 다음을 캡처할 수 있습니다:

* **이미지**: 처리된 원본 이미지와 연결된 출력 이미지
* **예측**: 모델이 반환한 객체 감지, 분류, 인스턴스 분할 또는 키포인트
* **소스 메타데이터**: 어떤 장치, 스트림 또는 워크플로가 이벤트를 생성했는지
* **사용자 정의 메타데이터**: 도메인에 맞게 정의하는 키-값 쌍(예: `line_number`, `shift`, `part_number`)

프로그램 방식의 접근은 [Vision Events API 레퍼런스](#http-api).

{% embed url="<https://www.youtube.com/watch?v=4HlYG1MacRk>" %}

### 핵심 개념

#### 사용 사례

하나의 **사용 사례** 공통 목적과 사용자 정의 메타데이터 구조를 공유하는 이벤트를 그룹화합니다. 같은 사용 사례의 이벤트는 일반적으로 유사한 메타데이터 필드를 보내므로 일관되게 필터링하고 조회할 수 있습니다.

예를 들어, "불량 감지" 사용 사례에는 항상 `line_id`, `shift`그리고 `part_number` 가 포함될 수 있습니다. 이벤트가 여러 공장이나 카메라 위치에서 발생하더라도 마찬가지입니다. 메타데이터 구조가 본질적으로 다른 경우에는 별도의 사용 사례를 만드세요(예: "PPE 준수"는 `zone` 및 `alert_type` 를 추적).

### 이 섹션에서

* [이벤트 전송](/deployment/ko/monitoring-and-analytics/vision-events/send-events.md) - 워크플로 블록, REST API 또는 엣지 장치 백업에서 이벤트를 전송합니다.
* [학습용 이미지 추가](/deployment/ko/monitoring-and-analytics/vision-events/add-images-for-training.md) - 캡처된 이벤트 이미지를 프로젝트로 옮겨 모델을 학습합니다.
* [작업자 피드백](/deployment/ko/monitoring-and-analytics/vision-events/operator-feedback.md) - 팀원이 이벤트를 올바름, 잘못됨, 또는 판단 불가로 표시할 수 있게 합니다.
* [요약 보고서](/deployment/ko/monitoring-and-analytics/vision-events/summary-reports.md) - 사용 사례의 정기 요약을 팀에 이메일로 보냅니다.
* [이벤트 삭제](/deployment/ko/monitoring-and-analytics/vision-events/delete-events.md) - 더 이상 필요하지 않은 이벤트를 사용 사례에서 제거합니다.

## HTTP API

Vision Events API를 사용하면 컴퓨터 비전 배포에서 구조화된 이벤트를 기록한 다음, 이를 조회하고 분석할 수 있습니다. 이벤트에는 이미지, 감지 주석, 사용자 정의 메타데이터, 그리고 품질 검사, 재고 수량, 안전 경고 등에 대한 유형별 데이터를 포함할 수 있습니다.

Vision Events API를 사용하면 다음을 수행할 수 있습니다:

* [비전 이벤트 이미지 업로드](/deployment/ko/monitoring-and-analytics/vision-events/upload-a-vision-event-image.md#http-api)
* [비전 이벤트 생성](/deployment/ko/monitoring-and-analytics/vision-events/create-a-vision-event.md#http-api)
* [비전 이벤트 일괄 생성](/deployment/ko/monitoring-and-analytics/vision-events/batch-create-vision-events.md#http-api)
* [비전 이벤트 조회](/deployment/ko/monitoring-and-analytics/vision-events/query-events.md#http-api)
* [사용 사례 목록 조회](/deployment/ko/monitoring-and-analytics/vision-events/use-cases.md#http-api)
* [사용자 정의 메타데이터 스키마 가져오기](/deployment/ko/monitoring-and-analytics/vision-events/get-custom-metadata-schema.md#http-api)

### 인증

모든 Vision Events 엔드포인트는 Roboflow API 키를 사용한 Bearer 토큰 인증을 사용합니다:

```
Authorization: Bearer YOUR_API_KEY
```

Vision Events 엔드포인트에는 특정 [범위가 지정된 API 키](https://docs.roboflow.com/reference/authentication/authentication/scoped-api-keys) 권한이 필요합니다:

* **읽기 작업** (조회, 목록, 스키마): `vision-events:read` 또는 `device:read`
* **쓰기 작업** (생성, 일괄 처리, 업로드): `vision-events:write` 또는 `device:update`

### 사용 사례

각 비전 이벤트는 사용 사례와 연결됩니다. 사용 사례를 생성하고 관리하는 방법은 [사용 사례 문서](/deployment/ko/monitoring-and-analytics/vision-events/use-cases.md).

도 참조할 수 있습니다. [기존 사용 사례를 나열](/deployment/ko/monitoring-and-analytics/vision-events/use-cases.md#http-api) 하여 API를 통해 기록된 이벤트를 확인할 수도 있습니다.

### 이벤트 유형

API는 고유한 `eventData` 스키마를 가진 다섯 가지 이벤트 유형을 지원합니다:

| 이벤트 유형              | 설명                |
| ------------------- | ----------------- |
| `quality_check`     | QA 및 검사 결과        |
| `inventory_count`   | 재고 측정             |
| `safety_alert`      | 안전 사고 및 경고        |
| `custom`            | 자유 형식 이벤트 데이터     |
| `operator_feedback` | 모델 예측에 대한 사람의 피드백 |

### 데이터 보존

이벤트는 구성 가능한 조회 기간 동안 보관됩니다(기본값: 14일). `lookbackDays` 값은 조회 응답에 반환되므로 작업 공간의 실제 보존 기간을 알 수 있습니다.

## Python SDK

Roboflow Python SDK는 `Workspace` 객체에서 비전 이벤트를 다루기 위한 메서드를 제공합니다. 이벤트를 생성하고, 필터와 페이지네이션으로 조회하고, 이미지를 업로드하고, 사용 사례를 관리할 수 있습니다.

이벤트 스키마, 필터링 옵션, 응답 형식에 대한 전체 세부 정보는 [Vision Events REST API 문서](#http-api).

### 빠른 시작

```python
import roboflow

roboflow.login()

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

# 사용 사례 생성
result = ws.create_vision_event_use_case("manufacturing-qa")
use_case_id = result["id"]

# 이미지 업로드
img = ws.upload_vision_event_image("photo.jpg")

# 업로드한 이미지로 이벤트 생성
ws.write_vision_event({
    "eventId": "c3d4e5f6-a1b2-4c3d-8e5f-6a7b8c9d0e1f",
    "eventType": "quality_check",
    "useCaseId": use_case_id,
    "timestamp": "2024-01-15T10:30:00Z",
    "images": [{"sourceId": img["sourceId"]}],
    "eventData": {"result": "pass"},
})

# 이벤트 조회
for page in ws.query_all_vision_events(use_case_id):
    for evt in page:
        print(evt["eventId"], evt["eventType"] )
```

### 사용 가능한 메서드

| 메서드                                                                                                                                    | 설명                             |
| -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
| [`upload_vision_event_image()`](/deployment/ko/monitoring-and-analytics/vision-events/upload-a-vision-event-image.md#python-sdk)       | 이벤트에 사용할 이미지를 업로드합니다           |
| [`write_vision_event()`](/deployment/ko/monitoring-and-analytics/vision-events/create-a-vision-event.md#python-sdk)                    | 단일 비전 이벤트를 생성합니다               |
| [`write_vision_events_batch()`](/deployment/ko/monitoring-and-analytics/vision-events/batch-create-vision-events.md#python-sdk)        | 한 번의 요청으로 최대 100개의 이벤트를 생성합니다  |
| [`query_vision_events()`](/deployment/ko/monitoring-and-analytics/vision-events/query-events.md#python-sdk)                            | 필터와 페이지네이션으로 이벤트를 조회합니다        |
| [`query_all_vision_events()`](/deployment/ko/monitoring-and-analytics/vision-events/query-events.md#paginate-through-all-results)      | 일치하는 모든 이벤트를 자동 페이지네이션으로 조회합니다 |
| [`list_vision_event_use_cases()`](/deployment/ko/monitoring-and-analytics/vision-events/use-cases.md#python-sdk)                       | 워크스페이스의 사용 사례를 나열합니다           |
| [`create_vision_event_use_case()`](/deployment/ko/monitoring-and-analytics/vision-events/use-cases.md#create-a-use-case)               | 새 사용 사례를 생성합니다                 |
| [`rename_vision_event_use_case()`](/deployment/ko/monitoring-and-analytics/vision-events/use-cases.md#rename-a-use-case)               | 사용 사례의 이름을 변경합니다               |
| [`archive_vision_event_use_case()`](/deployment/ko/monitoring-and-analytics/vision-events/use-cases.md#archive-a-use-case)             | 사용 사례를 보관합니다                   |
| [`unarchive_vision_event_use_case()`](/deployment/ko/monitoring-and-analytics/vision-events/use-cases.md#unarchive-a-use-case)         | 사용 사례 보관을 해제합니다                |
| [`get_vision_event_metadata_schema()`](/deployment/ko/monitoring-and-analytics/vision-events/get-custom-metadata-schema.md#python-sdk) | 검색된 사용자 정의 메타데이터 필드 유형 가져오기    |