Workflow定義の構文

Workflow定義のJSON構文: バージョンマーカー、入力、ステップ、セレクター、出力。

Roboflow Workflowsでは、Workflow Definition が内部の「プログラミング言語」です。これは、さまざまなブロックがどのように相互作用するかを定義するための構造化された方法を提供し、必要な入力、出力、設定を指定します。この構文を使うことで、ユーザーはUIなしでワークフローを作成できます。

まずは、作成された Workflow Definition を見てみましょう このチュートリアル そして、それを段階的に分析します。

ワークフロー定義

{
  "version": "1.0",
  "inputs": [
    {
      "type": "WorkflowImage",
      "name": "image"
    },
    {
      "type": "WorkflowParameter",
      "name": "model",
      "default_value": "rfdetr-small"
    }
  ],
  "steps": [
    {
      "type": "roboflow_core/roboflow_object_detection_model@v1",
      "name": "model",
      "images": "$inputs.image",
      "model_id": "$inputs.model"
    },
    {
      "type": "roboflow_core/dynamic_crop@v1",
      "name": "dynamic_crop",
      "images": "$inputs.image",
      "predictions": "$steps.model.predictions"
    },
    {
      "type": "roboflow_core/roboflow_classification_model@v1",
      "name": "model_1",
      "images": "$steps.dynamic_crop.crops",
      "model_id": "dog-breed-xpaq6/1"
    },
    {
      "type": "roboflow_core/detections_classes_replacement@v1",
      "name": "detections_classes_replacement",
      "object_detection_predictions": "$steps.model.predictions",
      "classification_predictions": "$steps.model_1.predictions"
    },
    {
      "type": "roboflow_core/bounding_box_visualization@v1",
      "name": "bounding_box_visualization",
      "predictions": "$steps.detections_classes_replacement.predictions",
      "image": "$inputs.image"
    },
    {
      "type": "roboflow_core/label_visualization@v1",
      "name": "label_visualization",
      "predictions": "$steps.detections_classes_replacement.predictions",
      "image": "$steps.bounding_box_visualization.image"
    }
  ],
  "outputs": [
    {
      "type": "JsonField",
      "name": "detections",
      "coordinates_system": "own",
      "selector": "$steps.detections_classes_replacement.predictions"
    },
    {
      "type": "JsonField",
      "name": "visualisation",
      "coordinates_system": "own",
      "selector": "$steps.label_visualization.image"
    }
  ]
}

バージョンマーカー

すべての Workflow Definition は、Workflows Execution Engine の互換バージョンを指定する version パラメータから始まります。Roboflow は セマンティック バージョニング を使ってこれらのバージョンを管理し、後方互換性を確保するために各メジャーリリースごとに1つのバージョンを維持しています。これは、Execution Engine のバージョン 1.0.0 向けに定義されたワークフローはバージョン 1.3.4 およびその他の新しいバージョンでは動作しますが、より新しいバージョン向けに作成されたワークフローは、古いバージョンと互換性がない場合があります。

Roboflow Hosted プラットフォームに読み込まれている Execution Engine のバージョン一覧は、 GET /workflows/execution_engine/versions または任意の Inference サーバー上で確認できます。

入力

この例のワークフローでは、2つの入力を指定しています：

[
    {
      "type": "WorkflowImage", "name": "image"
    },
    {
      "type": "WorkflowParameter", "name": "model", "default_value": "rfdetr-small"
    }
]

この定義エントリは、ワークフロー実行中にデータを入れられる2つのプレースホルダーを作成します。

1つ目のプレースホルダーの名前は image で、型は WorkflowImageです。この特別な入力型はバッチ指向であり、実行時に1つ以上の画像を受け取り、1つのバッチとして処理できます。型 WorkflowImageの入力を複数追加でき、これらのプレースホルダーに与えるデータは同じ数の要素を含むことが想定されています。あるいは、サイズが N と1の入力を混在させることもできます。ここで N はバッチ内の要素数を表します。

2つ目のプレースホルダーは、単純な WorkflowParameter model と呼ばれるものです。このタイプの入力では、モデルのバリアント、信頼度しきい値、参照値などのハイパーパラメータを実行時に注入できます。値が要素のバッチであることは想定されていないため、リストを与えると、それはバッチではなく要素のリストとして解釈され、各要素は個別に処理されます。

