为五种 LoRA 任务定制 Gradio 演示界面：huggingface-lora-space-builder 任务基线 UI 模式实战指南

本指南基于 huggingface-lora-space-builder Skill 中的 tasks.md 文档，系统讲解为 LoRA 在 Hugging Face Spaces 上构建 Gradio 演示时，如何针对文本到图像（T2I）、图像到图像（I2I）、文本到视频（T2V）、图像到视频（I2V）、视频到视频（V2V）五种任务类型设计基线 UI。读完本文，你将掌握每个任务的标准输入/输出骨架、共用的交互约定（种子可复现、Advanced 折叠面板、进度上报等）、三阶组件选择阶梯，以及 Gradio 6.x 时代最容易踩的版本陷阱，并能结合 adapting-to-the-lora.md 把基线进一步塑造成真正贴合某个具体 LoRA 的界面。

一、为什么需要"任务级基线 UI"

当拿到一个 LoRA、确认了它的任务类型之后，第一步不是打开代码编辑器凭空发挥，而是先套用一个该任务类别的基线 UI 骨架。tasks.md 文档的核心观点是：基线只负责给出"这类任务的标准输入是什么、标准输出是什么、交互上有什么通用约定"，它是一个起点骨架，几乎从不是最终答案。

这一点在 Skill 的整体工作流中处于第三阶段（Phase 3）。完整的流程在 SKILL.md 中有定义：先收集 LoRA 信息（Phase 1），再选定基础流水线（Phase 2），然后进入 UI 设计（Phase 3）——此时先读 tasks.md 拿到任务基线，再读 adapting-to-the-lora.md 针对具体 LoRA 做定制。基线的价值在于避免从零开始、也避免把不同任务的界面做成千篇一律的模板。

二、所有任务共用的 UI 骨架

无论哪种任务类型，tasks.md 都规定了以下六条通用交互约定，它们是 LoRA 演示的基本盘：

1. 双列等高布局

界面采用两列布局，左侧放输入、右侧放输出：

with gr.Row(equal_height=True):
    with gr.Column():
        # 输入组件
        pass
    with gr.Column():
        # 输出组件
        pass

equal_height=True 保证两列高度一致，视觉上对齐。

2. 唯一的主操作按钮

只保留一个主按钮 gr.Button("Generate", variant="primary", size="lg")。文档明确要求不要添加无意义的次要按钮——除非某个按钮确实做着语义上不同的事（比如"清除"或"随机示例"），否则一律不加。

3. Advanced 折叠面板

把大多数用户永远不会碰的"高级参数"收进折叠面板：

with gr.Accordion("Advanced", open=False):
    seed = gr.Slider(0, 2**32 - 1, value=0, label="Seed")
    randomize_seed = gr.Checkbox(value=True, label="Randomize seed")

对应 Skill 的总体原则："只暴露这个 LoRA 真正需要的 1～3 个控制项"，多余滑杆是成本而非功能（见 SKILL.md 的 "What to avoid"）。

4. 种子控制与可复现性

永远提供种子控件 + "Randomize seed" 复选框，并且把实际使用的种子随结果一起返回给用户，让他们能复现。这是从 SKILL.md 的 app.py 编写规范中反复强调的要求（"Return the actually-used seed alongside the result so the user can reproduce"）。

5. Enter 键提交

对文本输入框，除了按钮点击事件，还要把 prompt.submit 也接到推理函数上，这样用户按 Enter 就能触发生成：

prompt.submit(fn=generate, inputs=[prompt, seed], outputs=[output])
generate_btn.click(fn=generate, inputs=[prompt, seed], outputs=[output])

6. 进度上报

推理函数上挂 gr.Progress(track_tqdm=True)，让 diffusers 内部的 tqdm 进度条透传到 Gradio 界面：

def generate(prompt, seed, progress=gr.Progress(track_tqdm=True)):
    ...

这六条约定适用于五种任务的全部 LoRA 演示，任何偏离都需要理由。

三、Text-to-image（T2I）基线

输入：

• gr.Textbox，lines=2，带示例占位符（通常直接取 LoRA 模型卡中的示例提示词）。
• 宽高比或分辨率控制。
• 可选：负向提示词 negative prompt（仅当模型确实受益时才加，见 qwen-image.md 的提醒："Don't expose a negative prompt in the UI unless the LoRA's behavior actually benefits from it"）。

