Gradioのgr.Workflow(グラディオワークフロー)の使い方　AI処理の途中結果を見ながらつなぐ方法

Gradio Workflowの使い方で押さえたいのは、AI処理をつなぐことより、各工程の途中結果を確認できることです。
最後の答えだけが違っていると、入力、前処理、モデル出力のどこでずれたかを切り分けにくいからです。

本稿では、MacとPython 3.10以上を使い、入力文の整形と文字数カウントをつなぐ最小例から始めます。
外部AIモデルなしで配線と保存を確認し、その後にモデルやSpaceと置き換える順番なら、原因を追いやすくなります。

Gradio Workflowとは?途中結果を見られる仕組み

2026年8月27日確認時点で、Gradio Workflowは、入力、処理、出力を画面上のノードでつなぐビジュアルなパイプラインビルダーです。
Hugging Faceのモデル、Space、データセットに加え、自作のPython関数も処理ノードにできます。

価値は、一連の処理と同じ画面で、各ノードを個別に実行できることです。
例えば「入力文の整形は正しいが、次の要約で固有名詞が落ちた」というように、修正すべき工程を絞り込めます。

出典: Gradio公式Workflowsガイド(英語)

入力・処理・出力の3要素

gr.Blocksとの違い

`gr.Workflow`は`gr.Blocks`の中に追加する部品ではなく、それ自体がトップレベルのGradioアプリです。
Blocksがボタンや入力欄などのUIをPython側で構成するのに対し、Workflowはキャンバスで処理のつながりを編集します。

Gradio WorkflowをMacで動かす準備

準備は、専用フォルダとPython仮想環境を作り、Gradioを導入するだけです。
仮想環境は、この試作に必要なパッケージを他のPython作業と分ける専用の箱だと考えるとわかりやすいでしょう。

PythonとGradioを用意する

2026年8月27日のPyPI公式表示では、現行パッケージはPython 3.10以上が必要です。
ターミナルで次の順番のまま実行します。

mkdir gradio-workflow-demo
cd gradio-workflow-demo
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade gradio

出典: PyPI公式Gradioプロジェクトページ(英語)

• `python –version`の表示が3.10以上か確認する
• ターミナルの先頭に`.venv`が出ているか確認する
• 作業フォルダ以外に機密データを置かない

AI開発ツールを含めて環境を整理したい方は、AIコーディングツールの選び方もあわせて確認してください。
ここでは補助ツールを増やすより、Gradio単体で再現できる状態を先に作ります。

2つの関数を登録する

`app.py`を作り、入力文の余分な空白を整える`normalize`と、文字数を返す`count_chars`を登録します。
モデル呼び出しを含まないため、まず配線の学習に集中できます。

import gradio as gr

def normalize(text: str) -> str:
    return " ".join(text.strip().split())

def count_chars(text: str) -> int:
    return len(text)

demo = gr.Workflow(
    bind={
        "Normalize": normalize,
        "Count Characters": count_chars,
    }
)

demo.launch()

保存後に`python app.py`を実行し、ターミナルに表示されたURLを開きます。write-access URLは編集権限の入り口になるため、チャットや公開資料に貼らないでください。

Gradio Workflowの使い方、2つの処理をつなぐ

配線は「テキスト入力→文字整形→文字数カウント→数値出力」の4ノードで作ります。
一度に完成させるのではなく、接続するたびに出力型と途中結果を見るのがコツです。

キャンバスでノードを配線する

1. referenceからtext入力をキャンバスへ追加する
2. Functionsから`Normalize`と`Count Characters`を配置する
3. text referenceの出力を`Normalize`の入力へつなぐ
4. `Normalize`の出力を`Count Characters`の入力へつなぐ
5. number subjectを追加し、`Count Characters`の出力をつなぐ

型注釈がある単純なPython関数では、Gradio Workflowが入出力の種類を推定します。
ただし、画像や複数出力など複雑なポートはJSONで明示する場合があるため、最初はtextとnumberの組み合わせが安全です。

各ノードの途中結果を確認する

入力欄に「　会議　メモ　」のように余分な空白を含む文字を入れ、まず`Normalize`だけを実行します。
途中結果が「会議 メモ」になっていれば、前処理は正常です。

