RunAnywhere React Native Core SDK 实战指南基于 runanywhere/core 构建端侧 AI 应用【免费下载链接】runanywhere-sdksProduction ready toolkit to run AI locally项目地址: https://gitcode.com/gh_mirrors/ru/runanywhere-sdksrunanywhere/core是 RunAnywhere 为 React Native 提供的核心 SDK 包它统一封装了设备端 AI 的初始化、模型生命周期、流式推理与事件系统并通过 NitroModules 原生桥接层对接 C 实现的 runanywhere-commons。本文以 bindings/react-native/packages/core/README.md 为主线结合仓库源码与示例工程完整讲解从安装、初始化到模型下载、加载、生成与流式消费的实战流程并深入剖析 Hermes 环境下异步流、错误处理与多环境配置等关键细节读完即可在现有 React Native 工程中接入本地 LLM、语音与视觉推理能力。一、核心定位一个包打通端侧 AI 全链路runanywhere/core是整个 React Native SDK 的唯一必需包。它本身并不直接执行推理而是扮演三个角色公共 API 门面对外暴露统一的RunAnywhere命名空间所有能力LLM、STT、TTS、VAD、RAG、模型管理等都挂在这个门面之下模型与生命周期管理负责模型注册、下载、加载、卸载与注册表查询原生桥接层通过 NitroModulesreact-native-nitro-modules调用 C 实现的 runanywhere-commons将 proto 编码的请求/响应在 JS 与原生之间往返传递。从 src/index.ts 的导出声明可以看到包的主体就是RunAnywhere门面以及围绕它的 v3 类型体系LlmOptions、SttOptions、GenerationResult、SdkEvent等。而 src/Public/RunAnywhere.ts 中列出的 15 个能力命名空间llm、vlm、stt、tts、vad、embeddings、rerank、images、diarization、segmentation、voice、rag、models、lora、cua加上平台服务storage、logging、auth、pluginLoader、solutions构成了完整的端侧 AI 能力面。一个关键的设计事实所有推理都发生在原生 commons 层TypeScript 层只负责选项与结果的编解码。源码注释明确写道“All inference lives in native commons — this layer only marshals options and results.” 这意味着runanywhere/core的性能瓶颈在原生侧JS 侧只承担协议转换。二、环境要求与安装2.1 版本与环境要求根据 bindings/react-native/README.md 的要求矩阵组件最低版本推荐版本React Native0.83.10.85.3Node.js22.1224 LTSiOS17.517.5AndroidAPI 247.0API 28Xcode2626RAM3 GB6 GB用于较大模型Apple Silicon 设备与 6 GB 内存的 Android 手机推荐用于运行 3B 及以上参数模型。从 package.json 的 peerDependencies 可以看到核心包对react19.0.0、react-native-nitro-modules^0.33.9有强依赖其余如react-native-blob-util、react-native-device-info、react-native-fs均为可选依赖。2.2 安装命令核心包 README 给出的标准安装命令注意版本需要锁定到0.20.11与仓库当前版本线保持一致npm install runanywhere/core0.20.11 react-native-nitro-modules随后在 iOS 目录执行 CocoaPods 安装cd ios pod install cd ..Android 无需额外配置——原生库会随 Gradle 构建自动打包并下载这是 React Native SDK 与 iOS 的主要差异之一。iOS 麦克风权限若应用需要使用麦克风采集语音转写、语音 Agent 等必须在Info.plist中添加NSMicrophoneUsageDescription权限描述字符串否则系统会直接拒绝录音访问。完整配置流程见 React Native SDK README。2.3 选择推理后端包runanywhere/core是骨架具体模型推理由后端包提供。安装核心包后按需安装后端npm install runanywhere/core0.20.11 runanywhere/llamacpp0.20.11包用途runanywhere/core核心 SDK —— 必需runanywhere/llamacppLLM / VLMGGUF基于 llama.cpprunanywhere/onnxSTT、TTS、VADWhisper、Piper、Silerorunanywhere/mlxApple MLX物理 iOS 设备上的 Apple Silicon 加速runanywhere/qhexrt可选的 Qualcomm Hexagon NPU 加速Snapdragon Android三、初始化与运行环境语义3.1 开发环境快速初始化核心 README 给出了最简初始化方式import { RunAnywhere, SDKEnvironment } from runanywhere/core; await RunAnywhere.initialize({ environment: SDKEnvironment.SDK_ENVIRONMENT_DEVELOPMENT, }); console.log(Ready:, RunAnywhere.isInitialized);在开发环境SDK_ENVIRONMENT_DEVELOPMENT下SDK 以Keyless OSS 模式运行无需 API Key日志级别默认为DEBUG。从 SDKEnvironmentHelpers.ts 的源码可以确认这一行为——开发环境不要求后端 URL、不同步后端、不要求认证且默认日志级别为LOG_LEVEL_DEBUG。3.2 生产环境初始化生产环境需要认证与遥测配置await RunAnywhere.initialize({ apiKey: YOUR_API_KEY, baseURL: https://api.runanywhere.ai, environment: SDKEnvironment.SDK_ENVIRONMENT_PRODUCTION, });三个环境的值域与行为语义环境说明SDK_ENVIRONMENT_DEVELOPMENTKeyless OSS 模式详细日志SDK_ENVIRONMENT_STAGING使用真实服务进行测试SDK_ENVIRONMENT_PRODUCTION认证控制平面 遥测从 RunAnywhere.ts 的initializeCore实现可以看到初始化时的参数校验规则这是最容易踩坑的地方生产环境必须提供非空的apiKey且不能是占位符baseUrl必须是绝对 HTTP(S) URL且不能包含内嵌凭据、query 参数或 fragment生产环境强制要求 HTTPS开发环境允许 Keyless 的 Staging 接入commons 会覆盖 base URL 指向内置 staging 后端请求以未认证方式发出。校验失败会抛出SDKException.validationFailed其中fieldPath会精确指向出问题的字段如InitializeOptions.baseUrl或InitializeOptions.apiKey。3.3 两阶段初始化与后台网络相位初始化并非一次同步完成。initialize()实际分为两个相位源码注释明确描述Phase 1本地核心native.initialize(configJson)拉起平台适配器、原生 commons、设备注册等返回后本地推理即可用Phase 2网络相位认证、设备注册、模型目录同步、遥测在后台异步进行不阻塞调用方。网络相位失败是非致命的——SDK 会记录 warning并在下一次需要联网的调用前通过retryHTTPSetupInternal自动重试 HTTP/认证设置。RunAnywhere.isReady只反映本地核心是否初始化完成与网络相位是否成功无关。这种设计保证了离线优先没有网络时本地推理照常可用。此外initialize()具备幂等与并发安全语义重复调用会共享同一个 in-flight PromiseinitializingPromise并发调用不会重复初始化原生层reset()则是进程级生命周期屏障会等待所有挂起的初始化/网络工作结束后再销毁原生实例。四、快速上手从后端注册到模型生成核心 README 强调安装后端包后必须先注册对应后端才能下载与加载模型。结合 React Native SDK README 的 Quick Start一个完整的 LLM 推理流程如下import { RunAnywhere, SDKEnvironment } from runanywhere/core; import { LlamaCPP } from runanywhere/llamacpp; await RunAnywhere.initialize({ environment: SDKEnvironment.SDK_ENVIRONMENT_DEVELOPMENT, }); await LlamaCPP.register(); await RunAnywhere.downloadModel(smollm2-360m); await RunAnywhere.loadModel(smollm2-360m); const result await RunAnywhere.generate(What is the capital of France?); console.log(result.text);内置目录模型自动发现仓库内置模型目录中的条目如smollm2-360m在初始化完成后会被自动发现无需手动registerModel。只有自定义模型外部 GGUF、ONNX/Sherpa、MLX bundle才需要调用RunAnywhere.registerModel()显式注册。值得注意的细节生成类 API 并不强制要求预加载。从 Models.ts 的ensureModelLoaded实现可以看到如果调用llm.generate({ model })时模型尚未下载SDK 会自动执行下载 → 加载的完整链路内部先消费完整下载事件流再调用models.load。因此用户既可以显式管理生命周期也可以直接传model选项让 SDK 兜底。五、能力全景与模型生命周期管理5.1 统一命名空间能力矩阵RunAnywhere是唯一的入口门面所有能力通过命名空间访问。注册后端模块LlamaCPP、ONNX、MLX后才能下载与加载模型能力关键 API后端包LLMgenerate、generateStreamrunanywhere/llamacpp、runanywhere/mlxVLMprocessImage、processImageStreamrunanywhere/llamacpp、runanywhere/mlxSTTtranscribe、transcribeStreamrunanywhere/onnxTTSsynthesize、synthesizeStreamrunanywhere/onnxVAD语音活动检测辅助runanywhere/onnxVoice agentinitializeVoiceAgent、streamVoiceAgent、processVoiceTurnCore ONNX LLM 后端ModelsregisterModel、downloadModel、loadModel、listModelsrunanywhere/coreRAG / toolsragQuery、generateWithToolsrunanywhere/core5.2 支持的模型格式格式适用场景后端GGUFLLM、部分 VLMLlamaCPPONNX / Sherpa archivesSTT、TTS、VADONNXMLX bundlesApple Silicon 上的 LLM、VLM、语音MLXQHexRT bundlesSnapdragon 上的 NPU 加速模型QHexRT5.3 模型生命周期 API 深度解析RunAnywhere.models命名空间Models.ts提供了完整的注册表与生命周期控制list(filter?)/get(id)查询注册表。filter支持category模型类别、framework、downloadedOnly、search关键词筛选register(model)支持三种注册来源——单个 URLurl、归档 URLarchiveUrl自动按扩展名推断.zip/.tar.bz2/.tar.xz/.tar.gz归档类型、多文件集合files需显式iddownload(id)返回AsyncIterableDownloadEvent事件流事件类型包括started、progress含bytesDone/bytesTotal/percent、extracting、completed、failedload(id, options?)立即加载模型。注意当前原生 load ABI 只支持backendPreferences[0]即框架选择与forceReloadcontextLength、threads、accelerator等选项暂未随 ABI 传递传入会抛出明确的SDKException.invalidInputunload(id)/unloadAll(category?)按 id 或按类别/全局卸载delete(id)删除本地模型文件并清理注册表路径unregister(id)仅移除注册元数据要求模型已卸载且无本地产物state()返回每个类别的已加载模型快照 存储余量storageUsedBytes/storageFreeBytesrefresh()重新扫描托管模型目录并调和下载状态用于拾取磁盘上被外部改动的人工产物。一个实用的快捷方式llm.generate(input, { model: xxx })会在后台自动完成模型的下载与加载这是 Llm.ts 中buildRequest调用的ensureModelLoaded行为开发者在原型阶段可以完全跳过显式生命周期管理。5.4 LLM 生成与工具调用RunAnywhere.llm提供四种生成形态Llm.tsgenerate(input, options?)一次性生成返回GenerationResult含text、finishReason、token 用量、timeToFirstTokenMs、tokensPerSecond等generateStream(input, options?)流式生成产出started→token区分text/thought思维链 token→completed事件序列generateStructured(prompt, schema, options?, mode?)结构化输出。mode支持validationOnly默认自由生成后校验、repair校验失败后携带修复指令重试一次、constrained引擎级约束解码当前未接入调用会抛出notImplemented工具调用llm.tools.register/unregister/list/clear注册工具配合generateWithTools显式工具循环支持对循环预算maxCalls、思维链、并行执行的完全控制。六、流式输出与 Hermes 关键注意点核心 README 用醒目引用块强调了一条极易踩坑的规则Hermes消费 SDK 的AsyncIterable流时请使用手动[Symbol.asyncIterator]()循环不要使用for await...of。原因是 Hermes 运行时对AsyncIterable的for await...of语法支持存在限制。SDK 所有流式动词generateStream、download、sdkEvents、transcribeStream、synthesizeStream等返回的都是AsyncIterableT底层由 Stream.ts 的pushStream驱动——它基于runanywhere/proto-ts/streams/push的推送式异步迭代器实现消费端必须手动拉取。正确写法仓库示例工程 BenchmarkScreen.tsx 中的实际用法const iterator events[Symbol.asyncIterator](); let step await iterator.next(); while (!step.done) { // 处理 step.value如 GenerationEvent 的 token 增量 step await iterator.next(); }流式事件的取消语义当消费者中途跳出循环时pushStream的cancel回调会被触发进而调用原生层的llmCancelProto()取消底层推理任务见 Llm.ts。因此即使使用手动循环也建议在finally中调用迭代器的return()以确保原生资源被及时释放。七、错误处理统一的 SDKExceptionSDK 中所有错误都以SDKException抛出其内部封装了从 idl/errors.proto 生成的 protoSDKError载荷SDKException.ts 的实现。核心 README 给出的标准捕获方式import { SDKException, ErrorCode, isSDKException } from runanywhere/core; try { await RunAnywhere.generate(Hello!); } catch (error) { if (isSDKException(error)) { console.error(error.code, error.message); } }SDKException提供的结构化访问器code数字型 proto 错误码如ERROR_CODE_MODEL_NOT_FOUND 110category粗粒度分类网络、配置、校验、组件等fieldPath结构化校验错误的字段路径如InitializeOptions.baseUrl便于跨 SDK 统一读取cAbiCode对应的负值rac_result_tC ABI 错误码recoverySuggestion常见错误码的人类可读恢复提示如网络不可用 → Check your internet connection and try again.isExpected是否为预期内错误用户取消流式任务此类错误不应按 error 级别记录日志。原生桥接层返回的RAC_RESULT-NNN模式错误会被asNativeSDKException自动解析并调用 commons 的标准 ABIrac_result_to_proto_error转换为规范 proto 错误RunAnywhere.ts。也就是说无论错误源自 JS 校验、proto 解码还是原生 C 层最终都以同一套SDKException结构呈现这对统一错误上报与跨端对齐非常有利。八、平台适配与安全说明8.1 原生桥接结构从包目录结构看runanywhere/core的原生部分采用NitroModules架构iOSios/目录包含 Swift 实现的PlatformAdapter.swift、KeychainManager.swift、URLSessionHttpTransport来自共享的 shared-apple/URLSessionHttpTransport等Androidandroid/目录包含 Kotlin 实现的OkHttpHttpTransport.kt、SecureStorageManager.kt、PlatformAdapterBridge.kt等共享 Ccpp/目录下的HybridRunAnywhereCore*.cpp系列文件实现了 JS ↔ commons 的 proto 桥接包括生命周期、下载、注册表、语音、工具调用、解决方案等 15 个功能域Nitro 生成代码nitrogen/generated/下的 iOS/Android 桥接桩代码。8.2 隐私与安全推理完全在设备本地仅在首次模型下载时需要联网之后推理全程离线用户数据不上云生产模式可能收集匿名遥测可配置密钥存储iOS 使用 KeychainKeychainManager.swift、Android 使用加密存储SecureStorageManager.kt日志安全初始化失败时 SDK 只记录结构化的非敏感错误码/类别完整异常只返回给调用方不写入设备日志见 RunAnywhere.ts 的注释说明。九、支持与许可完整文档React Native SDK README另可查阅 架构文档、开发文档 与 API 参考可直接运行的 示例应用含聊天、基准测试、模型选择等完整场景是学习Symbol.asyncIterator消费模式的参考实现许可协议RunAnywhere License详见 LICENSE。结语runanywhere/core的定位非常清晰一个包搞定端侧 AI 的骨架推理能力由后端包按需插入。理解它的关键在于把握三条主线——两阶段初始化本地核心 后台网络相位保证离线可用性、统一的RunAnywhere门面收敛全部能力、proto 驱动的原生桥接保证跨 SDK 的错误与数据结构一致。对 React Native 开发者而言掌握本文的初始化校验规则、Hermes 流式消费方式和SDKException处理范式就能在真实工程中稳定地落地本地 LLM、语音与视觉应用。【免费下载链接】runanywhere-sdksProduction ready toolkit to run AI locally项目地址: https://gitcode.com/gh_mirrors/ru/runanywhere-sdks创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考