Pixelle-Video 源码解析 #13：RunningHub 云端工作流：没有显卡也能生成素材吗？

最新推荐文章于 2026-09-11 21:31:59 发布

原创最新推荐文章于 2026-09-11 21:31:59 发布 · 351 阅读

7 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

收录于

源码分析

python

前面第 12 篇，我们分析了 Pixelle-Video 如何接入本地 ComfyUI 工作流。

本地 ComfyUI 的优点很明显：自由度高、可控性强、模型和节点都在自己机器上。但它也有一个现实门槛：

需要本地环境。

你要安装 ComfyUI，要下载模型，要处理节点依赖，还要有合适的显卡。如果只是想快速生成短视频素材，这个门槛并不低。

所以 Pixelle-Video 还提供了另一条路线：

RunningHub 云端工作流。

简单说，就是不在本地跑 ComfyUI，而是把工作流放到云端执行。Pixelle-Video 只负责提交 prompt、尺寸、时长等参数，然后等待云端返回生成结果。

这一篇我们就分析：

RunningHub 在 Pixelle-Video 里是怎么接入的？没有本地显卡时，它能不能替代本地 ComfyUI？

一、RunningHub 在 Pixelle-Video 中解决什么问题？

Pixelle-Video 的媒体生成有几条路线：

1. 本地 ComfyUI workflow
2. RunningHub 云端 workflow
3. api/... 直连图像 / 视频模型

其中 RunningHub 的定位很清楚：

让用户不用在本地部署完整 ComfyUI 环境，也能执行图像、视频、TTS 等工作流。

在 config.example.yaml 中，Pixelle-Video 的默认图片工作流就是 runninghub/image_flux.json，配置注释里也写明这是推荐选项，并标注为 “no local setup”；对应的本地选项是 selfhost/image_flux.json，需要本地 ComfyUI。视频工作流也类似，默认是 runninghub/video_wan2.1_fusionx.json，本地选项则需要本地 ComfyUI。(raw.githubusercontent.com)

也就是说，Pixelle-Video 默认更偏向让新用户先用云端 workflow 跑通流程，而不是一开始就折腾本地显卡和 ComfyUI 环境。

二、RunningHub 配置入口在哪里？

RunningHub 的配置入口仍然在 config.yaml 的 comfyui 配置块里。

示例配置中有几个关键字段：

comfyui:
  comfyui_url: http://127.0.0.1:8188
  comfyui_api_key: ""
  runninghub_api_key: ""
  runninghub_concurrent_limit: 1

  image:
    default_workflow: runninghub/image_flux.json

  video:
    default_workflow: runninghub/video_wan2.1_fusionx.json

其中最重要的是：

runninghub_api_key
    RunningHub 的访问密钥，RunningHub workflow 需要它。

runninghub_concurrent_limit
    RunningHub 并发限制，配置示例中默认是 1，并标注范围是 1-10。

image.default_workflow
    图片生成默认使用哪个 workflow。

video.default_workflow
    视频生成默认使用哪个 workflow。

配置文件明确写到，runninghub_api_key 是 RunningHub workflows 所需的 API Key，runninghub_concurrent_limit 是 RunningHub 并发执行限制；图片默认 workflow 的推荐值是 runninghub/image_flux.json，视频默认 workflow 的推荐值是 runninghub/video_wan2.1_fusionx.json。(raw.githubusercontent.com)

所以，如果你想走 RunningHub 路线，核心配置就是：

comfyui:
  runninghub_api_key: "你的 RunningHub API Key"
  runninghub_concurrent_limit: 1

  image:
    default_workflow: runninghub/image_flux.json

  video:
    default_workflow: runninghub/video_wan2.1_fusionx.json

注意：comfyui_url 仍然存在，但 RunningHub workflow 的关键不是本地地址，而是 RunningHub API Key 和 runninghub workflow。

三、workflow key：RunningHub 和 selfhost 的分界线

Pixelle-Video 用 workflow key 来区分工作流来源。

比如：

runninghub/image_flux.json
selfhost/image_flux.json

这两个名字看起来只差一个前缀，但含义完全不同。

runninghub/image_flux.json
    表示使用 RunningHub 云端工作流。

selfhost/image_flux.json
    表示使用本地 ComfyUI 工作流。

