一张 512px 的低清图,怎么在 RN 的 TurboModule 里被送进 NPU、放大 4 倍、再原样回到 JS?——这篇文章用一个跑在鸿蒙 PC 上的 React Native 0.84 三方库,把端侧 AI 超分这条链路拆开讲透,也讲清楚 AI 退回 CPU 时怎么发现。

仓库地址:https://atomgit.com/oh-react-native/react-native-ohos-ai-vision
版本地址:https://atomgit.com/oh-react-native/ohos_react_native/tree/0.84-main
三方库框架:https://atomgit.com/oh-react-native

0. 环境与实测设备

项版本/型号
DevEco Studio<DevEco Studio 安装目录>(HarmonyOS SDK 26.0.0 / API 26)
运行设备HUAWEI MateBook Pro S(MOR-M1),HarmonyOS 7.0.0.111(SP15C00E101R9P2),API 26
React Native0.84.1
React19.2.3(与 RN 0.84.1 内置 renderer 严格同版)
RNOH@react-native-oh/react-native-harmony 0.84.3;OHPM @rnoh/react-native-openharmony 0.84.3
语言与构建TypeScript 5.9.3、Babel 7、Jest 29.7、Node.js 24.12.0 / npm 11.12.1
鸿蒙 SDK编译/目标 26.0.0;HAR compatibleSdkVersion: 26、minAPIVersion: 260000026
hvigorDevEco Studio 自带(HVIGOR_JS 可覆盖)
react-native-ohos-ai-vision0.3.0(本仓库,npm 包 + source-style HAR)
示例应用Ohos AI Vision(example/harmony,deviceTypes: phone / tablet / 2in1)
端侧引擎Core Vision Kit imageSuperResolution(NPU,API 26+)+ Catmull-Rom 双三次(CPU 兜底)

1. AI 真的跑了吗:一次静默回退

这个库在 0.2 版本还是做 OCR 和文档扫描的。到了 0.3,整个方向被推倒重来:HarmonyOS 7 把 imageSuperResolution 放进了 Core Vision Kit,API 26 起可以在设备本地把一张图放大 4 倍,跑在 NPU 上。库名 react-native-ohos-ai-vision 没变,能力全换了——旧的 OhosOcr、文档扫描管线、subjectSegmentation 全部移除,TurboModule 改名 OhosSuperResolution,HAR 目录、CMake target、Package 类跟着改,compatibleSdkVersion 直接抬到 26。

换方向本身不算难,难的是怎么证明 AI 真的跑了。

第一次在鸿蒙 PC 上装好,页面看起来一切正常:nativeBridge: OK,能力行写着 API 26、Core Vision 可用、上限 2048px。选了一张图,几秒后结果出来,尺寸也是 4 倍。直到我往下看到那一行:

实际引擎:本地双三次(CPU)

能力说可用,结果却不是 NPU 出的。页面上没有任何报错,返回的图也是对的,能看出问题的只有 engine 字段。

查下去,根因藏在一行很不起眼的构造里:

Constructor is false

visionBase.Request 这个类型没有对外暴露构造函数,new visionBase.Request() 在设备上直接抛错;我的 try/catch 把它当成"这张图 AI 处理不了",顺手回退到了本地双三次。因为回退路径能出图,整个调用仍然是"成功"的。修复方式与官方示例一致——不再 new,而是用类型化对象字面量:

const input: visionBase.ImageData = { pixelMap };
const request: visionBase.Request = { inputData: input };
const response: imageSuperResolution.ISPResponse = await analyzer.process(request);

改完再跑,同一个操作稳定返回 core-vision。系统日志里也终于出现了 NPU 服务的痕迹:

ML_ISP_ImageSRServiceStub: initAlgorithmV2 complete, code:0

这件事定下了整个库的设计前提:

  • 结果必须自报引擎:engine 不是调试字段,是契约的一部分,页面要把它显示给用户看;
  • 回退必须是显式的:AI 失败可以退 CPU,但要让调用方知道退过,而不是把 CPU 结果伪装成 NPU 结果;
  • 一致性必须可验证:光看尺寸不够,得有一个跨平台的校验和,证明"同一张图、同一份像素"。

所以这篇记录的边界很清楚:

  • 两条路线怎么选(AI 4× / 本地双三次 2/3/4×);
  • 4 倍双三次怎么写才能和 ArkTS 逐字节一致;
  • 512 → 2048 的像素和 PNG data URI 怎么经 RN 桥传给 JS;
  • npm 包 + source-style HAR 怎么交付,以及我踩到的每一个真机坑。

2. 效果展示

先看效果。示例应用叫 Ohos AI Vision,在鸿蒙 PC 上是一个 2in1 窗口:

在这里插入图片描述

页面只做一件事:相册图片 → 4× 超分。顶部三枚能力标签是 API 26、Core Vision 可用、上限 2048px;中间三个按钮分别走 AI 4×、本地双三次 3×、内置示例照片 4×;下面是原图与结果的并排对比。

这张截图里的数字:

  • 原图 512 × 341,超分结果 2048 × 1364,正好 4 倍;
  • 状态行:超分完成(Core Vision Kit)· 端侧 2682ms · 端到端 3630ms;
  • 端侧耗时是原生管线自己量的:解码、推理、读回、校验和、PNG 编码都算在里面;端到端多出来的是 JS 调用、JSON 解析和 React 状态更新;
  • 图右侧的岩石纹理、远处山脊和路面颗粒,是 4× 之后补出来的细节,不是把原图插值拉大。

对比图下方还有几行统计:实际引擎(Core Vision Kit(NPU) 或 本地双三次(CPU))、RGBA 校验和、PNG 体积(base64 字符数),以及一份把 base64 折成 <data URI · N chars> 的 JSON。再往下是确定性引擎契约卡片:三个演示场景的校验和、原生与纯 TS 引擎 JSON 逐字符一致、6 条自检。这些内容截图里只露出了一部分,但验收时要逐项核对。

