OpenMontage 在 Apple Silicon 上启用 MPS 本地视频生成与增强原理、配置与排障【免费下载链接】OpenMontageWorlds first open-source, agentic video production system. 12 production pipelines, 100 tools, 700 agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMontageOpenMontage 的本地 GPU 工具链视频生成、超分辨率、人脸修复通过 PyTorch 的 Metal Performance ShadersMPS后端在 M1/M2/M3/M4/M5 芯片的 Mac 上实现自动设备识别与推理。本文将完整讲解其硬件要求、安装步骤、设备选择与精度路由的底层实现并结合仓库源码与测试用例给出验证 MPS 生效与排查回退到 CPU 的完整方法。读完你可以在自己的 Apple Silicon Mac 上直接跑通 OpenMontage 的本地视频生产链路。适用环境与前置要求根据 docs/apple-silicon-mps.md使用 MPS 需要同时满足三个条件macOS 12.3Monterey或更高版本MPS 后端在 12.3 起随 PyTorch 官方轮子提供Apple Silicon MacM 系列芯片M1 / M2 / M3 / M4 / M5不支持 Intel MacPython 3.10并建议使用uv管理虚拟环境。需要说明的前提是MPS 只服务于 OpenMontage 的本地 GPU 工具upscale、face_restore、ltx_video_local、wan_video等大量走云端 API 的工具HeyGen、fal.ai、Kling 等与设备无关不在此文档讨论范围内。快速安装配置启用本地生成并安装依赖命令与官方文档保持一致# 启用本地生成环境变量开关必须在运行前导出 export VIDEO_GEN_LOCAL_ENABLEDtrue # 安装依赖 —— 默认 torch 轮子自带 MPS 支持 uv pip install diffusers transformers accelerate torch pillow requests # 超分辨率与人脸修复额外依赖 uv pip install realesrgan gfpgan关键点macOS 上无需 CUDA 专用构建也不需要单独的 MPS 包——uv pip install torch安装的官方轮子即包含 MPS 后端这是与 NVIDIA 平台最大的差异。在源码中VIDEO_GEN_LOCAL_ENABLED由 tools/video/_shared.py 的local_generation_enabled()解析接受true/1/yes三种取值local_generation_status()同文件第 286-294 行进一步校验diffusers与torch是否可导入两者齐备才把工具状态标记为ToolStatus.AVAILABLE。各本地工具的install_instructions统一来自local_install_instructions()第 297-309 行其中明确区分了三种硬件路径NVIDIA CUDA 开箱即用、Apple SiliconMPSmacOS ≥ 12.3开箱即用、CPU 兜底可用但较慢。设备自动选择原理get_torch_device() 的三档优先级OpenMontage 的设备选择收敛在一个函数上get_torch_device()位于 tools/video/_shared.py。它按如下优先级返回字符串设备名CUDANVIDIA GPU——存在即优先对扩散模型通常最快MPSApple Silicon Metal——M 系列 Mac 上的默认选择性能良好CPU——始终可用的兜底但明显更慢。实现上有几个值得注意的防御细节若import torch失败未安装直接返回cpuMPS 检测做了双重守卫先检查构建期支持torch.backends.mps.is_built()再检查运行期可用性is_available()两者都为真才返回mps对不含torch.backends.mps属性的旧版或非 macOS 构建用getattr兜底并捕获异常避免属性缺失导致崩溃。这些守卫行为在 tests/tools/test_mps_device.py 中有完整覆盖test_get_torch_device_returns_mps_when_cuda_absent无 CUDA 时走 MPS、test_get_torch_device_returns_cuda_when_availableCUDA 优先于 MPS、test_get_torch_device_cpu_when_mps_backend_missing模拟 Linux 轮子无 MPS 后端时回退 CPU、test_get_torch_device_returns_cpu_when_torch_not_installedtorch 不可导入时安全回退。测试通过sys.modules层注入假 torch 模块因此即使本机未安装 torch 也能运行。精度路由bfloat16 / float16 / float32 的自动切换设备选定之后模型加载的精度选择由load_diffusers_pipeline()tools/video/_shared.py统一处理设备推理精度原因CUDA支持 bf16torch.bfloat16精度与显存占用平衡最佳MPStorch.float16MPS 不支持 bfloat16float16 是 M 系列上的正确选择CPUtorch.float32float16 在 CPU 上是模拟运算不可靠Wan 本地引擎 tools/video/_wan_engine.py 采用完全相同的路由逻辑其resolve_precision()第 112-129 行在precisionauto且检测不到 CUDA 显存_vram_gb() 0即 CPU/MPS 环境时固定返回bf16注释明确说明原因int8/int4 量化后端bitsandbytes是 CUDA-only 的MPS 上无法使用量化只能走非量化精度。此外load_diffusers_pipeline()还顺带做了三件与内存相关的优化启用enable_attention_slicing()注意力切片降低峰值激活内存对 VAE 启用enable_tiling()与enable_slicing()瓦片化与切片解码720p 长片段尤其有效。内存与显存约束统一内存模型下的模型取舍Apple Silicon 采用统一内存unified memoryCPU 与 GPU 共享同一物理内存池因此没有独立显存但总量是硬约束。文档明确需要超过 16 GB 显存的模型在 16 GB 的 Mac 上可能放不下。如何判断一个模型是否超预算看工具的resource_profile.vram_mb。ResourceProfile定义在 tools/base_tool.py包含cpu_cores、ram_mb、vram_mb、disk_mb、network_required五个字段。各本地工具的预算可从源码直接读到工具vram_mbram_mb说明ltx_video_localLTX-21200016000见 tools/video/ltx_video_local.pywan_videoWan 2.x8000默认档16000见 tools/video/wan_video.pyupscaleReal-ESRGAN20484096见 tools/enhancement/upscale.pyface_restoreGFPGAN/CodeFormer20482048见 tools/enhancement/face_restore.py同一工具族内的具体模型预算在 tools/video/_shared.py 的变体表中逐条声明如wan2.1-14b的vram_mb为 24000wan2.2-t2v-a14b/wan2.2-i2v-a14b为 40000两个 14B 专家常驻wan2.1-1.3b为 8000hunyuan-1.5为 14000cogvideo-5b为 12000。16 GB 的 M 系列 Mac 建议优先选择 8-12 GB 档位的变体如 Wan 2.1 1.3B、LTX-2、CogVideoX 5BA14B 双专家模型大概率放不下。已知限制与规避方式文档列出的四条限制在源码中都有对应的实现落点bfloat16 不支持MPS 一律走 float16见上文精度路由这是由load_diffusers_pipeline()与load_wan_pipeline()的 dtype 分支共同保证的CPU offloading 仅限 CUDAenable_model_cpu_offload()是 CUDA-only 接口。MPS 上管道会回退为直接设备放置pipeline.to(device)。在 tools/video/_shared.py 中可见enable_offloadTrue时只有device cuda才调用 offload否则一律.to(device)tests/tools/test_mps_device.py 的test_load_diffusers_pipeline_offload_falls_back_on_mps专门断言了 MPS 上不得调用enable_model_cpu_offload()且必须回退到.to(mps)Real-ESRGAN 半精度 NaN 风险fp16 在 MPS 上可能产生 NaN 伪影因此非 CUDA 设备自动使用 fp32。实现位于 tools/enhancement/upscale.pyhalf _device cuda只有 CUDA 才开半精度低内存主机的分块推理同一处代码还做了额外保护——tile 0 if _device cuda else 256第 303 行。注释指出全帧 x4 推理在低内存的 CPU/MPS 主机上可能在 Python 抛出异常前就终止进程因此 MPS/CPU 用 256 的 tile 限制工作集CUDA 保留更快的单遍路径。从源码看 MPS 支持如何落地到各本地工具upscaleReal-ESRGAN 超分tools/enhancement/upscale.py 的_build_upsampler()是 MPS 适配的典型样本通过get_torch_device()取设备据此决定half与tile见上文用inspect.signature(RealESRGANer.__init__)检查安装版本的构造器是否接受device参数接受才传入torch.device(_device)否则跳过。这个签名守卫是为了兼容不同版本的 realesrgan 包对应的两条测试test_upscale_build_upsampler_uses_signature_guard/test_upscale_build_upsampler_skips_device_when_unsupported在 tests/tools/test_mps_device.py 中验证了两种分支都不会抛TypeError视频超分走「ffmpeg 抽帧 → 逐帧增强 → ffmpeg 重组并复制原音频」的流程第 206-259 行MPS 只影响中间的推理步骤。face_restoreGFPGAN / CodeFormer 人脸修复tools/enhancement/face_restore.py 的install_instructions明确写到「Works on: CUDA (NVIDIA), MPS (Apple Silicon M-series, macOS 12.3), CPU fallback」并强调 macOS 上uv pip install torch已包含 MPS 支持。测试test_local_gpu_tool_mentions_apple_silicon遍历了FaceRestore与LTXVideoLocal两个类的install_instructions强制要求其中必须出现 MPS / Apple / macOS 字样防止未来回归成「只讲 CUDA」的误导性文案。本地视频生成LTX / Wanltx_video_local与wan_video的install_instructions直接复用local_install_instructions()包含 Apple Silicon 说明实际生成统一走generate_local_video()tools/video/_shared.py或generate_wan()tools/video/_wan_engine.py。两条路径的设备与精度选择都收敛到上文讲过的get_torch_device() dtype 路由因此只要装了 torchM 系列 Mac 上这些工具就会自动落到 MPS无需任何额外配置。验证 MPS 是否生效按文档给出的最小验证方式from tools.video._shared import get_torch_device print(get_torch_device()) # Apple Silicon 上应输出 mps若在 Apple Silicon Mac 上打印出cpu按以下顺序排查macOS 版本是否为 12.3MPS 后端的系统要求PyTorch 是否已安装uv pip install torch未安装时get_torch_device()因 import 失败直接返回cpu是否运行在原生 ARM Python 下Rosetta x86 转译环境会丢失 MPS 可用性确认python -c import platform; print(platform.machine())输出arm64。补充一条更细的验证途径直接检查 torch 自身的 MPS 状态——import torch print(torch.backends.mps.is_built()) # 构建期是否包含 MPS print(torch.backends.mps.is_available()) # 运行期是否可用get_torch_device()正是把这两个标志位同时作为判据的见 tools/video/_shared.py任一为假都会回退cpu。测试保障设备路由的回归防线MPS 支持并非一次性适配仓库通过 tests/tools/test_mps_device.py 建立了分层回归防线覆盖设备路由CUDA 缺失时返回mps、CUDA 存在时优先、MPS 不可用/未构建/后端缺失时回退cpu、torch 未安装时安全回退管道加载MPS 上from_pretrained(..., torch_dtypefloat16)且.to(mps)MPS 上禁止调用 CUDA-only 的 offloadCPU 兜底必须用float32签名守卫RealESRGANer/GFPGANer是否接受device的两种分支文案约束本地 GPU 工具的install_instructions必须向 Apple Silicon 用户说明 MPS 可用不得只写 CUDA。这套测试在无 torch 环境下通过模块级 mock 也能运行意味着 CI 中即使没有 Mac 硬件也能守住设备路由与精度路由的核心逻辑不被破坏。综上OpenMontage 的 MPS 支持是一个「一次路由、处处复用」的设计设备检测、精度切换、内存优化全部收敛在get_torch_device()与load_diffusers_pipeline()两个共享助手内上层各本地工具零侵入接入你在 M 系列 Mac 上要做的只是导出VIDEO_GEN_LOCAL_ENABLEDtrue、装好依赖然后让工具自己选择最合适的执行路径。【免费下载链接】OpenMontageWorlds first open-source, agentic video production system. 12 production pipelines, 100 tools, 700 agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMontage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenMontage 在 Apple Silicon 上启用 MPS 本地视频生成与增强：原理、配置与排障
OpenMontage 在 Apple Silicon 上启用 MPS 本地视频生成与增强原理、配置与排障【免费下载链接】OpenMontageWorlds first open-source, agentic video production system. 12 production pipelines, 100 tools, 700 agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMontageOpenMontage 的本地 GPU 工具链视频生成、超分辨率、人脸修复通过 PyTorch 的 Metal Performance ShadersMPS后端在 M1/M2/M3/M4/M5 芯片的 Mac 上实现自动设备识别与推理。本文将完整讲解其硬件要求、安装步骤、设备选择与精度路由的底层实现并结合仓库源码与测试用例给出验证 MPS 生效与排查回退到 CPU 的完整方法。读完你可以在自己的 Apple Silicon Mac 上直接跑通 OpenMontage 的本地视频生产链路。适用环境与前置要求根据 docs/apple-silicon-mps.md使用 MPS 需要同时满足三个条件macOS 12.3Monterey或更高版本MPS 后端在 12.3 起随 PyTorch 官方轮子提供Apple Silicon MacM 系列芯片M1 / M2 / M3 / M4 / M5不支持 Intel MacPython 3.10并建议使用uv管理虚拟环境。需要说明的前提是MPS 只服务于 OpenMontage 的本地 GPU 工具upscale、face_restore、ltx_video_local、wan_video等大量走云端 API 的工具HeyGen、fal.ai、Kling 等与设备无关不在此文档讨论范围内。快速安装配置启用本地生成并安装依赖命令与官方文档保持一致# 启用本地生成环境变量开关必须在运行前导出 export VIDEO_GEN_LOCAL_ENABLEDtrue # 安装依赖 —— 默认 torch 轮子自带 MPS 支持 uv pip install diffusers transformers accelerate torch pillow requests # 超分辨率与人脸修复额外依赖 uv pip install realesrgan gfpgan关键点macOS 上无需 CUDA 专用构建也不需要单独的 MPS 包——uv pip install torch安装的官方轮子即包含 MPS 后端这是与 NVIDIA 平台最大的差异。在源码中VIDEO_GEN_LOCAL_ENABLED由 tools/video/_shared.py 的local_generation_enabled()解析接受true/1/yes三种取值local_generation_status()同文件第 286-294 行进一步校验diffusers与torch是否可导入两者齐备才把工具状态标记为ToolStatus.AVAILABLE。各本地工具的install_instructions统一来自local_install_instructions()第 297-309 行其中明确区分了三种硬件路径NVIDIA CUDA 开箱即用、Apple SiliconMPSmacOS ≥ 12.3开箱即用、CPU 兜底可用但较慢。设备自动选择原理get_torch_device() 的三档优先级OpenMontage 的设备选择收敛在一个函数上get_torch_device()位于 tools/video/_shared.py。它按如下优先级返回字符串设备名CUDANVIDIA GPU——存在即优先对扩散模型通常最快MPSApple Silicon Metal——M 系列 Mac 上的默认选择性能良好CPU——始终可用的兜底但明显更慢。实现上有几个值得注意的防御细节若import torch失败未安装直接返回cpuMPS 检测做了双重守卫先检查构建期支持torch.backends.mps.is_built()再检查运行期可用性is_available()两者都为真才返回mps对不含torch.backends.mps属性的旧版或非 macOS 构建用getattr兜底并捕获异常避免属性缺失导致崩溃。这些守卫行为在 tests/tools/test_mps_device.py 中有完整覆盖test_get_torch_device_returns_mps_when_cuda_absent无 CUDA 时走 MPS、test_get_torch_device_returns_cuda_when_availableCUDA 优先于 MPS、test_get_torch_device_cpu_when_mps_backend_missing模拟 Linux 轮子无 MPS 后端时回退 CPU、test_get_torch_device_returns_cpu_when_torch_not_installedtorch 不可导入时安全回退。测试通过sys.modules层注入假 torch 模块因此即使本机未安装 torch 也能运行。精度路由bfloat16 / float16 / float32 的自动切换设备选定之后模型加载的精度选择由load_diffusers_pipeline()tools/video/_shared.py统一处理设备推理精度原因CUDA支持 bf16torch.bfloat16精度与显存占用平衡最佳MPStorch.float16MPS 不支持 bfloat16float16 是 M 系列上的正确选择CPUtorch.float32float16 在 CPU 上是模拟运算不可靠Wan 本地引擎 tools/video/_wan_engine.py 采用完全相同的路由逻辑其resolve_precision()第 112-129 行在precisionauto且检测不到 CUDA 显存_vram_gb() 0即 CPU/MPS 环境时固定返回bf16注释明确说明原因int8/int4 量化后端bitsandbytes是 CUDA-only 的MPS 上无法使用量化只能走非量化精度。此外load_diffusers_pipeline()还顺带做了三件与内存相关的优化启用enable_attention_slicing()注意力切片降低峰值激活内存对 VAE 启用enable_tiling()与enable_slicing()瓦片化与切片解码720p 长片段尤其有效。内存与显存约束统一内存模型下的模型取舍Apple Silicon 采用统一内存unified memoryCPU 与 GPU 共享同一物理内存池因此没有独立显存但总量是硬约束。文档明确需要超过 16 GB 显存的模型在 16 GB 的 Mac 上可能放不下。如何判断一个模型是否超预算看工具的resource_profile.vram_mb。ResourceProfile定义在 tools/base_tool.py包含cpu_cores、ram_mb、vram_mb、disk_mb、network_required五个字段。各本地工具的预算可从源码直接读到工具vram_mbram_mb说明ltx_video_localLTX-21200016000见 tools/video/ltx_video_local.pywan_videoWan 2.x8000默认档16000见 tools/video/wan_video.pyupscaleReal-ESRGAN20484096见 tools/enhancement/upscale.pyface_restoreGFPGAN/CodeFormer20482048见 tools/enhancement/face_restore.py同一工具族内的具体模型预算在 tools/video/_shared.py 的变体表中逐条声明如wan2.1-14b的vram_mb为 24000wan2.2-t2v-a14b/wan2.2-i2v-a14b为 40000两个 14B 专家常驻wan2.1-1.3b为 8000hunyuan-1.5为 14000cogvideo-5b为 12000。16 GB 的 M 系列 Mac 建议优先选择 8-12 GB 档位的变体如 Wan 2.1 1.3B、LTX-2、CogVideoX 5BA14B 双专家模型大概率放不下。已知限制与规避方式文档列出的四条限制在源码中都有对应的实现落点bfloat16 不支持MPS 一律走 float16见上文精度路由这是由load_diffusers_pipeline()与load_wan_pipeline()的 dtype 分支共同保证的CPU offloading 仅限 CUDAenable_model_cpu_offload()是 CUDA-only 接口。MPS 上管道会回退为直接设备放置pipeline.to(device)。在 tools/video/_shared.py 中可见enable_offloadTrue时只有device cuda才调用 offload否则一律.to(device)tests/tools/test_mps_device.py 的test_load_diffusers_pipeline_offload_falls_back_on_mps专门断言了 MPS 上不得调用enable_model_cpu_offload()且必须回退到.to(mps)Real-ESRGAN 半精度 NaN 风险fp16 在 MPS 上可能产生 NaN 伪影因此非 CUDA 设备自动使用 fp32。实现位于 tools/enhancement/upscale.pyhalf _device cuda只有 CUDA 才开半精度低内存主机的分块推理同一处代码还做了额外保护——tile 0 if _device cuda else 256第 303 行。注释指出全帧 x4 推理在低内存的 CPU/MPS 主机上可能在 Python 抛出异常前就终止进程因此 MPS/CPU 用 256 的 tile 限制工作集CUDA 保留更快的单遍路径。从源码看 MPS 支持如何落地到各本地工具upscaleReal-ESRGAN 超分tools/enhancement/upscale.py 的_build_upsampler()是 MPS 适配的典型样本通过get_torch_device()取设备据此决定half与tile见上文用inspect.signature(RealESRGANer.__init__)检查安装版本的构造器是否接受device参数接受才传入torch.device(_device)否则跳过。这个签名守卫是为了兼容不同版本的 realesrgan 包对应的两条测试test_upscale_build_upsampler_uses_signature_guard/test_upscale_build_upsampler_skips_device_when_unsupported在 tests/tools/test_mps_device.py 中验证了两种分支都不会抛TypeError视频超分走「ffmpeg 抽帧 → 逐帧增强 → ffmpeg 重组并复制原音频」的流程第 206-259 行MPS 只影响中间的推理步骤。face_restoreGFPGAN / CodeFormer 人脸修复tools/enhancement/face_restore.py 的install_instructions明确写到「Works on: CUDA (NVIDIA), MPS (Apple Silicon M-series, macOS 12.3), CPU fallback」并强调 macOS 上uv pip install torch已包含 MPS 支持。测试test_local_gpu_tool_mentions_apple_silicon遍历了FaceRestore与LTXVideoLocal两个类的install_instructions强制要求其中必须出现 MPS / Apple / macOS 字样防止未来回归成「只讲 CUDA」的误导性文案。本地视频生成LTX / Wanltx_video_local与wan_video的install_instructions直接复用local_install_instructions()包含 Apple Silicon 说明实际生成统一走generate_local_video()tools/video/_shared.py或generate_wan()tools/video/_wan_engine.py。两条路径的设备与精度选择都收敛到上文讲过的get_torch_device() dtype 路由因此只要装了 torchM 系列 Mac 上这些工具就会自动落到 MPS无需任何额外配置。验证 MPS 是否生效按文档给出的最小验证方式from tools.video._shared import get_torch_device print(get_torch_device()) # Apple Silicon 上应输出 mps若在 Apple Silicon Mac 上打印出cpu按以下顺序排查macOS 版本是否为 12.3MPS 后端的系统要求PyTorch 是否已安装uv pip install torch未安装时get_torch_device()因 import 失败直接返回cpu是否运行在原生 ARM Python 下Rosetta x86 转译环境会丢失 MPS 可用性确认python -c import platform; print(platform.machine())输出arm64。补充一条更细的验证途径直接检查 torch 自身的 MPS 状态——import torch print(torch.backends.mps.is_built()) # 构建期是否包含 MPS print(torch.backends.mps.is_available()) # 运行期是否可用get_torch_device()正是把这两个标志位同时作为判据的见 tools/video/_shared.py任一为假都会回退cpu。测试保障设备路由的回归防线MPS 支持并非一次性适配仓库通过 tests/tools/test_mps_device.py 建立了分层回归防线覆盖设备路由CUDA 缺失时返回mps、CUDA 存在时优先、MPS 不可用/未构建/后端缺失时回退cpu、torch 未安装时安全回退管道加载MPS 上from_pretrained(..., torch_dtypefloat16)且.to(mps)MPS 上禁止调用 CUDA-only 的 offloadCPU 兜底必须用float32签名守卫RealESRGANer/GFPGANer是否接受device的两种分支文案约束本地 GPU 工具的install_instructions必须向 Apple Silicon 用户说明 MPS 可用不得只写 CUDA。这套测试在无 torch 环境下通过模块级 mock 也能运行意味着 CI 中即使没有 Mac 硬件也能守住设备路由与精度路由的核心逻辑不被破坏。综上OpenMontage 的 MPS 支持是一个「一次路由、处处复用」的设计设备检测、精度切换、内存优化全部收敛在get_torch_device()与load_diffusers_pipeline()两个共享助手内上层各本地工具零侵入接入你在 M 系列 Mac 上要做的只是导出VIDEO_GEN_LOCAL_ENABLEDtrue、装好依赖然后让工具自己选择最合适的执行路径。【免费下载链接】OpenMontageWorlds first open-source, agentic video production system. 12 production pipelines, 100 tools, 700 agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMontage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考