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¶
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:
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.
Related¶
- What a vDAG is: Key concepts: vDAG
- Worked example: Quickstart: deploy a vDAG
- Controller internals and APIs: vDAG controller