Upscayl 进阶实战指南：GPU ID 选择、日志排查、自定义 NCNN 模型与 Scale 缩放参数

本文基于 Upscayl 仓库的官方指南（docs/Guide.md）整理而成，围绕四个高频实战问题展开：如何从日志中识别并手动指定 Vulkan GPU（GPU ID）、如何使用设置页的日志区域定位问题并复制日志用于反馈、如何加载自己转换的 NCNN 自定义模型、以及 v2.8 之后 Scale（缩放倍数）选项的底层工作方式。读完本文，你可以掌握 Upscayl 从界面操作到底层命令行参数（-g、-s、-m、-n 等）的完整调用链路，并在多显卡、自定义模型、非 x4 缩放等场景下正确配置。

一、GPU ID：手动指定用于放大的 Vulkan 显卡

GPU ID 的作用是手动指定一个启用了 Vulkan 的 GPU 来执行图像放大。根据 Real-ESRGAN（Upscayl 底层使用的放大引擎）的文档，该选项在多显卡机器上同样适用。

1.1 如何找到自己的 GPU ID

按 docs/Guide.md 中的步骤操作：

1. 打开 Upscayl，并（尝试）放大一张图片；
2. 切换到 Settings（设置） 标签页，向下滚动到日志区域（LOGS area）；
3. 此时日志中会列出系统当前可用的所有 GPU ID。例如某台机器的日志显示 1 是 Nvidia、2 是 llvmpipe（软件渲染）、0 是 AMD Radeon。注意：这只是示例，实际 ID 数值会因机器而异；
4. 在 “GPU ID” 输入框中填入你想要的 ID，可以是单个数字 0、1、2，也可以填多个，如 0,1,2。

1.2 两个必须知道的限制

• Windows 系统可能覆盖该设置：如果 Upscayl 未在 Windows 高级显示设置中被设为“高性能”模式，系统可能忽略你填写的 GPU ID。在源码中，GPU ID 输入组件专门在 Windows 平台下追加了一段额外说明文案（window.electron.platform === "win" 时才渲染 ADDITIONAL_DESCRIPTION），见 input-gpu-id.tsx；
• 多 GPU 并不能均匀分担负载：由于 Real-ESRGAN 引擎自身的实现特性，即使填写 0,1,2 也不会把计算量均匀分配到多张显卡。官方 Issue #465 对此有详细讨论（此处不给出外部链接，可在工作区 Issue 中检索该编号）。

1.3 源码层面：GPU ID 如何生效

GPU ID 从界面输入框出发，最终会拼进底层 ncnn 可执行文件的命令行参数。查看 get-arguments.ts，单图放大参数构造中有一段：

// GPU ID
gpuId ? "-g" : "",
gpuId ? gpuId : "",

即当 gpuId 非空时，参数中才会附加 -g <value>；该逻辑在单图（getSingleImageArguments）、双通道二次放大（getDoubleUpscaleArguments）和批量（getBatchArguments）三处参数构造函数中完全一致（见 get-arguments.ts）。随后 spawn-upscayl.ts 通过 child_process.spawn 启动 ncnn 可执行文件并把整组参数传入，启动前还会通过 logit 把完整命令打印到日志——这也是你之所以能在日志区看到 GPU 信息的机制之一。

二、日志（Logs）：问题定位与 Bug 反馈的标准入口

Upscayl 的运行日志集中显示在 Settings 标签页内，无需打开系统终端。

2.1 日志区的使用方式

• 日志区位于设置页底部，界面上有一个 COPY 按钮，点击即可复制全部日志，随后粘贴到 Bug 报告的 Issue 模板中；
• 从前端组件 log-area.tsx 可以看到：日志为空时显示占位提示（SETTINGS.LOG_AREA.NO_LOGS）；每新增一条日志，容器会自动滚动到底部（useEffect 中设置 scrollTop = scrollHeight）；COPY 按钮点击后文案会切换为已复制状态（ON_COPY）。

2.2 日志是如何到达界面的

主进程侧的 logit.ts 很短但关键：

import log from "electron-log";

const logit = (...args: any) => {
  const mainWindow = getMainWindow();
  if (!mainWindow) return;
  log.log(...args); // 1) 写入 electron-log 本地日志文件
  mainWindow.webContents.send(ELECTRON_COMMANDS.LOG, args.join(" ")); // 2) 推送到渲染进程界面
};

可以看出日志走的是双通道：一条 log.log 落盘到本地日志文件（可用系统方式查看完整历史），另一条通过 IPC 命令 ELECTRON_COMMANDS.LOG 实时推送到界面 LOGS 区域。因此界面上看到的日志是实时增量推送的结果，而不是轮询读取文件。

排查 GPU 问题、自定义模型加载失败等问题时，优先看设置页日志；若需要更久的历史记录，再去找本地日志文件。

三、自定义模型（Custom Models）：加载自己的 NCNN 模型

自 v2.5 起，Upscayl 支持加载用户自有的 NCNN 模型。官方内置模型清单定义在 models-list.ts，共 7 个，全部为 -4x 后缀：upscayl-standard-4x、upscayl-lite-4x、high-fidelity-4x、remacri-4x、ultramix-balanced-4x、ultrasharp-4x、digital-art-4x。

3.1 官方六步操作法