两个交互细节,截图里看不出来:

  • 如果 AI 服务对这张图失败,或者请求的是 2×/3×(AI 只有 4× 模型),页面不会报错,而是把 实际引擎 改成 本地双三次(CPU),结果照常返回;
  • 请求进行中三个按钮全部禁用,因为官方明确不支持同进程并发调用;原生侧还有一道 busy 锁,第二次进入直接 reject Image super-resolution is already running。

也要提前说清楚一个反直觉的现象:文字截图不是这个模型的好输入。把一张代码编辑器截图放大 4 倍,笔画会被模型"脑补"成更粗、更连的形状,反而不如本地双三次好读。示例页因此把两条路线都放进了按钮:自然照片走 AI 4×,文字/图形截图可以走 3× 双三次。这是分布外输入的常见表现,不算缺陷。

3. 两条路线,一份契约:超分到底怎么发生

写代码之前先把链路捋清楚。整条管线全在设备本地,没有网络请求;AI 路线在 NPU 上跑,CPU 路线是确定性的 Catmull-Rom 双三次:

JS(React)
  └─ pickImage() ──► 系统 PhotoViewPicker ──► file://media/...
       │
       ▼
  superResolution(uri, 4) ──► OhosSuperResolution(TurboModule,跨 C++ 桥)
       │
       ▼
  SrImage.superResolution(ArkTS,设备本地)
       ├─ decodeImage(uri, 512)                RGBA_8888,长边 ≤ 512
       ├─ processPixelMap
       │   ├─ AI:pixelMapToRgba → createRgbaPixelMap
       │   │       → ImageSRAnalyzer.process → 尺寸校验
       │   │       → pixelMapToRgba → checksum → 重新封装
       │   └─ CPU:pixelMapToRgba → upscale(Catmull-Rom) → checksum
       ├─ toDataUri(PNG, 100)                  data:image/png;base64,...
       └─ imageResultToJson                    固定字段顺序
       │
       ▼
  { uri, id, source, factor, inputWidth, inputHeight, outputWidth,
    outputHeight, engine, durationMs, checksum, image }
路线触发条件实现engine
Core Vision Kit(NPU)API 26+,且 factor = 4imageSuperResolution.ImageSRAnalyzer.create() → process() → 4× PixelMapcore-vision
确定性双三次(CPU)其它平台、AI 异常、factor = 2/3upscale(),Catmull-Rom(a = -0.5),纯整数最终取整local-bicubic

官方对 AI 接口的约束有四条,直接决定了工程形态:

  • 输入不超过 2048 × 2048;
  • 输出固定 4 倍,没有 2× / 3× 模型;
  • 同一进程不支持并发调用;
  • 能力从 API 26 才开放,所以 HAR 的 compatibleSdkVersion 必须是 26。

这四条里,第一条和第三条最容易被低估。2048 的输入上限看起来宽裕,但 4 倍输出就是 8192px;再加上 PNG data: URI 要经过 RN 桥、进 JS 堆,字符串会大到不可接受。所以这个库把输入长边先缩到 512px,输出 2048px:

const MAX_INPUT_EDGE = 512;
const AI_FACTOR = 4;
const MAX_OUTPUT_EDGE = MAX_INPUT_EDGE * AI_FACTOR; // 2048

512 是一个折中值:AI 模型对 512 的输入仍有明显的细节补全效果,输出 2048 既落在官方规格内,PNG base64 也还在桥能承受的范围。验收记录里同一尺寸的 512 × 341 图输出 2048 × 1364,PNG base64 约 4,787,226 字符——这已经是一个接近 4.8 MB 的字符串了。如果再放大输入,字符串会线性膨胀,移动端 JS 堆首先吃不消。

为什么还要一套 CPU 引擎

如果只做 AI 路线,这个库在非鸿蒙宿主、API 26 以下、AI 异常、2×/3× 请求这四种情况下都会直接不可用。所以它带了一套确定性 Catmull-Rom 双三次引擎:

  • 同一份 SuperResolutionEngine.ts 在 src/(纯 TS)和 harmony/.../sr/SrEngine.ts(ArkTS)各放一份,两份逐字节相同,CI 会校验;
  • 支持 2/3/4 倍;演示语料是三个 96×64 的程序化场景(人像、标签、截图),不依赖图片解码器;
  • 每个结果带 8 位 FNV-1a checksum,同一张图在原生和纯 TS 两侧必须得到同一个值;
  • 非鸿蒙宿主上 superResolution 返回 null,调用方可以降级到 upscale(),而不是崩掉。

CPU 引擎在这里提供的是可复现的基准:没有它,就无法证明 AI 输出的像素是对的。 页面上的 原生与纯 TS 引擎 JSON 逐字符一致,比任何"AI 已启用"的文案都可信。

校验和的成本

AI 路线也会算 checksum,代价是把 4× 的 PixelMap 读回 RGBA:

  • 2048 × 2048 × 4 字节 = 16 MB(截图这张 2048 × 1364 约 11.2 MB);
  • 读回、遍历、FNV-1a 计算、再重新封装成 PixelMap,真机上大约 200–500ms;
  • 这段时间被算进 durationMs,所以 AI 的端侧耗时看起来比"纯推理"高。

这是刻意换来的:没有 checksum,AI 的结果只能靠尺寸和肉眼判断;有了 checksum,原生与纯 TS 的输出可以逐字符对拍,PNG 编码前后的像素也能自洽。对一个"看不见模型"的端侧库来说,这 200–500ms 是为可验证性付的成本。

4. 工程怎么搭:一个 npm 包、一个 source-style HAR、一个 2in1 示例

先看整体结构。这个库由一个 npm 包 + 一个原生 HAR + 一个示例宿主组成,三层各自解决不同的问题:

