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

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

安装、更新和磁盘空间

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

Phosphene 通过 Pinokio 运行在 Apple 芯片的 Mac(M1 或更新)上。这一页说明如何安装和更新,需要多少磁盘空间,以及某一步失败时该怎么办。

用 Pinokio 安装

  1. 安装 Pinokio。
  2. 在 Pinokio 里打开 Discover,选择 Download from URL,粘贴 https://github.com/mrbizarro/phosphene。
  3. 点击 Install。安装程序会先检查你的可用磁盘空间。如果不够,它会停下来,并显示你需要多少、现有多少。
  4. 安装完成后,点击 Start,再点击 Open Panel。面板会在 http://127.0.0.1:8198 打开。

应用会在它的 Python 运行环境和引擎软件包准备好之后打开,通常需要几分钟。在点击 Start 之前不会下载任何模型,首次打开时也不会自动下载。先选好你想做的内容,再去下载对应的模型。

注意 Pinokio 无法在 Intel 的 Mac 或 Windows 上安装 Phosphene。Apple 芯片上的 Linux 支持是一个独立的社区项目,Pinokio 不会安装它。见 Linux(社区)。

会下载什么,需要多少空间

部分下载大小何时下载
应用运行环境:Python 和引擎软件包约 0.5 GB;软件包版本变化会影响这个数字在 Start 之前。请预留 18 GB 可用空间,其中包括 15 GB 的保底空闲
LTX-2.5 Q4 视频模型,含提示词编码器约 27.5 GB在应用里点击下载视频模型。推荐在做第一个视频时下载
功能附加项:用于优化和分镜规划器的 Gemma 3,以及用于超清放大与人脸修复、运动控制、Ingredients 和上色的适配器全部选择则为 10.7 GB只下载你会用到的,在对应功能里或模型中下载
图片模型显示在所选模型旁边第一次生成时。FLUX.2 [klein] 4B 是一个紧凑的起点,约 4.3 GB
LTX-2.5 Q8 权重,用于训练过的角色和声音30.02 GB可选,在设置 → 模型或 Pinokio 侧边栏中下载
高画质附加包,用于 LTX 上的高画质、关键帧和延长29.50 GB可选,在“模型”窗口中下载(点击健康状态标签,然后点模型)
Hailuo H3,第二个视频引擎约 75 GB可选,在 Pinokio 侧边栏中下载。见 Hailuo H3
音乐引擎(YuE2)约 11 GB可选,在音频标签页或 Pinokio 侧边栏中下载。见 Music Studio
LTX-2.3,只在训练角色时需要约 20 GB,另有训练器约 21 GB打开训练角色时会提示下载

在 100 Mbps 的网速下,视频模型约需 37 分钟下载完。300 Mbps 时约 12 分钟;1 Gbps 时约 4 分钟。模型下载期间应用可以一直开着。模型卡片会显示已接收的字节数、当前文件和剩余的包。停止下载会停止整个视频下载;再次点击下载视频模型即可继续。已下载的文件会留在磁盘上。从“模型”发起的下载会保持 15 GB 的空闲,空间不足时会等待。

如果某个功能需要的附加项还没有下载完,它会显示一条下载提示,或者提供立即下载。它不会无声无息地失败。

提示 你可以在设置里添加 Hugging Face 访问令牌,下载速度大约能提升十倍。HDR 是唯一必须使用这个令牌的附加项,其他一切都不需要它。

把模型放在外接硬盘上

模型占了大部分空间。在 Mac 应用(5.0.20 或更高版本)里,你可以把它们放在外接硬盘上,腾出 Mac 的空间。

  • 在设置时选择模型的存放位置:那一行*模型存放在……*有一个更改按钮,再选择其他磁盘或文件夹…。你也可以稍后在设置 > 模型中选择。
  • 之后再移动。在设置 > 模型里,移到其他磁盘…会把模型复制到那块硬盘并检查每个文件,之后才删除 Mac 上的副本。移回这台 Mac会把它们复制回来,并保留硬盘上的副本;如果想要这部分空间,请在访达里自行删除。移动过程会显示进度并有一个停止按钮,已停止的移动在你再次开始时会继续。模型移动期间 Studio 会关闭,到位之后会重新打开。
  • 只有模型会移动。应用和它的引擎仍留在你的 Mac 上,所以 Phosphene 始终可以打开。
  • 如果硬盘被拔掉,应用会显示*“(硬盘名称)未连接”*。请把它插上并选择重新检查,或选择改为下载,把草稿模型(约 27.5 GB)下载到这台 Mac 上,或者选择不带模型打开。
  • 硬盘格式。APFS 和 exFAT 硬盘可以使用。FAT32 无法存放超过 4 GB 的文件,而有些模型文件比这更大,所以 Phosphene 会拒绝 FAT32 硬盘。如果你的部分模型与 Pinokio 安装共用,请使用 APFS 或 Mac OS 扩展格式的硬盘。

