> 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/query-events.md).

# 이벤트 쿼리

대시보드에서 Vision Event를 검색, 필터링, 탐색하거나, Agent에게 자연어로 질문하거나, API로 쿼리합니다

## 소개

이 페이지에서는 특정 [Vision Events](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events.md) (배포된 모델이 관찰한 내용을 타임스탬프와 함께 기록한 레코드)를 Vision Events 대시보드 또는 REST API에서 필터링하고 검색하는 방법을 설명합니다. 날짜 범위, 이벤트 유형, 디바이스, 스트림, 워크플로, 감지된 클래스 또는 피드백 상태별로 결과를 좁혀 프로덕션 동작을 감사하고 보고서를 작성할 수 있습니다. 자연어로 이벤트에 관해 [Roboflow Agent](https://docs.roboflow.com/agents/roboflow-agent) 에 질문할 수도 있습니다.

### 저장된 필터

저장된 필터는 해당 Use Case에 속하므로 Workspace의 모든 사용자가 열 수 있습니다. 상대 날짜는 상대값으로 유지됩니다. 예를 들어, 지난 7일을 기준으로 저장한 필터에는 언제나 가장 최근 7일간의 결과가 표시됩니다. Vision Events를 만들 수 있는 사용자는 누구나 필터를 덮어써 저장할 수 있습니다. 필터를 저장한 사람이나 Vision Events를 관리할 수 있는 사람만 필터 이름을 변경하거나 삭제할 수 있습니다.

### 자동 확정된 이벤트

자동 확정된 이벤트란 파이프라인이 기본 제한 시간(1시간) 안에 이벤트를 확정하지 못해 엣지 디바이스에서 자동으로 종료된 이벤트입니다. 파이프라인에서 첨부하려던 동영상이 없을 수 있습니다. 이벤트의 결과와 스틸 이미지는 그대로 남아 있습니다. 이는 다음을 통해 동기화된 이벤트에만 적용됩니다. [Edge Device Backup](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/send-events.md#edge-device-backup).

### 에이전트에 질문하기

에이전트에 이벤트 관련 질문을 하려면 "View Vision Events" [권한](https://docs.roboflow.com/platform/enterprise-features/role-based-access-control)이 필요합니다. 질문이 Workspace의 [보존 기간](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events.md#data-retention)보다 이전 시점을 대상으로 하는 경우, 에이전트는 결과가 0이라고 답하는 대신 조회 가능한 가장 이른 날짜를 알려줍니다. 날짜 경계와 시간 구간은 UTC를 기준으로 합니다.

## 웹 앱

### 이벤트 필터링

"Vision Events"를 열고 Use Case를 클릭하면 이벤트를 최신순으로 볼 수 있습니다.

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

필터 바를 사용해 날짜, 이벤트 ID, 이벤트 유형, 디바이스, 스트림, 워크플로, 감지(선택적으로 신뢰도 임계값 지정), 피드백, 사용자 지정 메타데이터, 동영상 개수 또는 수집 경고별로 결과를 좁힐 수 있습니다. 시작일이나 종료일은 "Relative"(예: 7일 전) 또는 "Absolute"(고정된 날짜와 시간)로 지정할 수 있습니다.

텍스트 필터(예: 디바이스, 스트림, 사용자 지정 메타데이터)는 "Contains", "Starts With" 또는 "Ends With"를 사용해 값의 일부만 일치시킬 수도 있습니다. 이 검색은 대소문자를 구분합니다. 대부분의 필터에서는 필드의 "Is Set" 여부도 확인할 수 있습니다. 반대 조건을 지정하려면 "is / is not" 토글을 사용하세요.

서로 다른 필터 집합 중 하나에 일치하는 이벤트를 찾으려면 "OR"을 클릭해 필터 행을 추가하세요. 이벤트가 하나 이상의 행에서 모든 필터와 일치하면 표시됩니다. 날짜는 모든 행에 적용됩니다.

이벤트 세부정보 사이드바의 값(예: 디바이스 ID 또는 사용자 지정 메타데이터 값)을 클릭하면 해당 값이 필터로 추가됩니다. 활성 필터 칩을 클릭하면 값이나 연산자를 변경할 수 있습니다.

일치하는 이벤트의 총 개수는 결과가 아직 로드되는 중에도 결과 위에 표시됩니다. Use Case에 [이벤트 값](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/use-cases.md#event-value)이 있는 경우, 일치하는 이벤트의 총 값도 표시됩니다.

필터를 재사용하려면 필터 바 시작 부분에서 "Saved Filters"를 열고 "Save Current Filters"를 클릭하세요. "Copy Link"를 사용해 공유할 수 있습니다. 변경 권한은 [저장된 필터](#saved-filters) 을 참조하세요.

이벤트를 보관하려면 이벤트를 열고 헤더의 별표를 클릭하거나 `S`를 누르세요. 별표 표시는 본인과 해당 Use Case에서만 볼 수 있습니다. 별표 표시한 이벤트를 보려면 "Saved Filters" 옆의 "Lists" 메뉴를 열고 "Starred"를 선택하세요. 별표 표시된 이벤트는 [보존 기간](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events.md#data-retention)이 지나도 계속 표시됩니다. Use Case당 최대 1,000개의 이벤트에 별표를 표시할 수 있습니다.

직접 목록을 만들려면 "Lists"를 열고 비공개 또는 Workspace 공유 목록을 만드세요. 별표 옆의 목록 버튼을 사용해 이벤트를 추가할 수 있습니다. Vision Events를 만들 수 있는 사용자는 누구나 공유 목록에 이벤트를 추가할 수 있지만, 목록을 만든 사람이나 Vision Events를 관리할 수 있는 사람만 목록 이름을 변경하거나 삭제할 수 있습니다.

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

### 이벤트 세부정보 보기

이벤트를 클릭하면 이미지, 동영상 클립, 소스 메타데이터, 예측, 이벤트 데이터, 사용자 지정 메타데이터 및 [값](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/use-cases.md#event-value).

이벤트에 감지 결과, 세그멘테이션 또는 키포인트가 있는 경우 "Draw Detections"를 선택해 소스 이미지에 표시할 수 있습니다. 파이프라인이 입력 이미지만 저장하는 경우 유용합니다. 브라우저는 이 설정을 모든 이벤트와 전체 화면 보기에 기억합니다. 이미 감지 결과가 표시되는 출력 이미지에서는 체크박스가 숨겨집니다.

이벤트 카드의 재생 아이콘은 해당 이벤트에 [동영상 클립](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/upload-a-vision-event-video.md)이 있음을 나타냅니다. 클립은 이미지 다음의 "Media" 스트립에서 재생되며, 아직 처리 중인 클립은 준비되면 재생됩니다. 감지 오버레이와 전체 화면 보기는 이미지만 지원하며, 클립을 [학습용으로 추가할](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/add-images-for-training.md).

수는 없습니다. 취소선이 있는 동영상 아이콘은 [자동 확정된 이벤트](#auto-finalized-events)를 나타냅니다. 세부정보 보기에서 이벤트가 확정된 시점을 확인할 수 있습니다.

### 시각적 검색

Use Case의 "Visual Lookup" 탭을 사용하면 프레임에 표시된 내용을 기준으로 프레임을 찾을 수 있습니다. 설명(예: 야간의 지게차)을 입력하고 "Search"를 클릭하세요. 보유한 프레임과 유사한 프레임을 찾으려면 프레임이나 이벤트 세부정보 보기에서 "Find similar frames"를 클릭하세요. 결과는 유사도가 높은 순으로 표시되며, 일치하는 항목 전체 목록은 아닙니다.

검색 범위를 좁히려면 시간 범위를 선택하세요. 프레임을 클릭하면 새 탭에서 해당 이벤트가 열립니다. 결과에서 이벤트에 별표를 표시하거나 [학습용 프레임을 추가할](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/add-images-for-training.md) 수도 있습니다. 이 탭을 보려면 Search Workspace Images 권한이 필요합니다. 새 프레임은 업로드 후 몇 분이 지나면 검색할 수 있습니다.

### 에이전트에게 질문하기

왼쪽 사이드바에서 "에이전트"를 클릭하고 다음을 물어보세요: [Roboflow Agent](https://docs.roboflow.com/agents/roboflow-agent) Use Case에 대해(예: "지난주 assembly-line-qa에서 실패한 횟수는 몇 번인가요?"). 에이전트는 이벤트 데이터를 조회해 답변합니다. 이벤트 수를 세고, 시간 경과에 따른 통과율과 실패율을 추적하며, 숫자 필드의 합계, 평균, 최솟값, 최댓값, 고유값 개수를 계산하고, 필드, 사용자 지정 메타데이터, 일별 또는 주별로 합계를 그룹화할 수 있습니다. 또한 이벤트 자체를 나열할 수도 있습니다(예: "기기 X에서 발생한 이벤트를 보여줘"). 이벤트의 다음 페이지를 보려면 더 요청하세요.

Use Case의 Overview 또는 Search 탭에서 "AI로 분석"을 클릭하면 질문이 전송 준비된 상태로 새 탭에서 에이전트가 열립니다. Search 탭에서는 현재 필터가 질문에 포함됩니다.

정기 이메일 요약을 받으려면 [요약 보고서](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/summary-reports.md).

## HTTP API

### 비전 이벤트 쿼리

필터, 시간 범위, 페이지네이션을 사용해 비전 이벤트를 쿼리합니다. 이 엔드포인트는 이벤트 유형, 기기 컨텍스트, 감지 클래스, 사용자 지정 메타데이터, 이미지 메타데이터 및 이벤트별 필드로 필터링할 수 있습니다.

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

{% openapi src="/files/07bb573a8b2a5a268b550bc4e2d87e5feae31c5d" path="/vision-events/query" 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 %}

{% hint style="info" %}
이 `detection`  필터의 이전 이름은  `detectionClass`였습니다. 이전 이름은 더 이상 허용되지 않습니다.
{% endhint %}

결과에 표시되는 각 동영상에는 해당 동영상의 `sourceId` 및 `label`. 재생하거나 다운로드하려면 [재생 URL을 가져오세요](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/upload-a-vision-event-video.md#get-a-playback-url) 의 `sourceId`.

필터 집합 중 하나라도 일치시키려면 필터를 다음과 같이 전송하세요: `filterGroup`. 저장된 필터를 실행하려면 해당 ID를 다음과 같이 전송하세요: `savedFilterId`. 해당 필터에 대해 검색 탭에 표시되는 것과 동일한 이벤트를 가져옵니다.

### 저장된 필터

저장된 필터는 Search 탭에 표시되는 필터와 동일하므로 API를 통해 저장한 필터는 웹 앱에도 표시됩니다. 일반 API 키는 워크스페이스를 대신해 동작하며, 소유한 필터는 없습니다. 필터를 이름 변경하거나 삭제하려면 다음 권한이 필요합니다. `vision-events:manage` 권한 범위입니다. OAuth 토큰은 해당 사용자를 대신해 동작하므로, 사용자는 다음 권한을 사용해 자신의 필터 이름을 변경하거나 삭제할 수 있습니다. `vision-events:write`. 다른 사용자의 필터를 변경하면 해당 변경 사항이 워크스페이스 감사 로그에 기록됩니다.

{% openapi src="/files/07bb573a8b2a5a268b550bc4e2d87e5feae31c5d" path="/vision-events/use-cases/{useCaseId}/saved-filters" 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 %}

{% openapi src="/files/07bb573a8b2a5a268b550bc4e2d87e5feae31c5d" path="/vision-events/use-cases/{useCaseId}/saved-filters/{savedFilterId}" 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 %}

{% openapi src="/files/07bb573a8b2a5a268b550bc4e2d87e5feae31c5d" path="/vision-events/use-cases/{useCaseId}/saved-filters" 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 %}

{% openapi src="/files/07bb573a8b2a5a268b550bc4e2d87e5feae31c5d" path="/vision-events/use-cases/{useCaseId}/saved-filters/{savedFilterId}" method="patch" %}
[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 %}

{% openapi src="/files/07bb573a8b2a5a268b550bc4e2d87e5feae31c5d" path="/vision-events/use-cases/{useCaseId}/saved-filters/{savedFilterId}" method="delete" %}
[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 %}

## Python SDK

필터, 시간 범위, 페이지네이션을 사용해 비전 이벤트를 쿼리합니다.

### 단일 페이지 쿼리

다음을 사용합니다. `query_vision_events()` 결과의 단일 페이지를 가져오려면:

```python
import roboflow

roboflow.login()

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

page = ws.query_vision_events(
    "a1b3c8e1",                          # 사용 사례 ID(필수)
    event_type="quality_check",          # 단일 이벤트 유형으로 필터링
    start_time="2024-01-14T00:00:00Z",   # ISO 8601 시작 시간
    end_time="2024-01-15T23:59:59Z",     # ISO 8601 종료 시간
    limit=50,                            # 페이지당 최대 이벤트 수
)

for evt in page["events"]:
    print(evt["eventId"], evt["eventData"])
```

키워드 인수로 추가 필터를 전달할 수도 있습니다. 이 인수는 API로 직접 전달됩니다:

```python
page = ws.query_vision_events(
    "a1b3c8e1",
    event_types=["quality_check", "safety_alert"],
    deviceId={"operator": "eq", "value": "camera-node-5"},
    customMetadataFilters=[
        {"field": "temperature", "operator": "gt", "value": 70, "type": "number"}
    ],
    eventFieldFilters=[
        {"column": "result", "operator": "eq", "value": "fail"}
    ],
)
```

수동으로 페이지를 매기려면 `cursor` 매개변수에 이전 응답의 `nextCursor` 값을 사용하세요:

```python
all_events = []
page = ws.query_vision_events("a1b3c8e1", limit=100)
all_events.extend(page.get("events", []))

while page.get("hasMore"):
    page = ws.query_vision_events("a1b3c8e1", cursor=page["nextCursor"], limit=100)
    all_events.extend(page.get("events", []))
```

### 모든 결과 페이지로 조회하기

를 사용하면 `query_all_vision_events()` 일치하는 모든 이벤트를 페이지 단위로 자동 조회할 수 있습니다. 한 번에 한 페이지의 이벤트를 반환합니다:

```python
all_events = []

for page in ws.query_all_vision_events(
    "a1b3c8e1",
    event_type="quality_check",
    start_time="2024-01-14T00:00:00Z",
    end_time="2024-01-15T23:59:59Z",
):
    all_events.extend(page)

print(f"Found {len(all_events)} events")
```

사용 가능한 필터, 연산자 및 응답 형식에 관한 자세한 내용은 [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_query</code></td><td>필터와 페이지네이션을 사용해 프로덕션 비전 이벤트를 조회합니다.</td></tr><tr><td><code>vision_events_use_cases_list</code></td><td>워크스페이스의 비전 이벤트 사용 사례를 나열합니다.</td></tr><tr><td><code>vision_events_custom_metadata_schema_get</code></td><td>사용 사례에 대해 확인된 사용자 지정 메타데이터 스키마를 가져옵니다.</td></tr></tbody></table>
