Gradio gr.Workflow: Visual AI Pipeline Orchestration

Hugging Face has introduced gr.Workflow, a new feature integrated into Gradio that transforms AI pipelines from hidden Python scripts into visual, interactive interfaces. By representing a pipeline as a graph of typed nodes, gr.Workflow allows developers to see intermediate results in real-time and deploy the entire graph as both a user interface and a set of REST API endpoints.

Visual Pipeline Orchestration with gr.Workflow

gr.Workflow treats the AI pipeline as the interface itself. Instead of relying on print-debugging to track data flow through multiple Python steps, developers can describe their pipeline as a graph where every node is runnable and every intermediate result is visible on a drag-and-drop canvas.

Core Architecture

A workflow consists of three primary node types:

  • References: These serve as the inputs for the workflow.
  • Operators: These are the functional steps that perform the work. An operator can be a custom Python function, a model hosted via Hugging Face Inference Providers, another Gradio Space, or a row from a Hub dataset.
  • Subjects: These serve as the outputs of the workflow.

These nodes are connected via typed ports, ensuring data consistency as it moves through the graph.

Key Capabilities and Patterns

gr.Workflow supports several complex AI orchestration patterns, including parallel execution and hybrid infrastructure deployment.

Parallel Execution (Fan-out)

The "fan-out" pattern allows a single input to feed multiple operator nodes simultaneously. For example, a single prompt can trigger multiple parallel processes: generating a base image via FLUX, creating two different stylistic re-imaginings of that image, and generating a gallery title using an LLM, all occurring in parallel.

Hybrid Infrastructure

Workflows can mix and match different compute sources within a single graph:

  • Inference Providers: Nodes can call external models via Hugging Face Inference Providers.
  • External Spaces: Nodes can call other existing Gradio Spaces.
  • Local GPU Execution: By decorating a bound function with @spaces.GPU, developers can run models directly within a Space using ZeroGPU, which dynamically allocates and releases GPU resources for that specific call.

Automatic API Generation

Every gr.Workflow is automatically converted into an API. Each output (subject) in the graph is assigned a REST endpoint named after its label, allowing the pipeline to be triggered via code without using the UI.

Programmatic Access

Developers can interact with these endpoints using the gradio_client Python library or plain HTTP requests via curl. For example, a workflow with a /word_count endpoint can be called as follows:

from gradio_client import Client

client = Client("ysharma/gr-workflow-multi-endpoint-API")
print(client.predict("hello there friend", api_name="/word_count"))

Implementation and Deployment

Deploying a workflow is designed to be a one-command process to Hugging Face Spaces. The simplest implementation in Python requires only a few lines of code:

import gradio as gr

def your_function(text: str) -> str:
  pass

gr.Workflow(bind=[your_function]).launch()

Sources

Related