> 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 バージョンの比較、デプロイ前の回帰チェックを行えます。

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

## 概要

Eval は、Case の Dataset と、確認内容を定義する Spec を組み合わせたものです。各 Case には、入力とグラウンドトゥルース（期待値またはアノテーション）が含まれます。Check では、予測ボックスがアノテーションとどの程度一致する必要があるかなど、評価器とその設定を選択します。

Run は、これらの Case と Check に対して 1 つ以上の Workflow を評価します。各 Run には、独自の入力、グラウンドトゥルース、Workflow 定義、評価設定が記録されます。Case を編集または削除すると今後の Run に影響しますが、既存の Run の結果は変更されません。

## Web アプリ

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

1. 「Select Workflow」: 使用する Workflow と推論サーバーを選択します。
2. 「Upload Ground Truth」: 「Browse Device」、「Pick from Asset Library」、または「Use a Dataset test set」で画像を追加します。確認する Workflow 出力を選択します。
3. 「Label Ground Truth」: 期待値を入力し、画像にアノテーションを付けます。Label Assist の提案をグラウンドトゥルースに追加する前に確認してください。Assist カードで、提案を生成する AI モデルまたは Workflow を選択します。この Eval またはその Run で使用される任意の Workflow を選択できます。削除された Workflow は「Discarded workflows」の下に表示され、保存済みのコピーから実行されます。デフォルトでは、提案は空のフィールドだけを埋めます。すでに存在するラベルを置き換えるには、「Existing labels」の下にある「Overwrite」をオンにします。Assist カードで「Auto-annotate」をオンにすると、空の Case を開いたときにラベル付けします。提案は下書きとして保存されます。承認するには、引き続き「Add to Ground Truth」をクリックする必要があります。
4. 「Define Eval Checks」: 要件を表す評価器としきい値を選択します。「Add check」をクリックし、出力をグラウンドトゥルースと比較するには「Output check」、Case ごとの時間制限を設定するには「Latency budget」を選択します。出力がグラウンドトゥルースと一致する場合にのみ Case を合格にするには、「Matches ground truth exactly」を選択します。許容誤差など、独自のメトリクスとしきい値を設定するには「Custom rule」を選択します。分類チェックでは、 `top` または `predicted_classes` 出力を、完全一致または F1 によって期待されるクラスと比較します。「Run preview」をクリックすると、Run を開始せずに、承認済みの 1 つの Case で Check をテストできます。
5. 「Run Evaluation」: セットアップとクレジット見積もりを確認してから、Run を開始します。

保存済みのグラウンドトゥルースを確認するには、Eval を開いて「Browse Ground Truth」をクリックします。ギャラリーには各 Case の画像とアノテーションが表示され、「Labeled」または「Needs labels」としてマークされます。Case をクリックすると、全画面エディターでそのグラウンドトゥルースを編集できます。

Run の後は、「Cases」を使用して個々の失敗を調査し、「Metrics」を使用して結果を比較します。Run に 2 つ以上の Workflow がある場合、最初のタブは「Overview」です。各 Workflow の品質をレイテンシまたはクレジットと比較してプロットし、ヒートマップには各 Workflow が各 Case で通過した Check の数が表示されます。「Vector Analysis」は、画像埋め込みを使用して類似した Case をグループ化するため、失敗のクラスターを調査できます。埋め込みの生成は非同期で実行されます。完了を待つか、そのタブから失敗した生成を再試行してください。

### レイテンシ

「Latency Avg」は、記録された所要時間を持つ失敗したリクエストを含む、Case ごとの記録済み平均リクエスト時間です。ネットワーク時間とランナーによって計測された入力準備時間が含まれ、評価のキューイングおよびスコアリングは除外されます。これはすべての Case 所要時間の合計ではなく、モデル推論時間だけを測る指標でもありません。

「Latency budget」Check を含む Run ではすべての Case が再度実行されるため、キャッシュされた結果は再利用されません。古い Run にレイテンシ Check を追加するには、新しい Run を開始してください。Rescore ではレイテンシを測定できません。

### クレジット

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

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

## HTTP API

API を使用して、Evals、Specs、Datasets、Cases、Runs、結果、エクスポート、埋め込みを管理します。名前空間は `https://api.roboflow.com/workspaces/{workspace}/workflow-evals`であり、 `workspace` は Workspace スラッグです。

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

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

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

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

### 評価器を検出する

Check を構築する前に評価器カタログを取得します。インストール済みエンジンの評価器タイプと構成スキーマが返されます。

{% 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 を管理する

Spec を使用して Check を定義し、Dataset に Case を保持し、バインディングで Workflow 出力を Spec にマッピングします。Run を開始する前に、Spec とバインディングを検証してください。一覧レスポンスでは `items` が使用され、結果がさらにある場合は `nextCursor`.

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

再試行する Case が残っている失敗した Run または一部しか完了していない Run はエクスポートできません。現在の状態のままエクスポートするには、 `allowPendingRetries: true` をエクスポートリクエストで送信してください。アクティブな Run はエクスポートできません。

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

## 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
```

次を使用して、 `roboflow workflow-eval --help` リソースおよび Run コマンドを確認してください。このコマンドグループは Workflow を評価するものであり、モデル評価コマンドとは別です。

## MCP

次の [Roboflow MCP Server](https://docs.roboflow.com/agents/mcp-server) をエージェントに接続します。Eval を作成する前に、 `workflow_evals_agent_manifest` と Workflow Evals のガイダンスを読み込むよう依頼してください。ツールは、同じ公開 API を通じて、評価器の検出、Spec の検証、作成、Run、結果をカバーします。

たとえば、次のように依頼します。「これらのテスト画像を使用して、この Workflow 用の Workflow Eval を作成してください。グラウンドトゥルースと Check の定義、セットアップの検証、Run を開始する前のクレジット見積もりの表示を手伝ってください。」