내부 워크플로우

내부 워크플로우 블록을 사용해 하나의 워크플로우 정의를 다른 워크플로우 안에 넣는 방법과 컴파일러가 이를 인라인하는 방식.

이 내부 워크플로 블록 (roboflow_core/inner_workflow@v1)를 사용하면 하나의 워크플로 정의를 다른 워크플로 안에 포함할 수 있습니다. 컴파일 시점에 엔진은 저장된 워크플로 참조를 모두 해석하고, 구성 (중첩 제한과 순환)을 검증하고, 매개변수 바인딩을 검증한 뒤 인라인으로 펼칩니다 . 자식의 단계들은 부모 안으로 들어갑니다. 컴파일 후에는 별도의 “중첩 실행”이 존재하지 않으며, 그래프는 마치 해당 단계들을 부모 수준에서 직접 작성한 것과 같습니다.

이 페이지에서는 이 블록, 컴파일 시점 파이프라인, 제한 사항, 그리고 최소한의 Python 예제를 설명합니다. 일반적인 컴파일 단계는 다음을 참조하세요. 워크플로 정의의 컴파일.

이 기능은 Execution Engine에 구현되어 있습니다 v1. 내부 워크플로 블록의 run() 메서드는 런타임에 사용되지 않으며, 해당 단계는 컴파일 중에 제거됩니다.

내부 워크플로 블록

각 내부 워크플로 단계는 부모의 steps 목록에 있는 JSON 객체이며, type: "roboflow_core/inner_workflow@v1".

자식 정의를 제공하는 방법

다음 중 하나를 제공해야 합니다 either:

• workflow_definition: 전체 중첩 워크플로 JSON 객체(루트 워크플로와 동일한 형태: version, inputs, steps, outputs), 또는

• workflow_workspace_id 및 workflow_id, 그리고 선택적으로 workflow_version_id를 포함하여, 컴파일 시점에 저장된 워크플로 사양을 불러옵니다.

반드시 하지 말아야 합니다 같은 단계에 인라인 workflow_definition 과 참조 필드를 동시에 설정하는 것.

parameter_bindings

parameter_bindings 는 객체이며, 그 키 는 이름 이며, 자식 워크플로의 항목이 있는 inputs 배열에 해당합니다. 각 값 은 선택자 (또는 엔진이 변환할 수 있는 값)이며 부모 범위에서 가져오고, 일반적으로 다음과 같습니다:

• $inputs.<parent_input_name> 부모 워크플로 입력의 경우, 또는

• $steps.<parent_step_name>.<output_property> 이전 부모 단계에서 생성된 데이터의 경우.

규칙:

• 부모의 값이 필요한 모든 자식 입력은 필요할 때 반드시 parameter_bindings, 에 나타나야 하며, 예외는 유형의 입력 WorkflowParameter / InferenceParameter 이며, 자식 정의에서 null이 아닌 default_value 를 선언한 경우입니다. 이런 항목은 생략할 수 있으며, 정의가 인라인될 때 자식의 기본값이 적용됩니다.

• 자식 입력 이름이 아닌 키는 컴파일 시점에 거부됩니다.

• 자식 단계는 다음을 통해 부모 데이터를 소비해야 합니다 $inputs.<child_input_name> 중첩 정의에서; 컴파일러는 인라인 중에 해당 참조를 바인딩된 부모 선택자(또는 주입된 기본값)로 바꿉니다.

부모에서 자식 출력 참조하기

중첩 워크플로의 outputs 배열은 JsonField 항목을 정의하며 name 및 선택자 를 가진 name . 컴파일 후 부모는 내부 단계를 해당 JsonField

값으로 이름 붙은 출력이 있는 논리적 블록처럼 다룹니다.

$steps.<inner_step_name>.<child_output_name>

여기서 <child_output_name> 은 name 자식의 outputs JsonField의 필드 이름이며, 반드시 마지막 단계의 이름일 필요는 없습니다.

컴파일 시점 파이프라인 (Execution Engine v1)

이 compile_workflow_graph 가 실행되면, 내부 워크플로는 다음 과정을 거칩니다. 이전 에 메인 “워크플로 정의 파싱” 단계가 실행되기 전에:

1. 참조 해석(정규화) 다음 workflow_workspace_id / workflow_id 을 사용하는 모든 단계(그리고 선택적 workflow_version_id도 포함)는 인라인 workflow_definition으로 해석됩니다. 이는 중첩 정의 내부에서도 재귀적으로 일어납니다.

   • 기본 해석기는 Roboflow API와 workflows_core.api_key 를 워크플로 초기화 매개변수에서 사용합니다(단, 작업 공간이 "local" 이거나 사용자 지정 해석기를 제공한 경우는 예외).

   • 초기화 매개변수로 다음을 재정의하세요 workflows_core.inner_workflow_spec_resolver: 콜러블 (workspace_id, workflow_id, workflow_version_id, init_parameters) -> dict 자식 워크플로 JSON을 반환합니다.

