一个只对 ArkTS 开放的端侧模型、一条同进程的回环 HTTP 桥、一次 4 倍(面积 16 倍)的重建——这篇文章用一个 Qt 6 CMake 库加一套可导入 DevEco 的 ArkTS 壳,把“怎么放大、怎么过桥、怎么显示”这三件事拆开讲。

仓库地址:https://atomgit.com/oh-tpc/qt-ohos-ai-vision
三方框架版本:https://wiki.qt.io/Qt_for_HarmonyOS
组织仓库链接:https://atomgit.com/ohos-qt

0. 环境与实测设备

三方库适配信息:

三方库版本形态仓库地址
qt-ohos-ai-vision0.2.0Qt 6 CMake 库(add_subdirectory / FetchContent,默认静态库)https://atomgit.com/oh-tpc/qt-ohos-ai-vision
qt-ohos-ai-vision(ArkTS 侧)0.2.0HarmonyOS stage 工程(ohos/ 目录 + examples/ohos-app 完整 HAP)同仓库

实测环境:

项版本/型号
Qt6.11.0(桌面,Homebrew qtbase/qtdeclarative);库基线 Qt 6.5+;设备端 Qt for HarmonyOS 6.12 technology preview 载具(部署步骤见 OpenHarmony 示例说明)
系统 SDKHarmonyOS 26.0.0(API 26);compatible / compile / target 均 26.0.0
DevEco Studio6.x(签名、真机运行、HAP 调试)
构建桌面 macOS arm64、Xcode 26.2、CMake 4.3.2、Ninja 1.13.2;设备 hvigor 6.26.4
测试QtTest 19 项(结果解析 9 + 引擎状态机 10;mock 传输,不开 socket)
能力Core Vision Kit imageSuperResolution,API 26 起,固定 4×,仅中国境内
实测设备HUAWEI MateBook Pro S(MOR-M1),HarmonyOS 7.0.0.111(SP15C00E101R9P2),API 26
实测360×240 → 1440×960(60 / 98 ms,PNG 1606 KB);419×600 → 1676×2400(210 ms,PNG 6890 KB);640×427 → 2560×1708(274 ms);3000×2000 → 1024×683 → 4096×2732(670 ms,响应 15,162,995 B,端到端约 4.9 s)

1. 超分不是“放大”:我遇到的问题

这个仓库不是从零开始的。上一版是 qt-ohos-ocr:把 Core Vision Kit 的 textRecognition 接进 Qt,桥、引擎、单测、ArkTS 侧工程都已经跑通。后来翻 @kit.CoreVisionKit 的时候看到 imageSuperResolution:API 26 起、固定 4 倍、端侧、不需要联网。对 Qt 来说,这是另一个“ArkTS 有、C++ 没有”的能力,而且比 OCR 更适合展示——文字识别是一行行文本,超分是一张能直接放在窗口里对比的图。

桥不用重写。要换的是结果模型、尺寸策略,以及桥另一端的负载:OCR 传的是几 KB 的 JSON,超分传的是一张 1.6 MB 到 11 MB 的 PNG,base64 之后 JSON 能到 15 MB。同一个 127.0.0.1,同一套路由,负载换了一个量级。

我一开始对超分的理解很朴素:放大不就是插值吗?drawImage 一行、Lanczos 一下,像素变多,信息不变。第一次把内置的 360×240 样例丢进去,出来 1440×960、PNG 1606 KB;第二次从系统相册选了一张 419×600 的森林照片,出来 1676×2400、PNG 6890 KB。看到 6890 KB 那个数字,我才意识到这不是“画布变大”:模型真的在补细节,补出来的还是一张几 MB 的图,要原样搬回 Qt。

于是问题变成三个:

  • 尺寸:4× 是宽高各 4 倍、面积 16 倍。什么图直接送、什么图先缩、输出多大、内存怎么算,得有一本明账。
  • 传输:请求体是裸字节,响应体是 base64;大的响应 15 MB,不能指望一次 socket send 发完,还要定界、分片、超时。
  • 显示:QML 的 Image 要 URL,不要内存里的 QImage;结果要落盘、要能保存、要能原图/结果对照,还要把 downscaled 这类元数据如实传给 UI。

下面是干完之后的记录,坑都在第 6 节。

2. 效果展示

先看效果。这三张运行图来自两个 UI 宿主:前两张是 examples/ohos-app 的 ArkTS 演示页,第三张是 Qt Quick 窗口。它们调的是同一个 SuperResolution、同一条桥。

第一张是内置示例,一张 360×240 的低清风景:山脊、太阳、芦苇、几只鸟。ArkTS 页跑完写的是 完成:360 × 240 → 1440 × 960,下面一行 原生耗时 60 ms · 输出 PNG 1606 KB。左边原图、右边 4× 结果;原图在卡片里被放大到和结果一样宽,所以两边构图一模一样——4 倍不在缩略图里,在文件里。内置示例也不是随便找的图:tools/make_sample.py 先画一张 1440×960,再缩到 360×240;4× 超分正好是这个过程的逆操作。这样至少知道“原本的细节”长什么样,不会被 4× 的数字唬住。

在这里插入图片描述

第二张换了一张 419×600 的森林照片,从系统相册选进来。输出 1676×2400、210 ms、PNG 6890 KB。1676 = 419 × 4、2400 = 600 × 4,宽高各 4 倍,像素数是 16 倍。这张图的信息量比内置示例大得多,PNG 从 1.6 MB 涨到 6.9 MB,base64 之后 JSON 约 9.2 MB——这是后面桥要面对的负载。

这张 419×600 的森林图在 Cordova 那篇里也出现过;那边写的是 344 ms、920.3 KB JPEG,这边是 210 ms、6890 KB PNG。数字别直接比:210 ms 只量 analyzer.process(),344 ms 是 Cordova 整条链路(含解码/编码/预览);JPEG 和 PNG 也不是一个体积口径。能横向比的只有输入/输出尺寸——都是 419×600 → 1676×2400。

在这里插入图片描述

第三张是 Qt Quick 窗口,同一张内置示例:360 × 240 → 1440 × 960 · 原生耗时 98 ms,PNG 1606 KB,底部 ArkTS 桥 127.0.0.1:52141 · 协议 1 · v0.2.0 · 设备支持。这张不是 mock:设备上跑着 ArkTS 桥,开发机用 hdc fport tcp:52141 tcp:52141 把端口转过来,Qt 示例用 QTOHOS_AI_VISION_ENDPOINT 直连,第 2 节那张 Qt 截图就是这么截的。Qt 窗口比 ArkTS 页多两个按钮:系统相册(只在 available && supported && pickerAvailable 时出现)和 保存结果(把当前 PNG 另存)。ArkTS 页只有选图和内置示例;两边是同一套桥,UI 各自按宿主能力裁剪。