输出： gr.Image；如果一次返回多张，则用 gr.Gallery。

标准高级控制： seed、randomize seed、num_inference_steps、guidance_scale。

少步 LoRA 的特殊处理： 对于 Lightning、Turbo、schnell 这类 4～8 步蒸馏 LoRA，把步数和 guidance 滑杆整体隐藏——在该参数区间模型是"配方锁定"的，步数几乎没有调节空间，CFG 往往也是 1.0。这类 LoRA 的界面应该直接锁定推荐值而不是暴露出来，这一判断与 adapting-to-the-lora.md 中"Few-step inference (≤ 8 steps)"的信号完全一致。

宽高比处理：

• 提供常见比例的下来框，宽高由比例自动推导。
• 尺寸对齐到模型的原生 bucket 尺寸：大部分扩散 Transformer 是 16 的倍数，老式 UNet 是 8 的倍数。
• 宽高以只读方式展示给用户。

Qwen-Image 家族的参考实现给出了具体 helper（见 qwen-image.md）：

def round_to_bucket(w, h, multiple=16):
    return (w // multiple) * multiple, (h // multiple) * multiple

LTX 视频家族的帧数对齐同理，num_frames 需要按 8k+1 取整（见下文 T2V 小节与 ltx.md）。

示例区： 把 LoRA 模型卡里的示例提示词提取到 gr.Examples 块中。配置时必须使用：

gr.Examples(
    examples=[...],
    fn=generate,
    inputs=[prompt, ...],
    cache_examples=True,
    cache_mode="lazy",
)

cache_examples=True, cache_mode="lazy" 是 ZeroGPU 上的硬性要求：普通 cache_examples=True 会在构建期执行示例函数，而构建期没有 GPU 分配，必然失败；lazy 模式把缓存推迟到用户第一次点击示例时，此时 GPU 已就绪。相关约束的完整说明见 zerogpu-and-publishing.md。

四、Image-to-image（I2I）基线

输入：

• 输入图像：gr.Image(type="pil")（如果你的预处理想要 numpy 数组也可用 numpy 类型）。
• 指令或提示词 gr.Textbox。

输出： gr.Image。对于编辑类 LoRA，优先考虑用内置的 gr.ImageSlider 做"编辑前/后"对比，而不是额外摆一张图。

分辨率处理： 对指令编辑流水线（Qwen-Image-Edit、Flux Kontext、Flux.2 Klein 这类），把输入图缩放到模型 bucket 尺寸的最近倍数，保持宽高比、不要裁剪，除非 LoRA 明确期望特定宽高比。

校验： 输入为空时抛出 gr.Error("Please upload an image first.")。更进一步的方案是：图像未加载时禁用 Generate 按钮，input_image.change 事件里再把它打开：

run_button = gr.Button("Generate", variant="primary", size="lg")
run_button.interactive = False

def enable_btn():
    return gr.update(interactive=True)

input_image.change(fn=enable_btn, outputs=[run_button])

在 ZeroGPU 上校验还要注意：在 @spaces.GPU 函数内部抛 gr.Error 会消耗一次 GPU 配额（zerogpu-and-publishing.md 明确要求"Validate inputs at the top of the GPU function"，甚至可以把校验挪到未装饰的普通函数里先做）。

子任务变体是这里的重点： relighting（打光重绘）、face swap（换脸）、object move（物体移动）、style transfer（风格迁移）、instruction edits（指令编辑）、inpainting（局部重绘）全都归在 "I2I" 下，但 UI 截然不同。tasks.md 特别强调：必须去读 adapting-to-the-lora.md，那里有完整的推理案例——比如 relighting LoRA 需要"用户用彩色笔刷画光源位置 + 光照风格下拉框"，而一个风格化 I2I LoRA 可能只需要输入图和一条指令。

五、Text-to-video（T2V）基线

输入：

• 提示词。
• 时长滑杆（典型 1～10 秒，视模型上限而定）。
• 分辨率/宽高比选择器。

输出：

gr.Video(autoplay=True, format="mp4")

帧率显式指定：24 是安全默认值，部分模型偏好 16 或 30。LTX 家族尤其提醒"帧率不匹配会产生画面异常"——如果 LoRA 按 24fps 训练而演示传 30，运动看起来就是错的（ltx.md）。

标准高级控制： seed、randomize seed、fps。蒸馏类视频模型的步数通常锁定。

时长感知： @spaces.GPU(duration=...) 必须设置得舒适地超过预期生成时间。文档给出量级参考：5 秒 720p 视频，180+ 秒 GPU 时间是现实的。UI 里要明确告知用户生成耗时（例如文案 "Generating a 5s video takes about 2 minutes"）。LTX 参考文件给出了更细的时长表（ltx.md）：短 T2V（3 秒、24fps、蒸馏）60～90 秒；标准 T2V（5 秒、50 步）120～180 秒；LTX-2.3 两阶段流水线 240～360 秒。

帧数数学： 大多数视频扩散模型期望 num_frames 满足 8k+1 这类约束。正确的做法是：

def num_frames_for_duration(seconds, fps=24, base=8):
    raw = seconds * fps
    return ((int(raw) - 1) // base) * base + 1

用 duration * fps 算出帧数后取整到最近的合法值，而不是把任意帧数传给流水线。某个基础模型具体支持哪些合法值，由对应的 base-model 参考文件说明（LTX 家族的典型值是 121、161、257 等）。

六、Image-to-video（I2V）基线

输入：

• 输入图像——可能是第一帧，也可能是风格参考图（取决于 LoRA 的语义）。
• 描述运动的提示词。
• 时长。

输出： gr.Video。

宽高比： 从输入图像自动检测，吸附到模型最近的 bucket，把选定的分辨率以信息文本形式展示给用户。

变体差异： 部分 I2V LoRA 把输入图当作字面意义的第一帧；另一些则把它当作风格参考，根据提示词重新生成新的第一帧。模型卡通常会说明是哪一种。两种情况的 UI 相似，区别在于 image= 传给流水线的方式，以及是否需要提供"用作第一帧（use as first frame）"的开关。

七、Video-to-video（V2V）基线

输入： 至少一个源视频；几乎总需要一条提示词；根据 LoRA 的能力往往还有额外输入（外观参考图、mask、control video 等）。

输出： gr.Video。如果 LoRA 对输入做预处理（姿态提取、深度估计、边缘/补边等），把预处理中间结果作为第二个较小的视频展示在结果旁边，让用户看到模型实际"看到"了什么。

这是最需要定制的地方： tasks.md 明确警告——"V2V" 这个标签本身几乎说明不了 UI 形态。姿态控制、深度控制、canny 控制、外扩（outpainting）、重绘（inpainting）、风格迁移、运动迁移、帧插值、超分全都是 V2V，但需要完全不同的 UI。设计前必须同时读 adapting-to-the-lora.md 和对应的 base-model 文件。

V2V 的通用模式：

# 预处理预览：小尺寸视频，输入变化时即时更新
preprocess_preview = gr.Video(height=240, label="Pose / depth / canny preview")

• 预处理预览：小尺寸 gr.Video(height=240) 显示提取出的姿态/深度/canny/补边视频，在输入变化时更新，让用户在点击 Generate 之前就看到预处理结果。
• 运动迁移类 LoRA 的双输入布局：源视频 + 外观图像，两个输入必须清晰标注（如 "appearance" 和 "pose source"）。
• 宽高比选择器只在 LoRA 真的会改变宽高比时才出现（典型是外扩 outpainting）。对姿态/深度/canny 控制类，输出宽高比与输入一致，加宽高比选择器反而误导用户。

八、组件选择阶梯：从内置组件到自定义 HTML/JS

tasks.md 给出了一条按顺序逐级下降的组件选择阶梯，停在第一个匹配 LoRA 输入形态的层级，不要跳跃、不要过度设计。

第一层：Gradio 内置组件（几乎总是首选）

• gr.ImageSlider —— 内置的前/后对比组件，编辑类 LoRA 的首选。
• gr.ImageEditor —— 上传 + 在图像上涂画。适用于输入形态是"图像上一个区域（通过涂画表达）"的 LoRA：物体移除（红色高亮区域训练）、打光（彩色笔刷训练）、涂鸦条件编辑。要点是用 gr.Brush 约束画笔颜色，让用户只能画 LoRA 训练时用的颜色：

  gr.ImageEditor(
      brush=gr.Brush(default_color="#ff0000", colors=["#ff0000"]),
      label="Paint the region to edit",
  )
  

  gr.ImageEditor 返回 {"background", "layers", "composite"} 字典，composite 才是要喂给流水线的内容。文档特别举了一个生产案例（linoyts/QIE-2509-Object-Remover-Bbox-v3）：即使 LoRA 是用 bbox 训练的，只要用户侧的自然输入形态是"涂画出的区域"，就不要为了 bbox 而引入 bbox 标注组件。
• @gr.render —— 根据输入动态改变形态的 UI（例如仅在某个输入被上传后才显示额外控件）。
• gr.Examples —— 可点击的示例输入，几乎总是值得加，内容从 LoRA 模型卡中提取。
• gr.BrowserState —— 跨会话持久化用户偏好（首选宽高比、上次用的种子等）。
• gr.DeepLinkButton —— 把某次生成以 URL 形式分享出去。

第二层：Hub 自定义组件（一次 pip install + 一个 import，无需维护 JS）

• gradio_image_annotation —— 在图像上做 bbox/点标注。适用于 LoRA 确实需要结构化的框坐标作为输入的场景（例如"把物体从 A 框拖到 B 框"的拖放类 LoRA、区域标签编辑）。不适用于需要涂画区域的 LoRA——那种情况用 gr.ImageEditor。
• gradio_imageslider —— 带额外控制的前/后对比滑杆替代品。
• gradio_modal —— 模态对话框。
• gradio_rangeslider —— 双手柄范围滑杆。

第三层：Creative mode（自定义 HTML/JS）

当内置组件和 Hub 自定义组件都不够用时才下探到这一层：点集、笔划、轨迹、带元数据的区域选择、3D 旋转 gizmo、时间轴拖拽……任何"用户在媒体之上操作一个东西"的输入形态。具体实现方式（gr.HTML、demo.launch(head=, css=)、elem_id 寻址、JS↔Python 两种状态同步方案、JSON 线协议纪律与常见陷阱）见 creative-mode.md。

两个强制纪律：

1. 不要跳过第二层直接进第三层——gradio_image_annotation 已经覆盖了大量看似需要自定义 HTML 的 bbox 场景；
2. Hub 自定义组件是脆弱的：版本不匹配会导致组件在页面上静默消失（Python 端 import 成功、构建日志无报错、API smoke-test 通过，但 DOM 里就是没有这个组件）。所以凡是用到第二、三层组件的 Space，gradio info / gradio predict 的 Python 端冒烟测试通过还不够，必须真的打开浏览器验证组件渲染与一次完整交互（详见 creative-mode.md 的 "Smoke-test caveat"）。

主题与文档检查： 默认主题用 gr.themes.Citrus()；在默认使用普通组件或猜测自定义组件之前，先核对当前 Gradio 文档中对应组件的签名。

九、Gradio 6.x 版本陷阱（构建期最容易踩的坑）

tasks.md 专门列出 Gradio 6.x 的三大改动——它们的共同特点是：失败发生在 Space 首次 import 时，而不是本地写文件时，因此极难排查。

1. theme= 和 css= 移到了 launch() 上

把它们传给 gr.Blocks(...) 只会产生弃用警告，且样式静默不生效。正确写法：

with gr.Blocks(title="...") as demo:
    ...

if __name__ == "__main__":
    demo.launch(theme=gr.themes.Citrus(), css=CSS)

Spaces 以 __main__ 方式运行 app.py，所以 launch() 一定会执行。

2. 部分组件 kwarg 被移除

例如 gr.Image 不再接受 show_download_button。传了不存在的 kwarg 时，Space 在容器启动时抛 TypeError: __init__() got an unexpected keyword argument 'show_download_button'。给组件传不常见的 kwarg 之前，先核对当前文档。

3. Space 实际运行的 Gradio 版本由 README 的 sdk_version: 决定

而不是 requirements.txt。在 requirements.txt 里 pin gradio 最好情况是被忽略，最坏情况是造成运行时版本冲突。正确做法：只在 README 的 YAML frontmatter 里设置一次版本，并按该版本编写 app.py（SKILL.md 的 README.md 小节对此有完整说明）。

排查路径： 首次构建如果失败在 Gradio 组件的 TypeError 或签名不匹配，读 /logs/container（构建日志）或 /logs/run（运行时日志），定位 app.py 出错行，再核对当前组件签名。

十、从基线到成品：与具体 LoRA 的适配闭环

tasks.md 全文反复强调一个前提：基线是骨架，不是终态。文档开篇就说 "the baseline is rarely the right final answer"，结尾又强调 V2V "is where adaptation matters most"。这与 adapting-to-the-lora.md 的核心问题形成闭环："这个 LoRA 到底需要用户提供什么，用户最自然的提供方式是什么？"

两者配合的实际工作流：

1. 用 tasks.md 按任务类型搭出基线骨架；
2. 读 adapting-to-the-lora.md，从模型卡的示例代码（取参数）、触发词、示例媒体、任务族、推荐超参五个来源判断这个 LoRA 的专属需求；
3. 判断哪些信号会改变 UI 形态：少步推理（隐藏步数滑杆）、LoRA scale 敏感（以推荐值为中心暴露滑杆）、多参考输入（双图槽位清晰标注）、可选输入（明确标注 "(optional)"）、多阶段流水线（用 progress(0.3, desc="...") 分阶段上报）、>5 秒视频（调高 @spaces.GPU(duration=...) 并在 UI 中预警）、结构化提示内容（用小 UI 生成结构而非让用户手敲）；
4. 最后用 SKILL.md 中定义的"十秒自检"验收："用一句话描述用户 10 秒内在这个 Space 做什么。如果这句话无法把当前 LoRA 与同任务的其他 LoRA 区分开，说明 UI 还不够成型。"

各 base-model 参考文件（qwen-image.md、ltx.md、krea-2.md）为每一层定制提供了事实依据——比如 Qwen-Image 的 16 对齐 bucket、LTX 的 8k+1 帧数与蒸馏 IC-LoRA 的四参数关闭法（guidance_scale=1.0, stg_scale=0.0, audio_guidance_scale=1.0, audio_stg_scale=0.0）、Krea 2 的 guidance_scale=0 关闭引导的约定。这些参数细节决定了基线 UI 里滑杆的默认值和取值范围，是"可复制、可运行"的最后一块拼图。

十一、实战自检清单

在把界面从基线推向发布之前，用下面的清单过一遍（综合 tasks.md 与 SKILL.md 的约束）：

• [ ] 双列等高布局，输入左、输出右，只有一个 primary 的 Generate 按钮；
• [ ] Advanced 折叠面板收纳高级参数，普通用户无感知；
• [ ] 种子控件 + Randomize 复选框齐备，且实际种子随结果返回；
• [ ] prompt.submit 与按钮点击都已接好，Enter 可提交；
• [ ] 推理函数挂了 gr.Progress(track_tqdm=True)；
• [ ] 尺寸/帧数对齐模型 bucket（DiT 16、UNet 8、视频 8k+1）；
• [ ] 少步 LoRA 隐藏了步数与 guidance 滑杆；
• [ ] I2I 有输入校验（gr.Error 或按钮禁用态）；
• [ ] 视频类 @spaces.GPU(duration=...) 舒适地大于预期生成时长，且 UI 告知用户耗时；
• [ ] gr.Examples 使用 cache_examples=True, cache_mode="lazy"；
• [ ] 组件选择严格走阶梯（stock → Hub custom → creative），没跳过第二层；
• [ ] Gradio 6.x：theme=/css= 在 launch()，没有已移除的组件 kwarg，版本只由 sdk_version 控制；
• [ ] 对照 adapting-to-the-lora.md 完成过一轮"这个 LoRA 独有需求"的适配，并通过十秒自检。

这套基线体系的价值在于：它把"为任意 LoRA 建演示"这个宽泛目标，拆解成任务骨架、组件阶梯、版本纪律、适配推理四个可执行的层次。对开发者而言，tasks.md 提供的是可直接落地的 Gradio 结构；对 AI Agent 而言，它是一份能显著降低返工概率的决策清单——尤其是 Gradio 6.x 的版本陷阱与 ZeroGPU 的示例缓存约束，恰恰是"构建变绿、运行时翻车"这一最常见失败模式的解药。