> 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로 쿼리합니다
## 소개
이 페이지에서는 특정 [비전 이벤트](/deployment/ko/monitoring-and-analytics/vision-events.md) - 배포된 모델이 관찰한 내용의 타임스탬프 기록을 - Vision Events 대시보드에서 필터링하고 검색하거나 REST API를 통해 프로그래밍 방식으로 조회하여 찾을 수 있습니다. 날짜 범위, 이벤트 유형, 디바이스, 스트림, 워크플로, 감지된 클래스 또는 피드백 상태로 결과를 좁혀 운영 동작을 감사하고 보고서를 작성할 수 있습니다. 또한 다음에게 질문할 수도 있습니다 [Roboflow 에이전트](https://docs.roboflow.com/agents/roboflow-agent) 이벤트에 대해 자연어로 질문할 수 있습니다.
## 웹 앱
### 이벤트 쿼리 및 필터링
Vision Events 대시보드의 필터를 사용해 특정 이벤트를 찾거나 REST API를 통해 프로그래밍 방식으로 쿼리할 수 있습니다.
#### 대시보드에서 이벤트 탐색
**사용 사례 선택**
Vision Events 페이지에서 사용 사례를 클릭해 해당 이벤트를 확인합니다. 이벤트는 시간 역순으로 표시됩니다.
**이벤트 필터링**
이벤트 목록 상단의 필터 컨트롤을 사용해 결과를 다음 기준으로 좁히세요:
* **날짜 범위** - 시작 및 종료 타임스탬프
* **이벤트 유형** - quality\_check, inventory\_count, safety\_alert, custom, operator\_feedback
* **디바이스** - 디바이스 ID로 필터링
* **스트림** - 스트림 또는 카메라 ID로 필터링
* **워크플로** - 이벤트를 생성한 워크플로로 필터링
* **감지** - 감지된 객체 클래스로 필터링하며, 선택적으로 신뢰도 임계값을 적용
* **피드백 상태** - 올바름, 잘못됨, 판단 불가, 또는 피드백 없음
* **사용자 지정 메타데이터** - 모든 사용자 지정 메타데이터 필드와 값으로 필터링
* **비디오 개수** - 첨부된 비디오 클립 수로 필터링(예: 비디오가 있는 이벤트를 찾으려면 "보다 크거나 같음" 1)
* **경고** - 수집 경고가 있었던 이벤트만 표시
시작 날짜나 종료 날짜는 "상대"일 수 있습니다(예: 7일 전) 또는 "절대"일 수 있습니다(고정된 날짜와 시간). 상대 날짜는 현재 시간에 따라 이동하므로, 최근 7일에 대한 저장된 또는 공유된 링크는 항상 가장 최근 7일을 표시합니다.
필터 집합을 다시 사용하려면 필터 바 시작 부분의 "저장된 필터" 메뉴를 열고 "현재 필터 저장"을 클릭하세요. 저장된 필터는 사용 사례에 속하므로 워크스페이스의 모든 사용자가 열 수 있습니다. 상대 날짜는 그대로 상대적으로 유지됩니다. 저장된 필터를 공유하려면 "링크 복사"를 사용하세요. Vision Events를 만들 수 있는 사람은 누구나 필터를 덮어써서 저장할 수 있습니다. 이를 저장한 사람이나 Vision Events를 관리할 수 있는 사람만 이름을 바꾸거나 삭제할 수 있습니다.
또한 이벤트 세부정보 사이드바의 값(예: 디바이스 ID, 스트림, 품질 검사 결과 또는 사용자 지정 메타데이터 값)을 클릭해 빠르게 필터로 추가할 수 있습니다.
필터 칩은 편집할 수 있습니다 -- 활성 필터 칩을 클릭하면 제거했다가 다시 추가하지 않고도 값이나 연산자를 수정할 수 있습니다.
필터가 적용되면 **총 개수** 의 일치하는 이벤트가 결과 목록 상단에 표시됩니다. 이 개수는 이벤트 목록과 별도로 업데이트되므로, 이벤트가 아직 로딩 중이어도 필터와 일치하는 이벤트 수를 확인할 수 있습니다. 사용 사례에 [이벤트 값](/deployment/ko/monitoring-and-analytics/vision-events/use-cases.md#event-value)이 있으면, 일치하는 이벤트의 총값도 표시합니다.
**이벤트 세부정보 보기**
목록의 아무 이벤트나 클릭해 전체 세부정보를 확인하세요:
* 소스 이미지, 출력 이미지, 그리고 모든 비디오 클립
* 모든 소스 메타데이터(디바이스, 스트림, 워크플로)
* 신뢰도 점수가 포함된 객체 감지, 분류 및 세분화
* 이벤트 유형별 데이터(예: 통과/실패 결과, 항목 수, 경고 심각도)
* 사용자 지정 메타데이터 키-값 쌍
* 이벤트의 값(있는 경우, 다음 참조 [이벤트 값](/deployment/ko/monitoring-and-analytics/vision-events/use-cases.md#event-value))
**감지 항목 그리기**
이벤트에 예측 데이터(객체 감지, 인스턴스 세분화 또는 키포인트)가 포함되어 있으면 이미지 위에 "감지 항목 그리기" 체크박스가 표시됩니다. 이를 활성화하면 소스 이미지 위에 신뢰도 점수가 포함된 바운딩 박스, 세분화 폴리곤, 레이블을 겹쳐서 표시할 수 있습니다.
파이프라인이 원본 입력 이미지만 저장하고 별도의 출력 이미지를 저장하지 않은 상태에서 모델이 감지한 내용을 시각화하고 싶을 때 유용합니다.
{% hint style="info" %}
별도의 출력 이미지를 볼 때는 해당 이미지에 이미 감지가 렌더링되어 있으므로 이 체크박스는 숨겨집니다.
{% endhint %}
**비디오 클립**
재생 아이콘이 있는 이벤트 카드에는 하나 이상의 [비디오 클립](/deployment/ko/monitoring-and-analytics/vision-events/upload-a-vision-event-video.md) 이 첨부되어 있습니다. 세부정보 보기에서는 클립이 이미지 뒤의 "Media" 스트립에 표시되며, 레이블 또는 "Clip 1", "Clip 2" 등의 이름으로 나타납니다. 클립을 클릭하면 브라우저의 비디오 플레이어에서 재생되며, 아래에 재생 시간이 표시됩니다.
Roboflow가 아직 처리 중인 클립에는 "처리 중입니다. 준비되는 즉시 재생됩니다."가 표시됩니다. 플레이어는 몇 분 동안 다시 확인한 후 "처리 중입니다."와 함께 "다시 확인" 버튼을 표시합니다. 업로드에 실패한 클립에는 "비디오 업로드 실패"가 표시되며, 로드할 수 없는 클립에는 "비디오를 사용할 수 없음"이 표시됩니다. 감지 오버레이와 전체 화면은 이미지에만 적용되며, 클립은 [학습용으로 추가됨](/deployment/ko/monitoring-and-analytics/vision-events/add-images-for-training.md).
**자동 확정된 이벤트**
자동 확정으로 표시된 이벤트는 비디오 업로드가 완료되기 전에 엣지 디바이스에서 자동으로 닫혀서 비디오가 없습니다. 그러나 이벤트에는 여전히 결과와 정지 이미지가 포함됩니다. 이벤트 카드에는 취소선이 있는 비디오 아이콘("자동 확정: 비디오 없음")이 표시되며, 세부정보 보기에는 확정된 시간이 표시됩니다. 이는 다음을 통해 동기화된 이벤트에만 적용됩니다 [엣지 디바이스 백업](/deployment/ko/monitoring-and-analytics/vision-events/send-events.md#edge-device-backup).
### 에이전트에게 질문하기
수동으로 필터를 만드는 대신 자연어로 이벤트를 쿼리할 수 있습니다. 다음을 여세요 [Roboflow 에이전트](https://docs.roboflow.com/agents/roboflow-agent) 왼쪽 사이드바에서 "Agent"를 클릭한 다음 사용 사례에 대해 질문하세요(예: "지난주 assembly-line-qa에서 실패가 몇 건 있었나요?", "결함률은 시간이 지나면서 어떻게 변했나요?", "스트림당 평균 항목 수는 얼마인가요?").
사용 사례에서 "AI로 분석"을 클릭할 수도 있습니다. 이 버튼은 개요 및 검색 탭에 표시되며, 해당 사용 사례에 대한 질문이 준비된 상태로 새 탭에서 에이전트를 엽니다. 검색 탭에서는 질문에 적용한 필터도 포함되므로, 에이전트는 보고 있는 것과 같은 이벤트를 확인합니다.
에이전트는 이벤트 데이터를 쿼리하여 답변하므로 숫자는 이벤트에 실제로 포함된 내용을 반영합니다. 에이전트는 다음을 할 수 있습니다:
* 시간 범위, 이벤트 유형 또는 결과와 일치하는 이벤트를 집계합니다.
* 시간에 따른 통과 및 실패율을 추적하고 결함률이 개선되는지 악화되는지 알려줍니다.
* 숫자 필드의 합계, 평균을 구하거나 최소값, 최대값 또는 고유 값의 개수를 찾습니다.
* 이벤트 필드 또는 사용자 지정 메타데이터별로 총합을 그룹화하거나, 일별 또는 주별로 버킷팅합니다.
질문이 워크스페이스의 [보존 기간](/deployment/ko/monitoring-and-analytics/vision-events.md#data-retention)을 넘어가면, 에이전트는 0으로 답변하는 대신 쿼리할 수 있는 가장 이른 날짜를 알려줍니다. 날짜 경계와 시간 버킷은 UTC를 사용합니다.
이벤트에 대해 질문하려면 "View Vision Events" [권한이 필요합니다.](https://docs.roboflow.com/platform/enterprise-features/role-based-access-control).
일회성 답변 대신 정기적으로 이메일로 발송되는 요약본은 다음을 참조하세요 [요약 보고서](/deployment/ko/monitoring-and-analytics/vision-events/summary-reports.md).
## HTTP API
### Vision Events 쿼리
필터, 시간 범위, 페이지네이션을 사용해 Vision 이벤트를 쿼리합니다. 이 엔드포인트는 이벤트 유형, 디바이스 컨텍스트, 감지 클래스, 사용자 지정 메타데이터, 이미지 메타데이터 및 이벤트별 필드로 필터링하는 기능을 지원합니다.
**필수 스코프:** `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-90cd0189aea08d3263ce3e004f4958cc7363d4ed%2Fopenapi.yaml?alt=media)
{% endopenapi %}
{% hint style="info" %}
이 `감지` 필터의 이전 이름은 `detectionClass`. 이전 이름은 더 이상 허용되지 않습니다.
{% endhint %}
결과의 각 비디오는 해당 `sourceId` 및 `레이블`. 하나를 재생하거나 다운로드하려면, [재생 URL을 가져오세요](/deployment/ko/monitoring-and-analytics/vision-events/upload-a-vision-event-video.md#get-a-playback-url) 해당 `sourceId`.
## Python SDK
필터, 시간 범위, 페이지네이션을 사용해 Vision 이벤트를 쿼리합니다.
### 단일 페이지 쿼리
다음을 사용하세요 `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"}
],
)
```
수동 페이지네이션을 사용하려면 `커서` 매개변수에 `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"{len(all_events)}개의 이벤트를 찾았습니다")
```
사용 가능한 필터, 연산자 및 응답 형식에 대한 전체 세부 정보는 다음을 참조하세요 [REST API 참조](#http-api).
## MCP 서버
AI 에이전트를 다음에 연결하세요 [MCP 서버](https://docs.roboflow.com/agents/mcp-server) 그리고 다음 도구를 사용해 이벤트에 대한 질문에 답할 수 있습니다:
.png?alt=media)
.png?alt=media)