在这里插入图片描述

同一张 360×240,ArkTS 页 60 ms,Qt 窗口 98 ms,PNG 都是 1606 KB。不是 Qt 慢,也不是两次结果不同:elapsedMs 只量 analyzer.process(),模型实测在 61–105 ms 之间浮动,60 和 98 都在这个量级;三次实测的输出逐字节一致,说明模型对同一输入是确定性的,差异只在耗时,不在像素。真要比快慢,得把解码、PNG 编码、base64、HTTP 传输都算进去,那是另一个数字。

这里得说清楚:截图里看不出 4 倍。Qt 窗口 1080 宽,左右各一张卡,1440×960 的结果被压到四百多像素宽;ArkTS 页同理。整图缩略只用来看构图和颜色,判断 4× 得把两边都放到 1:1 像素下裁一块对比——Cordova 那篇做过 1:1 细节区,Qt 示例目前没有,这是它不如那篇直观的地方。要补也不难:在 ImageCard 里加一个裁切/放大模式,或者单独开一个细节对比页。

截图时还遇到过一次 offscreen 渲染的纹理残影:连拍时画面里叠着上一张的纹理,重拍就没了。三次模型输出逐字节一致(diff max 0),所以那是渲染/截图的锅,不是模型的。遇到类似现象,先重拍,别急着怀疑 NPU。

3. 4 倍之后,像素从哪来:一次超分的六段链路

写代码之前得先把原理捋好。一次 4× 超分从用户点按钮开始,到 QML 拿到 imageUrl 结束,中间是六段:

QML / C++:enhanceFile / enhanceBytes / pickAndEnhance
  │
  ▼
QOhosSuperResolution(C++)   Idle → Busy → enhanced / failed
  ├─ 读文件:QtConcurrent 工作线程
  ├─ 请求:BridgeHttpTransport(QNAM)
  └─ 结果:base64 PNG → QImage + 临时文件 URL
  │
  ▼  POST /v1/enhance?source=...  raw PNG/JPEG bytes
127.0.0.1:52141(同进程回环)
  │
  ▼
SrBridgeService(ArkTS,573 行)   手写 HTTP/1.1 子集
  ├─ 解析 Content-Length / 半包
  ├─ 路由 /v1/ping · /v1/enhance · /v1/pick
  └─ 响应按 128 KiB 分片写回
  │
  ▼
SuperResolution(ArkTS)
  ├─ ImageSource → PixelMap(必要时先缩到长边 1024)
  ├─ ImageSRAnalyzer.create()(进程内复用)
  ├─ analyzer.process()(串行、60 s 超时)
  └─ PixelMap → PNG → base64
  │
  ▼
Core Vision Kit · imageSuperResolution(端侧 NPU / 系统服务)

第 1 段:按钮。 QML 调 enhanceFile()、enhanceBytes() 或 pickAndEnhance()。读文件在 QtConcurrent 工作线程;busy 立刻置 true,一直保持到结果或失败回来。Busy 期间再点,直接 SR_BUSY,不排队。

第 2 段:请求。 编码后的图片字节原样 POST,Content-Type: application/octet-stream,不做 base64。/v1/enhance 的传输超时 120 秒,/v1/ping 20 秒,/v1/pick 600 秒——选图要等用户,不能 2 分钟就掐。

第 3 段:桥。 SrBridgeService 读 Content-Length,半包就等下一段 message;三个路由各自处理。请求体是裸字节,响应体是 UTF-8 JSON。

第 4 段:模型。 SuperResolution 解码成 PixelMap;长边超过 1024 先等比缩到 1024;ImageSRAnalyzer.create() 建分析器,analyzer.process() 出 4× PixelMap。同一进程同一特性不支持并发,所以 ArkTS 侧用 Promise 链串行,单次 60 秒超时;超时就丢弃分析器,下一次重建。

第 5 段:回包。 PixelMap 编成 PNG,base64 塞进 JSON;几何、耗时、downscaled 一起回。响应按 128 KiB 分片写,Content-Length 是完整 JSON 的字节数。

第 6 段:Qt。 QJsonDocument 解析,base64 解回 PNG,QImage::fromData() 解码;结果 PNG(以及可解码的原图)各写一份到临时目录,imageUrl / sourceUrl 给 QML,QImage 给 C++;发 enhanced()。

把尺寸列出来,4× 的成本就很直观了:

输入送入模型输出输出像素输出 RGBA输出 PNG响应 JSON
200×150200×150800×6000.48 MP约 1.8 MB——
360×240360×2401440×9601.38 MP约 5.5 MB1606 KB约 2.1 MB
419×600419×6001676×24004.02 MP约 16.1 MB6890 KB约 9.2 MB
640×427640×4272560×17084.37 MP约 17.5 MB——
3000×20001024×6834096×273211.19 MP约 44.7 MB约 11 MB15,162,995 B(约 15 MB)

“输出 RGBA”是按 宽 × 高 × 4 算的,“响应 JSON”是按 PNG 的 4/3 估的;1606 KB、6890 KB、15,162,995 B 是实测或记录里的数,其余标了“约”。这张表要说明的是面积 16 倍:PNG 编码、base64、socket send、Qt 解码、QImage 内存,每一层都按 16 倍像素算。

1024 这个数是算出来的,不是拍脑袋的。 模型的输入约束是宽高都大于 16、小于 2048,官方建议 1024 以下。一个 3:2 的 2047×1365 图,4× 之后是 8188×5460,RGBA 约 178 MB;3000×2000 不缩的话,输出 12000×8000(96 MP),更不用说。本库把长边钳到 1024:3000×2000 先缩到 1024×683,再出 4096×2732。downscaled 为 true,inputWidth/Height 一起回传,UI 会写“输入已缩放到 …”。

请求方向和响应方向是不对称的。 请求不做 base64,QNAM 直接 POST 原始字节,省一次编码,也省 1/3 体积;响应必须 base64,因为 JSON 要自带几何、耗时、downscaled、错误和图片。如果返回裸 PNG,就得自定义响应头或多段协议,curl 和调试都变麻烦。代价是响应体积 +33%,这也是为什么 1024 的上限不能松。

为什么是回环 HTTP,而不是别的? 把可选通道摆在一起:

方案结论
N-API 回调C++ 无法发起调用,需要 ArkTS 主动轮询,侵入 Qt 事件循环
共享内存 / 文件同步与生命周期复杂,跨语言约定多,大图还要自己分片
WebSocket / 自定义 TCP需要事件循环与大消息分片,收益不明显
回环 HTTP(本方案)请求-响应语义天然匹配、两端都易实现、可 curl 直接调试