react-native-ohos-ai-vision/           # npm 库根目录(package.json,v0.3.0)
├─ src/                                # 纯 TS:引擎、spec、安全包装
│  ├─ NativeOhosSuperResolution.ts     # codegen spec:6 个方法
│  ├─ SuperResolutionEngine.ts         # 演示语料 + Catmull-Rom + checksum
│  ├─ SrModels.ts                      # RgbaImage / Result / 校验
│  ├─ SrJson.ts                        # 固定字段顺序的 JSON 契约
│  ├─ nativeBridge.ts                  # 纯 TS 兜底,永不抛错
│  ├─ ohosModule.ts                    # 原生安全包装,不可用 resolve null
│  └─ index.ts
├─ lib/                                # Babel CJS/ESM + tsc 声明(构建产物)
├─ harmony/
│  ├─ ohos_super_resolution/           # HAR 源模块
│  │  ├─ Index.ets / BuildProfile.ets / ts.ts
│  │  ├─ oh-package.json5 / build-profile.json5
│  │  └─ src/main/
│  │     ├─ ets/RNOhosSuperResolutionTurboModule.ts
│  │     ├─ ets/RNOhosSuperResolutionPackage.ets
│  │     ├─ ets/generated/             # codegen:ArkTS Spec + ts.ts
│  │     ├─ ets/sr/SrImage.ts          # 解码、AI 调用、回退、出图
│  │     ├─ ets/sr/SrPixels.ts         # PixelMap / 行宽 / data URI
│  │     ├─ ets/sr/SrEngine.ts         # 引擎副本(与 src 逐字节相同)
│  │     └─ cpp/                       # CMake + Package + codegen C++ 桥
│  └─ ohos_super_resolution.har        # source-style HAR
├─ example/
│  ├─ App.tsx                          # 单页超分演示
│  ├─ samplePhoto.ts                   # 内置 512px 示例照片(base64)
│  └─ harmony/                         # ★ DevEco 打开这个目录运行
├─ templates/                          # 手动接线的 ArkTS / C++ 模板
├─ tools/build-har.sh                  # 组装 source-style HAR
├─ scripts/                            # HAP 构建、包校验、bundle 预置头检查
├─ __tests__/                          # Jest 29 例
├─ tests/                              # node:test 原生模块 6 例
├─ artifacts/                          # 构建日志与 npm 压缩包(不进包)
├─ index.d.ts / react-native.config.js
└─ README*.md / CHANGELOG.md / VALIDATION.md

在这里插入图片描述

三层分工要拎清,否则很容易在 DevEco 里打开错地方:

  • src/ 是纯 TS,负责确定性引擎、JSON 契约和没有鸿蒙宿主时的降级;
  • harmony/ohos_super_resolution/ 是 HAR 源模块,承载 TurboModule、AI 调用和像素管线;
  • example/harmony/ 才是带 entry 的示例宿主,DevEco 打开它才能跑;示例的 deviceTypes 覆盖 phone、tablet、2in1,截图里就是 2in1 窗口。

这个库要同时满足三种消费者,所以 package.json 里三套入口并存:

{
  "name": "react-native-ohos-ai-vision",
  "version": "0.3.0",
  "source": "./src/index.ts",
  "main": "./lib/commonjs/index.js",
  "module": "./lib/module/index.js",
  "types": "index.d.ts",
  "react-native": "./src/index.ts",
  "harmony": {
    "alias": "react-native-ohos-ai-vision",
    "autolinking": {
      "ohPackageName": "react-native-ohos-ai-vision",
      "etsPackageClassName": "RNOhosSuperResolutionPackage",
      "cppPackageClassName": "RNOhosSuperResolutionPackage",
      "cmakeLibraryTargetName": "rnoh_ohos_super_resolution"
    }
  }
}
  • Metro 走 react-native 条件,直接读 src/index.ts;
  • 不用源码的工程走 main / module 和 types,读 lib/ 里的预编译产物;
  • RNOH 靠 harmony.autolinking 找到 OHPM 包名、ArkTS Package 类、C++ Package 类和 CMake target。

HAR 是 source-style,不是 hvigor 编出来的二进制产物。tools/build-har.sh 会把 ArkTS 源码、codegen 生成的 C++ 桥、CMakeLists.txt、module.json 和 oh-package.json5 一起装进 package/,再打成 tar.gz:

STAGE_DIR="$(mktemp -d)"
PKG_DIR="${STAGE_DIR}/package"
cp -R "${MODULE_DIR}/src/main/ets/." "${PKG_DIR}/src/main/ets/"
cp -R "${MODULE_DIR}/src/main/cpp/." "${PKG_DIR}/src/main/cpp/"
(cd "${STAGE_DIR}" && COPYFILE_DISABLE=1 tar --exclude='._*' --exclude='.DS_Store' \
  -czf "${OUTPUT_HAR}" package)

原因很实际:RNOH autolinking 会把模块的 src/main/cpp 加进宿主构建,所以 HAR 里必须有 C++ 源码、生成的 OhosSuperResolution.cpp 和 CMake 文件;只发编好的 HAR,宿主那边就没有可以链接的 target。HAR 是能力,编译发生在宿主。

HAR 的 module.json 里还有两个硬约束:

{
  "app": { "bundleName": "com.reactnative.aivision", "minAPIVersion": 260000026 },
  "module": { "name": "ohos_super_resolution", "type": "har", "deviceTypes": ["phone", "tablet", "2in1"] }
}

minAPIVersion 直接卡在 26:imageSuperResolution 是 API 26 才开放的能力,低版本系统找不到该服务,模块加载会失败。纯 TS 引擎不受这条限制,可以在任意 RN ≥ 0.68 的宿主里用。

示例宿主的接线只有三处。ArkTS 侧注册 Package:

// example/harmony/entry/src/main/ets/RNPackagesFactory.ets
import { RNOHPackage, RNPackageContext } from '@rnoh/react-native-openharmony';
import { RNOhosSuperResolutionPackage } from 'react-native-ohos-ai-vision';

