AI模型推理服务推理引擎本地部署多模态【免费下载链接】runanywhere-sdksProduction ready toolkit to run AI locally项目地址https://gitcode.com/gh_mirrors/ru/runanywhere-sdks点击查看免费下载导读runanywhere/qhexrt是 RunAnywhere React Native SDK 的 Qualcomm Hexagon NPU 后端包它让 Androidarm64-v8a应用可以在搭载 Snapdragon V75/V79/V81 级 Hexagon NPU 的设备上离线运行大语言模型LLM、视觉语言模型VLM、语音识别STT与语音合成TTS。本文以该包的官方 README 为骨架结合仓库中的 TypeScript 源码、Nitrogen 桥接规范、C 适配层与引擎头文件完整讲解安装步骤、探测/注册 API、设备能力判定逻辑、设备感知的模型注册流程以及底层实现原理帮助你在一台真实 Snapdragon 设备上把 NPU 加速的本地 AI 能力接入自己的 React Native 应用。一、QHexRT 是什么为 Snapdragon NPU 而生的后端模块runanywhere/qhexrt全称 Qualcomm Hexagon Runtime简称 QHexRT是 RunAnywhere 面向高通平台的私有、闭源 C NPU 运行时运行的是 Snapdragon HexagonHTP上预先编译好的 QNN context 二进制路由当前 LLM、VLM、ASR/STT、TTS、embedding 与图像恢复/修复等工作负载。它的定位在 qhexrt_backend.h 中有明确描述QHexRT is a PRIVATE, closed-source C runtime that runs prebuilt QNN context binaries on Snapdragon Hexagon NPUs (HTP).从仓库结构看QHexRT 的源码从不进入本仓库SDK 通过一个 ABI 稳定的 C 头文件qhexrt/qhexrt_c.h外加预编译静态库libqhexrt_core.alibqhexrt_host.a消费它这些归档被直接链接进插件.so因此不存在单独分发的 QHexRT 二进制。对于 React Native 开发者来说你只需要关心上层 npm 包暴露的 TypeScript API底层细节全部由引擎层封装。在 engines/qhexrt/qhexrt_backend.h 中还可以看到平台支持判定宏#if (defined(__ANDROID__) defined(__aarch64__)) || \ (defined(_WIN32) (defined(_M_ARM64) || defined(__aarch64__))) #define RAC_QHEXRT_PLATFORM_SUPPORTED 1 #else #define RAC_QHEXRT_PLATFORM_SUPPORTED 0 #endif也就是说除 Androidarm64-v8a外Windows on ARM64Snapdragon X / X2 Elite也被视为真实 Hexagon 目标但在 React Native 绑定层当前只面向 Android 交付见下文RunAnywhereQHexRT.nitro.ts中android: c的限定。二、安装与前置要求2.1 安装命令在 React Native 项目的package.json中同时安装 core 包与 qhexrt 后端包版本号需与 core 保持兼容README 示例为 0.20.11当前仓库内包版本为 0.20.37实际请以 npm 上发布的版本为准npm install runanywhere/core0.20.11 runanywhere/qhexrt0.20.11从 package.json 可以看到该包的依赖关系peerDependenciesrunanywhere/core 0.20.37、react 19.0.0、react-native 0.83.1、react-native-nitro-modules ^0.33.9QHexRT 模块基于 Nitro Modules 构建dependencies仅runanywhere/proto-ts工作区引用用于 protobuf 编解码。2.2 硬件与系统要求README 明确列出两条硬性要求要求说明系统架构Androidarm64-v8a专用Nitro spec 仅声明android: c芯片搭载 Qualcomm Snapdragon Hexagon V75 / V79 / V81 NPU 的设备在src/specs/RunAnywhereQHexRT.nitro.ts的接口注释中同样强调QHexRT is Qualcomm-only (Snapdragon Hexagon NPU); the package ships arm64-v8a Android binaries exclusively. 因此非 Android 平台iOS、WASM 等或非 Snapdragon 设备上该模块不可用即便是 Snapdragon 设备若 Hexagon 代次不在 V75/V79/V81 之列能力探测会返回不支持。2.3 Android 工程接入Android 侧原生代码位于 android/ 目录src/main/cpp/cpp-adapter.cpp是 React Native CMake 构建系统要求的 JNI 入口src/main/java/com/margelo/nitro/runanywhere/qhexrt/下包含 Kotlin 侧的 Package 与骨架安装器RunAnywhereQHexRTPackage.kt、QHexRTSkelInstaller.kt。骨架skel目录的设置通过 JNI 调用rac_qhexrt_set_skel_directory完成见 cpp-adapter.cpp。完整的 Android 环境搭建步骤请参考 React Native SDK README即 bindings/react-native/README.md。三、核心 API 与典型使用流程3.1 导入与三行接入包的公开入口 src/index.ts 重新导出了QHexRT门面对象以及两个 protobuf 线格式类型NpuCapability、HexagonArch。README 的最小示例import { QHexRT } from runanywhere/qhexrt; const npu await QHexRT.probeNpu(); // safe on any device if (npu.qhexrtSupported) { await QHexRT.register(); } // Register, download, load, and infer via runanywhere/core注README 示例中的qhexrtSupported字段对应 hardware_profile.proto 中NpuCapability.supported第 4 字段注释为 True iff this accelerator generation is in the device-validated supported set (Hexagon v75/v79/v81 today)。实际代码里更常见的写法是if (npu.supported)两种命名在语义上等价可参见源码中的用法。3.2 完整示例探测 → 注册 → 注册模型 → 推理src/index.ts 给出了一个更完整的端到端流程覆盖初始化、能力告警、后端注册与设备感知的模型注册import { RunAnywhere } from runanywhere/core; import { InferenceFramework, RegisterModelFromUrlRequest } from runanywhere/proto-ts/model_types; import { QHexRT } from runanywhere/qhexrt; await RunAnywhere.initialize({ apiKey: your-key }); // Warn unsupported devices up front (no QNN load). const npu await QHexRT.probeNpu(); if (!npu.supported) { console.warn(Hexagon ${npu.socModel} is outside V75/V79/V81); } // Register the QHexRT backend (covers LLM, VLM, STT, TTS). await QHexRT.register(); // URLs and display metadata stay app-owned; QHexRT selects the chip folder. await QHexRT.registerModelForDevice( RegisterModelFromUrlRequest.fromPartial({ id: qwen3_5_0_8b, name: Qwen3.5 0.8B (HNPU), url: https://huggingface.co/runanywhere/qwen3_5_0_8b_HNPU/qwen3.5-0.8b-1024.json, framework: InferenceFramework.INFERENCE_FRAMEWORK_QHEXRT, }) );流程要点初始化 coreRunAnywhere.initialize()来自runanywhere/core预检 NPUQHexRT.probeNpu()不加载 QNN安全地在任意设备上调用注册后端QHexRT.register()一次调用覆盖 LLM、VLM、STT、TTS 四个模态按设备注册模型registerModelForDevice只在本机架构匹配时注册模型模型 URL 与展示元数据完全由应用自己持有app-owned。四、NPU 能力探测probeNpu原理probeNpu()是 QHexRT 包最有价值的安全设计它是一套飞行前pre-flight探测不会加载 QNN 或引擎。核心实现在 src/QHexRT.tsasync probeNpu(): PromiseNpuCapability { const raw await QHexRTProvider.probeNpuRaw(); return decodeNpuCapability(raw); }其调用链如下QHexRT.probeNpu() └─ QHexRTProvider.probeNpuRaw() // src/QHexRTProvider.ts └─ NativeRunAnywhereQHexRT.probeNpuProto() └─ HybridRunAnywhereQHexRT::probeNpuProto() // C └─ rac_qhexrt_probe_proto() // QHexRT 引擎探测结果是一个序列化的runanywhere.v1.NpuCapabilityprotobuf 消息其字段定义在 hardware_profile.protomessage NpuCapability { string soc_model 1; // 厂商 SoC 型号如 SM8750未知时为空 optional int32 soc_id 2; // /sys/devices/soc0/soc_id 的值不可用时 ABSENT绝不是 -1 或 0 哨兵值 HexagonArch hexagon_arch 3; // 见下方枚举 bool supported 4; // 是否为已验证支持的代次V75/V79/V81 NPUChip npu 5; // NPU 厂商族系 }HexagonArch枚举同文件第 40-47 行定义了HEXAGON_ARCH_UNKNOWN 0、V68 68、V69 69、V73 73、V75 75、V79 79、V81 81。在解码失败或原生模块不可用非 Android、非 Snapdragon、或旧版 commons 缺少rac_qhexrt_probe_proto符号时decodeNpuCapability 会回退到unknownNpuCapability()第 44-46 行返回socModel: unknown且socId保持未设置——注意这里刻意不使用 -1 哨兵值因为默认构造的消息本身即表示不可用源码注释明确说明了这一点见第 39-42 行。五、后端注册与反注册一次调用覆盖四大模态5.1 register() / unregister() / isRegistered()QHexRT.register()通过QHexRTProvider.register()触发 C 服务注册见 src/QHexRTProvider.tsstatic async register(): Promiseboolean { if (this.registered) { log.debug(QHexRT already registered, returning); return true; } if (!isNativeQHexRTModuleAvailable()) { log.warning(QHexRT native module not available); return false; } const native getNativeQHexRTModule(); const success await native.registerBackend(); if (success) { this.registered true; log.info(QHexRT backend registered successfully (covers LLM, VLM, STT, TTS)); } return success; }关键实现事实幂等重复调用是 no-opregistered标志位会提前短路返回true单次调用覆盖全部模态底层调用rac_backend_qhexrt_register()这一个 C 符号即为 LLM、VLM、STT、TTS 全部注册服务提供者见 RunAnywhereQHexRT.nitro.ts 的说明原生模块缺失时优雅降级返回false而不是抛异常并记录 warning 日志异常会被捕获并记录QHexRT registration failed: ...同样返回false。unregister()第 78-102 行与isRegistered()第 108-121 行对称后者优先查询原生注册状态native.isBackendRegistered()仅当原生对象无法创建时才回退到 JS 侧状态。5.2 原生桥接Nitrogen 生成的 HybridObjectQHexRT 模块基于react-native-nitro-modules构建。接口定义在 RunAnywhereQHexRT.nitro.tsexport interface RunAnywhereQHexRT extends HybridObject{ android: c } { registerBackend(): Promiseboolean; unregisterBackend(): Promiseboolean; isBackendRegistered(): Promiseboolean; probeNpuProto(): PromiseArrayBuffer; isArchitectureSupported(arch: number): boolean; modelSupportsArchitecture(modelId: string, arch: number): boolean; modelRequiresHfAuth(modelId: string): boolean; catalogRegisterModelProto(requestBytes: ArrayBuffer): PromiseArrayBuffer; }C 侧实现类HybridRunAnywhereQHexRT位于 cpp/HybridRunAnywhereQHexRT.hpp继承由 Nitrogen 从上述 spec 自动生成的HybridRunAnywhereQHexRTSpec。修改 spec 后需要运行yarn qhexrt:nitrogen重新生成 nitrogen/generated/ 下的桥接代码源码注释明确警告这些文件不可手改。注意 spec 中HybridObject{ android: c }表明该混合对象只在 Android 平台实例化这也解释了为什么该包只支持 Android。六、设备感知的模型注册registerModelForDevice6.1 为什么需要它QHexRT 的模型仓库按芯片代次组织不同 Hexagon 架构V75/V79/V81对应不同的预编译 QNN 上下文二进制目录。模型 URL 与显示元数据由应用自己持有app-owned由原生 QHexRT 层负责探测设备、挑选芯片目录再组合 commons 的共享注册/下载管线。6.2 API 与编解码registerModelForDevice的实现见 src/QHexRT.tsasync registerModelForDevice( request: RegisterModelFromUrlRequest ): PromiseModelInfo | null { const raw await QHexRTProvider.registerModelForDeviceRaw( QHexRTCatalogWire.encodeRequest(request) ); return raw ? QHexRTCatalogWire.decodeModel(raw) : null; }入参RegisterModelFromUrlRequest来自runanywhere/proto-ts/model_types返回ModelInfo | nullnull是正常的模型与当前设备不匹配结果而非错误编解码由 QHexRTCatalogWire.ts 完成encodeRequest将请求编码为 protobuf 字节流decodeModel将返回字节解码为ModelInfo空缓冲区返回null。注释明确说明该文件仅做生成枚举/protobuf 传输所有 QHexRT 策略判断都留在原生层all QHexRT policy stays native。6.3 配套的策略查询 API在调用注册前你可以用三个同步查询 API 预判策略结果均委托给原生实现原生模块不可用时返回falseAPI作用源码位置isArchitectureSupported(arch)arch是否在原生设备验证支持集V75/V79/V81内QHexRT.tsmodelSupportsArchitecture(modelId, arch)按原生产品策略匹配模型与架构QHexRT.tsmodelRequiresHfAuth(modelId)模型是否标记为需 Hugging Face 认证QHexRT.ts其中V75/V79/V81 支持集只存在于原生层TypeScript 侧没有复制该集合见 QHexRT.ts 注释no V75/V79/V81 set is copied in TS避免双份策略漂移。七、引擎侧实现QHexRT 插件如何保持私有对于想深入理解底层的读者engines/qhexrt/qhexrt_backend.h 揭示了该引擎插件的架构约束两种构建模式RAC_QHEXRT_ENGINE_AVAILABLE0默认/公开插件编译为不可路由的 shell注册时以RAC_ERROR_BACKEND_UNAVAILABLE拒绝不需要任何 QHexRT 头文件或库RAC_QHEXRT_ENGINE_AVAILABLE1内部/授权构建链接预编译归档发布可路由的 vtable暴露文本、视觉、语音、embedding 与图像生成/修复原语。C ABI 边界仅存在于链接构建中来自qhexrt/qhexrt_c.hqhx_runtime* qhx_runtime_create(htp, system); // 每进程一个 qhx_model* qhx_model_load(rt, manifest_path, dir); // 加载模型 manifest qhx_session* qhx_session_create(model); // 每流一个 qhx_status qhx_generate(sess, inputs, cfg, cb, user, out);C 类型与异常不跨该边界所有错误都是qhx_status。这解释了 React Native 层为何能通过一个稳定的probeNpuProto/catalogRegisterModelProto字节流接口与引擎交互——protobuf 序列化消息成为跨层的通用契约。八、测试与验证仓库为 QHexRT 包提供了单元测试 tests/unit/QHexRTCatalogWire.test.ts覆盖QHexRTCatalogWire的请求编码与模型解码逻辑。运行方式见 package.json 的 scripts# 类型检查 npm run typecheck # tsc --noEmit # 单元测试 npm test # jest --config jest.config.js # lint npm run lint # eslint src/**/*.ts --max-warnings 0发布前的prepublishOnly钩子会依次执行 typecheck 与 lint。九、常见问题与边界情况在非 Snapdragon / 非 Android 设备上调用 probeNpu 安全吗安全。QHexRTProvider.probeNpuRaw()在原生模块不可用时返回nulldecodeNpuCapability随后返回socModel: unknown、supported: false的降级结果全程不加载 QNN见 src/QHexRTProvider.ts。重复调用 register() 会怎样不会重复注册。QHexRTProvider内部的registered标志会让后续调用直接返回truesrc/QHexRTProvider.ts。registerModelForDevice 返回 null 是不是出错了不是。null是正常的模型与当前设备不匹配/私有模型无 token结果见 src/QHexRT.ts 的注释。应用应把它当作可预期的分流逻辑而不是异常。QHexRT 支持哪些工作负载LLM、VLM、STT、TTS 四种模态注册时一次覆盖引擎层还支持 embedding 与图像恢复/修复见 qhexrt_backend.h。十、许可证与支持runanywhere/qhexrt是**专有Proprietary**许可参见包内 LICENSEpackage.json 中license: SEE LICENSE IN LICENSE。README 提供的支持渠道包括 React Native SDK 文档bindings/react-native/README.md与官方联系邮箱foundersrunanywhere.ai。结语runanywhere/qhexrt展示了应用持有模型 URL、引擎持有芯片策略的分层设计TypeScript 侧只做 protobuf 编解码与能力探测V75/V79/V81 的设备策略、QNN context 下载与推理全部收敛在原生层。接入时只需记住三步——probeNpu()预检、register()注册、registerModelForDevice()按设备注册模型之后 LLM/VLM/STT/TTS 的下载、加载与推理就交给runanywhere/core统一处理。对于目标用户是 Snapdragon Android 设备的团队这是将本地 AI 能力压榨到 Hexagon NPU 上的直接路径。赞分享AI模型推理服务推理引擎本地部署多模态【免费下载链接】runanywhere-sdksProduction ready toolkit to run AI locally项目地址https://gitcode.com/gh_mirrors/ru/runanywhere-sdks点击查看免费下载相关推荐RunAnywhere QHexRT Flutter 后端Snapdragon Hexagon NPU 上的端侧 LLM/VLM/STT/TTS 接入与工程实践RunAnywhere QHexRT Flutter 后端Snapdragon Hexagon NPU 上的端侧 LLM/VLM/STT/TTS 接入与工程实AI模型推理服务推理引擎本地部署多模态RunAnywhere Electron SDK 接入 QHexRT在 Snapdragon X 的 Hexagon NPU 上跑本地文本生成RunAnywhere Electron SDK 接入 QHexRT在 Snapdragon X 的 Hexagon NPU 上跑本地文本生成 runanyAI模型推理服务推理引擎本地部署多模态runanywhere/onnx 使用指南在 React Native 中接入 ONNX/Sherpa 语音能力STT/TTS/VADrunanywhere/onnx 使用指南在 React Native 中接入 ONNX/Sherpa 语音能力STT/TTS/VAD 导读 runaAI模型推理服务推理引擎本地部署多模态上一篇5分钟掌握gRPC压缩gzip与snappy性能终极对决下一篇MyTinySTL中的排序算法radix_sort实现创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考