> 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/ja/to/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>" %}

### 主要な概念

#### ユースケース

ユースケースは、 **ユースケース** 共通の目的とカスタムメタデータ構造を持つイベントをグループ化します。同じユースケースのイベントでは通常、類似したメタデータフィールドが送信されるため、一貫した方法でフィルタリングやクエリを実行できます。

たとえば、「欠陥検出」ユースケースには、常に `line_id`, `shift`、および `part_number` が含まれる場合があります。イベントが複数の工場やカメラの設置場所から送られる場合も同様です。メタデータ構造が根本的に異なる場合（例：「PPEコンプライアンス」では `zone` と `alert_type` を追跡する場合など）は、別々のユースケースを作成してください。

### このセクションの内容

* [イベントを送信する](https://docs.roboflow.com/deployment/ja/to/vision-events/send-events.md) - ワークフローブロック、REST API、またはエッジデバイスのバックアップからイベントを送信します。
* [イベントをクエリする](https://docs.roboflow.com/deployment/ja/to/vision-events/query-events.md) - ダッシュボードでイベントをフィルタリングする、エージェントに自然言語で質問する、またはAPI経由でクエリを実行します。
* [トレーニング用の画像を追加する](https://docs.roboflow.com/deployment/ja/to/vision-events/add-images-for-training.md) - キャプチャしたイベント画像をプロジェクトに移し、モデルのトレーニングに使用します。
* [自動化](https://docs.roboflow.com/deployment/ja/to/vision-events/automations.md) - 条件に一致するイベントの画像をプロジェクトに送信したり、手動操作なしでアラートメールを送信したりできます。
* [イベント未受信アラート](https://docs.roboflow.com/deployment/ja/to/vision-events/no-events-alerts.md) - カメラ、ストリーム、またはワークフローからのイベント送信が停止したときに、メールで通知を受け取ります。
* [オペレーターのフィードバック](https://docs.roboflow.com/deployment/ja/to/vision-events/operator-feedback.md) - チームメンバーがイベントを「正しい」「誤り」「判定不能」としてマークできるようにします。
* [サマリーレポート](https://docs.roboflow.com/deployment/ja/to/vision-events/summary-reports.md) - 見出しとなる数値とレポート全体へのリンクを含む、ユースケースの定期サマリーをチームにメールで送信します。
* [イベントを削除する](https://docs.roboflow.com/deployment/ja/to/vision-events/delete-events.md) - ユースケースから不要になったイベントを削除します。

## HTTP API

Vision Events API を使用すると、コンピュータービジョンのデプロイから構造化イベントを記録し、クエリや分析を行えます。イベントには、画像、動画クリップ、検出アノテーション、カスタムメタデータ、品質チェック、在庫数、安全アラートなどの種類固有のデータを含めることができます。

Vision Events API では、次の操作を行えます。

* [Vision Event 画像をアップロードする](https://docs.roboflow.com/deployment/ja/to/vision-events/upload-a-vision-event-image.md#http-api)
* [Vision Event 動画をアップロードする](https://docs.roboflow.com/deployment/ja/to/vision-events/upload-a-vision-event-video.md#http-api)
* [Vision Event を作成する](https://docs.roboflow.com/deployment/ja/to/vision-events/create-a-vision-event.md#http-api)
* [Vision Event を一括作成する](https://docs.roboflow.com/deployment/ja/to/vision-events/batch-create-vision-events.md#http-api)
* [Vision Event バンドルをアップロードする](https://docs.roboflow.com/deployment/ja/to/vision-events/upload-a-vision-event-bundle.md#http-api)
* [Vision Event をクエリする](https://docs.roboflow.com/deployment/ja/to/vision-events/query-events.md#http-api)
* [ユースケースを一覧表示する](https://docs.roboflow.com/deployment/ja/to/vision-events/use-cases.md#http-api)
* [カスタムメタデータのスキーマを取得する](https://docs.roboflow.com/deployment/ja/to/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 はユースケースに関連付けられています。ユースケースの作成と管理方法については、 [ユースケースのドキュメント](https://docs.roboflow.com/deployment/ja/to/vision-events/use-cases.md).

また、API 経由でイベントが記録された既存のユースケースを [一覧表示](https://docs.roboflow.com/deployment/ja/to/vision-events/use-cases.md#http-api) することもできます。

### イベントの種類

この API は、5 種類のイベントをサポートしています。それぞれに独自の `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()`](https://docs.roboflow.com/deployment/ja/to/vision-events/upload-a-vision-event-image.md#python-sdk)       | イベントで使用する画像をアップロード                  |
| [`write_vision_event()`](https://docs.roboflow.com/deployment/ja/to/vision-events/create-a-vision-event.md#python-sdk)                    | 単一のビジョンイベントを作成                      |
| [`write_vision_events_batch()`](https://docs.roboflow.com/deployment/ja/to/vision-events/batch-create-vision-events.md#python-sdk)        | 1回のリクエストで最大100件のイベントを作成             |
| [`query_vision_events()`](https://docs.roboflow.com/deployment/ja/to/vision-events/query-events.md#python-sdk)                            | フィルターとページネーションを使ってイベントをクエリ          |
| [`query_all_vision_events()`](https://docs.roboflow.com/deployment/ja/to/vision-events/query-events.md#paginate-through-all-results)      | 一致するすべてのイベントを対象に、ページネーションを自動処理してクエリ |
| [`list_vision_event_use_cases()`](https://docs.roboflow.com/deployment/ja/to/vision-events/use-cases.md#python-sdk)                       | ワークスペース内のユースケースを一覧表示                |
| [`create_vision_event_use_case()`](https://docs.roboflow.com/deployment/ja/to/vision-events/use-cases.md#create-a-use-case)               | 新しいユースケースを作成                        |
| [`rename_vision_event_use_case()`](https://docs.roboflow.com/deployment/ja/to/vision-events/use-cases.md#rename-a-use-case)               | ユースケースの名前を変更                        |
| [`archive_vision_event_use_case()`](https://docs.roboflow.com/deployment/ja/to/vision-events/use-cases.md#archive-a-use-case)             | ユースケースをアーカイブする                      |
| [`unarchive_vision_event_use_case()`](https://docs.roboflow.com/deployment/ja/to/vision-events/use-cases.md#unarchive-a-use-case)         | ユースケースのアーカイブを解除する                   |
| [`get_vision_event_metadata_schema()`](https://docs.roboflow.com/deployment/ja/to/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>