export function createRNPackages(ctx: RNPackageContext): RNOHPackage[] {
  return [new RNOhosSuperResolutionPackage(ctx)];
}

C++ 侧把生成的 Package 加进 PackageProvider,CMake 侧把 target 链上:

add_subdirectory("${OH_MODULE_DIR}/react-native-ohos-ai-vision/src/main/cpp" ./ohos_super_resolution)
target_link_libraries(rnoh_app PUBLIC rnoh_ohos_super_resolution)

对使用方来说,最终看到的 API 只有两类:一次能力探测,和一次超分。

const caps = await capabilities();          // 非鸿蒙宿主为 null
if (caps?.coreVision) {
  const uri = await pickImage();            // 取消时 null
  if (uri !== null) {
    const result = await superResolution(uri, 4);
    console.log(result?.engine, result?.outputWidth, result?.durationMs);
  }
}

下面就按"路由 → 双三次 → 像素管道 → 桥接 → 交付"的顺序,把代码拆开讲。

5. 把代码讲透

5.1 路由:先问 AI 能不能跑,再决定谁来放大

所有超分请求都汇到 processPixelMap。它的结构是一个"先试 AI、失败再退 CPU"的分支:

if (factor === AI_FACTOR && coreVisionAvailable()) {
  let candidate: image.PixelMap | null = null;
  let aiInput: image.PixelMap | null = null;
  try {
    // 给模型一张全新的、自己持有的 RGBA_8888 图
    const sourceImage: RgbaImage = await pixelMapToRgba(pixelMap);
    aiInput = await createRgbaPixelMap(sourceImage.pixels, sourceImage.width, sourceImage.height);
    candidate = await runCoreVision(aiInput);
    if (await hasExpectedSize(candidate, width * factor, height * factor)) {
      const aiImage: RgbaImage = await pixelMapToRgba(candidate);
      resultChecksum = checksum(aiImage);
      engine = SuperResolutionEngineKind.CoreVision;
      // 重新封装,编码器不直接碰服务自己的 native buffer
      output = await createRgbaPixelMap(aiImage.pixels, aiImage.width, aiImage.height);
    } else {
      const info: image.ImageInfo = await candidate.getImageInfo();
      Logger.warn(`Core Vision size mismatch: ${info.size.width}x${info.size.height}, ` +
        `expected ${width * factor}x${height * factor}; using bicubic`);
    }
  } catch (error) {
    Logger.warn(`Core Vision fallback to bicubic: ${describeError(error)}`);
  } finally {
    await releasePixelMap(aiInput);
    await releasePixelMap(candidate);
  }
}

if (output === null) {
  const source: RgbaImage = await pixelMapToRgba(pixelMap);
  const upscaled: RgbaImage = upscale(source, factor);
  resultChecksum = checksum(upscaled);
  output = await createRgbaPixelMap(upscaled.pixels, upscaled.width, upscaled.height);
  engine = SuperResolutionEngineKind.LocalBicubic;
}

这段代码里有四个刻意的处理,每一个都对应一类真机问题:

第一,给模型一张"干净"的输入图。 解码器产出的 PixelMap 带着解码器的元数据,直接交给 AI 模型不一定稳妥;代码先 pixelMapToRgba 读出像素,再 createRgbaPixelMap 造一张全新的、OPAQUE、RGBA_8888、自己持有的图。这一步多一次拷贝,但把"模型能不能吃这张图"变成了确定的事。

第二,AI 的结果要验尺寸。 官方说输出 4 倍,不代表每次都对。hasExpectedSize 在拿到 candidate 后先看 ImageInfo,尺寸不对就记一条 warn,走 CPU 分支。没有这一步,页面可能把一张尺寸不对的图标成 4 倍。

第三,AI 的输出也要重新封装。 candidate 是服务返回的 native buffer,直接交给 ImagePacker 编码可能受服务生命周期影响;代码先读成 RgbaImage、算 checksum,再用 createRgbaPixelMap 造一张自己的图给编码器。candidate 在 finally 里释放。

第四,engine 只在尺寸校验通过后才改。 这样"AI 跑过但结果不合规"不会被误报成 core-vision;页面上的 实际引擎 永远对应真正产生像素的那条路。

runCoreVision 本身很短,但那个 request 的写法是整篇文章的起点:

async function runCoreVision(pixelMap: image.PixelMap): Promise<image.PixelMap> {
  const analyzer: imageSuperResolution.ImageSRAnalyzer =
    await imageSuperResolution.ImageSRAnalyzer.create();
  try {
    // visionBase.Request 没有公开构造函数,不能 new
    const input: visionBase.ImageData = { pixelMap };
    const request: visionBase.Request = { inputData: input };
    const response: imageSuperResolution.ISPResponse = await analyzer.process(request);
    return response.pixelMap;
  } finally {
    try {
      await analyzer.destroy();
    } catch (error) {
      // 释放不能掩盖处理错误
    }
  }
}

最后是并发锁。官方说同一进程不支持并发,原生模块用一个模块级 busy 标志把第二次请求挡在门外:

if (busy) {
  throw new Error('Image super-resolution is already running');
}
busy = true;
try {
  // decode → processPixelMap → JSON
} finally {
  busy = false;
}

这是"库层保护",不是"UI 层禁用"。示例页在请求期间也禁用了按钮,但真正防止 NPU 被两个请求同时占用的是 busy——任何调用方都绕不过去。

5.2 双三次:8 个抽头、两次卷积、一次取整

CPU 路线要解决两个问题:像质和确定性。像质决定回退结果能不能看,确定性决定它能不能和 ArkTS 侧逐字节对拍。

先看核函数。Catmull-Rom 的权重只跟采样点到输出点的距离有关:

function cubicWeight(distance: number): number {
  const value = Math.abs(distance);
  if (value <= 1) {
    return ((1.5 * value - 2.5) * value) * value + 1;
  }
  if (value < 2) {
    return (((-0.5 * value + 2.5) * value) - 4) * value + 2;
  }
  return 0;
}