和系列里其它载具摆在一起,Qt 这一格的特殊之处还是“载具本身没有 C++ → ArkTS 通道”:

载具与 ArkTS 的通道谁调系统 API
原生 ArkTS同语言直接调用ArkTS
KMP(kmp-ohos-ai-vision)Kotlin/Native → C ABI → N-APIArkTS
Cordova(cordova-ohos-ai-vision)Cordova 插件(ArkTS 侧实现)ArkTS
Flutter(flutter_ohos_core_vision)MethodChannel 插件ArkTS
React Native(react-native-ohos-ai-vision)RNOH 原生模块ArkTS
Electron(electron-ohos-ai-vision)hdc 四步 + 设备侧 ArkTS 代理设备代理
Qt(本库)同进程 127.0.0.1 回环 HTTP(QNAM)ArkTS 桥

能力边界也如实写:固定 4×,没有倍数参数,也没有 1× 增强/去噪;输入宽高必须大于 16,长边超过 1024 会先缩;同一进程串行,一次一张;输出 PNG 1.6–11 MB,base64 后 2.1–15 MB,最大那档端到端约 5 秒;仅 API 26+ 的 phone/tablet/2in1,仅中国境内;桌面必须靠 mock 或设备转发桥。ArkTS 演示页底部那行 需要 HarmonyOS 26.0.0(API 26)及以上,能力仅在中国境内提供 不是装饰,是硬门槛。但超分补的是统计上合理的细节,不是事实——别拿它去做取证、医学影像,或者把模糊车牌“变清楚”。

性能账再记一笔:360×240 的模型耗时 60–105 ms,419×600 是 210 ms,640×427 是 274 ms,3000×2000 送进模型的是 1024×683,模型 670 ms。大图的时间主要花在回包:15.16 MB 的 JSON、116 个 128 KiB 分片、base64 和 PNG 编码,端到端约 4.9 秒。模型是几百毫秒的事,搬运是几秒的事——超分把桥的负载从 KB 级推到了 MB 级。

4. 工程怎么搭:一份 CMake 库,一份 ArkTS 工程

先看整体结构。库本体是标准 Qt 6 CMake 工程,ohos/ 是待合并进载具的 ArkTS 侧文件,另有桌面示例和可直接导入 DevEco 的完整鸿蒙工程:

qt-ohos-ai-vision/
├─ include/qt-ohos-ai-vision/            # 公共头:引擎 / 结果 / 传输接口
│  ├─ qohossuperresolution.h             # QML/C++ 异步门面
│  ├─ ohossuperresolutionresult.h        # Q_GADGET 结果 + 几何/耗时/PNG
│  └─ bridge/
│     ├─ BridgeTransport.h               # IBridgeTransport(mock 注入点)
│     └─ BridgeHttpTransport.h           # QNAM 回环实现
├─ src/                                  # 引擎、结果解析、回环 HTTP
├─ ohos/                                 # ArkTS 壳:sr/、srbridge/、EntryAbility、诊断页
├─ examples/
│  ├─ quick/                             # Qt Quick 示例(前后对照 + 保存 + 截图)
│  └─ ohos-app/                          # DevEco 直接导入的演示 HAP
├─ tests/                                # QtTest 19 项(mock 传输)
├─ tools/
│  ├─ mock_bridge.py                     # 桌面 4× Lanczos + 锐化模拟桥
│  └─ make_sample.py                     # 生成 360×240 内置样例
├─ docs/                                 # API、架构、验证、预览图
└─ CMakeLists.txt · README.md · README.en.md · CHANGELOG.md

在这里插入图片描述

这次设计最关键的决定有三个。

传输是一个接口,不是一条写死的 HTTP 调用。 IBridgeTransport 只有 ping / postEnhance / postPick 三个操作,BridgeHttpTransport 是它的 QNAM 实现。单测注入 mock,19 项测试不开 socket;未来官方开放 C++ → ArkTS 通道,换一个实现类,引擎和 QML 不动。这个注入口就是整个库的可测试性所在,也是为什么引擎能在没有设备的情况下被完整测一遍。

桌面先行的理由很实际:没有设备也能把 QML 侧做完。 桌面没有 ArkTS 运行时,但 tools/mock_bridge.py 用 Lanczos 4× + 锐化模拟同一套协议;QML 的对照、状态、错误、保存、截图都能在桌面做完。要真实结果,就 hdc fport 把设备桥转过来,Qt 示例改一个环境变量直连——同一份 QML,不换分支。第 2 节那张 Qt 截图就是后者。

ArkTS 按 merge 块组织,不替换载具的 QAbility。 把 ohos/entry/src/main/ets/sr/ 与 srbridge/ 两个目录拷进载具的 ets/,再把 EntryAbility.ets 里标好的两段合并块并进 QAbility.onCreate() / onDestroy()。嫌麻烦就直接用 examples/ohos-app/——一套能导入、能签名、能跑的完整 stage 工程。

对 QML 侧来说,API 就这么点:

import QtOhosAiVision 1.0

QOhosSuperResolution {
    id: sr
    onEnhanced: (result) => {
        viewer.source = result.imageUrl          // 已落盘的临时 PNG
        console.log(result.outputWidth + "×" + result.outputHeight,
                    result.elapsedMs + " ms")
    }
    onFailed: (error) => console.warn(error)     // "SR_CODE: message"
}

Component.onCompleted: sr.probeAvailability()

C++ 侧也一样,不经过 QML 直接用:

#include <qt-ohos-ai-vision/qt_ohos_ai_vision.h>

QOhosSuperResolution sr;
QObject::connect(&sr, &QOhosSuperResolution::enhanced,
                 [](const OhosSuperResolutionResult &result) {
    result.image().save("enhanced.png");
    qInfo() << result.originalSize() << "->" << result.outputSize()
            << result.elapsedMs() << "ms";
});
QObject::connect(&sr, &QOhosSuperResolution::failed, [](const QString &error) {
    qWarning() << error;
});

sr.probeAvailability();
sr.enhanceFile(QUrl::fromLocalFile("/path/to/low-res.jpg"));

Qt 示例里“原图 / 超分结果”两张卡片的绑定也就这几行,imageUrl 和 sourceUrl 都是引擎落好的临时文件:

ImageCard {
    heading: qsTr("原图")
    imageSource: root.originalUrl
    caption: root.result !== null
             ? root.result.originalWidth + " × " + root.result.originalHeight
               + (root.result.downscaled ? " · 超分前缩放到 "
                                           + root.result.inputWidth + " × "
                                           + root.result.inputHeight : "")
             : "—"
}

ImageCard {
    heading: qsTr("超分结果")
    badge: "4×"
    imageSource: root.result !== null ? root.result.imageUrl : ""
    caption: root.result !== null
             ? root.result.outputWidth + " × " + root.result.outputHeight
               + " · PNG " + Math.round(root.result.byteSize / 1024) + " KB"
             : "—"
}