2. 구성 검증 엔진은 구성 그래프를 만듭니다: 부모 워크플로의 핑거프린트에서 자식 정의의 핑거프린트로 가는 inner_workflow 단계마다 하나의 간선을 둡니다. 그런 다음 다음을 확인합니다:

   • 그래프가 비순환적이며 (A → B → … → A 없음),

   • 중첩 깊이 가 루트로부터 WORKFLOWS_MAX_INNER_WORKFLOW_DEPTH,

   • 이하인지, 전체 개수 의 내부 워크플로 단계(간선)가 WORKFLOWS_MAX_INNER_WORKFLOW_COUNT. 다음을 참조하세요 제한 사항 및 환경 변수 아래를.

3. 인라인 펼치기 각 inner_workflow 단계는 일반 단계로 확장됩니다: 자식 단계 이름은 {inner_step_name}__{child_step_name} 가 되며(이름 충돌 처리 포함), 선택자는 다시 작성되고($inputs / $steps 은 자식에서, 그리고 부모 참조는 $steps.<inner_step_name>…로 바뀝니다), 그다음 내부 단계가 제거됩니다. 나머지 컴파일(파싱, 워크플로 사양 검증, 실행 그래프 구성, 단계 초기화)은 평면 워크플로만 보게 됩니다.

4. 파싱 및 검증 평면화된 JSON은 블록 매니페스트와 함께 파싱되고, validate_workflow_specification 이 실행되며, 실행 그래프는 다른 워크플로와 동일하게 구성됩니다.

예제 (Python)

다음 패턴은 이 저장소의 examples/workflows/inner_workflows/main.py 예제와 일치합니다: id로 저장된 워크플로를 해석하고, 부모 이미지를 자식이 기대하는 입력 이름에 바인딩한 다음, 하위 부모 단계에서 자식 출력을 사용합니다.

import json
import os

from inference.core.managers.base import ModelManager
from inference.core.registries.roboflow import RoboflowModelRegistry
from inference.core.workflows.core_steps.common.entities import StepExecutionMode
from inference.core.workflows.execution_engine.core import ExecutionEngine
from inference.models.utils import ROBOFLOW_MODEL_TYPES

WORKFLOW_DEFINITION = {
    "version": "1.0",
    "inputs": [
        {"type": "WorkflowImage", "name": "image"},
    ],
    "steps": [
        {
            "type": "roboflow_core/inner_workflow@v1",
            "name": "inner",
            "workflow_workspace_id": "your-workspace",
            "workflow_id": "your-workflow-id",
            "workflow_version_id": "optional-version-id",
            "parameter_bindings": {
                "image": "$inputs.image",
            },
        },
        {
            "type": "roboflow_core/roboflow_classification_model@v2",
            "name": "classification",
            "images": "$steps.inner.dynamic_crop_output",
            "model_id": "resnet50",
        },
    ],
    "outputs": [
        {
            "type": "JsonField",
            "name": "predictions",
            "selector": "$steps.classification.predictions",
        },
    ],
}

if __name__ == "__main__":
    model_registry = RoboflowModelRegistry(ROBOFLOW_MODEL_TYPES)
    model_manager = ModelManager(model_registry=model_registry)

    execution_engine = ExecutionEngine.init(
        workflow_definition=WORKFLOW_DEFINITION,
        init_parameters={
            "workflows_core.model_manager": model_manager,
            "workflows_core.api_key": os.getenv("ROBOFLOW_API_KEY"),
            "workflows_core.step_execution_mode": StepExecutionMode.LOCAL,
        },
    )

    result = execution_engine.run(
        runtime_parameters={
            "image": {
                "type": "file",
                "value": "/path/to/your/image.jpg",
            },
        },
    )

    print(json.dumps(result, indent=2, default=str))

워크스페이스, 워크플로, 버전, 모델, 출력 선택자, 이미지 경로를 저장된 워크플로와 부모 그래프에 맞는 값으로 바꾸세요. 핵심 요구 사항은 parameter_bindings 키가 자식 워크플로의 inputs[].name 필드와 일치해야 한다는 점입니다.

제한 사항 및 환경 변수

변수	기본값	의미
WORKFLOWS_MAX_INNER_WORKFLOW_DEPTH	4	최대 깊이 루트 워크플로로부터의 구성 그래프 깊이: 각 직접 inner_workflow 자식은 경로상 하나의 수준으로 계산됩니다.
WORKFLOWS_MAX_INNER_WORKFLOW_COUNT	32	최대 수 의 inner_workflow 전체 중첩 정의에 걸친 단계 수(각 내부 단계는 구성 그래프의 하나의 간선입니다).

순환: 구성 그래프는 DAG여야 합니다. 각 워크플로의 단계별 실행 그래프가 비순환적이더라도, 중첩 참조의 순환(예: 워크플로 A가 B를 포함하고 B가 A를 포함하는 경우)은 허용되지 않습니다.

위반 시 컴파일 시점 오류가 발생합니다(InnerWorkflowNestingDepthError, InnerWorkflowTotalCountError, InnerWorkflowCompositionCycleError 등)이며, 메시지에는 깊이, 개수 또는 순환 관련 사항이 설명됩니다.

관련 자료

• 워크플로 정의 - JSON 형식, 입력, 단계, 출력

• 컴파일러 - 전체 컴파일 단계

• 워크플로 실행 - 컴파일 후 런타임 동작