chaiNNer 保姆级部署教程：节点式图像处理流水线，从 AI 放大到批量视频处理全链路

chaiNNer 是一个节点式图像处理 GUI，最初作为 AI 放大（upscaling）工具诞生，后来发展成一个极其灵活强大的可编程图像处理应用。它的核心思路是：把图像处理的每一步（读图、放大、裁剪、调色、保存）做成一个"节点"，你用鼠标把这些节点连起来，就像搭积木一样组成一条完整的处理流水线。和站点此前写过的 Real-ESRGAN、Upscayl 相比，chaiNNer 不只是一个放大工具，而是一个"图像处理流水线编辑器"——你可以把放大、人脸修复、色彩调整、视频抽帧等步骤串成一条链，一次跑完。本文按官方 README，从下载安装、依赖管理、节点连线到批量处理全流程讲清楚。

一、项目介绍与适用场景

chaiNNer 由 chaiNNer-org 社区维护，GPLv3 协议发布。它的界面风格和 ComfyUI 很像（都是节点式），但定位不同：ComfyUI 专注于生成式 AI（文生图、图生图），chaiNNer 专注于图像处理流水线（放大、修复、调色、格式转换）。你可以把 chaiNNer 理解成"图像处理版的 ComfyUI"——不生成新图，而是把已有图片/视频按你定义的流程处理一遍。

适用场景：

• AI 图片放大：把低分辨率图片放大到高分辨率（ESRGAN、Real-ESRGAN、Waifu2x 等模型）；
• 批量处理：一个文件夹里几百张图，自动放大+裁剪+保存；
• 视频超分：Load Video 节点逐帧放大，再合回视频；
• 复杂图像处理流水线：读图→人脸检测→人脸修复→整体放大→调色→保存；
• 研究/实验：快速组合不同图像处理算法，验证效果。

与 Real-ESRGAN 命令行工具的区别：Real-ESRGAN 是单一功能的命令行工具，只能放大；chaiNNer 是可视化流水线编辑器，你可以把放大和其他步骤组合起来。与 Upscayl 的区别：Upscayl 是简单的"拖进去就放大"的 GUI，没有流水线概念；chaiNNer 给你完全的节点控制权。

什么是"节点式流水线"？想象你在 Photoshop 里做一张图：先打开原图、然后抠图、然后调色、然后放大、然后加文字、最后导出。每一步都是一个独立的操作，上一步的输出是下一步的输入。节点式流水线就是把这些"操作"变成一个个方块，用线连起来表示数据流向。chaiNNer 里，方块就是节点，线就是数据通道。你可以随时插入新节点（比如在放大前加一个人脸修复），也可以随时删掉某个节点，整个流水线会自动重新计算。

为什么要用节点式？因为图像处理经常需要多步组合。比如你想做"老照片修复"：读图→人脸检测→人脸修复→整体放大→降噪→保存。用命令行工具你得一条条敲命令，每一步手动处理中间文件；用 chaiNNer 你把这些节点连好，点 Run 就自动跑完所有步骤，中间文件不用你管。

二、核心功能逐条拆解

1. 节点式流水线：拖拽节点、连线组成处理流程。
2. 多推理框架：PyTorch（CUDA）、NCNN、ONNX、TensorRT。
3. AI 放大模型：通过 Spandrel 包支持各种 PyTorch 放大模型（ESRGAN 系、Real-ESRGAN 系等）。
4. 批量图片处理：Load Images 节点批量处理整个文件夹。
5. 视频处理：Load Video 节点逐帧处理视频。
6. 内置 Python：不需要系统装 Python，chaiNNer 自带集成 Python。
7. Dependency Manager：右上角按钮一键安装 PyTorch/NCNN/ONNX/TensorRT。
8. 跨平台：Windows、macOS、Linux。
9. GPU 加速：NVIDIA CUDA、AMD ROCm（Linux）、Apple Silicon MPS。
10. 模板分享：社区有现成的 chain 模板可以直接导入。
11. Spandrel 模型支持：通过 Spandrel 包自动识别各种 PyTorch 模型架构，不用手动指定模型类型。
12. 夜版构建：提供 nightly builds，想尝鲜最新功能可以下载。

