Pro
中文
登录账户 下载 Mac 版
下载 Mac 版

帮助文档 / 安装与故障排除

故障排除

我的 Mac 能运行吗? 每款 Apple Silicon Mac 的内存、芯片、磁盘和渲染时间,汇总在一页。

Phosphene 拒绝渲染时,会告诉你原因和该怎么做。下面是大家实际会看到的提示。如果问题出在安装或更新阶段(Pinokio 里出现 FATAL error: 一行,或磁盘空间不足),请看安装、更新和磁盘空间。

内存和这台 Mac 的档位

顶部的健康状态标签会直观显示内存情况;点击它可以看到档位、内存、Helper、模型、队列和渲染几行。点击档位,可以看到这台 Mac 能运行什么。

  • “Helper killed by the OS, out of memory”:macOS 终止了这次渲染。请关闭占内存的应用(浏览器、Slack、iOS 模拟器)后重试,或者把画质切到快速,它大约只用一半内存。
  • “Image pre-flight: … needs a N GB Mac”:这个图像引擎在这台 Mac 上放不下。在 16 GB 及以下的 Mac 上,如果设置里选的引擎需要更大的 Mac,自动会改用 FLUX.2 [klein] 4B,而不会改动设置。这要求渲染时不带参考图;去掉参考图就能让“自动”使用 Klein,或者在设置里换一个更轻的引擎。”… needs ~N GB free” 表示引擎本身放得下,但内存当前被占用;这项检查现在会把 macOS 可以释放的内存和“自动”实际需要的内存都算进去。
  • “Training needs at least 24 GB of memory”:这台 Mac 无法进行角色训练。

16-60 GB Mac 上的 Hailuo H3

H3 的完整引擎需要 60 GB。从 16 GB 起,它会运行精简的 Q8 引擎,这个引擎只需在你的 Mac 上构建一次(低于 36 GB 时,渲染过程中会从硬盘读取模型):

  • 还没安装 H3: 在 Pinokio 的侧边栏里打开 Phosphene,点击 Install Hailuo H3 (second video engine, ~75 GB)。安装结束时会自动构建精简引擎(再等约 5 分钟)。
  • 已安装 H3,但缺少精简引擎,提示 “Hailuo H3 runs on this Mac, on its reduced-RAM lane … it is not built here yet”:在同一个侧边栏里点击 Build Hailuo H3 compact engine(约 5 分钟,不需要下载)。

面板运行期间,这两个入口都会出现在侧边栏里。

完成后,打开设置 → Hailuo H3 模型,选择自动或精简。低于 16 GB 时无法使用 H3:请改用 LTX 渲染,它支持所有模式。

模型或附加组件还没下载

  • “Enhance needs its language model, Gemma 3 (8.1 GB)“,适配器也是同样的情况:全新安装后,第一次点击开始,它们会在后台下载。提示会说明它是正在下载、在排队,还是在等待磁盘空间;点击立即下载可以马上开始。
  • “Extend needs the LTX-2.5 High add-on (the Q8 model), which isn’t downloaded on this Mac yet”:关键帧和高画质也一样。请在“模型”窗口里安装(点击健康状态标签,再点模型)。
  • “Upscale & Face Fix needs the LTX-2.5 Pixel Spatial Upscaler adapter”:在“模型”窗口里下载它,然后重新渲染。
  • “Stopped before rendering, the model weights are incomplete”:下载被中断了。打开“模型”窗口继续下载。设置 → 校验模型文件会检查每个文件,并为损坏的文件提供重新下载。

更新一开始就停止