每个轴上的输出位置只取 4 个源像素,权重按距离算一次,缓存成 indices + weights:

function buildTaps(sourceLength: number, targetLength: number): ResampleTaps {
  const scale = targetLength / sourceLength;
  const indices = new Int32Array(targetLength * 4);
  const weights = new Float32Array(targetLength * 4);
  for (let target = 0; target < targetLength; target += 1) {
    const center = (target + 0.5) / scale - 0.5;
    const base = Math.floor(center);
    const delta = center - base;
    const tap = target * 4;
    indices[tap] = clampIndex(base - 1, sourceLength);
    indices[tap + 1] = clampIndex(base, sourceLength);
    indices[tap + 2] = clampIndex(base + 1, sourceLength);
    indices[tap + 3] = clampIndex(base + 2, sourceLength);
    weights[tap] = cubicWeight(delta + 1);
    weights[tap + 1] = cubicWeight(delta);
    weights[tap + 2] = cubicWeight(1 - delta);
    weights[tap + 3] = cubicWeight(2 - delta);
  }
  return new ResampleTaps(indices, weights);
}

采样下标用 clampIndex 夹在 [0, length - 1],不引入镜像或循环边界。边界处理必须统一,否则原生和 TS 在图像最外一圈会算出不同的值,checksum 立刻对不上。

放大分两趟:水平趟把结果存进 Float32Array,保留小数;垂直趟读四行、加权、只在这时取整一次:

for (let x = 0; x < targetWidth * 4; x += 1) {
  output[targetRow + x] = clampChannel(
    horizontal[row0 + x] * weight0 +
    horizontal[row1 + x] * weight1 +
    horizontal[row2 + x] * weight2 +
    horizontal[row3 + x] * weight3,
  );
}

这样做的好处是每个输出像素的每个通道只做 8 次乘加(水平 4 次 + 垂直 4 次),而不是二维卷积的 16 次;同时只取整一次,避免两趟各自舍入带来的偏差。Float32Array 的精度足够,且所有运行时都遵循 IEEE-754,结果可复现。

确定性的另一半是 checksum。FNV-1a 的 32 位乘法在 JS 里有一个坑:Math.imul 在某些运行时/引擎版本上行为不一致。这个库手写了 16 位分段乘法:

function fnvMultiply(value: number): number {
  const high = (value >>> 16) * 16777619;
  const low = (value & 0xffff) * 16777619;
  return (((high & 0xffff) * 65536 + (low % 4294967296)) % 4294967296) >>> 0;
}

再加上"无随机数、无平台数学库、无 SIMD"的约束,同一个 Uint8Array 在 ArkTS 和纯 TS 里必须得到同一个 8 位十六进制串。三个演示场景的 checksum 分别是 d0734028、1af608c7、5c94bc69;测试会直接执行两边的源码比对,不是只比最终 JSON。

5.3 像素进出:512、行宽、16MB 与 4.79M 字符

解码入口先把长边压到 512,并统一成 RGBA_8888:

const scale = Math.min(1, limit / Math.max(info.size.width, info.size.height));
const width = Math.max(1, Math.round(info.size.width * scale));
const height = Math.max(1, Math.round(info.size.height * scale));
const options: image.DecodingOptions = {
  editable: false,
  desiredPixelFormat: image.PixelMapFormat.RGBA_8888,
  desiredSize: { width, height },
};
pixelMap = await source.createPixelMap(options);

512 × 341 的输入就是这样来的:原图可能是 4K,但解码时只保留长边 512,输出 2048。这一步同时决定了 AI 的输入尺寸和 PNG 的体积上限。

读像素时不能假设缓冲区紧排。PixelMap 的行宽可能带对齐 padding,readRgba 先问 getBytesNumberPerRow(),不一致就逐行重排:

const rowBytes = pixelMap.getBytesNumberPerRow();
const totalBytes = pixelMap.getPixelBytesNumber();
const buffer = new ArrayBuffer(totalBytes);
await pixelMap.readPixelsToBuffer(buffer);
const tightRowBytes = width * 4;
if (rowBytes === tightRowBytes) {
  return new Uint8Array(buffer);
}
// 行尾有 padding:逐行重排到 tightRowBytes

这个细节不处理,图会越往下越斜,而且不会报错——最后只能靠肉眼发现"超分结果怎么歪了"。

AI 路线的内存开销集中在这里:candidate 是 4× 的 PixelMap,读成 RgbaImage 后是 2048 × 1364 × 4 ≈ 11.2 MB(最大 2048 × 2048 时 16 MB);aiInput、candidate、output 三张图同时在生命周期里,峰值会更高。所以 finally 里的释放顺序是:先放 aiInput 和 candidate,再放 output,最后放解码得到的 DecodedImage。任何一个漏掉,连续超分几次就会把内存占满。

出图统一走 PNG data URI:

const packer = image.createImagePacker();
try {
  const option: image.PackingOption = { format: mime, quality };
  const encoded = await packer.packing(pixelMap, option);
  const base64 = new util.Base64Helper().encodeToStringSync(new Uint8Array(encoded));
  return `data:${mime};base64,${base64}`;
} finally {
  await packer.release();
}

为什么是 PNG 而不是 JPEG?超分结果是像素级的细节,JPEG 的块效应会把刚补出来的纹理再糊掉;PNG 无损,二值/图形内容也压得好。代价是字符串大:验收记录里一张 2048 × 1364 的结果 base64 约 4,787,226 字符,接近 4.8 MB。示例页的对策是在 JSON 面板里把它折成 <data URI · N chars>,真正的 result.image 仍然完整留给 <Image>:

<Image source={{ uri: result.image }} style={{ width: '100%', aspectRatio: 1.5 }} resizeMode="contain" />

data: URI 的好处是不落盘、不要权限、JS 直接能渲染;坏处是字符串要跨桥、进堆。所以输入长边取 512,不取官方允许的 2048:桥能接受的字符串体积决定了输出尺寸的上限。