只要 Phosphene 在运行,就请保持硬盘连接。

查看你的 Mac 内存

Mac 的内存决定了你能使用哪些画质设置和引擎。Phosphene 会自动检查这一点。要查看你的 Mac 能运行什么,点击页眉里的健康状态标签,再点档位。

功能所需内存
LTX 视频和图片任何 Apple 芯片的 Mac 都可以。内存低于 48 GB 时,只能使用较小的视频尺寸,LTX 的高画质、首尾帧和延长会被隐藏。内存 24 GB 或以下的 Mac 会自动使用低内存视频通道:在 16 GB 的 Mac 上,一个片段的内存峰值约为 5.7 GB,使用 LoRA 时约为 6.7 GB。
Music Studio16 GB 或以上。如果同时开着其他应用来做长歌曲,建议 24 GB 或以上
训练角色24 GB 或以上
Hailuo H316 GB 或以上(草稿和标准从 16 GB 起,高从 18 GB 起)。内存 60 GB 或以上时,还可以选择完整引擎
LTX 高画质 · 720p64 GB 的 Mac;内存占用峰值接近 50 GB

在进行较长的渲染之前,请关闭占用大量内存的应用,比如开了很多标签页的浏览器、Slack 或 iOS 模拟器。渲染就是创建视频或音频的过程。如果你的 Mac 内存耗尽,它会中止渲染。见疑难解答。

Pinokio 侧边栏

在 Pinokio 里选中 Phosphene,就能在左侧边栏看到这些操作。可用的操作取决于已安装的内容,以及面板是否在运行。

  • Install / Resume Install:安装必需的文件。如果上一次没有完成,会出现 Resume Install。已下载完成的文件会保留。
  • Start、Open Panel、Terminal:点击 Start 运行 Phosphene,再点击 Open Panel 使用它。Terminal 会显示它的活动日志。
  • Update:见更新。
  • Outputs、Models、Uploads:在访达里打开对应的文件夹。
  • Install Hailuo H3 (second video engine, ~75 GB):安装之后,它会变成 Repair Hailuo H3 或 Update Hailuo H3 runner。两者都会保留已下载的模型文件。
  • Build Hailuo H3 compact engine:在 16 到 59 GB 的 Mac 上,当模型文件已下载但精简引擎还没准备好时出现。大约需要 5 分钟,不会下载任何内容。
  • Install the music engine (YuE2, ~11 GB):安装之后,它会变成 Repair the music engine,会保留已下载的模型文件。
  • Reset engine (keeps models & outputs):重建 LTX 引擎和它所需的软件。它会保留你的模型和已完成的作品。它不影响 Hailuo H3;要修复 H3,请使用 Repair Hailuo H3。

更新 Phosphene

  • 页眉里的版本标签会显示已是最新,或者更新到后面跟着一个更新的版本。有可用更新时,点击横幅里的立即更新来安装,或点击稍后暂不更新。
  • 点击 Pinokio 侧边栏里的 Update,会更新所有内容,包括配套软件。你的队列、设置、模型和已完成的作品都会保留。
  • 应用内更新之后,横幅会显示*“已更新到 … 重启以完成”*。在 Pinokio 里先点 Stop,再点 Start。
  • 如果你是从很旧的版本更新,并且似乎只有面板发生了变化,请再点一次 Update。第一次更新会先替换更新程序本身。
  • 如果 Pinokio 的 Update 在开头一秒就停止(4.19.6 及更早版本可能出现),请改为点击 Phosphene 自己横幅或版本标签里的立即更新,然后重启。见更新立刻停止。
  • 如果面板的表现仍像旧版本,说明它需要重启。这时版本标签会显示 Restart Phosphene。点击它,或者在 Pinokio 里先点 Stop 再点 Start。
  • Hailuo H3 和音乐引擎各有独立的配套软件。如果面板提示其中任何一个需要更新,请点击 Pinokio 侧边栏里该引擎的 Update 或 Repair 项。已下载的模型文件会保留。

手动更新(更新没有送达时)

Phosphene 会自行检查更新,但网速慢或连接被屏蔽时,更新可能收不到。你随时可以自己安装最新版本。你的模型、已完成的作品、设置和 Pro 许可都会保留。

