> 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 데이터 저장소입니다. 이를 통해 프로덕션 환경에서 비전 시스템이 관찰한 모든 내용을 검색하고 필터링할 수 있는 기록으로 관리할 수 있습니다.

### Vision Event란 무엇인가요?

Vision Event는 모델이 이미지를 처리할 때 생성되는 타임스탬프가 포함된 레코드입니다. 각 이벤트에는 다음 항목을 선택적으로 기록할 수 있습니다.

* **이미지**: 처리된 원본 이미지와 관련 출력 이미지
* **동영상**: 이벤트 전후 상황을 보여 주는 동영상 클립(최대 4개)
* **예측**: 모델이 반환한 객체 감지, 분류, 인스턴스 분할 또는 키포인트
* **소스 메타데이터**: 이벤트를 생성한 기기, 스트림 또는 워크플로
* **사용자 지정 메타데이터**: 도메인에 맞게 정의하는 키-값 쌍(예: `line_number`, `shift`, `part_number`)

프로그래밍 방식으로 액세스하려면 다음을 참조하세요. [Vision Events API 참조](#http-api).

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

### 핵심 개념

#### 사용 사례

A **사용 사례** 공통된 목적과 맞춤 메타데이터 구조를 공유하는 이벤트를 그룹화합니다. 같은 사용 사례에 속하는 이벤트는 일반적으로 비슷한 메타데이터 필드를 전송하므로 일관되게 필터링하고 쿼리할 수 있습니다.

예를 들어, "결함 감지" 사용 사례에는 항상 다음 항목이 포함될 수 있습니다. `line_id`, `shift`, 그리고 `part_number` 이벤트가 여러 팩토리나 카메라 위치에서 발생하더라도 마찬가지입니다. 메타데이터 구조가 근본적으로 다를 때는 별도의 Use Case를 만드세요(예: "PPE Compliance"는 다음을 추적합니다. `zone` 및 `alert_type` 를 추적하는 대신).

### 이 섹션에서는

* [이벤트 전송](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/send-events.md) - Workflow 블록, REST API 또는 엣지 디바이스 백업에서 이벤트를 전송합니다.
* [이벤트 쿼리](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/query-events.md) - 대시보드에서 이벤트를 필터링하거나, Agent에게 자연어로 질문하거나, API를 통해 쿼리합니다.
* [학습용 이미지 추가](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/add-images-for-training.md) - 캡처한 이벤트 이미지를 프로젝트로 옮겨 모델을 학습합니다.
* [자동화](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/automations.md) - 일일이 처리하지 않아도 조건에 맞는 이벤트의 이미지를 프로젝트로 보내거나 알림 이메일을 보냅니다.
* [이벤트 없음 알림](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/no-events-alerts.md) - 카메라, 스트림 또는 Workflow에서 이벤트 전송이 중단되면 이메일을 받습니다.
* [운영자 피드백](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/operator-feedback.md) - 팀원이 이벤트를 정답, 오답 또는 판단 불가로 표시할 수 있습니다.
* [요약 보고서](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/summary-reports.md) - 주요 수치와 전체 보고서 링크가 포함된 Use Case 요약을 정기적으로 팀에 이메일로 보냅니다.
* [이벤트 삭제](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/delete-events.md) - Use Case에서 더 이상 필요하지 않은 이벤트를 제거합니다.

## HTTP API

Vision Events API를 사용하면 컴퓨터 비전 배포에서 구조화된 이벤트를 기록한 다음 이를 조회하고 분석할 수 있습니다. 이벤트에는 이미지, 동영상 클립, 탐지 주석, 사용자 지정 메타데이터, 품질 검사, 재고 수량, 안전 경고 등에 특화된 데이터가 포함될 수 있습니다.

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

* [Vision Event 이미지 업로드](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/upload-a-vision-event-image.md#http-api)
* [Vision Event 동영상 업로드](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/upload-a-vision-event-video.md#http-api)
* [Vision Event 생성](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/create-a-vision-event.md#http-api)
* [Vision Event 일괄 생성](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/batch-create-vision-events.md#http-api)
* [Vision Event 번들 업로드](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/upload-a-vision-event-bundle.md#http-api)
* [Vision Event 조회](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/query-events.md#http-api)
* [Use Case 목록 조회](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/use-cases.md#http-api)
* [사용자 지정 메타데이터 스키마 가져오기](https://docs.roboflow.com/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`

### 사용 사례

각 vision event는 하나의 use case와 연결됩니다. use case를 만들고 관리하는 방법은 [Use Cases 문서](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/use-cases.md).

를 참조하세요. 또한 API를 통해 이벤트가 기록된 기존 use case를 [조회할 수도](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/use-cases.md#http-api) 있습니다.

### 이벤트 유형

API는 다섯 가지 이벤트 유형을 지원하며, 각 유형에는 고유한 `eventData` 스키마가 있습니다.

| 이벤트 유형              | 설명                |
| ------------------- | ----------------- |
| `quality_check`     | 품질 보증 및 검사 결과     |
| `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()

# Create a use case
result = ws.create_vision_event_use_case("manufacturing-qa")
use_case_id = result["id"]

# Upload an image
img = ws.upload_vision_event_image("photo.jpg")

# Create an event with the uploaded image
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"},
})

# Query events
for page in ws.query_all_vision_events(use_case_id):
    for evt in page:
        print(evt["eventId"], evt["eventType"])
```

### 사용 가능한 메서드

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

## 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_query</code></td><td>사용 사례의 프로덕션 비전 이벤트를 쿼리합니다.</td></tr><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_custom_metadata_schema_get</code></td><td>사용 사례에 대해 발견된 사용자 지정 메타데이터 스키마를 가져옵니다.</td></tr></tbody></table>
