Pixelle-Video 常见问题实战指南ComfyUI 工作流集成、RunningHub 本地调试与报错排查【免费下载链接】Pixelle-Video AI 全自动短视频引擎 | AI Fully Automated Short Video Engine项目地址: https://gitcode.com/GitHub_Trending/pi/Pixelle-VideoPixelle-Video 是一套 AI 全自动短视频引擎通过 LLM 生成文案、TTS 合成语音、ComfyUI 工作流生成图像与视频最终渲染输出成片。本文基于官方 FAQ 文档结合仓库源码系统讲解如何将自研 ComfyUI 工作流接入项目、如何把 RunningHub 云端工作流拉回本地调试以及常见报错的根因与解决方案。读完本文你将掌握$prompt.text!参数绑定、image_/video_/tts_命名规范、工作流自动扫描机制并能独立排查 TTS、LLM 与浏览器内核相关故障。一、本地自研 ComfyUI 工作流如何集成Pixelle-Video 不要求你只会使用内置工作流它允许你把自己开发的 ComfyUI 工作流接入生成管线。官方集成规范共四步每一步都有严格的约定下面结合源码逐一说明。1. 本地跑通是前提第一步确保工作流在本地 ComfyUI 中能正常运行。这是所有后续步骤的基础——项目本身并不负责验证工作流逻辑它只负责把动态参数注入工作流并执行工作流内部的节点连线、模型加载是否正确需要你在 ComfyUI 界面先行确认。2. 参数绑定把节点标题改成$prompt.text!或$prompt.value!找到工作流中需要由程序动态传入提示词的Text 节点如 CLIP Text Encode 或类似文本输入节点编辑该节点的Title将其修改为$prompt.text!—— 当节点接受文本类型输入时使用$prompt.value!—— 根据节点实际接受的输入类型选择。这个机制的本质是项目在运行时扫描工作流 JSON识别出标题形如$prompt.xxx!的节点把生成好的提示词文本注入该节点后再提交执行。仓库中现有的自托管工作流都是这样编辑的可直接参考 workflows/selfhost/ 目录下的 JSON 文件例如 image_flux.json、video_wan2.1_fusionx.json来对照理解编辑方式。3. 导出 API 格式将修改好的工作流通过 ComfyUI 的Save (API Format)功能导出。只有 API 格式{prompt: {...}, extra_data: {...}}结构才能被项目执行引擎识别普通的工作流 UI 格式{nodes: [...]}无法直接驱动。4. 文件命名前缀决定能力类型将导出的 JSON 文件放入 workflows/ 目录并严格遵守以下命名前缀前缀能力类型示例image_图片生成类工作流image_my_style.jsonvideo_视频生成类工作流video_my_motion.jsontts_语音合成类工作流tts_my_voice.json这个命名前缀不是约定俗成而是硬性代码约束。在 comfy_base_service.py 的_scan_workflows()中项目会扫描workflows/{source}/目录下的所有 JSON 文件并用f.startswith(self.WORKFLOW_PREFIX) and f.endswith(.json)进行过滤——也就是说前缀不匹配的文件会被直接忽略不会出现在可用工作流列表中。各服务的WORKFLOW_PREFIX定义如下TTS 服务tts_service.pyWORKFLOW_PREFIX tts_其他 ComfyUI 派生服务图片、视频同样继承自ComfyBaseService各自覆写前缀常量。此外workflow_util.py 中的resolve_workflow_path()进一步规范了路径约定workflows/{source}/{service_name}.json其中source为runninghub云端默认或selfhost本地自托管。get_default_source()默认返回runninghub因为云端优先对新手更友好。工作流如何被识别与加载把文件放入目录后ComfyBaseService会在首次调用时扫描并缓存工作流清单_workflows_cache通过list_workflows()可查看全部可用项通过.available属性可拿到形如selfhost/image_flux.json的工作流 key。_resolve_workflow()会按 key 精确匹配comfy_base_service.py如果找不到会抛出异常并列出所有可用 key 供参考——这就是为什么命名前缀错了会导致工作流找不到。二、如何把 RunningHub 云端工作流拉回本地调试项目中 workflows/runninghub/ 目录下的工作流用于 RunningHub 云端执行若想在本地 ComfyUI 中测试调试按以下步骤操作1. 从工作流文件中提取 workflow ID打开 RunningHub 工作流 JSON 文件找到id字段。仓库中的 RunningHub 工作流采用轻量wrapper 格式例如 tts_edge.json 的完整内容只有两行{ source: runninghub, workflow_id: 1983513964837543938 }_parse_workflow_file()comfy_base_service.py识别到source与workflow_id字段后会把workflow_id存入工作流信息字典执行时若 source 为runninghub则直接以workflow_id作为执行输入提交给 ComfyKit见 tts_service.py。2. 通过 URL 打开工作流页面将提取到的 ID 粘贴到 RunningHub 网站 URL 后缀形如https://www.runninghub.cn/workflow/1983513964837543938即可直接进入该工作流的在线页面。3. 下载为 JSON 文件在工作台中将该工作流下载为 JSON 文件。4. 拖入本地 ComfyUI 测试将下载的文件直接拖入本地 ComfyUI 画布进行测试与调试。注意RunningHub 云端导出的工作流与本地执行环境在节点版本、模型路径上可能有差异调试时需按本地环境微调。本地与云端的执行差异从_call_comfyui_workflow()tts_service.py可以看出项目对两种来源采用不同的执行路径RunningHub以workflow_id提交到云端 API结果可能是远程文件 URL若指定了output_path会通过 httpx 下载到本地Selfhost以本地文件路径提交给 ComfyKit直接驱动本机 ComfyUI 执行。配置优先级为comfyui_url参数global_config 环境变量COMFYUI_BASE_URL 默认http://127.0.0.1:8188API Key 同理支持RUNNINGHUB_API_KEY环境变量注入见_prepare_comfykit_config()。三、常见报错及解决方案1. TTS语音合成报错原因默认的 Edge-TTS 调用的是微软的免费接口容易受网络波动影响失败频率较高。解决方案检查网络连接建议切换使用ComfyUI 合成 TTS的工作流即选择前缀为tts_的工作流如 tts_edge.json、tts_spark.json、tts_index2.json稳定性更高。从源码看TTS 服务支持两种推理模式tts_service.pyinference_modelocal走本地 Edge-TTS默认音色zh-CN-YunjianNeural、默认语速1.2xspeed_to_rate()会把倍率转换为 Edge-TTS 的rate参数输出到output/目录inference_modecomfyui走 ComfyUI 工作流可显式传入workflow如runninghub/tts_edge.json、voice、speed等参数。如果默认工作流未在config.yaml的tts段配置default_workflow_get_default_workflow()会直接抛出ValueError并列出所有可用工作流——这也是 TTS 报错的一类常见来源。2. LLM大模型报错按以下三步排查检查 Base URL 是否正确——不要有多余空格或错误后缀检查 API Key 是否有效且有余额检查 Model Name 是否拼写正确。提示请查阅你所使用模型服务商如 OpenAI、DeepSeek、阿里云通义千问等的官方 API 文档获取准确配置。从项目文档看Pixelle-Video 支持所有 OpenAI 兼容接口的 LLM包括通义千问、GPT-4o、DeepSeek以及 Ollama 本地模型见 docs/zh/faq.md配置时确保 Base URL 与模型名与服务商 API 文档一致即可。3. 错误提示 Could not find a Chrome executable...原因系统中缺少 Chrome 浏览器内核导致部分依赖浏览器的功能无法运行。解决方案下载并安装 Google Chrome 浏览器。这个报错与项目的帧渲染机制直接相关。项目通过 frame_html.py 中的HTMLFrameGenerator渲染 HTML 模板生成画面帧其底层依赖Playwright 驱动的 Chromium 内核async_playwright().start()后chromium.launch(...)见第 329-331 行。在 Linux 环境下还需要额外安装系统依赖与字体# Ubuntu/Debian sudo apt-get install -y fontconfig fonts-liberation fonts-noto-cjk # CentOS/RHEL sudo yum install -y fontconfig liberation-fonts google-noto-cjk-fonts # Playwright 浏览器内核 playwright install --with-deps chromium所以该报错除了安装 Chrome 外还可以通过安装 Playwright 的 Chromium 内核解决。四、生成的视频保存在哪里所有生成的视频自动保存到项目目录的output/文件夹中。生成完成后界面会显示视频时长、文件大小、分镜数量及下载链接。从源码可以印证这一点TTS 本地模式生成音频时若未指定output_path会通过uuid4().hex生成唯一文件名并写入output/目录tts_service.py视频、图像产物的落盘逻辑遵循同一约定。output/是项目运行时自动创建的产物目录已被 .gitignore 忽略不入库清理旧产物、归档成片都在该目录下进行。五、更多高频疑问速查以下内容来自仓库 docs/zh/faq.md与官方 FAQ 互为补充一并整理如下安装相关如何安装 uv项目推荐使用 uv 管理依赖curl -LsSf https://astral.sh/uv/install.sh | sh当然也可以不使用 uv改用传统的 pip venv 方式。配置相关必须要配置 ComfyUI 吗不一定取决于模板类型模板类型ComfyUI适用场景生成速度纯文本模板如simple.html❌ 不需要文字金句、公告、阅读提示⚡⚡⚡ 极快AI 配图模板如default.html✅ 需要图文并茂的丰富内容⚡ 标准新手推荐从纯文本模板开始零门槛体验需要 AI 配图但不想本地部署 ComfyUI 时可以使用 RunningHub 云端服务。支持哪些 LLM所有 OpenAI 兼容接口的 LLM 均支持包括通义千问、GPT-4o、DeepSeek、Ollama本地。使用相关第一次使用需要多久生成一个 3-5 分镜的视频大约需要 2-5 分钟。视频效果不满意怎么办依次尝试更换 LLM 模型 → 调整图像尺寸和提示词前缀 → 更换 TTS 工作流 → 更换不同的视频模板。费用大概多少完全免费Ollama 本地 ComfyUI 0 元推荐方案通义千问 本地 ComfyUI ≈ 0.01-0.05 元/视频云端方案OpenAI RunningHub费用较高。故障排查ComfyUI 连接失败确认 ComfyUI 正在运行 → 检查 URL 是否正确 → 在 Web 界面点击「测试连接」。LLM API 调用失败检查 API Key → 检查网络连接 → 查看错误提示。六、社区资源与后续支持GitHub 仓库项目托管于 GitHubAIDC-AI/Pixelle-Video可通过git clone https://github.com/AIDC-AI/Pixelle-Video获取源码问题反馈通过 GitHub Issues 提交 bug 或功能请求社区支持加入讨论群组获取帮助和分享经验贡献代码项目在 MIT 许可证下欢迎贡献见 LICENSE。提示如果在本 FAQ 中找不到所需答案请在 GitHub 提交 issue 或加入社区讨论。项目团队会根据用户反馈持续更新 FAQ。此外docs/zh/troubleshooting.md 与 docs/zh/faq.md 也提供了更多排查思路可在遇到问题时交叉查阅。【免费下载链接】Pixelle-Video AI 全自动短视频引擎 | AI Fully Automated Short Video Engine项目地址: https://gitcode.com/GitHub_Trending/pi/Pixelle-Video创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考