5.4 桥:六个方法、六条异步元数据、一份字段顺序固定的 JSON

RN 侧对原生只有一个入口:codegen spec。src/NativeOhosSuperResolution.ts 声明了六个方法,全部返回 Promise<string>:

export interface Spec extends TurboModule {
  result(index: number, revision: number): Promise<string>;
  checks(): Promise<string>;
  capabilities(): Promise<string>;
  pickImage(): Promise<string>;
  superResolution(uri: string, factor: number): Promise<string>;
  superResolutionData(base64: string, factor: number): Promise<string>;
}

export default TurboModuleRegistry.get<Spec>('OhosSuperResolution');

为什么返回字符串而不是对象?因为这条契约要和纯 TS 引擎逐字符对齐。对象过桥会被重新序列化,字段顺序、数字格式、转义都可能变;字符串不会。imageResultToJson 手工拼 JSON,字段顺序就是契约的一部分:

return (
  `{"uri":${jsonQuote(result.uri)}` +
  `,"id":${jsonQuote(model.id)}` +
  `,"source":${jsonQuote(model.source)}` +
  `,"factor":${model.factor}` +
  `,"inputWidth":${model.inputWidth}` +
  `,"inputHeight":${model.inputHeight}` +
  `,"outputWidth":${model.outputWidth}` +
  `,"outputHeight":${model.outputHeight}` +
  `,"engine":${jsonQuote(engine)}` +
  `,"durationMs":${model.durationMs}` +
  `,"checksum":${jsonQuote(model.checksum)}` +
  `,"image":${jsonQuote(result.image)}}`
);

jsonQuote 不是 JSON.stringify 的包装,而是逐字符处理引号、反斜杠、换行、回车、制表符和所有 < 0x20 的控制字符。这样原生和纯 TS 的输出可以直接用字符串比较,测试里也是这么做的。

codegen 把 spec 变成两半:ArkTS 的 OhosSuperResolution.Spec 接口,和 C++ 的异步桥。生成的 OhosSuperResolution.cpp 里有六条元数据:

ARK_ASYNC_METHOD_METADATA(result, 2),
ARK_ASYNC_METHOD_METADATA(checks, 0),
ARK_ASYNC_METHOD_METADATA(capabilities, 0),
ARK_ASYNC_METHOD_METADATA(pickImage, 0),
ARK_ASYNC_METHOD_METADATA(superResolution, 2),
ARK_ASYNC_METHOD_METADATA(superResolutionData, 2),

每条告诉 RNOH 这个方法是不是异步、有几个参数。少一条,对应的 JS 方法就不会以异步方式注册,Promise 回不来。codegen 还生成了 BaseReactNativeOhosAiVisionPackage.h,C++ Package 只要继承它就能被 autolinking 找到:

namespace rnoh {
class RNOhosSuperResolutionPackage
    : public BaseReactNativeOhosAiVisionPackage {
 public:
  explicit RNOhosSuperResolutionPackage(Package::Context ctx)
      : BaseReactNativeOhosAiVisionPackage(ctx) {}
};
}

ArkTS 侧的 Package 只做一件事:把 OhosSuperResolution 这个名字映射到实现类。

export class RNOhosSuperResolutionPackage extends RNOHPackage {
  getUITurboModuleFactoryByNameMap(): Map<string, (ctx: UITurboModuleContext) => UITurboModule> {
    return new Map<string, (ctx: UITurboModuleContext) => UITurboModule>([
      [RNOhosSuperResolutionTurboModule.NAME,
        (ctx: UITurboModuleContext): UITurboModule => new RNOhosSuperResolutionTurboModule(ctx)],
    ]);
  }
}

JS 侧不直接碰 TurboModule,而是走 ohosModule.ts 的安全包装。非鸿蒙宿主(iOS / Android / Web / Expo)上 TurboModuleRegistry.get('OhosSuperResolution') 会返回 null 或者抛错;包装层统一成 null:

function getNativeModule(): OhosSuperResolutionSpec | null {
  try {
    return TurboModuleRegistry.get<OhosSuperResolutionSpec>('OhosSuperResolution') ?? null;
  } catch {
    return null;
  }
}

export async function superResolution(uri: string, factor = 4): Promise<SuperResolutionPayload | null> {
  const nativeModule = getNativeModule();
  if (nativeModule === null) {
    return null;
  }
  const json = await nativeModule.superResolution(uri, factor);
  return JSON.parse(json) as SuperResolutionPayload;
}

除了 superResolution(uri, factor),还有一条 superResolutionData(base64, factor):不打开文件,直接把内存里的 JPEG/PNG/WebP base64 交给原生解码。示例页内置的那张 512px 照片就是 base64,走这条路,结果里的 uri 是 memory:image。两条路径共用同一个 processPixelMap,所以 AI/CPU 的选择、checksum、PNG 编码完全一致。

capabilities() 返回设备的超分能力:

{"coreVision":true,"apiVersion":26,"factor":4,"maxInputEdge":512,"maxOutputEdge":2048}

页面顶部的三枚标签就是它:API 26、Core Vision 可用、上限 2048px。调用方可以在超分之前决定要不要走 AI,而不是等失败再猜。

5.5 交付:114 个文件、两份逐字节相同的引擎

构建分三条线:

npm run verify:package   # npm pack + HAR 内容 + 类型解析 + autolinking 元数据
npm run build:har        # 组装 harmony/ohos_super_resolution.har
npm run build:example    # Metro bundle + ohpm install + Hvigor 构建 unsigned HAP

build:har 走 tools/build-har.sh,verify:package 走 scripts/verify-package.cjs。后者不信任工作区,而是先 npm pack,再解开 tarball 逐项断言:入口文件、lib 的 CJS/ESM/声明、HAR 内的 OhosSuperResolution.cpp、SrImage.ts、SrEngine.ts,以及 package.json 里的四个 autolinking 字段。它还会拒绝 oh_modules、build、.hvigor、.cxx、artifacts 和签名材料。