在 ComfyBaseService 的源码注释中，workflow info 会包含 source、path、key 等字段。如果是 RunningHub workflow，还会额外包含 workflow_id。示例结构中，runninghub/image_flux.json 对应的 source 是 runninghub，并带有 workflow_id。(raw.githubusercontent.com)

这说明 Pixelle-Video 并不是靠文件名随便判断，而是在解析 workflow 文件时把来源和 workflow_id 都整理成结构化信息。

可以理解成：

workflow key
    ↓
_resolve_workflow()
    ↓
workflow_info
    ↓
source = runninghub / selfhost

后面 MediaService 就根据 source 决定到底传 workflow 文件路径，还是传 RunningHub 的 workflow_id。

四、RunningHub workflow 文件放在哪里？

RunningHub workflow 仍然放在 workflows/ 目录下，只不过是在 runninghub/ 子目录中。

结构可以理解为：

workflows/
├── selfhost/
│   ├── image_flux.json
│   └── video_xxx.json
│
└── runninghub/
    ├── image_flux.json
    └── video_wan2.1_fusionx.json

MediaService 会扫描 workflows 目录下的来源目录，并筛选以 image_ 或 video_ 开头、以 .json 结尾的 workflow 文件。它会把这些文件解析成 workflow_info，并按 source/name 形成 key，例如 runninghub/image_flux.json 或 selfhost/image_flux.json。(raw.githubusercontent.com)

所以 RunningHub 的 workflow 并不是写死在代码里的，而是通过 workflow JSON 文件来描述。

这和本地 ComfyUI 的设计保持一致：

本地 workflow：
    文件描述本地工作流

RunningHub workflow：
    文件描述云端工作流，并带 workflow_id

Pixelle-Video 的上层 pipeline 不需要关心这个差异。

五、ComfyBaseService：负责找到 RunningHub workflow

无论是 selfhost 还是 RunningHub，第一步都是解析 workflow。

ComfyBaseService._resolve_workflow() 的逻辑是：

1. 如果调用时没有指定 workflow，就使用配置里的 default_workflow。
2. 扫描所有可用 workflows。
3. 按 workflow key 查找匹配项。
4. 找到就返回 workflow_info。
5. 找不到就抛出错误，并列出可用 workflows。

源码中也明确说明，default workflow 是必填项，没有 fallback；如果没有配置，会提示用户在 config.yaml 对应 section 下设置 default_workflow。(raw.githubusercontent.com)

这说明 RunningHub 接入的第一层不是调用 API，而是先找到：

runninghub/image_flux.json

对应的 workflow_info。

如果配置写错，比如写成：

image_flux.json

而不是：

runninghub/image_flux.json

就可能找不到 workflow。

六、MediaService：RunningHub 和 selfhost 共用同一个入口

图片或视频真正生成时，还是进入 MediaService.__call__()。

这个方法接收：

prompt
workflow
media_type
width
height
duration
negative_prompt
steps
seed
cfg
sampler

源码中 MediaService 的注释说明，它是基于 ComfyUI workflow 的媒体生成服务，使用 ComfyKit 执行 image/video workflows；同时支持 image_ 和 video_ 工作流前缀。(raw.githubusercontent.com)

对于上层来说，RunningHub 和 selfhost 的调用方式几乎一样：

media = await self.core.media(
    prompt=frame.image_prompt,
    workflow="runninghub/image_flux.json",
    media_type="image",
    width=1080,
    height=1920
)

或者：

media = await self.core.media(
    prompt=frame.image_prompt,
    workflow="selfhost/image_flux.json",
    media_type="image",
    width=1080,
    height=1920
)

区别只在 workflow key。

这就是 Pixelle-Video 设计得比较好的地方：

用同一个 MediaService 抽象本地和云端媒体生成。

七、真正分流：workflow_id 还是 workflow path？

RunningHub 和 selfhost 的真正分流发生在 MediaService.__call__() 里。

源码中，在执行 workflow 前会判断：

if workflow_info["source"] == "runninghub" and "workflow_id" in workflow_info:
    workflow_input = workflow_info["workflow_id"]
else:
    workflow_input = workflow_info["path"]

