nikopueringer/CorridorKey

# CorridorKey https://github.com/user-attachments/assets/1fb27ea8-bc91-4ebc-818f-5a3b5585af08 当你在绿幕前拍摄物体时，主体的边缘不可避免地会与绿色背景融合。这会产生主体颜色与绿幕颜色混合的像素。传统的抠像工具很难解开这些颜色，迫使你花费数小时构建复杂的边缘蒙版或进行手动 Roto。即使是现代的“AI Roto”解决方案通常也只会输出粗糙的二值化蒙版，完全破坏了合成真实感所需的精细半透明像素。 我构建 CorridorKey 就是为了解决这个*色彩还原*问题。 你输入一帧原始的绿幕画面，神经网络就能将前景物体与绿幕完全分离。对于每一个像素，甚至是运动模糊或失焦边缘等高度透明的像素，模型都能预测出前景元素真实的、未经预乘的直通颜色，以及一个干净的线性 Alpha 通道。它不仅仅是猜测什么是不透明、什么是透明；它还会主动重建前景物体的颜色，就好像绿幕从未存在过一样。 无需再与低质量的蒙版作斗争，也无需为“核心”与“边缘”抠像而苦恼。只需给 CorridorKey 一点提示，它就能为你分离光线。 ## 注意！ 这是一个全新发布的版本，我确信你会发现许多可以改进的地方！我邀请大家来帮忙。加入我们的“Corridor Creates” Discord 来分享想法、作品、Fork 等等！https://discord.gg/zvwUrdWXJm 如果你想要一个易于安装、对艺术家友好的用户界面版 CorridorKey，请查看 [EZ-CorridorKey](https://github.com/edenaion/EZ-CorridorKey) 本项目使用 [uv](https://docs.astral.sh/uv/) 来管理依赖——它能一步搞定 Python 安装、虚拟环境和软件包，所以你完全不需要操心这些。只需运行适合你操作系统的安装脚本即可。 自然地，我还没有对所有内容进行测试。如果你遇到错误，请考虑根据需要修补代码并提交 Pull Request。 ## 功能特性 * **物理精确的色彩还原：** 干净地提取直通颜色的前景和线性 Alpha 通道，完美保留头发、运动模糊和半透明区域。 * **分辨率无关性：** 引擎动态调整推理规模以处理 4K 素材，同时使用其原生的 2048x2048 高保真主干网络进行预测。 * **VFX 标准输出：** 原生读写 16 位和 32 位线性浮点 EXR 文件，保留真实的色彩数学运算，以便在 Nuke、Fusion 或 Resolve 中进行整合。 * **自动清理：** 包含形态学清理系统，可自动修剪掉任何逃过 CorridorKey 检测的跟踪标记或微小的背景特征。 ## 硬件要求 本项目是在配备 96GB 显存的 NVIDIA RTX Pro 6000 的 Linux 工作站（Puget Systems PC）上设计和构建的。社区正在积极为消费级 GPU 进行优化。 最新版本应该可以在具有 6-8GB 显存的计算机上运行，并且可以在大多数具有统一内存的 M1+ Mac 系统上运行。是的，它甚至可能可以在你那台旧的 MacBook Pro 上运行。请在 Discord 上告诉我们！ * **Windows 用户 (NVIDIA)：** 要在 Windows 上原生运行 GPU 加速，你的系统必须安装支持 **CUDA 12.8 或更高版本** 的 NVIDIA 驱动程序。如果你的驱动程序只支持较旧的 CUDA 版本，安装程序可能会退回到 CPU 模式。 * **AMD GPU 用户 (ROCm)：** 通过 ROCm 在 **Linux** 上支持 AMD Radeon RX 7000 系列 (RDNA3) 和 RX 9000 系列 (RDNA4)。Windows 上的 ROCm 支持是实验性的（torch.compile 尚未起作用）。请参阅下文的 [AMD ROCm 设置](#amd-rocm-setup) 部分。 * **GVM（可选）：** 需要大约 **80 GB 显存**，并使用大型的 Stable Video Diffusion 模型。 * **VideoMaMa（可选）：** 原生也需要大块显存（最初为 80GB+）。虽然社区已经调整了架构，使其能在不到 24GB 的环境下运行，但这些极限的内存优化尚未完全实现于此仓库中。 * **BiRefNet（可选）：** 轻量级 AlphaHint 生成器选项。 由于 GVM 和 VideoMaMa 的模型文件体积巨大且硬件要求极高，因此它们的模块安装完全是可选的。你可以随时提供由你的剪辑软件、BiRefNet 或任何其他方法生成的自定义 Alpha 提示。AlphaHint 质量越高，结果就越好。 ## 新手入门 ### 1. 安装 本项目使用 **[uv](https://docs.astral.sh/uv/)** 来管理 Python 及所有依赖项。uv 是 pip 的快速、现代替代品，可一步自动处理 Python 版本、虚拟环境和软件包安装。你**不需要**自己安装 Python——uv 会为你完成。 **对于 Windows 用户（自动安装）：** 1. 将此仓库 Clone 或下载到你的本地计算机。 2. 双击 `Install_CorridorKey_Windows.bat`。这将自动安装 uv（如果需要）、设置你的 Python 环境、安装所有依赖项并下载 CorridorKey 模型。 3. （可选）双击 `Install_GVM_Windows.bat` 和 `Install_VideoMaMa_Windows.bat` 以下载庞大的可选 Alpha 提示生成器权重。 **对于 Linux / Mac 用户（自动安装）：** 1. 将此仓库 Clone 或下载到你的本地计算机。 2. 打开终端并输入 `bash`。在 `bash` 后面留一个空格。 3. 将 `Install_CorridorKey_Linux_Mac.sh` 拖放到终端中。然后按回车键。 4. （可选）再次执行第 2 步。但这次拖入 `Install_GVM_Linux_Mac.sh` 和 `Install_VideoMaMa_Linux_Mac.sh` 以下载庞大的可选 Alpha 提示生成器权重。 **对于 Linux / Mac 用户（手动安装）：** 1. 将此仓库 Clone 或下载到你的本地计算机。 2. 如果你还没有安装 uv，请安装它： curl -LsSf https://astral.sh/uv/install.sh | sh 3. 安装所有依赖项（如果需要，uv 会自动下载 Python 3.10+）： uv sync # CPU/MPS（默认 — 通用） uv sync --extra cuda # CUDA GPU 加速 uv sync --extra mlx # Apple Silicon MLX 加速 关于 **AMD ROCm** 的设置，请参阅下文的 [AMD ROCm 设置](#amd-rocm-setup) 部分。 4. **下载模型：** * **CorridorKey v1.0 模型 (~300MB)：** 在首次运行时自动下载。如果在 `CorridorKeyModule/checkpoints/` 中未找到检查点，引擎会从 [CorridorKey 的 HuggingFace](https://huggingface.co/nikopueringer/CorridorKey_v1.0) 获取并将其保存为 `CorridorKey_v1.0.safetensors`（首选 — 更安全，无 pickle）。如果已存在旧的 `.pth` 文件，它们仍会被自动加载。无需手动下载。 * **GVM 权重（可选）：** [HuggingFace: geyongtao/gvm](https://huggingface.co/geyongtao/gvm) * 使用 CLI 下载：`uv run hf download geyongtao/gvm --local-dir gvm_core/weights` * **VideoMaMa 权重（可选）：** [HuggingFace: SammyLim/VideoMaMa](https://huggingface.co/SammyLim/VideoMaMa) * 下载 VideoMaMa 微调后的权重： uv run hf download SammyLim/VideoMaMa --local-dir VideoMaMaInferenceModule/checkpoints/VideoMaMa * VideoMaMa 还需要 Stable Video Diffusion 基础模型（仅 VAE + 图像编码器，约 2.5GB）。在 [stabilityai/stable-video-diffusion-img2vid-xt](https://huggingface.co/stabilityai/stable-video-diffusion-img2vid-xt) 接受许可协议，然后： uv run hf download stabilityai/stable-video-diffusion-img2vid-xt \ --local-dir VideoMaMaInferenceModule/checkpoints/stable-video-diffusion-img2vid-xt \ --include "feature_extractor/*" "image_encoder/*" "vae/*" "model_index.json" * VideoMaMa 是一个非常棒的项目，请去给他们的 [仓库](https://github.com/cvlab-kaist/VideoMaMa) 点个 Star 以示支持！ ### 2. 工作原理 CorridorKey 处理一帧画面需要两个输入： 1. **原始 RGB 图像：** 待处理的绿幕素材。这需要 sRGB 色域（可与 REC709 色域互换），引擎可以摄取 sRGB gamma 或 Linear gamma 曲线。 2. **粗糙的 Alpha 提示：** 一个粗略的黑白蒙版，大致隔离出主体。这*不需要*非常精确。你可以通过粗略的色度抠像或 AI Roto 来生成它。 我在使用 GVM 或 VideoMaMa 创建 AlphaHint 时取得了最好的效果，因此我重新打包了这些项目，并将它们作为可选模块集成到了 `clip_manager.py` 中。以下是它们的比较： * **GVM：** 完全自动，无需额外输入。它对人像的处理效果非常出色，但对无生命物体可能会遇到困难。 * **VideoMaMa：** 需要你提供一个粗略的 VideoMamaMaskHint（通常由手绘或 AI 生成）来告诉它你想抠出什么。如果你选择使用它，请将你的蒙版提示放置在向导为你的镜头创建的 `VideoMamaMaskHint/` 文件夹中。VideoMaMa 的结果令人惊叹，并且由于有了这个蒙版提示，它比 GVM 更容易控制。 * **请**去给这些项目的创作者点个赞，并为他们的仓库加星。[VideoMaMa](https://github.com/cvlab-kaist/VideoMaMa) 和 [GVM](https://github.com/aim-uofa/GVM) 也许在未来，我会为 AlphaHint 实现其他的生成器！与此同时，你的 Alpha 提示越好，CorridorKey 的最终结果就越好。尝试不同程度的蒙版腐蚀或羽化。该模型是在粗糙、模糊、被腐蚀过的蒙版上训练的，非常擅长根据提示补充细节。然而，如果你的 Alpha 提示扩展得太远，它在减去不需要的蒙版细节方面通常效果较差。 请提供反馈并分享你的结果！ ### Docker (Linux + NVIDIA GPU) 如果你不想在本地安装依赖项，可以在 Docker 中运行 CorridorKey。 前置条件： - 已安装 Docker Engine + Docker Compose 插件。 - 主机上已安装 NVIDIA 驱动程序，并且与本项目中使用的 PyTorch CUDA 12.6 wheel 包兼容。 - 已安装并配置好用于 Docker 的 NVIDIA Container Toolkit（主机上应能正常运行 `nvidia-smi`，且 `docker run --rm --gpus all nvidia/cuda:12.6.3-runtime-ubuntu22.04 nvidia-smi` 命令应能成功执行）。 1. 构建镜像： docker build -t corridorkey:latest . 2. 直接运行操作（示例：推理）： docker run --rm -it --gpus all \ -e OPENCV_IO_ENABLE_OPENEXR=1 \ -v "$(pwd)/ClipsForInference:/app/ClipsForInference" \ -v "$(pwd)/Output:/app/Output" \ -v "$(pwd)/CorridorKeyModule/checkpoints:/app/CorridorKeyModule/checkpoints" \ -v "$(pwd)/gvm_core/weights:/app/gvm_core/weights" \ -v "$(pwd)/VideoMaMaInferenceModule/checkpoints:/app/VideoMaMaInferenceModule/checkpoints" \ corridorkey:latest run_inference --device cuda 3. Docker Compose（推荐用于重复运行）： docker compose build docker compose --profile gpu run --rm corridorkey run_inference --device cuda docker compose --profile gpu run --rm corridorkey list docker compose --profile cpu run --rm corridorkey-cpu run_inference --device cpu 4. 可选：在多 GPU 工作站上绑定到特定的 GPU： NVIDIA_VISIBLE_DEVICES=0 docker compose --profile gpu run --rm corridorkey list NVIDIA_VISIBLE_DEVICES=1,2 docker compose --profile gpu run --rm corridorkey run_inference --device cuda 备注： - 你仍然需要将模型权重放置在原生运行所使用的相同文件夹中（已在上方挂载）。 - 容器不包含内核 GPU 驱动；这些始终由主机提供。镜像提供用户空间依赖项，并依赖 Docker 的 NVIDIA 运行时来传递驱动库/设备。 - 向导也能运行，但请使用容器内的路径，例如： docker run --rm -it --gpus all \ -e OPENCV_IO_ENABLE_OPENEXR=1 \ -v "$(pwd)/ClipsForInference:/app/ClipsForInference" \ -v "$(pwd)/Output:/app/Output" \ -v "$(pwd)/CorridorKeyModule/checkpoints:/app/CorridorKeyModule/checkpoints" \ -v "$(pwd)/gvm_core/weights:/app/gvm_core/weights" \ -v "$(pwd)/VideoMaMaInferenceModule/checkpoints:/app/VideoMaMaInferenceModule/checkpoints" \ corridorkeylatest wizard --win_path /app/ClipsForInference docker compose --profile gpu run --rm corridorkey wizard --win_path /app/ClipsForInference ### 3. 使用方法：命令行向导 为了获得最简单的体验，请使用提供的启动脚本。这些脚本会在你的终端中启动一个基于提示的配置向导。 * **Windows：** 将视频文件或文件夹拖放到 `CorridorKey_DRAG_CLIPS_HERE_local.bat` 上（注意：只能通过拖放或 CMD 启动。直接双击 `.bat` 文件会报错）。 * **Linux / Mac：** 运行或将视频文件或文件夹拖放到 `./CorridorKey_DRAG_CLIPS_HERE_local.sh` 上。 * - 或者在终端中再次输入 `bash`。留一个空格，然后分别将 `CorridorKey_DRAG_CLIPS_HERE_local.sh` 和你的剪辑文件夹一起拖放到终端中。然后按回车键。 **工作流步骤：** 1. **启动：** 你可以将单个松散的视频文件（如 `.mp4`）、包含图像序列的镜头文件夹，甚至是一次性包含多个不同镜头的主“批处理”文件夹拖放到启动脚本上。 2. **整理：** 向导会检测你拖入的内容。如果你拖入的是松散的视频文件或未整理的文件夹，第一个提示会询问你是否希望它将你的剪辑整理成正确的结构。 * 如果你选择是，脚本将自动创建一个镜头文件夹，将你的素材移动到 `Input/` 子文件夹中，并为你生成空的 `AlphaHint/` 和 `VideoMamaMaskHint/` 文件夹。引擎需要这种结构才能正确配对你的提示和素材！ 3. **生成提示（可选）：** 如果向导检测到你的镜头缺少 `AlphaHint`，它会询问你是否要使用重新打包的 GVM 或 VideoMaMa 模块自动生成它们。 4. **配置：** 一旦你的剪辑同时拥有输入和 AlphaHint，选择“Process Ready Clips”。向导将提示你配置运行参数： * **Gamma 空间：** 告诉引擎你的序列使用的是 Linear 还是 sRGB gamma 曲线。 * **去溢色强度：** 这是一个传统的去溢色滤镜（0-10），如果你希望现在就将其烘焙到输出中，而不是稍后在合成时再应用它。 * **自动去噪点：** 切换自动清理并定义大小阈值。这不仅适用于跟踪点，它还会移除任何微小、断开的像素孤岛。 * **细化强度：** 除非你正在尝试极限的细节推送，否则请使用默认值（1.0）。 5. **结果：** 引擎将在你的镜头目录中生成几个文件夹： * `/Matte`：原始的线性 Alpha 通道（EXR）。 * `/FG`：原始的直通前景颜色对象。（注意：引擎在 sRGB 色域中原生计算此项。在合成软件中与 Alpha 结合之前，你必须手动将此通道转换为 Linear gamma。） * `/Processed`：包含由线性 Alpha 预乘后的线性前景的 RGBA 图像（EXR）。这个通道的存在是为了让你可以立即将素材放入 Premiere/Resolve 进行快速预览，而无需处理复杂的预乘路由。然而，如果你想对图像进行更多控制，使用原始的 FG 和 Matte 输出将能满足你的需求。 * `/Comp`：在棋盘格上合成的抠像简单预览（PNG）。 ## 那么训练和数据集呢？ 如果有足够多的人觉得这个项目有趣，我会把训练程序和数据集上传，这样我们就可以一起尽情制作出绝对最好的抠像器微调版本！只需在 Corridor Creates Discord 或这里给我留言即可。如果有足够多的人感兴趣，我会把这些东西打包好。硬件要求很高，文件体积也很大，所以除非有需求，否则我不想投入时间。 ## 设备选择 默认情况下，CorridorKey 会自动检测最佳可用计算设备：**CUDA > MPS > CPU**。 **通过 CLI 标志覆盖：** ``` uv run python clip_manager.py --action wizard --win_path "V:\..." --device mps uv run python clip_manager.py --action run_inference --device cpu ``` **通过环境变量覆盖：** ``` export CORRIDORKEY_DEVICE=cpu uv run python clip_manager.py --action wizard --win_path "V:\..." ``` 优先级：`--device` 标志 > `CORRIDORKEY_DEVICE` 环境变量 > 自动检测。 ### Apple Silicon / MPS 故障排除 **确认 MPS 处于活动状态：** 运行详细日志记录以查看选择了哪个设备： ``` uv run python clip_manager.py --action list 2>&1 | grep -i "device\|backend\|mps" ``` **MPS 运算符错误**（`NotImplementedError: ... not implemented for 'MPS'`）：某些 PyTorch 操作尚未在 MPS 上受支持。为这些操作启用 CPU 回退： ``` export PYTORCH_ENABLE_MPS_FALLBACK=1 uv run python corridorkey_cli.py wizard --win_path "/path/to/clips" ``` **静默 CPU 回退**：如果没有设置此变量，MPS 静默回退到 CPU 将会使运行速度慢得多。在你的 shell 配置文件（`~/.zshrc`）中设置 `PYTORCH_ENABLE_MPS_FALLBACK=1` 可确保其始终处于活动状态。 **使用原生 MLX 而不是 PyTorch MPS：** MLX 完全避开了 PyTorch 的 MPS 层，通常在 Apple Silicon 上运行得更快。有关设置步骤，请参阅下文的 [后端选择](#backend-selection) 部分。 ### AMD ROCm 设置 CorridorKey 通过 PyTorch 的 ROCm/HIP 后端支持 AMD GPU。`torch.cuda.*` API 在 AMD 上透明运行——HIP 在运行时拦截所有 CUDA 调用，因此推理代码无需更改即可运行。 **支持的 GPU (ROCm 7.2+)：** - RX 7900 XTX (24GB) / XT (20GB) / GRE (16GB) — RDNA3, gfx1100 - RX 7800 XT (16GB) / 7700 XT (12GB) — RDNA3, gfx1101 - RX 9070 XT / 9070 (16GB) — RDNA4, gfx1201 **显存要求：** 在 2048x2048 下 CorridorKey 推理在 NVIDIA 上使用约 10GB，但由于 HIP 分配器开销，在 AMD 上使用约 18GB。RX 7900 XTX (24GB) 和 RX 7900 XT (20GB) 以全分辨率运行。具有 16GB 显存的显卡（RX 7800 XT、9070 XT）可在 Windows（使用系统内存作为溢出）上工作，但在 Linux 上可能会出现 OOM（内存不足）——请参阅下文的注释。 **Linux 原生（推荐）：** ``` uv sync --extra rocm # 验证 uv run python -c "import torch; print(torch.cuda.is_available(), torch.cuda.get_device_name(0))" ``` **WSL2 (Windows Subsystem for Linux)：** 需要在 Windows 上安装 AMD Adrenalin 26.1.1+ 驱动。在 WSL2 内部安装 ROCm，然后使用 AMD 特定于 WSL 的 torch wheel 包： ``` # 1. 为 WSL 安装 ROCm (Ubuntu 24.04) sudo apt update wget https://repo.radeon.com/amdgpu-install/7.2/ubuntu/noble/amdgpu-install_7.2.70200-1_all.deb sudo apt install ./amdgpu-install_7.2.70200-1_all.deb amdgpu-install -y --usecase=wsl,rocm --no-dkms # 2. 验证 GPU 是否可见 rocminfo # should show your AMD GPU # 3. 安装 AMD 的 WSL torch wheels (Python 3.12) pip3 install \ https://repo.radeon.com/rocm/manylinux/rocm-rel-7.2/torch-2.9.1%2Brocm7.2.0.lw.git7e1940d4-cp312-cp312-linux_x86_64.whl \ https://repo.radeon.com/rocm/manylinux/rocm-rel-7.2/torchvision-0.24.0%2Brocm7.2.0.gitb919bd0c-cp312-cp312-linux_x86_64.whl \ https://repo.radeon.com/rocm/manylinux/rocm-rel-7.2/triton-3.5.1%2Brocm7.2.0.gita272dfa8-cp312-cp312-linux_x86_64.whl # 4. 修复 WSL 运行时库冲突 (必需) location=$(pip3 show torch | grep Location | awk -F ": " '{print $2}') rm -f ${location}/torch/lib/libhsa-runtime64.so* # 5. 在 torch 之后安装 CorridorKey deps (以免 pip 覆盖 ROCm torch) pip3 install -e . ``` **Windows 原生（实验性）：** Windows ROCm 需要 Python 3.12 和 AMD Adrenalin 25.3.1+ 驱动。`torch.compile` 在 Windows ROCm 上不起作用——推理以 eager 模式运行（明显慢于 Linux）。 ``` py -3.12 -m pip install https://repo.radeon.com/rocm/windows/rocm-rel-7.2/rocm-7.2.0.dev0-py3-none-win_amd64.whl py -3.12 -m pip install --no-cache-dir https://repo.radeon.com/rocm/windows/rocm-rel-7.2/torch-2.9.1+rocmsdk20260116-cp312-cp312-win_amd64.whl https://repo.radeon.com/rocm/windows/rocm-rel-7.2/torchvision-0.24.1+rocmsdk20260116-cp312-cp312-win_amd64.whl ``` **CorridorKey 在 ROCm 上自动执行的操作：** - 设置 `TORCH_ROCM_AOTRITON_ENABLE_EXPERIMENTAL=1`，以便 SDPA 调度到 RDNA3 上的 Flash Attention 内核（如果没有这个，attention 会回退到缓慢的 O(n²) 路径） - 设置 `MIOPEN_FIND_MODE=2` 以更快地选择卷积内核（将预热时间从 5-8 分钟减少到几秒钟） - 在 Linux 上使用 `torch.compile(mode="default")` 以避免在 16GB 显卡上进行内核 autotuning 时发生 OOM - 在 Windows ROCm 上完全跳过 `torch.compile`，因为 Triton 编译会卡住 - 通过 `/opt/rocm`（Linux）、`HIP_PATH`（Windows）或 `CORRIDORKEY_ROCM=1` 环境变量（显式选择加入）自动检测 ROCm **首次运行注意事项：** 在新的 AMD GPU 上首次运行推理会触发 Triton 内核 autotuning（需要 10-20 分钟）。此内容会缓存在 `~/.cache/corridorkey/inductor/` 中，并且每个 GPU 架构只会发生一次。后续的运行会立即开始。 **Linux 上的 16GB 显卡：** CorridorKey 在 2048x2048 下需要约 18GB 显存。Windows 通过共享 GPU 内存（系统 RAM 溢出）透明地处理此问题。在 Linux 上，GPU 具有硬性的 VRAM 限制。如果你在 16GB 显卡上遇到 OOM，请安装 `pytorch-rocm-gtt` 以启用 GTT（系统 RAM 作为 GPU 溢出）——CorridorKey 会自动检测并使用它： ``` pip install pytorch-rocm-gtt ``` GTT 内存通过 PCIe 访问（比 VRAM 慢约 10-20 倍），因此预计 16GB 显卡的帧处理时间会比 20-24GB 显卡慢。 **WSL2 限制：** WSL2 无法使用 GTT 或共享内存——它具有硬性的 VRAM 限制。16GB 显卡在 WSL2 中以 2048x2048 运行时会出现 OOM。请改用 Windows 原生，或使用配备 20GB+ VRAM 的显卡。 ## 后端选择 CorridorKey 支持两种推理后端： - **Torch**（Linux/Windows 上的默认选项）— CUDA、MPS 或 CPU - **MLX** (Apple Silicon) — 原生 Metal 加速，无 Torch 开销 解决优先级：`--backend` 标志 > `CORRIDORKEY_BACKEND` 环境变量 > 自动检测。 自动模式在 Apple Silicon 上优先使用 MLX（如果可用）。 **通过 CLI 标志覆盖：** ``` uv run python corridorkey_cli.py wizard --win_path "/path/to/clips" --backend mlx uv run python corridorkey_cli.py run_inference --backend torch ``` ### MLX 设置 1. 安装 MLX 后端： uv sync --extra mlx 2. 获取 MLX 权重（`.safetensors`）——选择**一种**方式： **选项 A — 下载预转换的权重（最简单）：** # 将 weights 从 GitHub Releases 下载到本地缓存目录 uv run python -m corridorkey_mlx weights download # 打印缓存路径，然后复制到 checkpoints 文件夹 WEIGHTS=$(uv run python -m corridorkey_mlx weights download --print-path) cp "$WEIGHTS" CorridorKeyModule/checkpoints/corridorkey_mlx.safetensors **选项 B — 从现有的 `.pth` 检查点进行转换：** # 克隆 MLX repo (包含转换脚本) git clone https://github.com/nikopueringer/corridorkey-mlx.git cd corridorkey-mlx uv sync # 转换 (将 --checkpoint 指向你的 CorridorKey.pth) uv run python scripts/convert_weights.py \ --checkpoint ../CorridorKeyModule/checkpoints/CorridorKey_v1.0.pth \ --output ../CorridorKeyModule/checkpoints/corridorkey_mlx.safetensors cd .. 无论哪种方式，最终文件必须位于： CorridorKeyModule/checkpoints/corridorkey_mlx.safetensors 3. 使用自动检测或显式后端运行： CORRIDORKEY_BACKEND=mlx uv run python clip_manager.py --action run_inference MLX 默认使用 img_size=2048（与 Torch 相同）。 ### 故障排除 - **"No .safetensors checkpoint found"** — 请将 MLX 权重放置在 `CorridorKeyModule/checkpoints/` 中 - **"corridorkey_mlx not installed"** — 运行 `uv sync --extra mlx` - **"MLX requires Apple Silicon"** — MLX 仅在 M1+ Mac 上运行 - **Auto picked Torch unexpectedly** — 显式设置 `CORRIDORKEY_BACKEND=mlx` ## 高级用法 对于希望深入了解 CorridorKey 引擎具体操作细节的开发者，请查看 `/CorridorKeyModule` 文件夹中的 README。我们还有一份专门的交接文档，在 `/docs/LLM_HANDOVER.md` 中为 AI 助手概述了管道架构。 你也可以在 [DeepWiki](https://deepwiki.com/nikopueringer/CorridorKey) 上浏览完整的、自动生成的代码库文档。 ### 运行测试 本项目包含色彩数学和合成管道的单元测试。无需 GPU 或模型权重——测试可在任何机器上几秒钟内运行完毕。 ``` uv sync --group dev # install test dependencies (pytest) uv run pytest # run all tests uv run pytest -v # verbose output (shows each test name) ``` ## CorridorKey 许可和授权 你可以随意使用此工具，包括将其作为商业项目的一部分来处理图像！你不得重新打包此工具并将其出售，任何发布的此工具的变体或改进版本都必须保持在相同的许可下，并且必须包含 Corridor Key 的名称。 你不得将此模型的推理作为付费 API 服务提供。如果你运营商业软件包或推理服务，并希望将此工具整合到你的软件中，请给我们发送电子邮件以协商达成协议！我保证我们很容易合作。contact@corridordigital.com。除了上述规定外，此许可证实际上是 [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (CC BY-NC-SA 4.0)](https://creativecommons.org/licenses/by-nc-sa/4.0/) 的一种变体。 请在未来的任何分支或发行版中保留 Corridor Key 这个名字！ ## 社扩展 * [CorridorKeyOpenVINO](https://github.com/daniil-lyakhov/CorridorKeyOpenVINO) - 使用 OpenVINO 推理框架在 Intel 硬件上快速运行 CorridorKey 模型。 ## 致谢与许可 CorridorKey 集成了几个用于 Alpha 提示生成的开源模块。我们要明确感谢并致谢以下研究团队： * **Generative Video Matting (GVM)：** 由浙江大学先进智能机器 研究团队开发。GVM 的代码和模型在 `gvm_core` 模块中得到了大量使用。他们的工作基于 [2-clause BSD License (BSD-2-Clause)](https://opensource.org/license/bsd-2-clause) 授权。你可以在这里找到他们的源代码仓库：[aim-uofa/GVM](https://github.com/aim-uofa/GVM)。给他们点个 Star 吧！ * **VideoMaMa：** 由韩国科学技术院 (KAIST) 的 CVLAB 开发。VideoMaMa 架构被用于 `VideoMaMaInferenceModule` 中。他们的代码基于 [Creative Commons Attribution-NonCommercial 4.0 International License (CC BY-NC 4.0)](https://creativecommons.org/licenses/by-nc/4.0/) 发布，并且他们的特定基础模型检查点（`dino_projection_mlp.pth`、`unet/*`）受 [Stability AI Community License](https://stability.ai/license) 约束。你可以在这里找到他们的源代码仓库：[cvlab-kaist/VideoMaMa](https://github.com/cvlab-kaist/VideoMaMa)。给他们点个 Star 吧！ 使用这些可选模块即表示你同意遵守它们各自的非商业许可。请查看它们的仓库以获取完整条款。

标签：Alpha通道, Apex, DNS解析, Python, ROTO抠像, Vectored Exception Handling, 人工智能, 凭据扫描, 前景分离, 合成, 图像分割, 图像处理算法, 图像重建, 开源项目, 无后门, 机器学习, 深度学习, 用户模式Hook绕过, 神经网络, 绿幕抠像, 蒙版生成, 视觉特效, 视频后期处理, 视频编辑工具, 计算机视觉, 请求拦截, 逆向工具, 颜色解混