当前包的结果是 114 个文件、100,741 字节(解包后 353,172 字节),包内容、HAR、Node16/Node 类型解析与 autolinking 元数据全部通过。示例 HAP 是 39,952,884 字节(约 38 MB);从 npm 压缩包安装、走 autolinking 构建的独立消费方 HAP 是 39,745,429 字节。

这里要说的是引擎的两份副本。HAR 必须自包含,所以 src/SuperResolutionEngine.ts 和 harmony/ohos_super_resolution/src/main/ets/sr/SrEngine.ts 各放一份,内容逐字节相同;tests/native-module.test.cjs 会直接读两个文件做字节比对。任何一边改了算法、忘了同步另一边,测试立刻失败。跨语言契约靠两份文件必须一样来约束,文档只是说明。

6. 我踩过的坑(每一条都有真实报错或真机现象)

以下坑全部来自这次开发的报错、真机现象和排查记录,按踩到的顺序排列。

坑一:visionBase.Request 不能 new,AI 路线静默退回 CPU。 这是整篇文章的起点。第一次在鸿蒙 PC 上跑,页面 nativeBridge: OK、Core Vision 可用,选图后结果尺寸也对,但 实际引擎 显示 本地双三次(CPU)。日志里只有一条被 catch 接住、没有往上抛的:

Constructor is false

原因是 visionBase.Request 没有公开构造函数,官方示例用的是类型化对象字面量:

const request: visionBase.Request = { inputData: input };

改掉之后 engine 立刻变成 core-vision。这个坑的教训是:回退路径太顺滑,会把失败伪装成成功。 如果页面不显示 engine,我会一直以为 NPU 在跑。

坑二:setCaps 拼错,首次安装页面直接报错。 示例页把 setCapabilities 写成了 setCaps,真机首次安装显示:

nativeBridge: FAILED · Property 'setCaps' doesn't exist

这类错误在 TypeScript 里本应被 tsc 挡住,但示例页当时没有走完整的类型检查路径。修复就是改名,教训是:示例代码也要进类型检查,不能因为"只是 demo"就放过。

坑三:Logger 的 hilog 格式串多了一个参数。 原代码:

hilog.error(0x0000, 'OhosSuperResolution', '%{public}s, %{public}s', message);

格式串有两个占位符,只传了一个参数,日志尾部残留一个 %{public}s。它不影响功能,但会污染每一条日志。改成 '%{public}s' 即可。这种问题只有真机看日志才会发现,单测和编译都不会报。

坑四:AI 说它是 4×,不代表它真的是 4×。 官方承诺输出固定 4 倍,但代码不能只信承诺。hasExpectedSize 在拿到 candidate 后先读 ImageInfo,尺寸不对就记一条 warn 并走 CPU 分支。这个检查没有等它出问题才加——如果没有这道检查,一旦某个设备/图片返回了非 4 倍的结果,页面会把它标成 core-vision,用户看到的"4×"就只是个标签。尺寸是模型契约的一部分,必须验。

坑五:4× 的 PixelMap 读回来是 16MB,checksum 不是免费的。 AI 路线为了算 checksum,要把 2048 × 2048 的 RGBA 读回 ArkTS 侧可比较的缓冲区:16 MB 内存、200–500ms 的遍历。一开始我以为 checksum 只是"加个哈希",实测才发现它把 AI 的端侧耗时抬高一截。最后的取舍是保留:没有它,原生和纯 TS 的一致性只能靠肉眼;有了它,两边可以逐字符对拍。代价写进 durationMs,不藏。

坑六:4.79M 字符的 base64,先把调试面板卡住了。 第一版把 result.image 原样塞进页面上的 JSON 预览,验收记录里一张 2048 × 1364 的图让页面明显卡顿——PNG 本身不算大,但 base64 膨胀 33%,再经过一次 JSON.stringify 和一次桥传输,字符串在 JS 堆里翻了几倍。修复是示例页在展示 JSON 前把 data: 字段折成 <data URI · N chars>;原生侧把输入长边压在 512,从源头上限制输出体积。如果业务真的需要归档大图,正确做法是让原生写沙箱文件返回 file://,而不是把几 MB 的字符串塞进 JSON。

7. 现在怎么用:从一次 pickImage 到一张 2048 的图

这个工程现在是一个标准的 React Native 三方库(包名 react-native-ohos-ai-vision,版本 0.3.0)。仓库已经按 npm 发布形态准备好,现阶段用本地 tarball 或 path 依赖接入:

# 先生成压缩包
npm pack

# 在应用的 JS 根目录安装
npm install /absolute/path/to/react-native-ohos-ai-vision-0.3.0.tgz

它只使用 peer 依赖,不捆绑 react / react-native;纯 TS 路径要求 react-native >= 0.68,原生路径要求 HarmonyOS 7(API 26)+ RNOH 0.84。本文的验证环境是 React 19.2.3 + RN 0.84.1 + RNOH 0.84.3。

最小用法:

import React, { useState } from 'react';
import { Image, Pressable, Text, View } from 'react-native';
import {
  capabilities,
  isOhosSuperResolutionAvailable,
  pickImage,
  superResolution,
  type SuperResolutionPayload,
} from 'react-native-ohos-ai-vision';

