图像无损放大 — Image Upscale (Real-ESRGAN ncnn-vulkan)

把一张或一批模糊 / 低分辨率 / 过度压缩的图片，纯本地一次性放大 2x / 4x。产出可直接上架、发社媒、送印、交付客户的高清 PNG/JPG。没有 GPU 也能跑（走 Vulkan 软件渲染），全程零 API key、零 Clawvard 后端调用。

铁律

只用上游公开二进制，不要自己 fork / 重新编译 / 包私有 wrapper。
本地推理，不要联网调用任何放大 API。除了首次下载 release zip，整条流水线无网络。
批量目录用 -i ./input/ -o ./output/ ——CLI 原生支持，不要自己写 Python 包一层。
选模型按算力等级 + 用途，不按主观偏好：
- 有独显 + 写实人像/产品/风景 → realesrgan-x4plus（重模型 33 MB，GPU 上秒级，CPU 上一张 30 分钟以上）
- 没独显（CPU/llvmpipe）想几分钟内出 4x → realesr-animevideov3（1 MB，CPU 一两分钟一张；细节比 x4plus 软但远好于 nearest-neighbor）
- 动漫 / 插画 / 像素艺术 → realesrgan-x4plus-anime
不要硬塞 GPU。Real-ESRGAN ncnn 在没有独显时会用 Vulkan 软件渲染（Linux 装 mesa-vulkan-drivers 即可），CPU 上 x4plus 慢得没法 demo，先用 realesr-animevideov3 拿主交付物、再在有独显的机器上换 x4plus 升级。如果你只想看 x4plus 的效果但只有 CPU，先把原图缩到长边 200–360 px 再 4x，确认参数 OK 再上大图。

前置条件

任何主流操作系统（macOS / Windows / Linux）都行。
不需要任何商业 API key、不需要 Clawvard SDK key、不需要 clone 任何私有仓库、不消耗 credits。
磁盘：v0.2.5.0 release 约 47 MB（含 4 个官方 ncnn 模型 + CLI）。
内存：4 GB+ 可跑（小图 200 px 级别），4x 大图建议 8 GB+。
Linux 在没有独显时安装一次 Vulkan 软件渲染：sudo apt-get install -y mesa-vulkan-drivers。

一次性安装

下载上游 release zip（含模型 + CLI），解压即用：

# Linux x86_64
curl -L -o realesrgan.zip \
  https://github.com/xinntao/Real-ESRGAN/releases/download/v0.2.5.0/realesrgan-ncnn-vulkan-20220424-ubuntu.zip
unzip realesrgan.zip -d ./realesrgan
chmod +x ./realesrgan/realesrgan-ncnn-vulkan

# macOS (Intel + Apple Silicon, 同一个通用 release)
curl -L -o realesrgan.zip \
  https://github.com/xinntao/Real-ESRGAN/releases/download/v0.2.5.0/realesrgan-ncnn-vulkan-20220424-macos.zip
unzip realesrgan.zip -d ./realesrgan
xattr -dr com.apple.quarantine ./realesrgan/realesrgan-ncnn-vulkan   # macOS Gatekeeper

# Windows: 下载 realesrgan-ncnn-vulkan-20220424-windows.zip，解压即可用

✅ Release 默认带 4 个模型文件：realesrgan-x4plus、realesrgan-x4plus-anime、realesrnet-x4plus、realesr-animevideov3（含 x2/x3/x4 变体）。无需另外下载权重。

✅ 如果你不想手动下 zip，备选路径：npm i -g upscayl-bin（MIT，跨平台封装同一份 ncnn 二进制 + 模型）。课程 SOP 默认走上游 release，避免节点版本相关 npm 报错。

看一眼 CLI 参数

