Skip to content

vDAG creator guide

A vDAG creator combines existing blocks into a workflow, for example detect objects → track them → estimate pose, and publishes it as one service that applications can call.

At a glance

You will: prepare the workflow's policies, describe the graph, create the vDAG, and deploy a controller so it can accept tasks.
You need: the blocks your workflow uses must already be running, or findable through an assignment policy. You also need the Parser and Cluster Controller Gateway URLs.

Your tasks

  1. Prepare the policies
  2. Write the vDAG specification
  3. Create the vDAG
  4. Deploy a vDAG controller
flowchart LR
    A["Policies<br/><small>quota, health, quality,<br/>pre/post, assignment</small>"] --> B["vDAG spec<br/><small>vdag.json</small>"]
    B -->|"Parser: createvDAG"| C["vDAG registered"]
    C -->|"Gateway: create_controller"| D["vDAG controller<br/>accepting tasks"]

1. Prepare the policies

All of these policies are optional. Add the ones you need, and register each with the Policies System before referencing it.

Workflow-level policies (run by the vDAG controller)

Policy What it does How to write it
Quota checker Limits how much the workflow can be used, globally or per session_id. Quota checker policy
Quality checker Periodically samples requests and responses to audit output quality, either itself or by forwarding samples to an external QA system or human review. Quality checker policy
Health checker Periodically checks the health and performance of every block in the workflow. Health checker

Step-level policies (one set per node in the graph)

Policy What it does How to write it
Pre-processing Runs before the node's main computation, for example to validate, enrich or reshape the input. Pre- and post-processing policies
Post-processing Runs after the node's computation, for example to transform or validate the output, or choose which path to take next. Pre- and post-processing policies
Assignment Chooses which running block serves this node, by evaluating candidate blocks that match a filter. Assignment policy

2. Write the vDAG specification

The specification describes the graph: its name and version, its nodes (each pinned to a block or chosen by an assignment policy), the connections between them, and the policies above.

See the vDAG spec for every field. A complete example:

cd services/applications/examples/vdag-pose-estimation
cat vdag.json

3. Create the vDAG

Submit the specification to the network's Parser:

curl -X POST http://$SERVER_URL/api/createvDAG \
  -H "Content-Type: application/json" \
  -d @./vdag.json

The vDAG is now registered under its vDAG URI, for example pose-estimator:v0.0.1-stable, but it cannot accept tasks yet.


4. Deploy a vDAG controller

The controller is the gateway that accepts tasks for your vDAG. Creating a vDAG does not create a controller. You choose when, and on which cluster, to run one, and you can remove it at any time.

Controllers are created through the network's Cluster Controller Gateway, which forwards the request to the chosen cluster:

POST /vdag-controller/<cluster_id>

curl -X POST http://<cluster-controller-gateway-url>/vdag-controller/<cluster-id> \
  -H "Content-Type: application/json" \
  -d '{
    "action": "create_controller",
    "payload": {
      "vdag_controller_id": "<controller-id>",
      "vdag_uri": "<vdag-uri>",
      "config": {
        "policy_execution_mode": "local",
        "replicas": 2
      }
    }
  }'
Parameter Type Description
cluster_id (in the URL) string Cluster on which to run the controller.
action string "create_controller".
vdag_controller_id string A unique ID for the controller.
vdag_uri string The vDAG this controller serves.
config.policy_execution_mode string Where the controller runs its policies: "local" or "remote".
config.replicas integer Number of controller replicas.
curl -X POST http://<cluster-controller-gateway-url>/vdag-controller/<cluster-id> \
  -H "Content-Type: application/json" \
  -d '{
    "action": "remove_controller",
    "payload": {
      "vdag_controller_id": "<controller-id>"
    }
  }'
Parameter Type Description
cluster_id (in the URL) string Cluster where the controller runs.
action string "remove_controller".
vdag_controller_id string The controller to remove.

Other actions, such as scale_controller and list_controllers, are listed in Cluster Controller: vDAG controller actions.

Once the controller is running, applications can send tasks to it. See the Inference user guide.