Gradio queue 控制并发请求与超时的配置方式

Gradio 应用出现“请求越积越多”时，先别急着把并发数调大。更稳妥的分层是：max_size 控制等待区能放多少请求，事件级 concurrency_limit 控制同时执行多少个任务，concurrency_id 把多个事件绑到同一个资源额度；真正的模型推理或 HTTP 调用超时，仍要在函数和下游客户端里设置。

官方地址：https://www.gradio.app/

先把队列上限与执行上限分开

我在给一个图片生成事件加队列时，最容易混淆的是“排队多久”和“执行多久”。Gradio 的 Blocks.queue(max_size=...) 只描述队列最多保存多少个等待事件；队列满了，新请求会收到队列已满的反馈。它不负责终止已经进入 Python 函数的任务。

事件真正能同时跑几个，由事件监听器上的 concurrency_limit 决定。默认并发上限可以通过 default_concurrency_limit 设定，但重型推理最好在具体事件上显式写出限制，避免一个全局默认值影响轻任务和 GPU 任务。

用全局默认值和事件级覆盖组织并发

下面的配置把“普通事件默认并发 2”和“图片生成事件最多并发 1”分开。代码里的 max_size=20 只是给突发流量留一个有限等待区；它不表示 20 个推理任务会同时运行。

import gradio as gr

def generate(prompt):
    # 这里放模型推理；生产环境还应在模型客户端设置调用超时
    return f"生成任务：{prompt}"

with gr.Blocks() as demo:
    prompt = gr.Textbox(label="提示词")
    output = gr.Textbox(label="结果")
    button = gr.Button("生成")
    # 重型事件先限制为 1，避免显存竞争；新增请求进入队列等待
    button.click(generate, inputs=prompt, outputs=output, concurrency_limit=1)

# max_size 只限制等待区容量，default_concurrency_limit 是未显式设置事件的默认值
demo.queue(max_size=20, default_concurrency_limit=2)
demo.launch()

如果某个事件调用的是外部 API，可以把它的并发上限提高到服务商允许的范围；如果是共享显存的模型，先用 1 或小整数观察显存和尾延迟，再逐步调整。不要用已经废弃的全局 concurrency_count 代替事件级配置。

用 concurrency_id 保护共享 GPU 或外部配额

两个按钮即使对应不同函数，也可能抢同一张 GPU 或同一个第三方 API 配额。这时分别写 concurrency_limit=2 仍可能让总并发超过资源承受范围。给事件配置相同的 concurrency_id，再用一个更低的并发上限，就能表达“这一组共享额度”。

import gradio as gr

def generate(prompt):
    # 真实项目中，在这里调用模型 SDK，并捕获其超时异常
    return f"生成：{prompt}"

def upscale(image):
    # 放大任务也占用同一资源池，因此加入同一个并发组
    return image

with gr.Blocks() as demo:
    prompt = gr.Textbox()
    image = gr.Image()
    generate_btn = gr.Button("生成")
    upscale_btn = gr.Button("放大")
    # 两个事件共享 gpu_pool；整个资源组最多允许 2 个任务
    generate_btn.click(generate, prompt, image, concurrency_id="gpu_pool", concurrency_limit=2)
    upscale_btn.click(upscale, image, image, concurrency_id="gpu_pool", concurrency_limit=2)

demo.queue(max_size=20)
demo.launch()

需要注意的是，Gradio 的并发限制解决的是“同时有多少个事件在跑”，不是“一个事件最多跑多少秒”。对 HTTP 客户端、模型服务或数据库调用，应使用对应 SDK 的 timeout；捕获超时后返回简短错误提示，并在函数内部释放临时资源。若使用流式事件，文档中的 time_limit 只适用于相应的流式参数，不能把它当作所有事件的统一队列超时。

按资源类型选择配置组合

一个实用判断是：如果请求还在等待区，优先看 max_size 和用户提示；如果已经进入函数但 GPU 被打满，优先看 concurrency_limit 与 concurrency_id；如果函数长时间不返回，去检查下游客户端 timeout 和取消逻辑，而不是继续增加队列容量。

相关问题

把 concurrency_limit 设为 None 就一定更快吗？

不一定。它允许该事件不受并发上限约束，适合轻量或由外部服务自行限流的任务；对显存敏感的推理函数，可能直接带来 OOM 或尾延迟放大。

max_size 设置很大能解决超时吗？

不能。它只让更多请求进入等待区，反而可能增加用户等待时间。真正的执行超时要由函数或被调用的客户端处理。

多个事件如何共享一张 GPU？

给它们设置相同的 concurrency_id，并为这组使用一个经过资源测试的 concurrency_limit。事件内部仍需处理模型调用失败和超时。