如果是 RunningHub，并且 workflow_info 里有 workflow_id，就把 workflow_id 传给 ComfyKit；否则就把本地 workflow 文件路径传给 ComfyKit。随后统一调用 kit.execute(workflow_input, workflow_params)。(raw.githubusercontent.com)

这就是 RunningHub 接入的核心。

selfhost:
    kit.execute(workflow_file_path, workflow_params)

runninghub:
    kit.execute(workflow_id, workflow_params)

上层业务完全不需要知道 ComfyKit 里面如何跟 RunningHub 通信。

Pixelle-Video 只做两件事：

1. 根据 workflow source 决定传 path 还是 workflow_id。
2. 把 prompt、width、height 等参数传进去。

八、ComfyKit 配置如何拿到 RunningHub API Key？

RunningHub 需要 API Key。

Pixelle-Video 在 PixelleVideoCore._get_comfykit_config() 中读取当前配置，并把相关字段交给 ComfyKit。源码中会读取 comfyui_url、comfyui_api_key、runninghub_api_key、runninghub_instance_type，如果这些字段存在，就放入 kit_config。(raw.githubusercontent.com)

简化理解：

kit_config = {}

if comfyui_url:
    kit_config["comfyui_url"] = comfyui_url

if comfyui_api_key:
    kit_config["api_key"] = comfyui_api_key

if runninghub_api_key:
    kit_config["runninghub_api_key"] = runninghub_api_key

if runninghub_instance_type:
    kit_config["runninghub_instance_type"] = runninghub_instance_type

然后在 _get_or_create_comfykit() 中创建：

self._comfykit = ComfyKit(**current_config)

源码还说明，ComfyKit 是懒加载的：第一次使用时才创建，并且会检测配置变化；如果配置变化，就关闭旧实例并重新创建。(raw.githubusercontent.com)

这对 WebUI 很重要。

因为用户可能在页面里修改 RunningHub API Key 或工作流配置。如果每次都要重启应用才生效，体验会很差。Pixelle-Video 通过配置 hash 检测和 ComfyKit 重建，尽量支持配置热更新。

九、workflow_params：RunningHub 接收的参数是什么？

RunningHub workflow 最终也要接收参数。

MediaService.__call__() 会先构造：

workflow_params = {"prompt": prompt}

然后按需加入：

width
height
duration
negative_prompt
steps
seed
cfg
sampler

最后再把额外参数 params 合并进去。(raw.githubusercontent.com)

所以 RunningHub 接收到的并不是 Pixelle-Video 的完整对象，而是一组面向工作流的参数。

可以理解成：

StoryboardFrame.image_prompt
    ↓
prompt

视频尺寸
    ↓
width / height

TTS 音频时长
    ↓
duration，主要用于 video workflow

采样参数
    ↓
steps / seed / cfg / sampler

额外参数
    ↓
params

这和本地 ComfyUI workflow 的参数结构基本一致。

也就是说，RunningHub 和 selfhost 在 Pixelle-Video 里不是两套业务逻辑，而是同一套 workflow 参数协议的两个执行后端。

十、RunningHub 为什么能支持并发处理？

RunningHub 云端工作流还有一个很重要的优势：可以并发处理多个 frame。

在 StandardPipeline.produce_assets() 中，源码会判断当前配置是否使用 RunningHub workflow：

tts_workflow 以 runninghub/ 开头
或者 media_workflow 以 runninghub/ 开头

只要 TTS 或媒体 workflow 是 RunningHub，并且 runninghub_concurrent_limit > 1，就会使用 asyncio.Semaphore 控制并发处理多个 frame。否则就走普通串行处理。(raw.githubusercontent.com)

这段逻辑非常关键。

普通 selfhost 模式下，Pixelle-Video 默认走串行处理：

frame 1 → frame 2 → frame 3 → frame 4

RunningHub 并发模式下，可以变成：

frame 1 ┐
frame 2 ├── 同时提交，受 runninghub_concurrent_limit 控制
frame 3 ┘

当然，并发数不是越大越好。配置示例里默认值是 1，并标注并发限制范围是 1-10。(raw.githubusercontent.com)

这说明 Pixelle-Video 允许用户根据 RunningHub 账户能力、任务规模和稳定性来控制并发。

十一、为什么并发只特别针对 RunningHub？

