> 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/workflows/ja/ping-si/workflow-evals.md).

# ワークフロー評価

Webアプリ、HTTP API、Python SDK、CLI、またはMCPを通じて、ラベル付きケースに対してワークフローを評価・比較します。

Workflow Evals は、一連のサンプルを使って Workflow が要件を満たしているかを確認します。失敗の検出、Workflow のバージョン比較、デプロイ前のリグレッション確認に使用できます。

次の [モデル比較チュートリアル](https://docs.roboflow.com/workflows/ja/chtoriaru/compare-models-with-workflow-evals.md) に従って、ボルトの個数を数える Eval を定義し、エージェントを使って候補となる Workflow を構築して比較してください。

## 概要

Eval は、確認項目を定義する Spec と、Case で構成される Dataset を組み合わせたものです。各 Case には入力と正解データ（期待値またはアノテーション）が含まれます。Check では評価器とその設定を選択します。たとえば、予測ボックスがアノテーションとどの程度一致する必要があるかを指定できます。

Run は、1 つ以上の Workflow をこれらの Case と Check に照らして評価します。各 Run には、入力、正解データ、Workflow の定義、評価設定がそれぞれ記録されます。Case を編集または削除しても、今後の Run に影響するだけで、既存の Run の結果は変わりません。正解データが揃っていない Case はスキップされ、スキップした件数が表示されます。

Check には 2 種類あります。「出力チェック」は Workflow の出力を正解データと比較し、「レイテンシ上限」は Case ごとの制限時間を設定します。比率指標（例：適合率、再現率、F1、mAP）のしきい値には 0～1 の小数を使用するため、80% の場合は 0.8 と入力します。分類チェックでは、 `top` または `predicted_classes` の出力を期待されるクラスと比較します。完全一致または F1 で評価できます。キーポイントチェックでは、ラベル付けされた点に対する予測点を COCO AP、AR、および平均 OKS しきい値での F1 によって評価し、すべての Case をまとめて算出します。

正解データは Dataset のテストセットからインポートできます。インポートされるのは元画像に付けられた現在のアノテーションであり、Dataset Version の前処理済み画像や拡張画像のアノテーションではありません。ボックス、分類、セグメンテーションに対応しています。キーポイントの Dataset では画像のみがインポートされます。インポートしたラベルは、確認するまで未承認のままです。

### レイテンシ

「Latency Avg」は、記録された Case ごとのリクエスト時間の平均です。所要時間が記録された失敗リクエストも含まれます。ネットワーク時間と、Runner が計測する入力準備時間を含みますが、評価キューでの待ち時間やスコア算出時間は含みません。すべての Case の所要時間の合計でも、モデルの推論時間だけを表す値でもありません。

「Latency budget」チェックを含む Run では、キャッシュ結果を再利用せず、各 Case をもう一度実行します。既存の Run にレイテンシチェックを追加するには、新しい Run を開始してください。Rescore ではレイテンシを計測できません。

### クレジット

Eval で承認された Workflow の実行は、ローカル実行でも Serverless 実行でも、1 回につき 1/10,000 クレジットを消費します。100 件の Case に対して 3 つの Workflow を評価すると、評価に 3/10,000 クレジットがかかり、これに推論料金が加算されます。

Serverless Workflow の推論と Label Assist には、それぞれ別の料金がかかります。新しい Replay または Rescore を実行すると、課金対象の評価実行が新たに作成されます。同じ作成リクエストを元の冪等性キーで再試行しても、新たな課金は発生しません。埋め込みの生成では評価クレジットを消費しません。正解データのラベル付け中に Smart Select を使用すると、アノテーションエディターと同様に AI Labeling クレジットを消費します。

## Web アプリ

Workspace で「Workflows」を開き、「Evals」を選択して、「Create Eval」をクリックします。次の手順に従います。

1. 「Select Workflow」：Workflow を選択します。ステップのヘッダーにあるサーバーチップをクリックすると、推論サーバーを切り替えられます。
2. 「Upload Ground Truth」：デバイス、Asset Library、または Dataset のテストセットから画像を追加し、チェックする Workflow の出力を選択します。
3. 「Label Ground Truth」：期待値を入力し、画像にアノテーションを付けます。「Assist」カードを使うと、モデルまたは Workflow から提案を取得できます。「Auto-annotate」をオンにすると、Case を開くときにラベルが自動で付けられます。ボックス、マスク、またはキーポイントの出力に該当するオブジェクトが画像にない場合は、その出力の横にある空集合アイコンをクリックして、オブジェクトがないことを示します。「Add N to the Eval and Continue」をクリックすると、ラベル付けした画像をすべて一度に追加できます。ラベル付けせずに残した画像は下書きのままになります。キーポイントにラベルを付けるとき、ステップでは Workflow のキーポイントモデルに保存されたスケルトンを使用します。モデルにスケルトンがない場合は、「Create With AI」または「Create Manually」をクリックして Eval 用に作成します。ポイント名は Workflow のポイント名と一致している必要があります。Label Assist は信頼度が 0.5 未満の点を配置しません。
4. 「Define Eval Checks」：「Add check」をクリックして、しきい値を設定します。「Run preview」をクリックすると、1 つの Case で Check をテストできます。
5. 「Run Evaluation」：設定とクレジットの見積もりを確認し、Run を開始します。

Eval ページには、正解データと Check の横に Run の一覧が表示されます。そこから正解データを開いて編集できます。編集内容は随時保存されます。インポートしたラベルや下書きラベルをそのまま承認するには、「Approve Labels」をクリックします。Case を探すには、「Search saved ground truth」に入力し、正解データ（例：クラス、個数、完全性）または元画像（例：ファイル名、タグ、セマンティック検索）で絞り込みます。

![品質、レイテンシ、失敗した Check の傾向、4 件の Run、正解データの画像、2 件の Check が表示された Eval ページ](https://4077895066-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoO0Ceoy9R0lHDZATcPyh%2Fuploads%2Fgit-blob-c9b38e2d3b29b8a9419e5780fc673efa923b122e%2Fworkflow-evals-eval-page.png?alt=media)

Run を開くと結果を確認できます。Workflow が 2 つ以上ある場合、「Overview」には各 Workflow の品質とレイテンシまたはクレジットの関係がプロットされ、Case ごとに合格した Check のヒートマップも表示されます。「Metrics」では Check ごとに結果を比較でき、「Vector Analysis」では類似する Case がグループ化され、失敗のまとまりを見つけられます。

![6 つの Workflow について、合格した Check の数とレイテンシの関係をプロットし、その下に Case ごとの合格 Check 数のヒートマップを表示した Overview タブ](https://4077895066-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoO0Ceoy9R0lHDZATcPyh%2Fuploads%2Fgit-blob-9a7612903ca0ae3e2043d0bc43c710a0ef9594da%2Fworkflow-evals-results-overview.png?alt=media)

### デプロイゲート

デプロイゲートを設定すると、Eval に合格するまで Workflow のバージョンが本番環境に公開されないようにできます。設定するには、Workflow を開き、「Publish」の横にあるドロップダウンをクリックします。「Publishing Requirements」で「Require an Eval to pass」を選択します。Eval を選び、各 Check の最小合格率（デフォルトは 100%）を設定して、「Save Checks」をクリックします。一覧には、Workflow に適合しているものの、まだ追加されていない使用可能な Eval も表示されます。その Eval を選んで保存すると、Workflow が追加されます。この操作には、Workflow Evals の管理と実行の権限が必要です。

「Run Checks」をクリックすると、最後に保存されたバージョンで Eval が実行されます。すべての Check に合格したら、「Publish」をクリックします。「Auto-Publish」モードでは、保存のたびに Check が実行され、合格するとバージョンが自動で公開されます。

新しいバージョンごとに、そのバージョンで合格した Run が必要です。Eval を編集した場合は、それ以前に合格していたバージョンでも Check を再実行する必要があります。ゲートの設定または解除には、Workflow のデプロイゲートを管理する権限が必要です。

各バージョンについて担当者の承認を必須にするには、「Publishing Requirements」で「Require approval」を選択し、承認できるユーザーまたはロールを選びます。承認者には Workflow を管理する権限が必要です。承認者の誰か 1 人が承認するとバージョンを公開でき、1 人でも却下すると公開がブロックされます。自分が保存したバージョンは承認できません。新しいバージョンごとに個別の承認が必要です。レビューを依頼するには、「Publish」をクリックして「Request Review」を選択します。承認者は「Approve」または「Reject」をクリックします。Workflow に Eval ゲートも設定されている場合、バージョンは両方の条件に合格する必要があります。

## HTTP API

API を使用して、Eval、Spec、Dataset、Case、Run、結果、エクスポート、埋め込みを管理できます。名前空間は `https://api.roboflow.com/workspaces/{workspace}/workflow-evals`です。ここで `workspace` は Workspace のスラッグです。

プライベート Workspace API キーまたは OAuth アクセストークンを `Authorization: Bearer` ヘッダーに指定して認証します。フォルダー制限付きの認証情報には対応していません。OAuth アクセスには、ユーザーの Workspace 権限に加えて、元画像、Dataset、または Workflow を読み取るために必要な権限も適用されます。

Workflow Evals には、相互に独立した 4 つの OAuth スコープがあります。

* `workflow-evals:read`：Eval の読み取り、評価器とスキーマの確認。
* `workflow-evals:write`：評価リソースの作成と編集。
* `workflow-evals:run`：Run を開始および制御します。
* `workflow-evals:export`：結果をエクスポートします。

連携に必要なすべてのスコープをリクエストしてください。1つのスコープで他のスコープが付与されることはありません。アプリケーションの接続方法については、 [OAuth 認証](https://docs.roboflow.com/reference/authentication/authentication/oauth) をご覧ください。

### 評価器を確認する

Checks を作成する前に、評価器カタログを取得してください。インストール済みエンジンの評価器タイプと設定スキーマが返されます。

{% openapi src="/files/bde017722cc783a0a76e203f415001f10d904cfd" path="/workspaces/{workspace}/workflow-evals/evaluators" method="get" %}
[workflow-evals-discovery.openapi.json](https://4077895066-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoO0Ceoy9R0lHDZATcPyh%2Fuploads%2Fgit-blob-2928c95a7448a440bb1fffe80e25051dc965410d%2Fworkflow-evals-discovery.openapi.json?alt=media)
{% endopenapi %}

### API コントラクトを確認する

Workspace の OpenAPI ドキュメントを取得すると、すべての操作、リクエストスキーマ、必須スコープ、ヘッダーを確認できます。出力タイプや評価器の設定を推測せず、評価器カタログと併用してください。

{% openapi src="/files/bde017722cc783a0a76e203f415001f10d904cfd" path="/workspaces/{workspace}/workflow-evals/openapi.json" method="get" %}
[workflow-evals-discovery.openapi.json](https://4077895066-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoO0Ceoy9R0lHDZATcPyh%2Fuploads%2Fgit-blob-2928c95a7448a440bb1fffe80e25051dc965410d%2Fworkflow-evals-discovery.openapi.json?alt=media)
{% endopenapi %}

### リソースと Run を管理する

Specs で Checks を定義し、Datasets に Cases を格納し、バインディングで Workflow の出力を Spec にマッピングします。Run を開始する前に、Spec とバインディングを検証してください。リストのレスポンスには `items` が使われ、結果がさらにある場合は、 `nextCursor`.

が使われます。操作で `Idempotency-Key`が必要な場合は、UUID v4 を送信し、同じリクエストを再試行するときは同じキーを使用してください。操作で `If-Match`が必要な場合は、別の編集による上書きを防ぐため、リソースの現在のリビジョンを送信してください。Run、インポート、エクスポートは非同期です。完了するまでステータスをポーリングし、Run をキャンセルするには専用のキャンセル操作を使用してください。

Dataset の Cases を検索するには、 `POST /workspaces/{workspace}/workflow-evals/eval-datasets/{evalDatasetId}/search`を送信します。ソース画像のフィルターとセマンティック検索には、 `image:read` スコープも必要です。空のページが返された後も、 `nextCursor` がなくなるまで送信し続けてください。

再試行対象の Cases が残っている失敗済みまたは一部完了の Run はエクスポートできません。その時点の状態でエクスポートするには、エクスポートリクエストに `allowPendingRetries: true` を指定してください。実行中の Run はエクスポートできません。

{% hint style="info" %}
クラウドバックエンドは、コンピューターの `localhost`に接続できません。ローカル Run では、クライアントランナーが Workflow を実行し、その出力をスコアリング用に送信します。API で Run を作成しても、ローカルサーバーがクラウドからアクセス可能になるわけではありません。
{% endhint %}

### Eval を削除する

削除は2段階で行います。まず影響をプレビューし、次に返された `deletionKey`を使って確定します。Eval がデプロイゲートを設定している場合、 `impact.deployGates` に影響を受ける Workflows が一覧表示されます。確定すると、それらのゲートが削除され、保留中のデプロイチェックがキャンセルされます。ゲートが設定された Eval の削除には、 `workflow:update` と、Workflow のデプロイゲートを管理する権限も必要です。ゲートが設定されていない Eval には、これらの追加権限は必要ありません。返された削除操作を、完了するまでポーリングしてください。

## Python SDK

Workflow Evals には、 [Roboflow Python SDK](https://docs.roboflow.com/reference/platform/python-sdk)のバージョン 1.7.0 以降が必要です。インストールまたは更新するには、次のコマンドを実行します。

```bash
pip install --upgrade roboflow
```

Workspace の Workflow Evals クライアントを使って、評価器を確認し、Eval の一覧を取得します。

```python
import os

from roboflow import Roboflow

rf = Roboflow(api_key=os.environ["ROBOFLOW_API_KEY"])
evals = rf.workspace("your-workspace").workflow_evals()

catalog = evals.list_evaluators()
page = evals.list(limit=20)

for evaluation in page["items"]:
    print(evaluation["id"], evaluation["name"])
```

同じクライアントでは、 `create`, `start_run`, `get_run`, `wait_for_run`、および `openapi`を利用できます。Run を開始する前に、 `openapi()` と `list_evaluators()`.

## CLI

「 [Roboflow CLI](https://docs.roboflow.com/reference/platform/cli/install-and-set-up-the-cli) には、 `workflow-eval` コマンドグループが含まれています。プライベート API キーで認証し、Workspace を指定します。

```bash
export ROBOFLOW_API_KEY="your-private-api-key"
roboflow --workspace your-workspace --json workflow-eval list
roboflow --workspace your-workspace --json workflow-eval evaluator list
roboflow --workspace your-workspace --json workflow-eval run list --eval your-eval-id
```

リソースと Run のコマンドを確認するには、 `roboflow workflow-eval --help` を使用します。このコマンドグループは Workflows を評価するもので、モデル評価コマンドとは別です。

## MCP

エージェントを [Roboflow MCP Server](https://docs.roboflow.com/agents/mcp-server) に接続します。Eval を作成する前に、 `workflow_evals_agent_manifest` と Workflow Evals のガイダンスを読み込むよう指示してください。ツールでは、同じ公開 API を通じて、評価器の検索、Spec の検証と作成、Runs、および結果の確認ができます。 `workflow_evals_datasets_search` を使うと、正解データまたはソース画像のフィルターで Cases を検索できます。ソース画像検索とセマンティック検索には、 `image:read`.

も必要です。たとえば、次のように依頼します。「これらのテスト画像を使って、この Workflow の Workflow Eval を作成してください。正解データと Checks の定義、設定の検証を手伝い、Run を開始する前にクレジットの見積もりを提示してください。」