三、全套官方链接

四、硬件与环境前置要求

官方 README 的 Compatibility Notes 和 GPU Support 小节明确：

• 系统：Windows 10+（8.1 及以下不支持）、macOS 11+（10.x 及以下不支持）、Linux；
• Python：不需要！chaiNNer 自带集成 Python。如果你坚持用系统 Python，需要 3.10+（推荐 3.11+）；
• GPU：
• NVIDIA：完整支持 PyTorch CUDA、ONNX、TensorRT（TensorRT 性能最好）；
• AMD：Linux 上用 PyTorch ROCm，全平台用 NCNN；
• Apple Silicon（M1/M2/M3）：支持 PyTorch MPS 加速；
• Intel：支持 NCNN 推理；
• CPU：所有框架都支持 CPU 模式（慢）。
• Linux 剪贴板：用 Clipboard 节点需要装 xclip（X11）或 wl-copy（Wayland）。

官方出处：README "Compatibility Notes" 和 "GPU Support" 两个小节。

补充说明：显存要求。放大一张 1024x1024 的图，用 Real-ESRGAN x4 模型大约需要 2-4GB 显存。如果你要放大 4K 大图，建议 6GB+ 显存。显存不够时，在 Upscale 节点里设置 tile size（比如 256 或 512），chaiNNer 会把大图切成小块逐块放大，最后拼回来——代价是速度慢一些，但不会 OOM。

五、多平台部署步骤

5.1 下载安装包（官方）

第 1 步：打开 https://github.com/chaiNNer-org/chaiNNer/releases ，下载最新版本的安装包。

第 2 步：按你的操作系统选对应安装包： - Windows：.exe 或 .msi； - macOS：.dmg； - Linux：.AppImage 或 .deb。

第 3 步：双击安装，按向导完成。chaiNNer 会自动下载一个隔离的集成 Python 环境，不影响你系统的 Python。

官方 README 原文："Download the latest release from the Github releases page and run the installer best suited for your system. Simple as that. You don't even need to have Python installed, as chaiNNer will download an isolated integrated Python build on startup."

5.2 安装依赖框架（官方 Dependency Manager）

第 1 步：启动 chaiNNer，点右上角的 Dependency Manager 按钮。

第 2 步：选择你需要的推理框架： - NVIDIA 用户：选 PyTorch（CUDA）或 TensorRT； - AMD 用户：选 NCNN（或 Linux 上的 PyTorch ROCm）； - Apple Silicon：选 PyTorch（会自动用 MPS）。

第 3 步：chaiNNer 会自动下载并安装对应的 Python 依赖。

官方 README 原文："You'll need to install one of the neural network frameworks from the dependency manager."

5.3 快速跑通 AI 放大（官方 Basic Usage）

第 1 步：在节点选择面板里搜索"Load Image"，双击添加到编辑器。

第 2 步：搜索"Upscale Image (using Model)"，双击添加。

第 3 步：搜索"Save Image"，双击添加。

第 4 步：连线： - Load Image 的输出 → Upscale 的输入； - Upscale 的输出 → Save Image 的输入。

第 5 步：在 Load Image 节点里选择要放大的图片；在 Upscale 节点里选择放大模型；在 Save Image 节点里选择输出路径。

第 6 步：点顶部绿色的 Run 按钮，开始处理。节点之间的连线会动起来，处理完的节点停止动画。

官方 README 原文："this is all you need to do in order to perform an upscale"——就是 Load Image → Upscale → Save Image 三个节点连起来。

六、配置文件全部参数解释

chaiNNer 无传统配置文件，参数都在节点上。按官方 README 整理关键节点：

七、启动、后台常驻与开机自启

