Gradio 工作流怎么把长任务状态实时显示到界面

Gradio 长任务要让用户看到“正在做什么”，关键不是给函数外面加一个旋转图标，而是让事件函数持续产生可显示的中间状态：生成器用 yield 推送阶段文本，gr.Progress 提供可量化进度，停止按钮再通过 cancels 关联到同一个事件依赖。这样，界面状态和任务控制各自有清晰职责。

能拆成阶段的任务用生成器持续 yield；有总量时用 gr.Progress 更新完成数；停止只能保证 Gradio 不再继续迭代该事件，已经提交给外部队列或进程的工作仍要由业务层提供取消协议。

先用生成器把阶段状态推到界面

如果函数只在最后 return 一次，前端只能看到等待和最终结果。把长任务拆成可观察的小阶段后，函数改成生成器，每完成一段就 yield 当前状态。下面的示例用文本框显示已完成阶段，读者可以直接判断任务卡在哪一步。

import time
import gradio as gr

def run_job(total, progress=gr.Progress()):
    states = []
    total = int(total)
    for index in range(1, total + 1):
        # 这里代表一个可独立确认的处理阶段，真实项目中替换成模型或数据操作。
        time.sleep(0.2)
        states.append(f"阶段 {index}/{total} 已完成")
        progress((index, total), desc=f"处理第 {index} 个阶段")
        # 每次 yield 都会把当前状态发回输出组件，而不是等整个函数结束。
        yield "\n".join(states)

with gr.Blocks() as demo:
    total = gr.Slider(1, 12, value=5, step=1, label="阶段数量")
    output = gr.Textbox(label="工作流状态", lines=8)
    start = gr.Button("开始")
    start.click(
        run_job,
        inputs=total,
        outputs=output,
        show_progress="minimal",
    )

demo.queue().launch()

这里有两个不同的反馈通道。文本框的内容来自函数的 yield，适合“读取文件”“调用模型”“整理结果”这类阶段描述；上方的进度提示来自 progress((index, total))，适合有明确总数的循环。demo.queue() 是生成器事件使用队列传递中间结果的基础配置。

把进度数字和状态文字分成两层

长任务最容易出现的误导是把“函数还没返回”直接写成“正在处理 63%”。先判断任务是否真的有可靠的总量，再选择进度表达方式。

gr.Progress 是函数签名里的默认参数，既可以直接调用，也可以用 progress.tqdm(iterable) 跟踪迭代。要注意：进度条是用户反馈，不是任务一致性证明。即使显示 100%，仍应由生成器最后一次输出或明确完成状态来确认结果已经写入。

把停止按钮接到同一个事件依赖

停止按钮要保存开始事件的返回值，再把它传给 cancels。不要只在 Python 函数里增加一个“停止”文本框，却没有把按钮和正在执行的事件建立关系。

import gradio as gr

def long_job(total, progress=gr.Progress()):
    for index in range(int(total)):
        # 每轮都产生一个可见状态，取消时前端不会再等待下一轮输出。
        progress((index + 1, int(total)), desc="执行中")
        yield f"已完成 {index + 1}/{int(total)}"

with gr.Blocks() as demo:
    total = gr.Number(value=20, precision=0, label="任务数量")
    start = gr.Button("开始")
    stop = gr.Button("停止", variant="stop")
    status = gr.Textbox(label="状态")

    # 保存事件依赖，停止按钮才能准确指向这次长任务。
    job_event = start.click(long_job, total, status, show_progress="minimal")
    stop.click(fn=None, inputs=None, outputs=None, cancels=[job_event], queue=False)

demo.queue().launch()

cancels 对等待中的事件和正在迭代的生成器尤其有用；一个已经进入普通阻塞函数内部的工作不一定会瞬间被强制杀死。若生成器内部调用了外部任务系统，推荐把任务 ID、取消标记和幂等清理放在那个系统里，Gradio 只负责把用户意图传到正确的事件边界。

用三条检查清单避免状态失真

• 先问“状态是否可拆分”：不能拆分的单次阻塞调用只能显示等待提示，不能凭空制造阶段进度。
• 再问“总量是否可信”：批次数量、文件数和明确阶段可以给出比例，未知耗时只展示描述性状态。
• 最后问“停止影响谁”：Gradio 事件、后台线程、消息队列和外部推理服务可能是四个边界，停止按钮不应承诺超出自身边界的结果。

常见问题

为什么函数里 print 了日志，界面还是不动？

标准输出不会自动成为组件输出。需要让事件函数 yield 输出值，或把状态写入专门的组件更新路径。

只有进度条，没有阶段文字可以吗？

可以，但排障体验较差。进度条回答“完成多少”，阶段文字回答“现在在做什么”，长任务最好同时提供。

点击停止后，外部模型调用一定会中断吗？

不一定。cancels 取消的是 Gradio 事件依赖；外部模型、队列消息或子进程需要自己的取消接口和清理策略。

总量未知时怎样显示进度？

用生成器 yield “正在读取”“等待返回”等状态，或只更新已知阶段；不要用估算数字冒充精确完成率。