源码中，RunningHub workflow 才会触发并发处理逻辑；非 RunningHub workflow 会走串行处理。(raw.githubusercontent.com)

这背后的原因很容易理解。

本地 ComfyUI 通常受限于本机显卡。
如果同时提交多个重型生图或视频任务，可能造成显存爆掉、队列堆积或性能下降。

RunningHub 是云端执行，理论上更适合多任务并发，但也必须受账号并发限制控制。

所以 Pixelle-Video 的设计是：

selfhost：
    默认串行，更稳。

runninghub：
    可根据 concurrent_limit 并发，提高批量 frame 处理速度。

这也是 RunningHub 路线相对本地路线的一个工程优势。

十二、RunningHub 生成结果如何回到 Pixelle-Video？

无论是 RunningHub 还是 selfhost，ComfyKit 执行完成后都会返回 result。

MediaService.__call__() 会检查：

result.status 是否等于 completed

如果不是 completed，就抛出媒体生成失败。
如果是图片任务，则要求 result.images 不为空，并取第一张图片 URL。
如果是视频任务，则要求 result.videos 不为空，并取第一段视频 URL。(raw.githubusercontent.com)

然后返回：

MediaResult(
    media_type="image",
    url=image_url
)

或者：

MediaResult(
    media_type="video",
    url=video_url,
    duration=duration
)

后面 FrameProcessor 会把这个 url 下载或保存到任务目录，并写回当前 StoryboardFrame 的 image_path 或 video_path。

所以 RunningHub 的输出并不会直接成为最终视频，而是先变成 frame 的素材：

RunningHub result.images[0]
    ↓
MediaResult.url
    ↓
frame.image_path
    ↓
HTML 模板渲染
    ↓
video_segment_path

十三、RunningHub 和本地 ComfyUI 的完整对比

从源码角度看，RunningHub 和 selfhost 的差异可以总结成这样：

selfhost：
    workflow key：selfhost/image_flux.json
    workflow input：本地 workflow 文件 path
    执行位置：本地 ComfyUI
    主要依赖：本地 ComfyUI、模型、节点、显卡
    默认处理：串行处理 frame
    适合用户：有显卡、想深度控制 workflow 的用户

runninghub：
    workflow key：runninghub/image_flux.json
    workflow input：workflow_id
    执行位置：RunningHub 云端
    主要依赖：runninghub_api_key、云端 workflow
    默认处理：可根据 runninghub_concurrent_limit 并发
    适合用户：没有本地显卡、想快速跑通素材生成的用户

两者的共同点是：

都由 MediaService 调用
都通过 ComfyKit 执行
都接收 prompt、width、height、seed 等参数
都返回 MediaResult
都写回 StoryboardFrame
都进入后续模板渲染和视频合成

所以 Pixelle-Video 的设计重点不是“只能本地”或“只能云端”，而是把二者统一成：

workflow source 不同，pipeline 逻辑相同

十四、没有显卡也能生成素材吗？

答案是：可以，但前提是你使用 RunningHub 或直连 API 模型，而不是 selfhost 本地工作流。

如果你选择：

comfyui:
  image:
    default_workflow: runninghub/image_flux.json

并且正确填写：

runninghub_api_key: "你的 RunningHub API Key"

那么图片生成会走 RunningHub 云端工作流，而不是本地 ComfyUI。配置示例中也明确把 RunningHub image workflow 标注为推荐、无需本地 setup；selfhost workflow 则标注为需要本地 ComfyUI。(raw.githubusercontent.com)

同理，视频素材生成也可以使用：

comfyui:
  video:
    default_workflow: runninghub/video_wan2.1_fusionx.json

这样可以避免本地显卡门槛。

但要注意，RunningHub 不是“完全无成本、无依赖”。它仍然依赖：

RunningHub API Key
可用的 RunningHub workflow
账户并发限制
网络连接
云端任务执行结果

所以更准确的说法是：

没有本地显卡，也可以通过 RunningHub 云端 workflow 生成素材；但你需要配置 RunningHub 账号和 API Key。

十五、RunningHub 模式的完整调用链路

把整个流程串起来，RunningHub 模式大概是这样：

【配置】
config.yaml
    ↓
runninghub_api_key
runninghub_concurrent_limit
image.default_workflow = runninghub/image_flux.json

