一、背景与痛点

上个月我接手一个"老照片修复 + 缩略图放大预览"的需求，第一反应是把图传到服务端用超分模型跑——结果弱网下上传慢、流量烧钱，更麻烦的是用户把证件照、家庭合影传上去，隐私合规直接亮红灯。正当我准备自己攒一套端侧模型时，发现 HarmonyOS 7.0.0（API 26）的 Core Vision Kit 已经把**图像超分（Image Super-Resolution）**做成了系统级能力：import { imageSuperResolution } from '@kit.CoreVisionKit' 几行就能调用，推理全程跑在设备 NPU 上，图片不出设备。

听起来很美，但真把 Demo 打成可上线的功能，我还是踩了一圈坑。本文把端侧超分接入最常见的 5 个坑逐一拆开，都是我实打实调出来的经验，照着避能省你半天调试时间。

二、环境与能力规格

接入前先把边界摸清，超分的约束比想象中硬：

关键就两句：倍率写死 4 倍、输入图超过 2048×2048 直接失败。后面两个坑都和它有关。

三、核心代码（可复用骨架）

最稳的写法是一个页面只 create 一次分析器，所有图共用，用完再 destroy。

import { imageSuperResolution, visionBase } from '@kit.CoreVisionKit';
import { image } from '@kit.ImageKit';
import { fileIo } from '@kit.CoreFileKit';

// 页面级单例：避免每次推理都 create，省内存也省初始化耗时
let analyzer: imageSuperResolution.ImageSRAnalyzer | null = null;

async function getAnalyzer(): Promise<imageSuperResolution.ImageSRAnalyzer> {
  if (!analyzer) {
    analyzer = await imageSuperResolution.ImageSRAnalyzer.create();
  }
  return analyzer;
}

// 超限图先等比缩到 2048 以内，否则 process 直接抛异常
async function safeDecode(path: string): Promise<image.PixelMap> {
  const file = await fileIo.open(path, fileIo.OpenMode.READ_ONLY);
  const src = image.createImageSource(file.fd);
  const info = await src.getImageInfo();
  const scale = Math.min(1, 2048 / Math.max(info.size.width, info.size.height));
  return await src.createPixelMap({
    desiredPixelFormat: image.PixelMapFormat.RGBA_8888, // 必须是 RGBA_8888
    desiredSize: {
      width: Math.floor(info.size.width * scale),
      height: Math.floor(info.size.height * scale),
    },
  });
}

async function superResolve(path: string): Promise<image.PixelMap> {
  const a = await getAnalyzer();
  const input = await safeDecode(path);
  const request: visionBase.Request = { inputData: { pixelMap: input } };
  const res: imageSuperResolution.ISPResponse = await a.process(request);
  return res.pixelMap; // 输出已是 4 倍尺寸，直接给 Image 组件或保存
}

四、踩坑实录（5 条）

坑 1：每次推理都 create，内存抖到崩。
最初我把 create 放在每次点击里，连点几张图后手机开始掉帧、偶发 OOM。超分分析器内部持有 NPU 资源，反复创建销毁开销极大。正确做法：页面级单例复用，页面退出时 destroy 一次（见上方 getAnalyzer）。

坑 2：原图超过 2048×2048，process 直接抛异常。
用户相册里随手一张 4000×3000 的照片，没缩放就塞进去，必崩。务必在解码阶段按 2048 / max(w,h) 等比缩放——这是输入硬上限，不是建议值（见 safeDecode）。

坑 3：PixelMap 格式不对，结果全黑或报错。
超分要求输入是 RGBA_8888。我从相册拿到的 PixelMap 默认可能是别的格式，没显式指定就出现黑图。解码时强制 desiredPixelFormat: RGBA_8888 最稳。

坑 4：把超分当"放大镜"，文字场景翻车。
超分本质是模型"猜"细节，不是无损还原。一次我把一张模糊的发票截图超分，原本糊掉的一行小字确实变清晰了，但个别字符被猜错，金额数字对不上。结论：超分适合提升观感（老照片、商品图、缩略图放大），别用在证件、票据、证据类强真实细节场景。

坑 5：并发调用没加锁，偶发结果串图。
我在列表里对多张图做并行超分，结果有时 A 图的输出挂到了 B 的坑位。端侧分析器对并发并不友好，同一分析器实例应串行调用，多图处理用 for...of + await，或每张图独立 create/destroy（代价是性能）。我选了单例串行，实测 4 张图顺序处理稳得一批。

五、小结与适用边界

端侧超分最大的价值是隐私闭环 + 零云端成本 + 弱网可用：图片不出设备、不烧服务器带宽、飞行模式也能跑。但它有清晰边界——固定 4 倍、2048 输入上限、结果是"猜测式增强"。把它用在"提升观感"的场景（老照片修复、电商缩略图放大、截图增强、证件照预览）是甜区；用在"必须保真"的场景请谨慎，必要时配一份原图留底。

接入记住三件事就够了：分析器单例复用、输入先缩到 2048 内、PixelMap 锁死 RGBA_8888。剩下的，交给系统 NPU 跑就好。

本文为原创首发实战笔记，基于 HarmonyOS 7.0.0（API 26）Core Vision Kit 图像超分能力，代码示例为可复用骨架，实际接口以华为官方文档为准。