ワークフローにおけるバッチ指向データ処理の性質についての詳細は こちら.

汎用バッチ指向入力

Execution Engine v1.3.0 （inference リリース v0.27.0）以降、Workflows は任意の 種類 と 次元数のバッチ指向入力をサポートします。これらの入力は 現時点では強制されていませんが、エコシステムが成長するにつれて、ますます有用になると考えています。

汎用バッチ指向入力の定義

もし WorkflowImage 入力を汎用バッチ指向入力に置き換えたい場合は、次の構成を使用します：

{
  "inputs": [
    {
      "type": "WorkflowBatchInput",
      "name": "image",
      "kind": ["image"]
    }
  ]
}

さらに、画像がより高い 次元レベルにある場合は、 次元数 プロパティを追加します：

{
  "inputs": [
    {
      "type": "WorkflowBatchInput",
      "name": "image",
      "kind": ["image"],
      "dimensionality": 2
    }
  ]
}

これにより、 image ワークフロー実行時のデータの想定形式が dimensionality=2 強制します image で、画像のネストされたバッチ、つまり画像のリストのリストになります。

ステップ

前述のとおり こちら、ステップは、他のステップの入力と出力で接続された Workflow ブロックのインスタンスであり、ワークフロー内でデータがどのように流れるかを決定します。例として、ステップ定義を見てみましょう：

{
  "type": "roboflow_core/roboflow_object_detection_model@v1",
  "name": "model",
  "images": "$inputs.image",
  "model_id": "$inputs.model"
}

各ステップに共通する2つのプロパティは type と nameです。Type はどのブロックを読み込むかを示し、name はステップの一意の識別子を与えます。これに基づいて、他のステップはそのステップの出力を参照できます。

残りの2つのプロパティは セレクタ （Workflows では参照をこう呼びます）を入力に対して宣言します - image と model。ワークフローの実行中、それらのプレースホルダーに渡されたデータがブロックに提供され、処理されます。

当社のドキュメントでは、各ブロックの構造を紹介し、各ブロックをワークフローステップとしてどう使えるかの例を示しています。ブロックのコレクションを確認して こちら ブロックのデータ入力、出力、設定プロパティが何かを見つけてください。

ブロックの入力データバインディング（たとえば images プロパティ）は、バッチ指向入力やステップ出力へのセレクタで埋めることができます。ブロックの設定プロパティ（たとえば model_id）は通常、ワークフロー定義にハードコードされた値（実行時に変更できません）または入力型 WorkflowParameterへのセレクタで埋めることができます。たとえば、 model_id が次のいずれかであるとき、 "$inputs.image" または rfdetr-small.

では、ステップ出力が別のステップの入力としてどのように参照されるかを見てみましょう：

{
  "type": "roboflow_core/dynamic_crop@v1",
  "name": "dynamic_crop",
  "images": "$inputs.image",
  "predictions": "$steps.model.predictions"
}

この場合、 predictions プロパティは、という名前のステップの出力を定義します model。セレクタの構成は次のとおりです： $steps.{step_name}.{step_output_name}。この参照のおかげで、 model ステップは dynamic_crop と接続され、実行時にはモデルの予測が dynamic crop に渡され、画像切り抜き処理の参照になります。

出力

Workflow Definition のこのセクションでは、ワークフロー実行からの応答がどのような形になるかを指定します。各応答フィールドの定義は次のようになります：

{
  "type": "JsonField",
  "name": "detections",
  "selector": "$steps.detections_classes_replacement.predictions"
}

この セレクター は、入力またはステップ出力のいずれかを参照できます。さらに、 "coordinates_system" プロパティを指定でき、これは2つの値を受け付けます： "own" または "parent"。このプロパティは、モデルの検出結果を返す出力に関連し、検出に使用される座標系を決定します。これは、主要モデルの予測から派生した画像クロップに対して二次的な物体検出モデルを適用する際に非常に重要です。そのような場合、二次モデルの予測は元の入力画像ではなく、クロップの座標に基づきます。これらの座標が親の座標系へ戻されないようにするには、 "coordinates_system": "own" (親 を設定します（デフォルトのオプションです）。

さらに、出力セレクタはワイルドカード（$steps.step_nane.*"）をサポートしており、特定のステップのすべての出力を取得できます。

出力構造がどのように作成されるかを完全に理解するには、 Workflows におけるデータ処理について読んでください.