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

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

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

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 関数を二つの入口から呼んでいます。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 の二本でした。

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

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

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

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'] の二つでした。

対話画面は専用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 で同時に開始します。47 今回のAとBはどちらも入力文字列だけに依存するため、同じ段に置かれました。

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

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

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

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

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

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

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

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