【工作流解析】
MediaService / ComfyBaseService
    ↓
扫描 workflows/runninghub/image_*.json
    ↓
解析 workflow_info
    ↓
得到 workflow_id

【分镜】
narration
    ↓
image_prompt
    ↓
StoryboardFrame.image_prompt

【逐帧处理】
FrameProcessor
    ↓
self.core.media(
    prompt=frame.image_prompt,
    workflow=runninghub/image_flux.json,
    media_type=image,
    width=...,
    height=...
)

【执行】
MediaService
    ↓
_resolve_workflow()
    ↓
_get_or_create_comfykit()
    ↓
workflow_input = workflow_id
    ↓
kit.execute(workflow_id, workflow_params)
    ↓
RunningHub 云端执行 workflow

【结果】
result.status == completed
    ↓
result.images[0]
    ↓
MediaResult(url=image_url)
    ↓
FrameProcessor 保存到 frame.image_path
    ↓
HTML 模板渲染
    ↓
视频片段生成

这条链路和 selfhost 最大区别就是：

selfhost 传 workflow path
runninghub 传 workflow_id

其他部分基本共用。

十六、RunningHub 常见问题

1. 忘记填写 runninghub_api_key

RunningHub workflow 需要 runninghub_api_key。配置示例中也明确标注该字段是 RunningHub workflows required。(raw.githubusercontent.com)

如果没填，ComfyKit 执行 RunningHub workflow 时就可能失败。

2. default_workflow 写错

必须写完整 key，例如：

runninghub/image_flux.json

而不是：

image_flux.json

因为 _resolve_workflow() 是按 workflow key 查找，找不到就会抛出错误并列出可用 workflow。(raw.githubusercontent.com)

3. workflow 文件没有 workflow_id

RunningHub workflow 需要在解析后带有 workflow_id。ComfyBaseService 的示例 workflow_info 中，RunningHub workflow 会包含 workflow_id；MediaService 也只有在 source == "runninghub" 且存在 workflow_id 时，才会把 workflow_id 传给 ComfyKit。(raw.githubusercontent.com; raw.githubusercontent.com)

如果 workflow 文件缺少 workflow_id，就可能不能按 RunningHub 路线正确执行。

4. 并发设置过高

runninghub_concurrent_limit 控制并发处理数量。源码中只有当 RunningHub workflow 且并发限制大于 1 时，才使用并行处理；否则走串行。(raw.githubusercontent.com)

如果并发设置过高，可能出现任务失败、排队、限流或成本不可控的问题。一般建议先用默认值 1 跑通，再逐步增加。

5. 生成结果为空

MediaService 要求图片任务返回 result.images，视频任务返回 result.videos。如果云端 workflow 执行完成但没有返回对应媒体，Pixelle-Video 会报 “No image generated” 或 “No video generated”。(raw.githubusercontent.com)

这时要检查 workflow 输出节点和 media_type 是否匹配。

十七、二次开发：如何新增 RunningHub workflow？

如果你想给 Pixelle-Video 添加自己的 RunningHub 工作流，思路大致是：

第一，把 workflow JSON 放到：

workflows/runninghub/

第二，文件名遵守命名规则：

image_xxx.json
video_xxx.json

因为 MediaService 会扫描以 image_ 或 video_ 开头的 JSON workflow 文件。(raw.githubusercontent.com)

第三，确保 workflow 文件里能解析出 RunningHub 的 workflow_id。

第四，在 config.yaml 中设置默认工作流：

comfyui:
  image:
    default_workflow: runninghub/image_my_custom.json

第五，确认配置了：

runninghub_api_key: "你的 RunningHub API Key"

第六，让 Pixelle-Video 通过 MediaService 调用：

prompt
width
height
negative_prompt
steps
seed
cfg
sampler

第七，看生成结果是否能正确返回 images 或 videos。

如果这些都正常，你的 RunningHub workflow 就能进入 Pixelle-Video 的视频生成 pipeline。

十八、RunningHub 模式的优点

从源码设计看，RunningHub 模式有几个明显优点。

第一，不需要本地显卡。

用户可以通过云端 workflow 生成图片和视频素材。

第二，不需要本地维护 ComfyUI 环境。