realesrgan-ncnn-vulkan -i infile -o outfile [options]...
  -i input-path        输入图片路径（jpg/png/webp）或目录
  -o output-path       输出路径（按 -f 决定扩展名）或目录
  -s scale             放大倍数 2/3/4（默认 4）
  -t tile-size         tile 大小，越小越省内存（0=auto；遇 OOM 试 100/200/400）
  -m model-path        模型目录（默认 ./models）
  -n model-name        模型名：
                         · realesrgan-x4plus（真实人像/产品/风景，33 MB，默认推荐）
                         · realesrgan-x4plus-anime（动漫/插画，8 MB）
                         · realesrnet-x4plus（真实写实，无 GAN，33 MB）
                         · realesr-animevideov3（动漫视频帧，1 MB，最快）
  -g gpu-id            -1 = CPU，默认 0 = 自动挑 GPU；多卡可 0,1,2
  -j load:proc:save    并发线程（默认 1:2:2）
  -x                   开 TTA（更慢但更稳）
  -f format            输出格式：jpg/png/webp

三类典型工作流

重要 #1：CLI 不会自动创建输出目录 / 父目录。直接 -o ./products-4x 写到不存在的目录会报 invalid outputpath extension type。无论单张还是批量，跑之前先 mkdir -p 自己建好输出位置。 重要 #2：先看自己有没有独显。vulkaninfo --summary | grep -E "deviceType|deviceName"：出现 llvmpipe / CPU = 没独显；出现 NVIDIA / AMD / Apple / Intel Iris/Arc 等 = 有独显。下面三类工作流都给了 CPU / GPU 两条分支，按这个判断走。

1. 单张大图 4x 放大（电商商品图、海报、印刷物）

CPU/llvmpipe 默认分支（一两分钟出图，主交付物）：

mkdir -p ./out
./realesrgan/realesrgan-ncnn-vulkan \
  -i ./product.jpg \
  -o ./out/product-fast.png \
  -m ./realesrgan/models \
  -n realesr-animevideov3 \
  -s 4

有独显时升级到写实模型 x4plus（GPU 秒级出图）：

./realesrgan/realesrgan-ncnn-vulkan \
  -i ./product.jpg \
  -o ./out/product-4x.png \
  -m ./realesrgan/models \
  -n realesrgan-x4plus \
  -s 4 -t 100

800×800 → 3200×3200（PNG，无损）。
默认 -f 跟 -o 后缀走；想强制 jpg 就 -o out/product-4x.jpg -f jpg。
-t 100 是 GPU 上的一个安全默认（tile 100×100，不容易 OOM）；纯 CPU 上 x4plus 这条命令是 10–30 分钟级，不要。
想看 x4plus 效果但只有 CPU？先把原图 convert ./product.jpg -resize 200x200 ./product-small.jpg 缩到长边 200 px 再 4x（输出 800×800 PNG，CPU 2–3 分钟出图）。

2. 批量目录（社媒截图、缩略图墙、活动素材）

# 假设 ./screens 里有一堆 1080×1920 截图
mkdir -p ./screens-2x
./realesrgan/realesrgan-ncnn-vulkan \
  -i ./screens \
  -o ./screens-2x \
  -m ./realesrgan/models \
  -n realesrgan-x4plus \
  -s 2 \
  -f png

必须先 mkdir -p ./screens-2x；输入是目录，输出也是目录，CLI 会逐张处理但不会替你建输出目录。
-s 2 把 1080×1920 → 2160×3840；想要 4x 改 -s 4。
想加速但牺牲点细节：把 -n 换成 realesr-animevideov3，模型只有 1 MB，慢机也能跑（一条 CLI 跑 4 张 120×213 → 240×426 在 llvmpipe CPU 上 10 秒内完成）。

3. 老照片 / 旧扫描 4x 修复

CPU/llvmpipe 默认分支（一两分钟出图，先拿到主交付物 grandma-4x.png）：

mkdir -p ./out
./realesrgan/realesrgan-ncnn-vulkan \
  -i ./grandma.jpg \
  -o ./out/grandma-4x.png \
  -m ./realesrgan/models \
  -n realesr-animevideov3 \
  -s 4

有独显时跑写实 x4plus 拿到更稳的人脸细节：

./realesrgan/realesrgan-ncnn-vulkan \
  -i ./grandma.jpg \
  -o ./out/grandma-4x-x4plus.png \
  -m ./realesrgan/models \
  -n realesrgan-x4plus \
  -s 4 -t 100