下面把库内部拆开讲:引擎怎么管一次任务、桥怎么搬几 MB 的图、SuperResolution 怎么把分析器和 60 秒超时管住、结果怎么从 JSON 落成可显示的图,最后是上鸿蒙的合并链路。

5. 把代码讲透

5.1 引擎:Busy 只有一位,临时文件只有一份

QOhosSuperResolution 的状态机很小:

Idle ── enhanceBytes()/enhanceFile()/pickAndEnhance() ──▶ Busy
Busy ── 桥回复 ──▶ enhanced(result) | failed(err) ──▶ Idle

所有公开入口都在调用线程(QML 下就是 GUI 线程)立即返回。读文件丢给 QtConcurrent,传输本身是 QNAM 异步;Busy 期间再调用,直接 SR_BUSY,不改 busy。probeAvailability() 是唯一允许并行的操作——探测不该被一次大图挡住。

// src/qohossuperresolution.cpp(节选)
void QOhosSuperResolution::enhanceFile(const QUrl &fileUrl)
{
    if (m_busy) {
        rejectCall(QStringLiteral("SR_BUSY: an enhancement is already running"));
        return;
    }
    // Accept file URLs, plain paths and Qt resource URLs. QFile() does not
    // understand the qrc: scheme, but it does understand the ":/" form, so
    // the bundled sample can stay inside the application binary.
    QString path;
    if (fileUrl.isLocalFile()) {
        path = fileUrl.toLocalFile();
    } else if (fileUrl.scheme() == QLatin1String("qrc")) {
        path = QLatin1Char(':') + fileUrl.path();     // qrc:/x → :/x
    } else {
        path = fileUrl.toString(QUrl::PreferLocalFile);
    }
    if (path.isEmpty()) {
        rejectCall(QStringLiteral("SR_INVALID_ARGUMENT: file URL must not be empty"));
        return;
    }

    if (m_available && !m_supported) {
        rejectCall(QStringLiteral("SR_UNSUPPORTED: this device does not advertise "
                                  "Core Vision Kit image super-resolution"));
        return;
    }

    setBusy(true); // held for the whole read + enhancement

    auto *watcher = new QFutureWatcher<QByteArray>(this);
    connect(watcher, &QFutureWatcherBase::finished, this, [this, watcher, path]() {
        const QByteArray bytes = watcher->result();
        watcher->deleteLater();
        if (bytes.isEmpty()) {
            failOperation(QStringLiteral("SR_IO_ERROR: cannot read ") + path);
            return;
        }
        startEnhanceBytes(bytes, QFileInfo(path).fileName());
    });
    watcher->setFuture(QtConcurrent::run([path]() -> QByteArray {
        QFile file(path);
        if (!file.open(QIODevice::ReadOnly))
            return QByteArray();
        return file.readAll();
    }));
}

这段里有四个决定:

先探测,再决定要不要发图。 如果 ping 回来 supported:false,enhanceBytes/enhanceFile/pickAndEnhance 都直接失败,不把几 MB 的图片发出去。m_available && !m_supported 这个条件很关键:还没探测过时不能拦,否则第一次调用会被误杀。

qrc: 与 :/ 是两套写法。 QFile 不认 qrc: scheme,只认 :/。内置样例用 qrc:/samples/sample.png 打进二进制,enhanceFile() 里必须映射一次,否则桌面点“内置示例”直接吃 SR_IO_ERROR: cannot read qrc:/samples/sample.png。

回调必须归一。 mock 可能在 postEnhance() 返回前就同步回调,QNAM 走的是异步信号。queued() 用 QMetaObject::invokeMethod(..., Qt::QueuedConnection) 把所有回调压到引擎线程,状态机始终单线程,测试才稳定:

// 同上(节选)
BridgeCallback QOhosSuperResolution::queued(
        std::function<void(const BridgeReply &)> handler)
{
    // Capture by value: the mock may fire before this function returns.
    return [this, handler](const BridgeReply &reply) {
        QMetaObject::invokeMethod(this, [this, handler, reply]() {
            handler(reply);
        }, Qt::QueuedConnection);
    };
}

临时文件只有一份当前结果。 引擎把增强 PNG 和原图各写一份到 QStandardPaths::TempLocation/qt-ohos-ai-vision/,新结果替换旧文件;clearResult() 和析构都会删。QML 只拿 imageUrl,不要长期缓存那个路径——下一次超分就把文件换了。

QML 那边注册的值类型名是小写的 ohosSuperResolutionResult(qmlRegisterUncreatableType<OhosSuperResolutionResult>(..., "ohosSuperResolutionResult", ...))。QML 的值类型命名要求小写,写成大写会注册不上或 QML 侧拿不到类型;引擎类型 QOhosSuperResolution 则只注册一次。

5.2 桥服务:图片进、base64 出,中间还有 128 KiB

ArkTS 侧 SrBridgeService 用 @ohos.net.socket 的 TCPSocketServer 监听回环,路由三条:

方法路径请求体响应
GET/v1/ping—{"name":"qt-ohos-ai-vision-bridge","protocol":1,"version":"0.2.0","capability":"imageSuperResolution","supported":true,"picker":true,"api":26,"scale":4,"minEdge":17,"maxEdge":1024}
POST/v1/enhance?source=原始图片字节几何 + elapsedMs + base64 PNG
POST/v1/pick—结果 JSON,或 {"cancelled":true}

传输规则收得很窄:HTTP/1.1 over 127.0.0.1:52141、Connection: close、一连接一请求、Content-Length 定界、ping 20 秒 / enhance 120 秒 / pick 600 秒。OCR 那版只有 20 秒;超分把 enhance 放宽到 120 秒,是因为模型 60 秒超时之后还要 base64、分片、传输,不能 60 秒一到就把回包掐了。

响应体是手写 JSON,图片 base64 直接拼进去:

// ohos/entry/src/main/ets/srbridge/SrBridgeService.ets(节选)
private static enhanceBody(run: SrRun): string {
  const helper: util.Base64Helper = new util.Base64Helper();
  const data: string = helper.encodeToStringSync(run.png);
  let text: string = `{"source":${jsonQuote(run.source)}` +
    `,"format":"png","scale":4` +
    `,"original":{"width":${run.originalWidth},"height":${run.originalHeight}}` +
    `,"input":{"width":${run.inputWidth},"height":${run.inputHeight}}` +
    `,"output":{"width":${run.outputWidth},"height":${run.outputHeight}}` +
    `,"downscaled":${run.downscaled}` +
    `,"elapsedMs":${run.elapsedMs}` +
    `,"data":${jsonQuote(data)}`;
  if (run.originalPng !== null) {
    text += `,"originalData":${jsonQuote(helper.encodeToStringSync(run.originalPng))}`;
  }
  return text + '}';
}