1. 新建一个名为 models 的文件夹；
2. 把你的 NCNN 模型（.bin + .param 两个文件）放入该文件夹；
3. 打开 Upscayl；
4. 进入 Settings 标签页，向下滚动到 “Add Custom Models” 区域，点击 Select Folder 按钮；
5. 选择第 1 步创建的 models 文件夹；
6. 切回 Upscayl 标签页，在放大类型（模型）下拉框中选择你自定义模型的文件名。

PyTorch 模型转 NCNN 的完整流程见 Model Conversion Guide（使用 chaiNNer 加载 .chn 转换链，改好 .param 中的 input 名称后放入 models 文件夹即可）。仓库根目录下的 models/ 也提供了示例文件（如 realesr-animevideov3-x2.bin/.param、x3、x4 三组），可直接观察一个合法自定义模型文件夹应有的结构。

3.2 源码层面：文件夹校验与模型扫描

点击 Select Folder 后，实际执行的是 custom-models-select.ts：

• 弹出 openDirectory 对话框，标题即 “Select Custom Models Folder”；
• 强制校验文件夹名必须以 models 结尾（兼容 Windows 反斜杠与 POSIX 正斜杠，见 custom-models-select.ts）。不符合时弹出错误框：“Please make sure that the folder name is 'models' and nothing else.”——这解释了为什么第 1 步必须叫 models；
• macOS App Store 版本还使用 Security-Scoped Bookmarks 持久化文件夹访问权限（securityScopedBookmarks + settings.set("custom-models-bookmarks", ...)）。

随后 get-models.ts 用 fs.readdirSync 扫描该文件夹：

• 只识别扩展名为 .param / .PARAM / .bin / .BIN 的文件；
• 去掉扩展名后作为模型名去重收集；
• 若文件夹中没有任何合法模型文件，弹出 “Invalid Folder” 错误框，日志记录 “❌ Invalid Custom Model Folder Detected”。

渲染进程侧，use-custom-models.ts 在组件挂载时从 localStorage 读取 customModelsPath，并通过 ELECTRON_COMMANDS.GET_MODELS_LIST 让主进程重新拉取模型列表，最终通过 CUSTOM_MODEL_FILES_LIST 事件把模型名数组发回界面——所以下拉框中“你的模型出现在列表底部”的行为正是这条 IPC 链路的结果。

选中某个自定义模型放大时，底层命令由 -m（模型文件夹路径）+ -n（模型文件名，不含扩展名）传给 ncnn，见 get-arguments.ts。

四、Scale 选项：v2.8 的“模拟缩放”机制

自 v2.8 起，Upscayl 通过**对 x4 结果做 Downscayl（降采样）**来模拟非原生支持的缩放倍数。

关键点：

• 并非所有模型都支持 x1、x2、x3；官方内置模型只支持 x4；
• 若希望获得“模型原生输出”的其他倍数，需要来自官方 Custom Models Repository 的兼容模型。例如 realesr-animevideov3-x2 模型支持原生 x2，realesr-animevideov3-x3 支持原生 x3（仓库 models/ 目录中即附带这三组文件的示例）。

4.1 源码层面：模型缩放倍数的推断逻辑

check-model-scale.ts 展示了应用如何判断一个模型的“原生缩放”：

export default function getModelScale(model: string) {
  const modelName = model.toLowerCase();
  let initialScale = "4";
  if (modelName.includes("x2") || modelName.includes("2x")) {
    initialScale = "2";
  } else if (modelName.includes("x3") || modelName.includes("3x")) {
    initialScale = "3";
  } else {
    initialScale = "4";
  }
  return initialScale;
}

即从模型文件名中解析 x2/2x/x3/3x 标记，识别不到时默认按 x4 处理。命名习惯因此直接影响行为：自定义模型文件里带上 x2/x3 字样，应用才会把它当作对应缩放的模型。

4.2 -s 与 -w 参数的取舍逻辑

在 get-arguments.ts 中，每个参数构造函数都有同一行判断：

const modelScale = getModelScale(model);
let includeScale = modelScale !== scale && !customWidth;

含义是：只有当“模型原生缩放 ≠ 用户选择的缩放”且没有指定自定义宽度时，才向 ncnn 追加 -s <scale> 参数。由此可以推断出完整的优先级关系：

场景	实际行为
x4 模型 + 选 x4	不传 -s，直接输出原生 x4
x4 模型 + 选 x2	传 -s 2，先放大到 x4 再降采样（模拟）
x2 模型 + 选 x2	不传 -s，输出原生 x2
任意模型 + 填写自定义宽度	不传 -s，改传 -w <width> 按目标宽度控制输出

此外该文件还展示了完整的参数面：-i 输入、-o 输出、-f 输出格式、-c 压缩率、-t tile size、-x TTA 模式，均按“值非空才附加”的规则拼入最终命令，方便在日志中对照实际执行的命令核对配置。

五、小结

主题	界面入口	关键源码	底层参数
GPU ID	Settings → GPU ID 输入框	input-gpu-id.tsx	-g
日志	Settings → LOGS 区域 + COPY	logit.ts、log-area.tsx	IPC LOG 命令
自定义模型	Settings → Add Custom Models → Select Folder	custom-models-select.ts、get-models.ts	-m、-n
Scale	Upscayl 标签页 → 缩放选择	check-model-scale.ts	-s / -w

以上机制共同构成了 Upscayl “界面设置 → 参数拼装 → ncnn 子进程执行 → 日志回显” 的闭环。理解这条链路后，遇到 GPU 选择失效、模型不显示、缩放结果不符预期等问题时，即可按“看日志 → 对参数 → 查校验规则”三步定位原因。