Gradio に組み込まれたワークフロー機能「gr.Workflow」の紹介と活用方法

最も興味深い AI アプリの多くは、パイプライン構造を持っています。画像を生成した後、必要に応じて背景を切り抜いたり、別の要素を組み合わせて新しい画像を作成したりします。スクリプトを書いたら、そのための音声を読み上げさせたり、スクリプトはそのままに声質だけを変更したりもできます。通常、これらのステップは Python でつなぎ合わせますが、どこかおかしくなると、print デバッグに戻ってどの工程で異常な値が生成されたのかを探すことになります。

Gradio に標準搭載されている gr.Workflow は、パイプラインそのものをインターフェースにします。手順を型付きノードのグラフとして記述するだけで、Gradio がドラッグ＆ドロップ可能なキャンバスを提供し、すべてのノードを実行可能にし、中間結果も可視化できます。同じグラフは REST API としても機能し、Hugging Face Spaces へのデプロイもコマンド一つで完了します。

この仕組みを理解する最善の方法は、実際に動作しているワークフローを見ることです。以下に紹介するすべてのアプリは、Huggingface Space 上でライブで開き、実行し、複製できるものです。

画像の編集

画像をアップロードし、「雪景色に変える」「サングラスを追加する」「車を赤くする」などの編集指示を入力すると、編集済みの写真が返ってきます。このアプリ全体は、Hugging Face Inference Providers の Qwen-Image-Edit を呼び出す単一のノードで構成されています。

👉 画像編集パイプラインを試す

実在するモデルをメディアスタジオに連携させる

1 つのグラフで、3 つのパイプラインを動かす。プロンプトを入力して FLUX で画像を生成し、その画像を 背景除去用の Gradio Space に渡してステッカーに変換する。同じトピックは テキスト読み上げ用の Gradio Space を通じて音声ナレーションになり、LLM の呼び出しによってキャッチーなエピソードタイトルにもなる。

これは 1 つのキャンバス上で、Hugging Face の Inference Providers を介したモデル呼び出しが 2 回、Gradio Space への呼び出しが 2 回行われる構成だ。

ワークフローとして、3 つの出力それぞれに独自の REST エンドポイント /sticker、/voiceover、/episode_title が用意されている。UI を開かずにコードから直接これらのエンドポイントを呼び出すことも可能だ。実行可能な例については、以下の Call it from code を参照。

👉 AI Media Studio を試す

並列での画像生成（ファンアウト）

アイデアを 1 つ入力するだけで、一瞬で複数の生成アートワークが完成する。FLUX によるベース画像、その画像を再解釈した AI による 2 バリエーション（柔らかい水彩風とネオンサイバーパンク風）、そして LLM が作成したギャラリータイトルだ。

各画像は、Inference Providers を介したモデルノードがプロンプトから直接生成します。一方、タイトルは LLM を呼び出す fn ノードによって作成されます。これは「ファンアウト（Fan-out）」パターンの典型例です。一つのアイデアを複数の演算ノードに同時に送り込み、並列で生成を行うことができます。

👉 Generative Art Lab を試す

Hugging Face データセットのプロファイル

stanfordnlp/imdb や mteb/tweet_sentiment_extraction といった Hugging Face のデータセット ID を入力すると、単一の入力がファンアウトして 4 つの演算ノードに分配されます。これらは Datasets Server API を活用し、データセットをリアルタイムで分析します。

概要カード、最初の数行のプレビュー、各列の統計情報、そして分布チャートが、すべて独立して並列で計算されます。これがワークフローの真価です！

👉 Data Detective を試す

独自の GPU モデルを実行する

これまでに紹介したすべてのノードは Hugging Face にアクセスしていましたが、fn ノードは単なる Python コードです。つまり、Space 内で GPU を使用してモデルを直接実行することも可能です。

バインドされた関数に @spaces.GPU デコレーターを付与すれば、そのノードが実行される際に ZeroGPU がその呼び出しのために GPU を確保し、モデルを実行した後に解放します。必ずしも Inference Provider や既存の Gradio Space に依存する必要はありません。

Diffusers を経由して Lightricks/LTX-Video モデルを読み込み、1 つのノードだけで動作するデモをご覧ください。静止画をアニメーション化するこのデモでは、gr.Workflow が GPU の設定について知る必要はありません。バインドされた関数を呼び出すだけです。

👉 ZeroGPU アニメーターを試す

仕組みを一言で

すべてのワークフローは、3 つの種類のノードからなるグラフです。参照（入力）、演算子（処理を行うステップ）、そして対象（出力）がそれです。演算子には、独自の Python 関数、Hugging Face Inference Providers のモデル、別の Gradio Space、あるいは Hub データセットの行が含まれます。これらは型付きポート間をドラッグして接続し、「Run」をクリックすると、各結果がその場で表示されます。

コードから呼び出す

構築したワークフローは、追加の手間なしで API としても機能します。各出力はラベル名にちなんだ REST エンドポイントとなり、Gradio クライアントを使って Python から呼び出せます。以下は、トークン不要で動作するマルチエンドポイントデモ Space に対する、そのままのライブ例です。

from gradio_client import Client

client = Client("ysharma/gr-workflow-multi-endpoint-API")

print(client.predict("hello there friend", api_name="/word_count"))  # -> 3
print(client.predict(20, api_name="/fahrenheit"))                    # -> 68.0

モデルや Space を呼び出すエンドポイントは Hugging Face トークンの下で実行されるため、クライアント作成時にトークンを渡してください。

from gradio_client import Client, handle_file

client = Client("ysharma/gr-workflow-image-editor", token="hf_...")

edited = client.predict(
    handle_file("dog.jpg"),
    "turn it into a snowy winter scene",
    api_name="/edited_image",
)

平素 HTTP をお好みですか？すべてのエンドポイントは curl でもアクセス可能です。

curl -s https://ysharma-gr-workflow-multi-endpoint-API.hf.space/gradio_api/call/word_count \
  -H "Content-Type: application/json" -d '{"data": ["hello there friend"]}'

自分だけのワークフローを構築する

最も簡単な方法は、上記のデモを開いてDuplicateをクリックし、配線を書き換えることです。Python から行う場合は、以下の短縮コードで十分です。

import gradio as gr

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

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

完全な手順、オペレータの種類、JSON スキーマ、再利用可能なパターンについては、Gradio ドキュメントの公式 gr.Workflow ガイド をご覧ください。

gr.Workflow を使えば、AUTOMATIC1111 のような複雑なプロジェクトも構築可能です。次回の投稿では、これをステップバイステップで解説する予定です。まずは少しだけお見せしましょう 😉👇