/v1/pick 会多带一个 originalData:系统相册选中的原图编码字节,Qt 侧据此写出 sourceUrl,前后对照才有“前”。这也意味着 picker 路径的响应比 enhance 多一张原图,base64 体积更大;UI 上只是多一个左侧卡片,桥上是实打实的几 MB。

回写要分片,一次 send 只写 128 KiB:

// 同上(节选)
private async write(
  client: socket.TCPSocketConnection,
  handled: Handled,
): Promise<void> {
  const bodyBytes: Uint8Array = SrBridgeService.encodeUtf8(handled.body);
  const header: string =
    `HTTP/1.1 ${handled.status} ${handled.reason}\r\n` +
    `Content-Type: application/json; charset=utf-8\r\n` +
    `Content-Length: ${bodyBytes.length}\r\n` +
    `Connection: close\r\n` +
    `\r\n`;
  const headerBytes: Uint8Array = SrBridgeService.encodeUtf8(header);
  const payload: Uint8Array =
    new Uint8Array(headerBytes.length + bodyBytes.length);
  payload.set(headerBytes, 0);
  payload.set(bodyBytes, headerBytes.length);

  try {
    // A 4x PNG of a large input crosses a few megabytes; chunking keeps
    // each socket send comfortably small.
    const chunkSize: number = 128 * 1024;
    for (let offset = 0; offset < payload.length; offset += chunkSize) {
      const end: number = Math.min(offset + chunkSize, payload.length);
      await client.send({ data: payload.slice(offset, end).buffer });
    }
  } finally {
    SrBridgeService.closeQuietly(client);
    this.drop(client);
  }
}

Content-Length 是完整 JSON 的字节数,不是单个分片的长度;Qt 侧 QNetworkReply::readAll() 收齐后一次性解析。15 MB 的响应大约 116 个分片。把 15 MB 一次 send 出去,等待时间和失败面都不可控;按 128 KiB 切片,每一片都有明确的完成边界。切片大小选 128 KiB 是为了可控,与吞吐优化无关。

HTTP 解析还是那套最小子集,但有两个边界值得单独说。GET 没有 body:QNAM 的 GET /v1/ping 不带 Content-Length,解析器一开始对所有方法都要求长度,ping 直接回 411 Length Required / SR_BRIDGE_BAD_REQUEST: Content-Length is required。修复是按方法给默认值:

// 同上(节选)
if (state.contentLength < 0) {
  // GET/HEAD/OPTIONS/DELETE carry no body, and Qt's
  // QNetworkAccessManager does not send Content-Length for them
  // (the GET /v1/ping probe is the important case).
  const method: string = SrBridgeService.methodOf(headerText);
  if (method === 'GET' || method === 'HEAD' ||
    method === 'OPTIONS' || method === 'DELETE') {
    state.contentLength = 0;
  } else {
    this.respondError(client, 411, 'Length Required',
      'SR_BRIDGE_BAD_REQUEST', 'Content-Length is required');
    return;
  }
}

头部有 64 KiB 上限,超了回 431 Request Header Fields Too Large;半包则 received.length < total 就 return,等下一段 message。这两条和模型无关,是手写 HTTP 必须自己兜的底。

错误也走同一层:{"error":{"code":"SR_TOO_SMALL","message":"..."}},HTTP 状态按错误码映射——SR_INVALID_ARGUMENT / SR_INVALID_IMAGE / SR_TOO_SMALL → 400,SR_UNSUPPORTED / SR_UNAVAILABLE → 503,SR_TIMEOUT → 504,其它 SR_VISION_ERROR → 500。Qt 侧原样映射成 "CODE: message",QML 不用解析裸字符串。用户取消选图是 {"cancelled":true} → SR_PICKER_CANCELLED——取消不是错误,UI 静默处理。

5.3 SuperResolution:分析器、串行队列和 60 秒

ArkTS 侧 SuperResolution 是实际调用模型的地方。它不长,351 行,但每一段都在处理设备侧的限制:

// ohos/entry/src/main/ets/sr/SuperResolution.ets(节选)
private static async run(bytes: Uint8Array, source: string): Promise<SrRun> {
  const analyzer: imageSuperResolution.ImageSRAnalyzer =
    await SuperResolution.ensureAnalyzer();

  let imageSource: image.ImageSource | null = null;
  let input: image.PixelMap | null = null;
  let output: image.PixelMap | null = null;
  try {
    imageSource = image.createImageSource(SuperResolution.toArrayBuffer(bytes));
    const sourceInfo: image.ImageInfo = await imageSource.getImageInfo();
    const originalWidth: number = sourceInfo.size.width;
    const originalHeight: number = sourceInfo.size.height;
    if (originalWidth < MIN_EDGE || originalHeight < MIN_EDGE) {
      throw new SrError('SR_TOO_SMALL',
        `Image is ${originalWidth}×${originalHeight}; both edges must be at ` +
        `least ${MIN_EDGE} px`);
    }

    let inputWidth: number = originalWidth;
    let inputHeight: number = originalHeight;
    let downscaled: boolean = false;
    const longEdge: number = Math.max(originalWidth, originalHeight);
    if (longEdge > MAX_EDGE) {
      const ratio: number = MAX_EDGE / longEdge;
      inputWidth = Math.max(MIN_EDGE, Math.round(originalWidth * ratio));
      inputHeight = Math.max(MIN_EDGE, Math.round(originalHeight * ratio));
      downscaled = true;
    }

    const decoding: image.DecodingOptions = {
      desiredPixelFormat: image.PixelMapFormat.RGBA_8888,
    };
    if (downscaled) {
      decoding.desiredSize = { width: inputWidth, height: inputHeight };
    }
    input = await imageSource.createPixelMap(decoding);

MAX_EDGE = 1024、MIN_EDGE = 17、PROCESS_TIMEOUT_MS = 60000 是三个硬常数。1024 的来历第 3 节算过;17 是因为模型要求宽高都大于 16;60 秒是“模型卡住”和“正常大图”之间的折中——正常 1024×683 只要 670 ms,60 秒足够覆盖慢设备,又不至于让 UI 挂死。

分析器创建一次,进程内复用。 ImageSRAnalyzer.create() 不便宜;ensureAnalyzer() 先查 canIUse('SystemCapability.AI.Vision.VisionBase'),再查静态缓存,最后才 create。release() 在 EntryAbility.onDestroy() 调,analyzer.destroy() 失败也只是吞掉——进程都要走了。

模型不支持并发,所以串行。 官方约束写得很清楚:同一特性不支持同进程并发调用。serialized() 用一条 Promise 链把 run() 排成一队,前一个失败也不能堵住后一个:

// 同上(节选)
private static serialized(task: () => Promise<SrRun>): Promise<SrRun> {
  const run: Promise<SrRun> = SuperResolution.tail.then(
    (): Promise<SrRun> => task(),
    (): Promise<SrRun> => task());
  SuperResolution.tail = run.then((): void => {
  }, (): void => {
  });
  return run;
}

注意 then 的第二个参数:上一条任务失败时也要执行下一条。只写 then(task) 的话,一次 SR_TOO_SMALL 会让整条链变成 rejected 状态,后面的调用全跟着失败——这是 Promise 链最容易踩的坑之一。

超时之后要丢掉分析器。 withTimeout() 给 analyzer.process() 套 60 秒;超时抛 SR_TIMEOUT,run() 里捕获到就把静态分析器置空并异步 destroy(),下一次调用重新 create。不丢的话,下一次会继续等一个已经卡死的实例,等于把 60 秒的坑变成永久卡死:

// 同上(节选)
const started: number = Date.now();
let response: imageSuperResolution.ISPResponse;
try {
  response = await SuperResolution.withTimeout(analyzer.process(request));
} catch (error) {
  if (error instanceof SrError && error.code === 'SR_TIMEOUT') {
    SuperResolution.resetAnalyzer();
  }
  if (error instanceof Error) {
    throw error;
  }
  throw new SrError('SR_VISION_ERROR', srErrorMessage(error));
}
const elapsedMs: number = Date.now() - started;

finally 里的释放顺序是 output → input → imageSource,逆着获取顺序,每个都包 try/catch。原因很实际:释放失败不能盖住结果或原始错误;逆序释放,避免先放掉还被前面引用的底层对象。elapsedMs 从 analyzer.process() 之前开始,到它返回结束——只算模型,不含解码、PNG 编码、base64、传输。这也是为什么 60 ms/98 ms/210 ms 这些数字不能和 Cordova 那篇的 344 ms(整条链路)直接比。

最后 encodePng() 用 image.createImagePacker(),format: 'image/png'、quality: 100;finally 释放 packer。PNG 是无损的,所以 419×600 的输出能到 6890 KB——4 MP 的 RGBA 照片本来就大,和编码优化无关。

5.4 结果解析:图片是真相,JSON 只是说明

Qt 侧 OhosSuperResolutionResult::fromWireJson() 的规则是“对负载严格,对元数据宽容”:

// src/ohossuperresolutionresult.cpp(节选)
const QByteArray png = QByteArray::fromBase64(
            object.value(QStringLiteral("data")).toString().toLatin1());
if (png.isEmpty()) {
    setError(errorMessage, QStringLiteral("\"data\" is missing or empty"));
    return false;
}
const QImage image = QImage::fromData(png);
if (image.isNull()) {
    setError(errorMessage,
             QStringLiteral("the bridge returned a picture Qt cannot decode"));
    return false;
}

// The picture itself is the ground truth for its dimensions.
parsed.m_png = png;
parsed.m_image = image;
parsed.m_outputSize = image.size();

parsed.m_scaleFactor = object.value(QStringLiteral("scale")).toInt(4);
if (parsed.m_scaleFactor <= 0)
    parsed.m_scaleFactor = 4;

QSize input;
QSize original;
if (!readSize(object, QStringLiteral("input"), &input, errorMessage)
        || !readSize(object, QStringLiteral("original"), &original, errorMessage)) {
    return false;
}
if (!input.isValid()) {
    input = QSize(qMax(1, parsed.m_outputSize.width() / parsed.m_scaleFactor),
                  qMax(1, parsed.m_outputSize.height() / parsed.m_scaleFactor));
}
if (!original.isValid())
    original = input;
parsed.m_inputSize = input;
parsed.m_originalSize = original;

parsed.m_downscaled = object.contains(QStringLiteral("downscaled"))
        ? object.value(QStringLiteral("downscaled")).toBool(false)
        : (original != input);

几个决定值得说:

输出尺寸以解码后的图片为准,不以 JSON 为准。 JSON 里也写了 output.width/height,但 QImage 解出来是多大就是多大;模型和编码器给的是实际像素,JSON 可能过期或写错。这个选择让“图片坏了但 JSON 看起来正常”这种半成品不会当成成功。

输入/原图尺寸可以缺,缺了就从输出反推。 input = output / scale,original = input;如果 original != input 且没有 downscaled 字段,就推断为 true。这样 mock 或旧版桥少给字段时 UI 仍能显示,不会因为缺元数据把整张图丢掉。

缺 data 或解不出图,直接失败。 SR_BRIDGE_PROTOCOL,不是“返回一张空图”。这条在测试里专门钉住:

// tests/tst_ohossuperresolutionresult.cpp(节选)
const QImage output = testImage(32, 20);
const QByteArray payload = QJsonDocument(QJsonObject{
        {QStringLiteral("source"), QStringLiteral("plain.png")},
        {QStringLiteral("data"), QString::fromLatin1(imagePng(output).toBase64())},
}).toJson(QJsonDocument::Compact);

OhosSuperResolutionResult result;
QVERIFY(OhosSuperResolutionResult::fromWireJson(payload, &result));
QCOMPARE(result.outputSize(), QSize(32, 20));
// 没有 input/original 时按 4× 反推:32/4=8,20/4=5。
QCOMPARE(result.inputSize(), QSize(8, 5));
QCOMPARE(result.originalSize(), QSize(8, 5));
QVERIFY(!result.downscaled());

这段测试只给 source 和 data,故意不给几何;如果实现偷偷依赖 input,这里就红了。契约不靠注释,靠断言。

临时文件是另一半。QOhosSuperResolution::writeTemp() 把 PNG 写到 <temp>/qt-ohos-ai-vision/,文件名带毫秒时间戳和自增计数器;新结果替换旧文件,clearResult() 和析构删除。原图预览是“尽力而为”:写失败不影响超分本身,sourceUrl 为空,QML 左侧卡片显示占位。这个取舍很重要——不能因为一张对照图写不出来,把已经成功的结果判失败。

saveResult() 则相反:用户主动保存,失败必须报。QImageWriter 按后缀选格式,没后缀默认 PNG;路径为空、图无效、写不进去,返回 false 并发 SR_IO_ERROR。

5.5 上鸿蒙:Qt 载具、hdc fport 和一次真机联调截图

上鸿蒙分两条路。只跑 ArkTS 半边:DevEco 打开 examples/ohos-app/,自动签名,运行;页面自己就能完成选图/超分。接 Qt:用 Qt for HarmonyOS 的 harmonydeployqt 生成官方 stage 壳,把 sr/、srbridge/ 拷进去,合并两段:

// ohos/entry/src/main/ets/entryability/EntryAbility.ets(节选)
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
  // ---- qt-ohos-ai-vision merge block 1/2: start the bridge ----------
  SrBridgeService.getInstance().start(this.context);
  // ---------------------------------------------------------------------
  // Qt carrier note: keep the carrier template's Qt initialization call
  // here (loading the Qt runtime / your Qt main()).
}

onDestroy(): void {
  // ---- qt-ohos-ai-vision merge block 2/2: stop the bridge -----------
  SrBridgeService.getInstance().stop();
  // Release the process-wide Core Vision Kit analyzer; not awaited.
  SuperResolution.release().catch((): void => {
  });
}

QAbility 是载具模板生成的文件,不要替换;只在它生成的生命周期里加这两段。桥在 onCreate 尽早启动,避免 Qt UI 第一帧就发请求时端口还没监听。module.json5 里要有 ohos.permission.INTERNET(loopback socket 需要,system_grant,无运行时弹窗);不需要相册/存储权限,选图走系统 Picker。

构建和真机联调大概是这样一条线:

# 前提:演示 HAP 已安装并启动(构建/安装命令见第 7 节)

# 1) 把设备桥端口转到开发机,先验协议
hdc fport tcp:52141 tcp:52141
curl -s http://127.0.0.1:52141/v1/ping

# 2) 桌面 Qt 示例直连设备桥,截一张真机结果的图
QTOHOS_AI_VISION_ENDPOINT=http://127.0.0.1:52141 \
  ./build-desktop/examples/quick/quick_example --sample --capture preview.png

最后一步就是那张截图的来源。hdc fport 把设备的 52141 转到开发机,Qt 示例以为自己在连本地,其实是设备上的 ArkTS 桥在跑模型。--capture 等 4.5 秒才截图(OCR 示例是 2.2 秒),因为超分 + PNG 编码 + base64 比文本慢;第一次按 OCR 的 2.2 秒等,截到的是“正在超分…”,后来才调到 4.5 秒。

需要说明的是:仓库里验证的是“桌面 Qt 示例 + hdc fport + 设备 ArkTS 桥”这条链路;把 Qt 运行时和示例可执行文件整个装进 HarmonyOS 载具的部署不在本仓库 CI 里,命令和合并清单在 OpenHarmony 示例说明里。桥这半边已经用真机跑通,Qt 载具那半边按文档接——这也是为什么第 2 节的 Qt 截图是桌面窗口,不是设备桌面上的 Qt 窗口。

Qt for HarmonyOS 这边还有两个现实约束:官方载具目前是 Qt 6.12 technology preview,主机以 Linux 为主,macOS 走 Qt 官方安装器 + DevEco;Qt 6.8/6.9 的发布说明里没有 OpenHarmony/HarmonyOS,别拿网上的“官方支持”当依据。手工集成(不用 harmonydeployqt)时,Qt 运行库进 entry/libs/arm64-v8a/,QML 模块文件进 entry/src/main/resources/resfile/qml/——so 走 libs、QML 文件走 resfile,少一条都 import 失败。

6. 踩坑与经验

这一节全是坑,全部来自这次开发的真实报错、代码注释、提交记录和实测。

坑一:4× 还是 2×?文档摘要骗了我。 有摘要把 imageSuperResolution 写成 2×,我按 2× 算过 360×240 的预期输出是 720×480;实际跑出来是 1440×960。200×150 → 800×600、419×600 → 1676×2400、640×427 → 2560×1708,全是宽高各 4×。接口没有倍数参数,别在代码里写死 2,也别按“面积 4 倍”算内存——是面积 16 倍。以设备实测为准,别以摘要为准。

坑二:2047 的输入上限,不等于 2047 可以随便给。 模型要求宽高小于 2048,但 4× 之后是 8188 长边;一个 3:2 的 2047×1365 图输出 8188×5460,RGBA 约 178 MB,还没算 PNG 编码和 base64。本库把长边钳到 1024:3000×2000 → 1024×683 → 4096×2732,RGBA 约 44 MB。downscaled=true 和 inputWidth/Height 必须回传,否则 UI 会把一张缩过的图当成原尺寸结果。模型的“能收”和设备的“能扛”是两回事。

坑三:同一进程不支持并发,Promise 链还会被一次失败卡死。 官方约束是同一特性不支持同进程并发调用;Qt 侧同时只允许一个任务,SR_BUSY 直接失败。ArkTS 侧用 Promise 链串行,这里有个很容易写错的点:只写 tail.then(task) 的话,一次 SR_TOO_SMALL 会让整条链变 rejected,后面的任务全跟着失败。实现里是 then(task, task):成功和失败都继续下一条。串行队列的失败分支,比成功分支更重要。

坑四:60 秒超时之后,分析器必须一起丢掉。 withTimeout() 抛 SR_TIMEOUT 只是让这次调用失败;如果静态 analyzer 还留着,下一次 process() 会继续等一个已经卡死的实例。代码里超时后走 resetAnalyzer():置空 + 异步 destroy(),下次重建。正常 1024×683 只要 670 ms,60 秒是给慢设备/大图留的余量;真超时了,分析器多半已经不可用。超时要连资源一起重置,不能只重置 Promise。

坑五:15 MB 的响应,不能指望一次 socket send。 1024×683 → 4096×2732 的那次,HTTP 响应 15,162,995 字节,端到端约 4.9 秒。把整个 payload 一次 client.send,等待时间和失败面都不可控;实现里按 128 KiB 分片、await 每一片,15 MB 那次完整回来。Content-Length 仍然是完整 JSON 的字节数,Qt 侧 readAll() 收齐再解析。大响应不能只靠多等一会儿,发送方式本身要改。

坑六:超分成功了,ArkTS 页两栏还是空的。 这个单独一个 commit:fix(ohos-app): 修复超分结果面板不刷新。现象是 status 已经变成“完成:360×240 → 1440×960”,左右两栏还停在“选择图片开始”/“结果会显示在这里”。原因是 @Builder beforePane(pixelMap) / afterPane(pixelMap) 把 PixelMap 当参数传进去;ArkUI 的 @Builder 参数按值传递,@State 变了但 Builder 不重绘。修复是 Builder 里直接读 this.before / this.after,不再传参。代码注释写得很直白:parameters are passed by value and do not refresh when the PixelMap state changes。ArkUI 的 Builder 不是 React 组件,别把状态当 props 传。

坑七:buffer.Buffer.buffer 是池化的,Content-Length 会对不上。 ArkTS 侧一开始用 buffer.from(...).buffer 拼响应,设备上偶尔出现 Content-Length 和实际字节数不一致,Qt 侧随后报 SR_BRIDGE_PROTOCOL。原因是 Buffer 的底层是池化 ArrayBuffer,byteOffset/length 不一定是 0/长度。修复是用 util.TextEncoder 生成独立的 Uint8Array。跨语言边界上,字节数组必须是“独立的”,不能是别人池子里的一段。

坑八:GET /v1/ping 被自家桥回了 411。 QNAM 的 GET 不带 Content-Length,而微型解析器一开始对所有方法都要求长度,ping 直接 411 Length Required / SR_BRIDGE_BAD_REQUEST: Content-Length is required。修复是 GET/HEAD/OPTIONS/DELETE 默认 0,其它方法才回 411。HTTP 子集越小,越要把“谁带 body”写死。

坑九:API 26、中国境内、支持的设备类型,一个不满足就是 SR_UNSUPPORTED。 模拟器通常没有这个 AI 服务;低版本系统、非 phone/tablet/2in1、境外设备都可能直接 supported:false 或模型创建失败。canIUse('SystemCapability.AI.Vision.VisionBase') 只能说明系统声明了能力,不代表模型服务真的可用——真机实测才是准。遇到 SR_UNSUPPORTED,先看系统版本/设备类型/地区,再怀疑代码。别在模拟器上验端侧 AI,验 UI 和桥就够了。

7. 现在怎么用:从 add_subdirectory 到 1676×2400

经过上面的整理,这个工程是“Qt 6 CMake 库 + ArkTS 工程”双形态交付(版本 0.2.0,MIT)。接入两种方式:

# 方式一:add_subdirectory
find_package(Qt6 6.5 REQUIRED COMPONENTS Core Gui Quick Qml Network)
add_subdirectory(third_party/qt-ohos-ai-vision)

target_link_libraries(my_app PRIVATE
    Qt6::Quick
    qt-ohos-ai-vision::qt_ohos_ai_vision)

# 方式二:FetchContent
include(FetchContent)
FetchContent_Declare(qt_ohos_ai_vision
    GIT_REPOSITORY https://atomgit.com/oh-tpc/qt-ohos-ai-vision.git
    GIT_TAG        main)
set(QT_OHOS_AI_VISION_BUILD_EXAMPLES OFF CACHE BOOL "" FORCE)
set(QT_OHOS_AI_VISION_BUILD_TESTS OFF CACHE BOOL "" FORCE)
FetchContent_MakeAvailable(qt_ohos_ai_vision)

宿主检查清单六条:加载 QML 前调 qtOhosAiVisionRegisterQmlTypes();QAbility 合并两个 merge 块;module.json5 加 ohos.permission.INTERNET;sr/ 与 srbridge/ 拷进载具;改端口时 SrBridgeService.start(context, port) 与 QTOHOS_AI_VISION_ENDPOINT 成对;设备不支持时 supported:false 要 fail fast,别把图发出去。

桌面构建有一处 Homebrew 的坑:qtbase 和 qtdeclarative 是两个 keg,只给一个 CMAKE_PREFIX_PATH 时 CMake 会报找不到 Qt6Quick 的 config;两个前缀都给了才行:

cmake -S . -B build-desktop -G Ninja \
  -DCMAKE_PREFIX_PATH=/opt/homebrew/opt/qtbase \
  -DQT_ADDITIONAL_PACKAGES_PREFIX_PATH=/opt/homebrew/opt/qtdeclarative
cmake --build build-desktop --parallel
ctest --test-dir build-desktop --output-on-failure

桌面看完整效果,先起 mock 桥(需要 Pillow),再跑内置示例:

python3 tools/mock_bridge.py &
QTOHOS_AI_VISION_ENDPOINT=http://127.0.0.1:52141 \
  ./build-desktop/examples/quick/quick_example --sample
# 截图模式在结果出来后写文件并退出
QTOHOS_AI_VISION_ENDPOINT=http://127.0.0.1:52141 \
  ./build-desktop/examples/quick/quick_example --sample --capture sr.png

设备侧一条 hvigor 命令出 HAP,DevEco 配自动签名后安装;桥的协议可以直接从开发机调:

# 安装演示 HAP
cd examples/ohos-app
hvigorw --mode module -p product=default -p module=entry@default assembleHap
hdc install -r entry/build/default/outputs/default/entry-default-signed.hap
hdc shell aa start -a EntryAbility -b com.example.qt_ohos_ai_vision_app

# 端口转发 + 能力探测
hdc fport tcp:52141 tcp:52141
curl -s http://127.0.0.1:52141/v1/ping

# 直接调超分:原始图片字节进,JSON 出,data 是 base64 PNG
curl -s --data-binary @examples/quick/samples/sample.png \
  -H 'Content-Type: application/octet-stream' \
  'http://127.0.0.1:52141/v1/enhance?source=sample.png' -o sr.json

# 看桥日志
hdc shell hilog | grep qt_ohos_ai_vision

更完整的 API、协议、错误码和合并步骤在仓库的文档里:

  • 中文主文档(能力边界、环境、集成、构建、部署、FAQ);
  • 英文说明:英文版;
  • API 文档:QOhosSuperResolution、OhosSuperResolutionResult、传输层与错误码;
  • 架构文档:架构、为什么桥、生命周期、尺寸策略、完整协议;
  • 验证记录:桌面单测、ArkTS 编译、真机 ping/enhance 记录;
  • OpenHarmony 示例说明:DevEco 导入、签名、hdc 验证、载具合并;
  • tests/:19 项 QtTest(结果解析 9 + 引擎状态机 10,mock 传输,不开 socket)。

当前版本在 Qt 6.11.0(macOS arm64)与 HUAWEI MateBook Pro S(API 26,2in1)上验证:Qt 侧 2/2 测试二进制、19 项函数全绿(几何回退、base64/PNG 严格校验、落盘、能力探测、不支持 fail-fast、桥不可用、SR_BUSY、错误体映射、选图取消、文件读取、保存/清理、协议违规);ArkTS 两份工程在 API 26 下编译出 HAP;设备上 /v1/ping、/v1/enhance 实测通过,360×240 三次 61/83/85 ms 且输出逐字节一致,419×600 210 ms / 6890 KB,640×427 274 ms,3000×2000 先缩到 1024×683 再出 4096×2732(模型 670 ms,响应 15,162,995 字节,端到端约 4.9 s);Qt 示例经 hdc fport 直连设备桥,截到 98 ms / 1606 KB 的那张图。4 倍的产出是 16 倍像素:模型算完,还要 PNG 编码、base64、HTTP 传输、Qt 解码、落盘,最后给到 QML。两端都在 127.0.0.1,中间每一段都有协议约束。

Logo

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念,把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起,为开发者提供从开发、训练到部署的一站式体验。

更多推荐