在部分 Mac 上,4.19.7 之前版本的 Pinokio Update 会在第一秒就停下:Pinokio 的终端把 Update 自己命令文本里的 “error:” 当成了失败(#114)。Pinokio 运行的是你已安装版本里的 Update 脚本,所以修复只有在更新一次之后才会生效。

请改为在 Phosphene 内部更新一次:点击更新横幅里的立即更新(或者顶部的版本标签),等它显示更新完成,然后重启。或者在 Phosphene 文件夹(~/pinokio/api/<your Phosphene folder>)里打开终端,运行 git pull,再点一次 Pinokio 里的 Update,这时它运行的就是修复后的新脚本。之后这个按钮就正常了。

“Click Update”:引擎比面板旧

“This install’s vendored engine predates LTX-2.5’s text encoder … Click Update, and if the first click only moves the panel, click it once more.”

面板已经更新,但底层的引擎还没有。请点击 Pinokio 里 Phosphene 侧边栏的 Update。如果看起来没有变化,再点一次:由旧版本发起的更新会先更新它自己。对 H3 来说,“the installed Hailuo H3 runner is behind this panel” 的意思是:重新运行 Install Hailuo H3,磁盘上已有的所有权重都会保留。

如果你已经更新,但面板的表现仍像旧版本,说明它还在运行旧代码。这时顶部的版本标签会显示 Restart Phosphene:点击它,或者在 Pinokio 里先点 Stop,再点 Start。

GPU 看门狗

“the macOS GPU watchdog killed a Metal command buffer”:macOS 自己终止了一个运行时间过长的 GPU 任务。这是驱动层面的终止,并不是 Phosphene 的 bug,在 M1 和 M2 Mac 上最常见。Phosphene 会立刻用短 GPU 步骤(把 GPU 工作切成更小的块,稍微慢一点)把同一个任务再渲染一次,并记住这个规格:这台 Mac 上的下一次渲染会直接以短步骤开始,队列那一行也会这样说明。如果 macOS 在短步骤下仍然终止它,这个规格会在这台 Mac 上暂停 24 小时(或直到下次更新),卡片上会出现降低画质重试。如果问题反复出现,提示里会附上 GitHub issue 的链接,附上芯片型号、macOS 版本和崩溃日志最有帮助。

角色训练失败

“training exited with code 1”:训练器在完成前停止了。请在日志标签页查看真正的原因:内存不足被终止(换一台内存更大的 Mac,或者在有更小预设时改用更小的预设)、缺少 LTX-2.3 训练所需的下载(训练标签页自带的预检卡片会提供下载),或者超长描述导致描述编码超时。24 GB 以下的训练一定会失败,那样的 Mac 无法运行训练。

面板显示离线

提示 “Phosphene offline”,并且点击生成没有反应:说明面板进程没有响应。你正在输入的内容不会丢失:提示词会保持原样,面板重新运行后,页面会自动重连并接上队列。如果几秒钟内没有恢复,请从 Pinokio 的 Phosphene 侧边栏启动它。

队列自己暂停了

“Queue paused: the last N renders failed the same way”:连续三次渲染因为同样的问题失败后,Phosphene 会停止继续消耗队列里的其余任务,因为重试也解决不了这个问题。请先解决提示里指出的原因,然后点击继续;或者点击清空队列,丢弃剩下的任务重新开始。

重启后的队列

重启面板会恢复队列:面板停止时处于暂停状态的队列会自动重新开始,日志里也会注明这一点。

查看日志

底部面板里的日志标签页显示渲染日志。渲染中途失败时,以 step: 开头的最后一行会指出它到达的阶段,这一行是你在报告问题时最有用的信息。Pinokio 的 Terminal 里能看到同样的输出。

报告问题

顶部的小虫图标会打开报告问题。在发生了什么?下面写一两句话(至少 10 个字符,因为日志无法告诉我们你看到了什么);它会自动填入版本、你的 Mac 信息和最近的日志(错误行排在普通行前面),并在新标签页里打开一个 GitHub issue 供你完成,你在那里提交之前不会发送任何内容。Issue 在 github.com/mrbizarro/phosphene/issues。

来源:webapp/docs/troubleshooting.md,位于公开仓库。发布前已针对本网站审阅。译自英文原文。建议修改。