Mac 应用

  1. 退出 Phosphene(Phosphene → 退出,或 Cmd+Q)。
  2. 从 phosphene.video/download 下载最新的安装包(每个 GitHub 发布版本里也附有同一个文件)。
  3. 打开下载好的 .dmg,把 Phosphene 拖到应用程序上。Mac 询问时,选择替换。
  4. 从应用程序里打开 Phosphene。页眉里的版本标签会显示新版本。

请只保留一份,也就是应用程序里的那一份。留在“下载”文件夹或安装磁盘上的旧副本可能会代替新版本被打开:请把它们移到废纸篓,并在访达侧边栏里推出任何名为 Phosphene 的磁盘。你的作品保存在 ~/Library/Application Support/Phosphene,而不在应用内部,所以替换或删除应用不会影响它们。

Pinokio

  1. 在 Phosphene 的 Pinokio 侧边栏里点击 Stop。
  2. 打开“终端”应用,进入 Phosphene 文件夹(cd ~/pinokio/api/<your Phosphene folder>),运行 git pull。
  3. 点击侧边栏里的 Update,然后点 Start。

如果 git pull 提示你有本地修改,请先运行 git stash,再运行一次 git pull。

安装或更新因错误而中断时

如果某个必需的步骤失败,Pinokio 会停下来,并显示一行以 FATAL error: 开头的文字。请在 Pinokio 为这次安装或更新显示的日志里向上翻,找到它。这一行会说明问题,以及接下来该点什么。几乎所有情况下,都没有任何东西被删除。解决问题之后,再次点击 Install 或 Update 即可继续。

请用下面的表格,对照 FATAL error: 之后的文字:

那一行写的是该怎么做
not enough disk space to install Phosphene腾出它给出的空间,然后再次点击 Install
could not download the video engine version Phosphene needs … (a VPN, proxy or blocked GitHub is the usual cause)检查网络连接,关闭 VPN 或代理,然后再次点击 Install 或 Update
the engine environment did not install after 3 attempts检查网络连接和磁盘可用空间,然后再次点击 Install 或 Update。如果一再出现,请按下面的说明报告这一行
the video engine is on the wrong version再次点击 Install 或 Update。如果一再出现,请报告这一行
Hailuo H3 needs a Mac with at least 16 GB of memory你的 Mac 无法运行 H3。请继续使用 LTX,除了添加声音之外,它具备所有模式
Hailuo H3 needs about N GB of free disk space全新安装需要约 97 GB(75 GB 的下载加 22 GB 的精简引擎);如果模型文件已经下载,则约需 25 GB。腾出空间后,再次点击 Install Hailuo H3
the compact Hailuo H3 engine could not be built这通常意味着磁盘已满(构建需要约 22 GB)。腾出空间,然后再次点击 Pinokio 侧边栏里的 H3 项。它会根据已下载的模型文件重新构建
a Phosphene render has been running for over 60 minutes, so the compact Hailuo H3 engine was not built等 Phosphene 完成当前的渲染,然后再次点击 Pinokio 侧边栏里的 H3 项
the H3 venv has no working Python点击 Pinokio 侧边栏里的 Repair Hailuo H3。已下载的模型文件会保留
YuE2 (the music engine) needs a Mac with at least 16 GB of memory这台 Mac 无法运行音乐引擎。Phosphene 的其他部分不受影响
YuE2 (the music engine) needs at least 14 GB free腾出空间,然后再次点击 Install the music engine
could not download the YuE2 music engine检查网络连接,以及是否有 VPN 或代理屏蔽了 GitHub,然后再次点击 Install the music engine
untracked/ignored paths obstruct Update. Move them; nothing deleted.你在应用文件夹里添加的文件挡住了更新。紧挨着上方的几行会列出它们。请把它们移出 Phosphene 文件夹,然后再次点击 Update
fetch failed (offline?) - nothing changed, re-run Update重新连网,然后再次点击 Update
the Update safety check did not pass - not updating没有任何改动。再次点击 Update。如果一再出现,请报告这一行

如果你的错误没有列在表里,请按它的 FATAL error: 那一行里的指示操作。要报告错误,请把那一行和它上面的几行复制到问题报告里。见报告问题。

重新开始而不丢失你的作品

  • 在 Pinokio 里点击 Reset engine,可以重建 LTX 引擎。你的模型、已完成的作品和设置都会保留。
  • 要找到你完成的作品,请点击 Pinokio 侧边栏里的 Outputs。这会打开 Phosphene 文件夹里的 mlx_outputs。
  • 要找到你下载的模型,请点击侧边栏里的 Models。这会打开 mlx_models。除非你想重新下载所有内容,否则请不要删除这个文件夹。

如果 Phosphene 能打开,但某个任务失败、缺少模型,或者你的队列暂停了,请见疑难解答。

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