# AI処理を画面とAPIへ再利用する Gradio Workflowで分岐の待ち時間を測る

- 媒体: 知能圏（CHINOUKEN）
- 公開日: 2026-08-29
- カテゴリー: エージェント・ソフトウェア
- タグ: Gradio、ワークフロー、REST API、実験
- 想定読了時間: 約24分
- 調査基準日: 2026年8月29日
- 出典: 12件（末尾の「参照リンク」に番号順で記載）
- ページ: https://www.chinouken.com/articles/gradio-workflow-api-boundary
- このMarkdown: https://www.chinouken.com/articles/gradio-workflow-api-boundary.md
- 利用条件: 引用する場合は出典として「知能圏（chinouken.com）」と該当ページのURLを明記してください。本文の再配布は行わず、要約や引用の範囲で使ってください。

GradioはPython関数やAIモデルをブラウザから試せるWeb画面にするオープンソースライブラリです。最小のInterfaceを画面とAPIから実行し、複数工程をノードでつなぐWorkflowが必要になった背景を整理しました。二つの2秒関数では、画面は約2.01秒で並列、同じ図の生成APIは約4.04秒で逐次完了しました。

![同じ二つの2秒処理を対話画面は並列で約2.01秒 生成APIは逐次で約4.04秒かけて実行する比較](https://www.chinouken.com/images/articles/gradio-workflow-api-boundary/hero.png)

*二つの関数を各2秒待たせた実験です。同じ処理図でも、対話画面は並列、生成APIは逐次になりました。*

## GradioはPython関数をWeb画面へ変える

通常のPython関数は、ターミナルや別のPythonコードから呼びます。ほかの人に触ってもらうには、HTMLで入力欄を作り、JavaScriptで送信し、サーバーで受け取り、結果を画面へ戻す処理が必要です。Gradioは、この試作段階の配線をPython側の少ない記述で引き受けます。[1][2]

最小形は `gr.Interface` です。処理する関数、入力部品、出力部品を指定し、`launch()` を呼ぶとローカルのWebサーバーが立ち上がります。

```py
import gradio as gr

def inspect_text(text: str) -> dict:
    return {
        "文字数": len(text),
        "空白区切りの語数": len(text.split()),
        "大文字変換": text.upper(),
    }

demo = gr.Interface(
    fn=inspect_text,
    inputs=gr.Textbox(label="入力する文章"),
    outputs=gr.JSON(label="Python関数の戻り値"),
)
demo.launch()
```

Gradio 6.26.0でこのコードを起動し、専用Chromeプロファイルから文章を入力しました。`Gradio turns a Python function into a web screen.` に対して、文字数49、空白区切り9語、大文字へ変換した文章が右側へ表示されました。

画面の下にはAPIの案内も出ます。同じ処理へGradioクライアントから `hello from the API` を送ると、文字数18、4語、`HELLO FROM THE API` が返りました。画面用の処理とAPI用の処理を別々に書いたわけではありません。同じ `inspect_text` 関数を二つの入口から呼んでいます。

![文章を入力して実行するとPython関数が文字数 語数 大文字変換をJSONで返すGradio Interfaceのローカル画面](https://www.chinouken.com/images/articles/gradio-workflow-api-boundary/figure-basic-interface.png)

*Gradio 6.26.0で作った最小画面です。同じPython関数をブラウザとAPIから実行しました。*

## Web画面にすることで何が変わるのか

Gradioが特に役立つのは、関数の利用者がPythonコードを書かないときです。研究者が画像をドラッグしてモデルを試す、担当者が録音を入れて文字起こしを確認する、開発中の分類器をチームへ見せる、といった場面で入力と結果を共有しやすくなります。

Gradioが担当する範囲は、主に次の部分です。

| Gradioが用意するもの | 例 |
|---|---|
| 入力部品 | 文章、画像、音声、数値、ファイル |
| 出力部品 | 文章、表、JSON、画像、音声 |
| 実行 | ボタンや入力変更からPython関数を呼ぶ |
| API | 別プログラムから同じ処理を呼ぶ入口 |

ただし、`launch()` しただけで業務用システムが完成するわけではありません。認証、保存先、監査、同時利用、費用、障害対応、公開範囲は別に設計します。Gradioは、モデルや関数を人とプログラムの両方から触れる形へする層です。

Gradioには段階の違う作り方があります。

| 作り方 | 向くもの | 画面の作り方 |
|---|---|---|
| `Interface` | 一つの関数をすぐ試す | 入力と出力を指定する |
| `Blocks` | 独自レイアウトやイベントがあるアプリ | Pythonコードで部品を配置する |
| `Workflow` | 複数処理の依存関係を見てつなぐ | ノードを画面上で配線する |

今回の最小画面は `Interface`、枝分かれ実験は `Workflow` です。どちらもGradioですが、Workflowは通常画面の別名ではありません。

## 複数のAI処理はコードだけでは追いにくい

画像を受け取り、説明文を作り、商品タグも作る。音声を文字にし、その文章を要約し、感情も分類する。実際のAI機能は、一つのモデル呼び出しより複数工程の組み合わせへ広がります。

Pythonコードでも順番は書ける。しかし、工程が増えると「どの値がどこへ入ったか」「二つの枝は同時に動くのか」「途中でどの処理が失敗したか」を、ログや `print` で確かめる時間が膨らみます。企画担当やデザイナーにとっても、関数呼び出しの入れ子だけで全体像を共有するのは困難です。

Gradio Workflowが出てきた背景はここです。処理の依存関係そのものを画面に置き、途中の値をノードへ表示し、完成した図からAPIも作る。公式ガイドは、AIパイプラインをコードの裏側に隠すのではなく、操作するインターフェースにする考え方を示しています。[4][5]

## Workflowは処理図そのものを動かす

Workflowの画面は、方眼状のキャンバスへ箱と線を置くノードエディターです。下部から文章、画像、音声、Python関数などを追加し、丸い端子をドラッグして接続します。Runを押すと、各ノードに入力、結果、所要時間が表示されます。

筆者が作った画面では、左の文章 `hello` を二つの関数 `slow_a` と `slow_b` へ分けました。二つとも2秒待ち、右側へ `A:hello` と `B:hello` を表示します。画面上でも両方の関数に `2.0s` と出ました。完成図だけでなく、どこで時間を使ったかが同じキャンバスに残るのが、通常の `Interface` との大きな違いです。

図には三つの役割があります。

| 役割 | 画面での意味 | 例 |
|---|---|---|
| Reference | 外から入る値 | 文章、画像、数値 |
| Operator | 値を処理するもの | Python関数、モデル、Space |
| Subject | 最後に取り出す値 | 要約、分類、変換結果 |

線の入口と出口は `text`、`number`、`image` などの型を持ちます。[4] 文字列を数値専用の入口へつなぐような配線ミスは見つけやすくなります。ただし、摂氏と華氏はどちらも数値です。型の一致と値の意味は別問題です。

Workflowを保存すると、ノードと線は `workflow.json` に残ります。対話画面はこの図を読み、途中結果を各ノードへ表示。同じ図から、Gradioの標準APIで呼べる入口も生成されます。[4] 画面用とAPI用に処理を二重実装しなくてよい点が魅力です。

なお、2026年8月29日時点で `gr.Workflow` はベータ機能です。公式文書もAPIや使い勝手が変わり得ると注意しています。[4] 保存JSON、Gradioの版、API情報を一緒に固定して試す必要があります。

![一つのText入力からslow_aとslow_bの二つの2秒関数へ分岐しA helloとB helloを表示したGradio Workflowの実行画面](https://www.chinouken.com/images/articles/gradio-workflow-api-boundary/figure-workflow-canvas.png)

*実際に作ったWorkflowです。一つの文章を二つの2秒関数へ分け、途中時間と両方の結果を画面で確認しました。*

## APIは出力の数ではなく接続単位で生まれる

WorkflowのAPI名は、通常の `Interface` で `api_name` を付ける場合と規則が違います。固定した公開例の `app.py` では、関数を次のように `bind` へ渡していました。[6]

```py
demo = gr.Workflow(
    graph_path,
    bind={
        "word_count": word_count,
        "to_fahrenheit": to_fahrenheit,
    },
)
```

関数に `api_name` は付いていません。Workflowでは、互いにつながった一つの処理群が一つのAPIになります。名前は、その処理群で最初のSubject、つまり出力ノードのラベルから作られます。[4]

- つながっていない処理群が二つなら、APIも二つ
- 一つの処理群に出力が二つなら、APIは一つで戻り値が二つ

この規則は、画面の見た目より「線でつながった一群」という単位で考えると分かりやすくなります。

## 公開例の二本を実際に呼んだ

Hugging Faceの公開例をコミット `8ca30ab5` へ固定しました。[6] 一方は文章を単語数へ変え、もう一方は摂氏を華氏へ変えます。二つの枝はつながっていないため、APIは `/word_count` と `/fahrenheit` の二本でした。

| API | 入力 | 出力 |
|---|---|---:|
| `/word_count` | `hello there friend` | `3` |
| `/fahrenheit` | `20` | `68.0` |

どちらも2026年8月29日に公開状態で応答しました。最初の呼び出しは単語数が16.107秒、温度変換が1.751秒、続く呼び出しはおおむね0.64〜0.71秒でした。これは共有Spaceの起動、通信、混雑を含む単発観測です。関数自体の性能としては使いません。ここで確認したのは、固定した二つの処理群が、期待した名前と値で呼べることです。

公開例はGradio 6.22.0を使っていました。筆者の分岐実験は6.26.0です。[6][9] 同じ日に見た公開画面だからといって、同じ版で動いているとは限りません。

## 二つの2秒関数で実行順を見た

待ち時間の差を通信速度から切り離すため、ローカルへ小さなWorkflowを作りました。入力文字列を二方向へ分け、どちらの関数も2秒待ってから結果を返します。

```py
def slow_a(text: str) -> str:
    time.sleep(2)
    return f"A:{text}"

def slow_b(text: str) -> str:
    time.sleep(2)
    return f"B:{text}"
```

各関数の開始と終了では `time.perf_counter()` を記録しました。図は一つの入力から二つへ枝分かれし、二つの出力へつながっています。全体が一つにつながっているため、生成されたAPIは `/slow_a_result` の一本です。戻り値は `['A:api-test', 'B:api-test']` の二つでした。

| 経路 | AとBの開始差 | 両方が終わるまで | 実行 |
|---|---:|---:|---|
| 対話画面 | 約0.00005秒 | 約2.01秒 | 並列 |
| 生成API | A終了後にB開始 | 約4.04秒 | 逐次 |

対話画面は専用Chromeプロファイルで `ui-test` を入力し、Runを押して `A:ui-test` と `B:ui-test` が出るところまで確認しました。APIはローカルのGradioクライアントから `api-test` を送り、二つの戻り値を確認しています。どちらも同じ保存グラフと同じPython関数です。

画面撮影時にも `hello` で再実行しました。AとBの開始差は約0.00013秒、全体は約2.004秒でした。これは再現確認であり、統計的な性能測定ではありません。4秒と2秒も、Gradio全体の性能値ではなく、差を見えやすくするため関数内で意図的に2秒待った結果です。

## なぜ同じ図で時間が変わるのか

対話画面側の実行器は、依存関係の同じ深さにあるノードを集め、`Promise.all` で同時に開始します。[4][7] 今回のAとBはどちらも入力文字列だけに依存するため、同じ段に置かれました。

生成API側も、まずノードを依存順に並べます。ただし固定したPython実装は、その順番を `for` でたどり、各処理を待ってから次へ進みます。[4][8] そのため、出力が正しくても待ち時間が足し算になりました。

仮に、独立した三つのモデル呼び出しが各10秒なら、画面は最長の約10秒へ、同じ逐次実行のAPIは合計の約30秒へ近づきます。これは説明用の計算で、今回測った値ではありません。実際にはGPUの同時実行、外部APIの上限、キュー、通信時間も影響します。

重要なのは、「並列に見える図」だから常に並列ではないことです。図は依存関係を表しますが、その依存関係をどの順番で実行するかは実行器が決めます。

## 画面で試せることとAPIの契約を分ける

Workflowの画面は、配線を変え、途中値を見て、試作を直す場所として便利です。しかし運用側が必要とするのは、固定されたAPIの契約です。

| 保存するもの | 理由 |
|---|---|
| `workflow.json` | ノード、型、接続を固定する |
| Gradioの版 | ベータ機能の変化を追える |
| `client.view_api()` の結果 | API名、入力、戻り値を固定する |
| 代表入力と期待出力 | 値の回帰を検査する |
| UIとAPIの所要時間 | 実行順の変化を検査する |
| 認証と公開範囲 | 誰が呼べるかを固定する |

公式文書では、ローカル起動時に編集用の非公開URLと実行用URLが分かれ、Spacesでは `hf_oauth` を使って所有者の編集権限を扱います。[4] ただし、編集できる人を絞ることと、生成APIを誰が呼べるかは同じ確認ではありません。顧客データや社内文書を扱うなら、API情報を取得し、認証なしの要求が本当に拒否されるかまで試します。[12]

## 最初は小さな二分岐で確かめる

導入時は、いきなり大きなAIエージェントを図にする必要はありません。筆者なら、今回のような二分岐から始めます。

| 試すこと | 観測すること |
|---|---|
| 型の違う入力をつなぐ | 保存前に止まるか |
| 2秒待つ二関数を枝分かれさせる | 画面とAPIの時間 |
| 出力を二つ置く | API一本から二つ返るか |
| 枝を切り離す | APIが二本になるか |
| 認証なし、誤入力、関数失敗を送る | 応答と公開範囲 |

この小さな試験で、型、APIの単位、実行順、公開範囲という四つの境界をまとめて確認できます。その後で、実際のモデルを一つずつ置き換えれば、遅くなった原因も追いやすくなります。

Gradioは、Python関数を人が触るWeb画面へ変える道具です。Workflowは、その対象を一つの関数から複数工程の処理図へ広げます。一枚の図を画面とAPIへ再利用できるのは確かに便利ですが、再利用されるのは依存関係と処理であって、すべての実行規則ではありません。最小の画面を一度作り、次に小さな分岐を置き、最後に実際に使う入口から時計を取る。この順番で触ると、GradioそのものとWorkflow固有の特徴を混同せずに判断できます。

## 参照リンク

1. [Gradio: Gradio Docs](https://gradio.app/docs)
2. [Gradio: Interface](https://gradio.app/main/docs/gradio/interface)
3. [Gradio: Gradio GitHub repository](https://github.com/gradio-app/gradio)
4. [Hugging Face: Building AI Workflows with Gradio](https://huggingface.co/blog/gradio-workflow-guide)
5. [Gradio: Workflows](https://gradio.app/guides/workflows)
6. [Hugging Face Spaces: gr-workflow-multi-endpoint-API at 8ca30ab](https://huggingface.co/spaces/ysharma/gr-workflow-multi-endpoint-API/tree/8ca30ab50021c0f581c7dfa8fd20abe6871def11)
7. [Gradio: workflow-executor.ts at 44f8712](https://github.com/gradio-app/gradio/blob/44f8712bfc11d53b714c9fc9b44cd7486a407777/js/workflowcanvas/workflow/workflow-executor.ts)
8. [Gradio: workflow_api.py at 44f8712](https://github.com/gradio-app/gradio/blob/44f8712bfc11d53b714c9fc9b44cd7486a407777/gradio/workflow_api.py)
9. [MDN Web Docs: REST](https://developer.mozilla.org/ja/docs/Glossary/REST)
10. [PyPI: Gradio 6.26.0](https://pypi.org/project/gradio/6.26.0/)
11. [Microsoft Learn: RAGチャットボットを構築する](https://learn.microsoft.com/ja-jp/azure/cosmos-db/gen-ai/rag-chatbot)
12. [AWS Japan: ML@Loft #15 イベントレポート](https://aws.amazon.com/jp/blogs/startup/event-report-ml-at-loft-15/)

2026年8月29日時点の公式資料を確認しています。仕様は更新される可能性があります。

---

© 知能圏 https://www.chinouken.com/articles/gradio-workflow-api-boundary