帮助文档 / 安装与故障排除
安装、更新和磁盘空间
我的 Mac 能运行吗? 每款 Apple Silicon Mac 的内存、芯片、磁盘和渲染时间,汇总在一页。
Phosphene 通过 Pinokio 运行在 Apple 芯片的 Mac(M1 或更新)上。这一页说明如何安装和更新,需要多少磁盘空间,以及某一步失败时该怎么办。
用 Pinokio 安装
- 安装 Pinokio。
- 在 Pinokio 里打开 Discover,选择 Download from URL,粘贴
https://github.com/mrbizarro/phosphene。 - 点击 Install。安装程序会先检查你的可用磁盘空间。如果不够,它会停下来,并显示你需要多少、现有多少。
- 安装完成后,点击 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 Studio | 16 GB 或以上。如果同时开着其他应用来做长歌曲,建议 24 GB 或以上 |
| 训练角色 | 24 GB 或以上 |
| Hailuo H3 | 16 GB 或以上(草稿和标准从 16 GB 起,高从 18 GB 起)。内存 60 GB 或以上时,还可以选择完整引擎 |
| LTX 高画质 · 720p | 64 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 应用
- 退出 Phosphene(Phosphene → 退出,或 Cmd+Q)。
- 从 phosphene.video/download 下载最新的安装包(每个 GitHub 发布版本里也附有同一个文件)。
- 打开下载好的
.dmg,把 Phosphene 拖到应用程序上。Mac 询问时,选择替换。 - 从应用程序里打开 Phosphene。页眉里的版本标签会显示新版本。
请只保留一份,也就是应用程序里的那一份。留在“下载”文件夹或安装磁盘上的旧副本可能会代替新版本被打开:请把它们移到废纸篓,并在访达侧边栏里推出任何名为 Phosphene 的磁盘。你的作品保存在 ~/Library/Application Support/Phosphene,而不在应用内部,所以替换或删除应用不会影响它们。
Pinokio
- 在 Phosphene 的 Pinokio 侧边栏里点击 Stop。
- 打开“终端”应用,进入 Phosphene 文件夹(
cd ~/pinokio/api/<your Phosphene folder>),运行git pull。 - 点击侧边栏里的 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,位于公开仓库。发布前已针对本网站审阅。译自英文原文。建议修改。