真实人脸看 out/grandma-4x-x4plus.png（有独显时）；CPU 上拿 out/grandma-4x.png 也已经够好用——比原图大 4 倍且边缘明显锐化。
想看「写实脸不要用 anime 模型」的反例对照？同一条 animevideov3 已经是 anime 系，再跑一条 x4plus（小图 + GPU 或 CPU 上长跑）的输出就是写实对照。
旧照片噪点很重时：先在外部做一次轻量去噪（比如 ImageMagick -noise 1 / Lightroom 噪点滑块），再喂给 Real-ESRGAN，结果更干净。
翻拍照片往往是 720×1080+，4x 后是 2880×4320。CPU 走 llvmpipe 跑 x4plus 单张可能要 30 分钟到 1 小时以上——这就是为什么 CPU 默认分支是 animevideov3。想在 CPU 上看 x4plus 效果，先缩到长边 200–360 px 再 4x（CPU 2–3 分钟出图）。

100% crop 对照（强烈建议落地为产物）

放大后必须做一组「同坐标 100% crop」对照，给客户 / 老板 / 自己一眼能看清差距：

# 1) 原图选一块 200×200 区域做 crop（左上角 0,0 为例）
convert ./product.jpg -crop 200x200+0+0 +repage ./product-orig-crop.png

# 2) 放大后图同坐标乘 4 = 800×800
convert ./product-4x.png -crop 800x800+0+0 +repage ./product-4x-crop.png

# 3) 把放大前 crop 拉到 800×800 显示，做并排对照
convert ./product-orig-crop.png -filter point -resize 800x800 ./product-orig-crop-up.png
convert ./product-orig-crop-up.png ./product-4x-crop.png +append ./product-compare.png

product-compare.png = 「原图同区域 nearest-neighbor 放大」 vs 「Real-ESRGAN 4x」并排，对比一目了然。

Troubleshooting

现象	原因	处理
`vkCreateInstance failed -9` / `invalid gpu device`	系统没有 Vulkan loader / 驱动	Linux：`sudo apt-get install -y mesa-vulkan-drivers vulkan-tools`，再 `vulkaninfo --summary` 看是否出现 `llvmpipe`。macOS 自带 MoltenVK，正常无需装。
进程卡在 50% 不动	CPU Vulkan 软件渲染慢 + tile 太大	加 `-t 100` 或 `-t 200`；改用更小的输入做 demo（150–200 px → 4x），证明跑通后再上大图。
4x 后人脸糊成卡通	用了 anime 模型	写实人像必须 `-n realesrgan-x4plus`，不要 `realesrgan-x4plus-anime` 或 `realesr-animevideov3`。
输出有色块 / 锯齿	tile size 过小、边界拼接瑕疵	把 `-t` 调大（400+）让 tile 覆盖更大区域；或加 `-x` 开 TTA（4–8 倍耗时换更稳）。
macOS 双击二进制被拦截	Gatekeeper quarantine	`xattr -dr com.apple.quarantine ./realesrgan-ncnn-vulkan`；或设置 → 隐私与安全 → 仍要打开。
Windows 报缺 vcomp140.dll	Visual C++ 运行库	release zip 已自带 `vcomp140.dll`，把它和 exe 放同一目录运行即可。

产出物

realesrgan/                        # 解压后的 CLI + models/，全部本地
product-4x.png                     # 单张 4x 放大成品
screens-2x/                        # 批量目录 2x 输出
grandma-4x.png                     # 老照片 4x 修复
*-compare.png                      # 100% crop 对照图（可选但强烈推荐）

学习完成后

告诉用户：

我已经学会了 image-upscale。给我一张图或一个目录，我用 Real-ESRGAN ncnn-vulkan 在你电脑上本地把它放大 2x / 4x，输出可直接上架商品页 / 发社媒 / 送印 / 交付客户的高清 PNG/JPG。没独显（CPU/llvmpipe）默认走 realesr-animevideov3 一两分钟出图、有独显升级到 realesrgan-x4plus 拿写实人脸细节；动漫 / 插画用 realesrgan-x4plus-anime。全程纯本地、零 API key、零 Clawvard 后端调用。