chaiNNer 是桌面 GUI 应用，不是服务，没有"后台常驻"概念。直接双击图标启动即可。

如果你想做成批量处理服务（无 GUI 跑），官方未提供 headless 模式——chaiNNer 是桌面应用，所有操作都在 GUI 里完成。需要批量自动化的话，建议直接用对应框架的命令行工具（比如 Real-ESRGAN CLI）。

八、功能实操教程

第 1 步：装好 chaiNNer，用 Dependency Manager 装好 PyTorch（CUDA）。

第 2 步：从 https://openmodeldb.info/ 下载一个放大模型（比如 Real-ESRGAN x4），保存到本地。

第 3 步：搭一条最简单的放大流水线：Load Image → Upscale Image → Save Image。

第 4 步：点 Run，等几秒钟，输出目录里就有放大后的图。

第 5 步：批量处理整个文件夹：把 Load Image 换成 Load Images，指向你的图片文件夹。Run 一次，chaiNNer 会自动处理文件夹里所有图片。

第 6 步：视频超分：把 Load Images 换成 Load Video，Save Image 换成 Save Video。chaiNNer 会逐帧放大，再合回视频。注意官方说"不能同时用 Load Images 和 Load Video"。

第 7 步：组合复杂流水线：Load Image → 人脸修复节点 → 整体放大节点 → Save Image。把多个节点串起来，一次完成多步处理。

第 8 步：快捷键：按住 Shift 拖拽可以多选节点；右键删除；右键编辑器空白处弹出节点列表。

第 9 步：导入社区模板。如果你不想从零搭流水线，可以从 https://github.com/kimberly990/kim-chaiNNer-Templates/ 下载现成的 chain 模板，导入 chaiNNer 直接用。官方 README 推荐这个模板集作为新手入门资源。

第 10 步：选择放大模型。去 https://openmodeldb.info/ 下载模型，按用途分类： - 通用照片：Real-ESRGAN x4plus、BSRGAN； - 动漫/插画：Waifu2x、ESRGAN anime； - 人脸：GFPGAN、CodeFormer 相关模型。

下载 .pth 文件后，在 Upscale 节点里选这个文件即可。

第 11 步：保存和加载 chain。你搭好的流水线可以导出成 JSON 文件，下次直接导入，不用重新搭。点顶部菜单的 Export/Import 即可。和朋友分享你的流水线也很方便——把 JSON 发过去就能用。

九、全套报错故障排查

1. 报错：NCNN 下 AMD 显卡输出全黑。 原因分析：官方 README 说"some NCNN users with non-Nvidia GPUs might get all-black outputs"，可能是显卡驱动 OOM。 分步解决方案：在设置里手动设置 tiling（分块）大小；或换用 PyTorch 框架。

2. 报错：Apple Silicon 上 ONNX 不工作。 原因分析：官方 README 说"ONNX only supports the CPU Execution Provider"在 Apple Silicon 上。 分步解决方案：Apple Silicon 用户用 PyTorch（MPS），不要用 ONNX。

3. 报错：Linux 上 Clipboard 节点不能用。 原因分析：缺 xclip 或 wl-copy。 分步解决方案：X11 用户 sudo apt install xclip；Wayland 用户 sudo apt install wl-clipboard。

4. 报错：模型加载失败。 原因分析：模型文件格式不对，或框架不支持。 分步解决方案：PyTorch 模型用 Spandrel 支持的格式；去 OpenModelDB 下载经过验证的模型。

5. 报错：处理大图时 OOM。 原因分析：显存不够。 分步解决方案：在 Upscale 节点里设置 tile size（分块处理），把大图切成小块逐块放大。

6. 报错：安装包打不开或提示"已损坏"。 原因分析：macOS 安全策略，或 Windows SmartScreen。 分步解决方案：macOS 右键打开→确认；Windows 点"仍要运行"。