配置示例里也把 RunningHub workflow 标注为推荐、无需本地 setup。(raw.githubusercontent.com)

第三，可以和 selfhost 共用同一套 MediaService。

上层 pipeline 不需要为 RunningHub 单独写一套流程。

第四，支持并发。

当 RunningHub workflow 被使用且 runninghub_concurrent_limit > 1 时，StandardPipeline 会用 semaphore 并发处理 frame。(raw.githubusercontent.com)

第五，适合普通用户快速跑通。

对于没有显卡、不想装 ComfyUI 的用户，RunningHub 比 selfhost 更容易上手。

十九、RunningHub 模式的局限

RunningHub 也不是万能的。

1. 依赖外部服务

云端服务不可用、网络不稳定、API Key 问题，都会影响生成。

2. 依赖 workflow_id

本地 workflow 可以直接传文件路径。
RunningHub workflow 需要正确的 workflow_id。

3. 可控性不如本地

本地 ComfyUI 可以随时修改节点、模型、LoRA、插件。
RunningHub 的工作流修改和调试方式取决于云端平台。

4. 并发需要谨慎

并发能提高速度，但也可能带来限流、失败率或资源成本问题。

5. 调试链路更长

selfhost 出错可以直接看本地 ComfyUI 控制台。
RunningHub 出错时，可能需要同时看 Pixelle-Video 日志、ComfyKit 返回、RunningHub 云端任务状态。

二十、源码阅读建议

如果你要读 Pixelle-Video 的 RunningHub 接入源码，建议按这个顺序：

1. config.example.yaml
   看 runninghub_api_key、runninghub_concurrent_limit、runninghub/image_flux.json 的配置方式。

2. pixelle_video/services/comfy_base_service.py
   看 workflow 如何扫描、解析、resolve，以及 RunningHub workflow_info 如何带 workflow_id。

3. pixelle_video/services/media.py
   看 MediaService 如何判断 source == runninghub，并把 workflow_id 传给 ComfyKit。

4. pixelle_video/service.py
   看 PixelleVideoCore 如何把 runninghub_api_key 放进 ComfyKit 配置，以及 ComfyKit 如何懒加载和热更新。

5. pixelle_video/pipelines/standard.py
   看 RunningHub workflow 如何触发并发处理逻辑。

6. pixelle_video/services/frame_processor.py
   看每个 StoryboardFrame 如何调用 MediaService 生成图片或视频素材。

这样读，可以完整理解：

配置 → workflow 解析 → workflow_id → ComfyKit → RunningHub → MediaResult → StoryboardFrame

二十一、总结

这一篇我们分析了 Pixelle-Video 的 RunningHub 云端工作流接入。

它的核心链路是：

config.yaml
    ↓
runninghub_api_key
runninghub_concurrent_limit
default_workflow = runninghub/image_flux.json
    ↓
ComfyBaseService 扫描并解析 RunningHub workflow
    ↓
得到 workflow_info 和 workflow_id
    ↓
FrameProcessor 调用 MediaService
    ↓
MediaService 构造 workflow_params
    ↓
PixelleVideoCore 创建 ComfyKit
    ↓
kit.execute(workflow_id, workflow_params)
    ↓
RunningHub 云端执行工作流
    ↓
返回 images 或 videos
    ↓
MediaResult
    ↓
frame.image_path 或 frame.video_path
    ↓
模板渲染和视频合成

从设计上看，Pixelle-Video 并没有把 RunningHub 做成一套完全独立的流程，而是把它纳入了统一的 MediaService：

selfhost 传 workflow 文件路径
runninghub 传 workflow_id
api/... 走直连 API provider

这让上层视频生成流程保持稳定。

所以，没有显卡能不能生成素材？

答案是：

可以。只要选择 RunningHub workflow，并正确配置 runninghub_api_key，Pixelle-Video 就可以把图片或视频素材生成任务交给 RunningHub 云端执行，而不是依赖本地显卡。

一句话总结：

Pixelle-Video 的 RunningHub 接入，本质是把云端 workflow_id 当成 ComfyKit 的执行入口，用同一套 prompt、尺寸和采样参数协议，把每个分镜的素材生成任务提交到云端，再把结果写回 StoryboardFrame。

标签

#前端