次に`Count Characters`を実行し、整形後の文字が入力に渡っているかを見ます。
この順番を守れば、最終数値が予想と違うときも、配線、文字整形、カウントのどこから調べるかがはっきりします。

こうした小さなAI処理を社内ツールへ育てる考え方は、社内向けAIツールの作り方でも解説しています。
一度に全業務を載せるのではなく、必要な処理と確認ポイントを小さく閉じるのが基本です。

出典: Hugging Face公式ブログ「Wire It, Run It, Deploy It: AI Workflows in Gradio」(英語)

Gradio Workflowをworkflow.jsonに保存して直す

キャンバスの変更は、既定で`app.py`と同じ場所の`workflow.json`へ保存されます。
そのため、ブラウザを閉じても次回の起動で配線を再利用できます。

保存ファイルとbindの関係

`bind=`は関数をWorkflowから呼べるようにし、`workflow.json`は実際のノードとエッジの状態を保持します。
関数を`bind=`に追加しただけでは、既存キャンバスへノードは自動追加されません。

edgesを変えても配線が変わらないとき

公式ガイドでは、`edges=`で新規ワークフローの関数間をコード定義できます。ただし、既存のworkflowファイルがあると`edges=`は無視されるため、コードだけを変えても配線は更新されません。

配線が変わらないときの確認順序

確認	状態	対応
bind	関数登録	名前を揃える
JSON	既存グラフ	先に退避
edges	新規時のみ	削除後に再生成

Gradio WorkflowをREST APIから呼び出す

接続済みの各パイプラインは、Gradio REST APIのエンドポイントとして再利用できます。
キャンバスで確認した処理を、別のPythonプログラムや社内画面から呼ぶ段階へ進められます。

エンドポイントを確認する

`gradio_client.Client`でアプリへ接続し、`client.view_api()`を実行すると、利用できるエンドポイント名と引数を確認できます。
画面のラベルだけで推測せず、実際のAPI仕様を先に表示すると、引数順の間違いを減らせます。

並列実行と順次実行を混同しない

画面で並列に見えるからといって、APIの応答時間も同じだと見積もらないでください。実務では、本番と同じ呼び出し方で処理時間と失敗時の戻り値を測り、タイムアウトを決めます。

Spacesで共有するときの権限

Spacesへ配置するときは、実行できる人とキャンバスを編集できる人を分けます。
所有者を識別して編集を許可するには、SpaceのREADMEに`hf_oauth: true`を設定します。

出典: Hugging Face公式Spaces OAuthドキュメント(英語)

write-access URLは編集者だけに渡す

ローカル起動時には、通常の実行URLとは別にwrite-access URLが表示されます。
このURLを知る人の編集が、他の利用者が使うワークフローに影響するため、画面共有時もアドレスバーを隠す必要があります。

トークンと機密データを分けて考える

• Hugging Faceトークンをコードやworkflow.jsonに直書きしない
• モデルやSpaceが必要とする最小権限だけを渡す
• 個人情報と社外秘を外部モデルへ送る前に保存と二次利用を確認する
• 退職や役割変更時に編集権限を失効させる担当を決める

共有・運用まで自社で抱えるかを迷う場合は、AI開発の内製と外注の判断軸も参考になります。
コード量だけではなく、認証、監視、データ取扱いを継続運用できるかで判断してください。

社内で試すときの判断軸

Gradio Workflowが向くのは、複数処理のつながりと途中出力を共有したい検証です。
一方、止まらない本番処理、厳格な承認、詳細な監査ログまでWorkflow単体に任せる判断は適しません。

最初の小さな検証

最初の検証では、入力1つ、処理2つ、出力1つの範囲に限定します。
各処理に「この出力なら正常」という確認条件を書き、配線図と一緒に共有すると、技術と業務の認識を揃えられます。

Gradio Workflowの使い方とは、AI処理をノードでつなぎ、途中結果を見ながら修正箇所を絞る方法です。
グラフが見えることと、安全に本番運用できることを分け、小さく検証してください。

部門横断の導入方針まで整理するなら、社内AI導入を進めるときの設計ポイントも続けてお読みください。
同記事では、個別デモの成功を、権限・運用・評価のルールへつなげる視点を扱っており、デモの成功だけで全社展開を決めないことも大切です。

よくある質問