7. 报错：TensorRT 初始化失败。 原因分析：TensorRT 需要 NVIDIA 的 CUDA 和 cuDNN 环境，版本不对。 分步解决方案：先确认你的 NVIDIA 驱动支持 CUDA 12+；用 Dependency Manager 重装 TensorRT 框架；或先用 PyTorch 框架跑通再试 TensorRT。

8. 报错：NCNN 默认用了集成显卡而不是独立显卡。 原因分析：官方 README 说"For NCNN, make sure to select which GPU you want to use in the settings. It might be defaulting to your integrated graphics!" 分步解决方案：打开 Settings，找到 NCNN 设置，手动选你的独立显卡。

9. 报错：Load Video 处理视频很慢。 原因分析：视频是逐帧处理的，帧数多就慢。 分步解决方案：先用 ffmpeg 把视频降到 720p；或缩短视频时长；或用更快的放大模型（NCNN 通常比 PyTorch 快但精度稍低）。

十、升级、回滚与卸载

升级：下载最新 release 安装包，直接覆盖安装即可。chaiNNer 处于活跃开发中，建议定期看 Releases 页面更新。升级时集成 Python 环境和模型缓存不会丢失，只是更新程序本身。如果遇到 bug，可以试 nightly builds（https://github.com/chaiNNer-org/chaiNNer-nightly），但 nightly 不稳定，生产环境别用。

备份建议：chaiNNer 的 chain 模板可以导出成 JSON 文件，记得备份；模型文件在你自己选的目录，单独备份；处理过的输出文件默认在你指定的 Save 路径，和 chaiNNer 程序本身无关。

回滚：下载旧版本安装包覆盖安装。chaiNNer 的历史版本都在 GitHub Releases 页面。

卸载：正常卸载（Windows 设置→应用，macOS 拖到废纸篓，Linux 用包管理器卸载）。卸载不会删你下载的模型和导出的 chain 文件。

十一、商用许可与合规风险提示

GPLv3 协议——这是一个 copyleft 协议，要求任何基于 chaiNNer 修改/分发的衍生作品也必须以 GPLv3 开源。这意味着： 1. 你个人用 chaiNNer 处理图片，没问题； 2. 你想把 chaiNNer 打包进自己的商业产品里分发，必须开源你的修改； 3. 你只是在自己电脑上跑 chaiNNer 处理图片，不涉及分发，不受 GPLv3 约束。

另外，chaiNNer 本身不附带模型权重——你从 OpenModelDB 下载的放大模型各有自己的许可证，商用前需要单独确认。本教程不构成法律意见。

附录：chaiNNer vs Real-ESRGAN vs Upscayl 怎么选

一句话：只想一键放大，用 Upscayl；脚本化批量放大，用 Real-ESRGAN CLI；需要组合多步图像处理、做复杂流水线，用 chaiNNer。

附录：新手常见问题 FAQ

Q1：chaiNNer 是 AI 绘图工具吗？ A：不是。chaiNNer 不生成新图片，它是处理已有图片的工具（放大、修复、调色等）。想生成图片去用 ComfyUI 或 SD WebUI。

Q2：我需要自己装 Python 吗？ A：不需要。chaiNNer 自带集成 Python，首次启动会自动下载。如果你想自己的系统 Python 也能用，可以在设置里开 System Python 开关。

Q3：放大一张图要多久？ A：取决于模型和 GPU。1024x1024 放大到 4096x4096，在 RTX 3060 上大约 10-20 秒；在 CPU 上可能要几分钟。

Q4：支持哪些图片格式？ A：常见格式都支持（PNG、JPG、WebP 等）。视频支持 MP4、MKV 等常见格式。

参考链接

• GitHub 仓库：https://github.com/chaiNNer-org/chaiNNer
• Nightly 构建：https://github.com/chaiNNer-org/chaiNNer-nightly
• OpenModelDB 模型库：https://openmodeldb.info/
• Discord：https://discord.gg/pzvAKPKyHM