export function UpscaleCard() {
  const [result, setResult] = useState<SuperResolutionPayload | null>(null);
  const [message, setMessage] = useState('选择一张低清照片');

  const run = async () => {
    if (!isOhosSuperResolutionAvailable()) {
      setMessage('当前宿主没有注册原生 OhosSuperResolution');
      return;
    }
    const caps = await capabilities();
    setMessage(`API ${caps?.apiVersion} · Core Vision ${caps?.coreVision ? '可用' : '不可用'}`);
    const uri = await pickImage();
    if (uri === null) {
      return;
    }
    const payload = await superResolution(uri, 4);
    if (payload === null) {
      setMessage('原生超分模块不可用');
      return;
    }
    setResult(payload);
    setMessage(`超分完成 · ${payload.engine} · 端侧 ${payload.durationMs}ms`);
  };

  return (
    <View>
      <Pressable onPress={run}><Text>选择图片并超分(4×)</Text></Pressable>
      <Text>{message}</Text>
      {result !== null ? (
        <>
          <Image source={{ uri: result.image }} style={{ width: '100%', aspectRatio: result.outputWidth / result.outputHeight }} resizeMode="contain" />
          <Text selectable>校验和 {result.checksum} · {result.outputWidth} × {result.outputHeight}</Text>
        </>
      ) : null}
    </View>
  );
}

返回结构:

字段类型说明
uristring输入图片 URI;内存图路径为 memory:image
id / sourcestring结果标识与来源标签
factornumber本次放大倍数(2/3/4)
inputWidth / inputHeightnumber解码后的输入尺寸(长边 ≤ 512)
outputWidth / outputHeightnumberinput × factor,由模型构造器强制
engine'core-vision' | 'local-bicubic'实际产生像素的路线
durationMsnumber设备端实测(解码 + 推理 + 读回 + checksum + 编码)
checksumstring8 位小写十六进制 FNV-1a
imagestringPNG data: URI,可直接 <Image> 渲染

API 一览:

API说明
superResolution(uri, factor = 4)文件/相册 URI 的端侧超分;不可用时 resolve null
superResolutionData(base64, factor = 4)内存 JPEG/PNG/WebP base64 超分;uri 为 memory:image
pickImage()系统 PhotoViewPicker;取消或不可用时 null,不需要相册权限
capabilities(){ coreVision, apiVersion, factor, maxInputEdge, maxOutputEdge }
isOhosSuperResolutionAvailable()原生模块是否注册
resultJson / checksJson原生演示结果 / 自检 JSON;不可用时 null
SuperResolutionEngine纯 TS 确定性引擎(demoImage / result / runChecks)
upscale(image, factor)2/3/4 倍双三次放大,返回 RgbaImage
checksum(image)8 位 FNV-1a 校验和
toJson / imageResultToJson固定字段顺序的 JSON 序列化
superResolutionResultJson / runChecksJson纯 TS 桥接,失败返回 {"error":"..."} 而不抛错

构建与验证:

npm ci
npm test                  # Jest 29 例 + node:test 原生模块 6 例
npm run typecheck         # tsc --noEmit
npm run build:har         # 组装 source-style HAR
npm run build:example     # 构建示例 HAP(需要 DevEco 的 hvigor / ohpm)
npm run verify:package    # 校验 npm tarball、HAR、类型与 autolinking
npm run verify:integration # 打包产物 → autolinking → 独立消费方 HAP

当前版本的验证结果:

项目状态
npm test通过:Jest 29 / 29;node:test 原生模块 6 / 6
npm run typecheck通过,0 错误
npm run codegen:harmony通过:6 条 ARK_ASYNC_METHOD_METADATA,ArkTS Spec 同步
npm run build:har通过:BUILD SUCCESSFUL in 4 s 229 ms,产出 source-style HAR
npm run build:example通过:Metro bundle、ArkTS/C++ 链接,unsigned HAP 39,952,884 字节(约 38 MB)
npm run verify:package通过:114 个文件、100,741 字节;HAR、类型解析与 autolinking 全部通过
npm run verify:integration通过:从 npm 压缩包安装 → autolinking → 独立消费方 HAP 39,745,429 字节
真机HUAWEI MOR-M1 鸿蒙 PC(HarmonyOS 7.0.0.111 / API 26):engine = core-vision;512×341 → 2048×1364;端侧 2.64–2.68s、端到端 3.46–3.63s(两次记录);RGBA 校验和 67f7ebb6(验收记录);日志可见 ML_ISP_ImageSRServiceStub: initAlgorithmV2 complete, code:0

能力边界也写清楚:

  • 原生模块只支持 API 26+:HAR 的 compatibleSdkVersion 是 26,低版本系统加载会失败;纯 TS 引擎不受影响,可以在任意 RN ≥ 0.68 的宿主里跑;
  • AI 只支持 4×:2× / 3× 永远走本地双三次,factor 只接受 2…4 的整数;
  • 输入长边被压到 512:官方允许 2048,但为了让 PNG data: URI 能通过 RN 桥,本库在解码阶段就缩到 512;需要更大输出时改 MAX_INPUT_EDGE,同时要承担更大的 JS 字符串;
  • 不支持并发:同一进程第二次调用会 reject Image super-resolution is already running,UI 应该在请求期间禁用入口;
  • 它不是"万能增强":文字截图属于分布外输入,笔画会被模型"脑补",不如本地双三次好读;自然照片才是 AI 路线的正确演示对象;
  • checksum 有成本:4× RGBA 读回 + 遍历约 200–500ms,已计入 durationMs;不需要跨端对拍时可以在宿主侧关掉这段逻辑(需要改原生实现);
  • 结果不落盘:PNG 以 data: URI 返回,适合展示与转发,不适合归档超大图;需要落盘时由业务把 base64 写到沙箱。

更完整的说明在仓库的文档里:

  • 能力、API、JSON 契约、算法与兼容性;
  • RNOH 接入、手动链接、构建与真机验收步骤;
  • 构建记录、包校验与已知约束;
  • example/App.tsx:本文截图对应的单页超分示例;
  • templates/:宿主手动接线的 ArkTS / C++ 模板。

同系列的其它实现走了不同的路:kmp-ohos-ai-vision、electron-ohos-ai-vision、cordova-ohos-ai-vision 共享同一份 JSON 契约,但承载方式各不相同;RN 这条选的是 TurboModule + NPU + 确定性双三次兜底,一次调用同时拿回像素与可验证的元数据,不申请相册权限,也不落盘。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