AI模型推理服务推理引擎本地部署多模态【免费下载链接】runanywhere-sdksProduction ready toolkit to run AI locally项目地址https://gitcode.com/gh_mirrors/ru/runanywhere-sdks点击查看免费下载导读RunAnywhere Web SDK 是 RunAnywhere 项目在浏览器端的官方实现它以 Swift 对齐的 TypeScript 门面facade覆盖底层的 RACommons C/C 核心将 iOS/Android/桌面端同源的 AI 引擎通过 Emscripten 编译为 WASM 在浏览器中运行。本文以 bindings/web/CLAUDE.md 为核心骨架结合仓库内的源码、构建脚本与文档系统讲解 Web SDK 的包结构、Commons-First 设计原则、初始化流程、构建命令与部署验证要求。读完本文你将掌握如何在浏览器应用中集成runanywhere/web系列包理解 WASM 与 WebGPU 的分工边界并能按官方规范完成构建、部署与发布验证。一、架构总览三个 npm 包各自独立的 WASM 产物Web SDK 不是一个单一的 npm 包而是由三个可发布的包组成的体系。每个后端包都自带一个自包含的 Emscripten WASM 产物公共代码commons被嵌入到每一个后端 WASM 内部不存在跨 WASM 的符号共享——应用只需要加载自己真正用到的 WASM而不是一次性下载全部引擎。browser app - runanywhere/web - runanywhere/web/browser - runanywhere/web-llamacpp and/or runanywhere/web-onnx runanywhere/web-llamacpp - runanywhere/web/backend runanywhere/web-onnx - runanywhere/web/backend runanywhere/web - runanywhere/proto-ts backend-neutral commons各入口的定位依据 bindings/web/packages/core/src/index.ts、bindings/web/packages/core/src/backend.ts 源码确认入口职责runanywhere/web公开的 Swift 形状核心门面、生成的 proto 类型以及仅含 commons 的racommons.{js,wasm}供RunAnywhere.initialize()使用runanywhere/web/backend窄而类型化的后端集成契约模块安装、能力路由、生命周期钩子、安全日志runanywhere/web/internal更宽泛的核心内部实现导出应用和后端包都不得依赖此入口runanywhere/web/browser浏览器专用辅助工具音频采集/播放、视频采集、能力检测等runanywhere/web-llamacppLLM GGUF 文本嵌入 VLM LoRA 工具调用 结构化输出后端内置两套执行变体runanywhere/web-onnxONNX 嵌入 STT TTS VAD 后端注册onnx与sherpa两个 vtable二者共享 ONNX Runtime应用代码应当停留在根RunAnywhere门面上后端包只通过runanywhere/web/backend集成浏览器应用可以从runanywhere/web/browser导入 UI/设备辅助函数。WASM 产物与执行变体runanywhere/web-llamacpp携带两种执行模式racommons-llamacpp.{js,wasm}CPU和racommons-llamacpp-webgpu.{js,wasm}WebGPU Asyncify。两者都携带统一的 llama.cpp vtable模型框架路由使其嵌入能力可以与 ONNX 共存。runanywhere/web-onnx由racommons-onnx-sherpa.{js,wasm}CPU/pthread和racommons-onnx-sherpa-webgpu.{js,wasm}ORT WebGPU EP支撑。语音加速与 LLM WebGPU 相互独立ONNX.register({ acceleration, threads })与RunAnywhere.runtime.speech各自管理。浏览器中默认使用 fail-closed 的 BackendWorker。关于「为什么同时存在 WASM 与 WebGPU」的详细论证见 bindings/web/docs/WASM_AND_WEBGPU.md语音/ONNX 的 WebGPU 双胞胎产物细节见 bindings/web/docs/ONNX_WEBGPU.md。二、Commons-First业务逻辑归 CTypeScript 保持轻薄这是 Web SDK 最重要的设计原则。Commons 拥有业务与模型逻辑校验、模态modality流水线、工具调用/结构化输出/LoRA/RAG/混合路由/语音代理会话规则、流式状态机全部位于runanywhere-commonsC/C并且只通过生成 proto 的 C ABIrac_*_proto、生命周期、事件在每个后端 WASM 内部被消费。TypeScript 只允许做四件事不能更多编码/解码 proto 字节并通过ccall或 BackendWorker RPC 调用rac_*拥有浏览器 I/O麦克风、扬声器、权限、DOM、fetch、OPFS/IndexedDB 协调托管 BackendWorker并把请求路由到拥有模型的模块暴露 Swift/Kotlin 形状的RunAnywhere.*门面。当 commons 已有对应导出时不要在 TS 中重新实现 commons 流水线。应优先使用原生会话 ABICrossWasm/TS 回退只是降级路径绝不能成为生产路径。一切推理都离开 UI 线程所有 commons/WASM 推理与模型变更都运行在 BackendWorker 中主线程只做 I/O 与轻薄门面。加速策略是 WebGPU 优先当引擎与设备支持时即存在navigator.gpu且支持shader-f16否则退回 CPU worker当必需 worker 失败时绝不静默回退到主线程推理。三、包边界与依赖方向三个可发布的包之外runanywhere/web/backend、runanywhere/web/internal、runanywhere/web/browser都是核心包的入口entrypoints不是额外的包。边界约束如下核心包不得导入任何后端包不得包含 llama.cpp、ONNX Runtime、Sherpa 或 WebGPU 的实现决策。它只拥有契约、生命周期、路由钩子、生成的 wire 适配器与浏览器无关的基础设施。后端包只实现并注册自己 WASM 能服务的能力。它们只能使用文档化的核心backend入口不得导入internal、不得互相导入、不得深度导入包源码文件。示例/应用代码使用公开包根不得导入runanywhere/web/internal也不得在视图中重建 SDK 业务规则。这些约束在 bindings/web/packages/core/src/backend.ts 中有直接体现该文件刻意保持窄面仅导出registerWasmModule/unregisterWasmModule、BackendWorkerHost、运行时配置设置器setAccelerationSwitcher、setActiveAccelerationMode、setSpeechAccelerationMode等以及各类适配器后端包的全部集成都收敛在这一个入口上。四、初始化流程与公开 API 面标准引导序列import { RunAnywhere, SDKEnvironment } from runanywhere/web; import { LlamaCPP } from runanywhere/web-llamacpp; import { ONNX } from runanywhere/web-onnx; await RunAnywhere.initialize({ environment: SDKEnvironment.SDK_ENVIRONMENT_DEVELOPMENT, }); await LlamaCPP.register({ acceleration: auto }); // 加载 racommons-llamacpp.wasm await ONNX.register(); // 加载 racommons-onnx-sherpa.wasm await RunAnywhere.completeServicesInitialization();各步骤的实际行为依据 bindings/web/example/src/main.ts 与 bindings/web/packages/core/src/Public/API/RunAnywhere.tsRunAnywhere.initialize()加载racommons.wasm仅 commons并记录核心 SDK 状态。InitializeOptions支持apiKey缺省即 keyless 本地模式、baseUrl、environmentproduction | development、appIdentifier/appName/appVersion等字段。每个后端的register()加载自己的专属 WASM对该模块调用rac_init()向插件注册表注册自己的 vtable并把自身安装到核心 proto 字节适配器上使后续操作正确路由。ONNX.register()接受可选的wasmUrl覆盖旧的skipProtoBytePlugins/skipStandaloneSpeech选项已移除——proto-byte 是唯一路径。completeServicesInitialization()完成第二阶段后台服务。在示例中该调用是保留的 no-op 兼容转发器因为initialize()已合并了两个阶段但文档化的两阶段引导顺序仍是initialize()→ 后端注册 →completeServicesInitialization()→ 模型目录注册/水合。公开 API 形状根门面刻意保持小巧且 Swift 形状化完整方法清单见 bindings/web/docs/reference/PUBLIC_API_SURFACE.md。要点模型生命周期/注册表loadModel、unloadModel、currentModel、listModels、queryModels、getModel、downloadedModels、downloadModel、importModel。LLM / 结构化输出 / 工具调用generate、generateStream、cancelGeneration、generateStructured、generateStructuredStream、extractStructuredOutput、generateWithTools。语音 / VLM / 语音代理 / RAGtranscribe、transcribeStream、synthesize、synthesizeStream、speak、detectVoiceActivity、streamVAD、processImage、processImageStream、initializeVoiceAgent、processVoiceTurn、streamVoiceAgent、ragCreatePipeline、ragIngest、ragQuery等。命名空间只在 Swift 也有的地方保留RunAnywhere.solutions、RunAnywhere.pluginLoader。从源码看RunAnywhere还聚合了llm、vlm、stt、tts、vad、embeddings、rerank、images、diarization、segmentation、voice、rag、models、lora等能力命名空间以及跨 SDK 对齐的CUA计算机使用代理脚手架见 bindings/web/packages/core/src/index.ts 的导出面。一个最小可运行的流式生成示例来自 bindings/web/example/src/main.tsconst events RunAnywhere.llm.generateStream(prompt, { model: smollm2-360m-q8_0, maxOutputTokens: 256, }); for await (const event of events) { if (event.type textDelta || event.type reasoningDelta) { outputEl.textContent event.text; } else if (event.type completed) { setStatus(Done — ${event.result.outputTokens} tokens at ${event.result.tokensPerSecond.toFixed(1)} tok/s.); } else if (event.type failed) { setStatus(Generation failed: ${event.error.message}); } else if (event.type cancelled) { setStatus(Generation cancelled.); } }模型目录由应用自己持有SDK 会在首次使用时按需下载并加载模型但它只能解析自己已知的 id。示例通过RunAnywhere.models.register({ id, name, category, framework, format, url, sizeBytes, memoryRequiredBytes, contextLength })注册目录条目。Demo 启动顺序与运行时诚实性示例的启动顺序严格为RunAnywhere.initialize()→ 后端注册 →completeServicesInitialization()第二阶段→ 模型目录注册/水合。生产身份identity在本地 shell 就绪之后异步完成绝不能阻塞本地就绪。BackendWorkerHost是生产环境的 LlamaCPP 推理路径当Worker可用时LlamaCPP.register()安装backendWorker.ts在 worker 中加载模型优先采用无 pthread 的 WebGPU WASM并把RunAnywhere.runtime.executionContext设为worker。握手失败时runtime.degradedReason会解释主线程回退的原因。将 pthread CPU 产物嵌套进 DedicatedWorker 需要mainScriptUrlOrBlob以便em-pthread子进程启动。Diffusion 通过runanywhere/web核心暴露Swift/Kotlin 对齐在它发布自己的 WASM 产物之前不存在单独的runanywhere/web-diffusion包——不要把它与四个规范的 JS/WASM 对并列打包。混合 STT 只在ONNX.register()之后才注册Cloud.registerBackend()缺失可选的云端引擎不得让本地 ONNX/Sherpa 不可用。五、类型、校验与错误规则TypeScript 严格模式不得引入any、ts-ignore、未检查的 JSON 断言或重复手写 wire DTO。外部数据一律从unknown开始经过校验后刻意收窄。ESM 发布规范这些包发布 ESM。相对 TS 导入/导出必须写出产出的.js路径例如./runtime/EmscriptenModule.js包括动态导入与 barrel 导出。仅靠 bundler 的扩展名推断会掩盖坏掉的 NodeNext 声明与运行时入口保持npm run check:esm-specifiers与npm run verify:nodenext通过。类型来源模型、生命周期、存储、事件、模态、环境与错误类型都来自生成的runanywhere/proto-ts模块。本地类型只适合 Web 专属的调用点选项或 IDL 中不存在的判别式 UI/运行时状态。边界校验在进入 WASM 之前校验每一个外部边界URL、凭据、模型元数据、下载字节、JSON、浏览器媒体、持久化状态。抛出/返回 SDK 的结构化错误形状带上可操作的字段或操作不要把堆栈跟踪当作用户消息泄漏。SDK 的错误体系在 bindings/web/packages/core/src/Foundation/SDKException.ts 中实现runanywhere/web导出SDKException、isSDKException、ProtoErrorCategory、ProtoErrorCode、ProtoErrorSeverity携带生成的 proto 错误分类法。六、安全与「诚实的运行时状态」凭据红线绝不记录或持久化 API 密钥、bearer token、授权头、含凭据的请求体或含秘密的 URL包括 localStorage、OPFS、IndexedDB、截图、trace、.env文件。VITE_*值是公开的浏览器 bundle 配置永远不是服务器机密——完整部署契约见 bindings/web/docs/DEPLOYMENT.md。同源与固定目标当上游未发布 CORS 时浏览器控制平面访问必须同源。中继目的地保持固定并在白名单内绝不让来自 Settings、查询参数或请求体的 URL 成为代理目标。运行时状态必须诚实UI 与就绪探针必须报告真实的 registered/loaded/inference 状态。缺失后端、WebGPU 路径不可用、模型加载失败、模态失败都是明确的 unavailable/error 状态——不是假开关、静默回退、占位成功或「已下载」通过。动态流程要暴露区分明确的 idle/loading/ready/success/error/cancelled 状态typed union 或生成枚举错误必须留下重试或恢复路径。这一点在 bindings/web/packages/core/src/Public/API/RunAnywhere.ts 中有代码级印证capabilitiesSnapshot()从Runtime.modalities对已注册后端的实时探测生成能力快照而不是从「本模块存在哪些命名空间」推导EXPLICITLY_ABSENT_CAPABILITIES明确声明agents、wakeword、realtime不在 v4 公开 API 面上。七、构建命令与 WASM 产物以下命令在bindings/web/下运行npm run typecheck npm run build npm run lint npm run test npm run check:esm-specifiers npm run verify:nodenext # 发布的声明 Node ESM 入口 npm run test:browser npm run test:browser:release # 可选的完整真实模型发布旅程 # WASM 构建——每个 flag 只向所属包输出 ONE 个产物 npm run build:wasm -- --core # packages/core/wasm/racommons.{js,wasm} npm run build:wasm -- --llamacpp # packages/llamacpp/wasm/racommons-llamacpp.{js,wasm} (CPU) npm run build:wasm -- --webgpu # packages/llamacpp/wasm/racommons-llamacpp-webgpu.{js,wasm} npm run build:wasm -- --onnx # packages/onnx/wasm/racommons-onnx-sherpa.{js,wasm} npm run build:wasm -- --onnx-webgpu # packages/onnx/wasm/racommons-onnx-sherpa-webgpu.{js,wasm} npm run build:wasm:all # core llama CPU/WebGPU onnx CPU/WebGPU npm run vendor:wasm:speech # CPU ORT WebGPU ORT Sherpa发布前必需 npm run build:wasm:debug npm run clean:wasm # 移除所有 WASM 构建目录与生成的 glue/binaries npm run build:wasm:clean ./scripts/package-sdk.sh最小示例仓库内的验证 harness完整 demo 应用位于独立的 runanywhere-web 仓库cd example npm install npm run typecheck npm run build npm run dev产物对应关系与发布门槛依据 bindings/web/docs/DEVELOPMENT.md发布期望的 JavaScript/WebAssembly 对每个build:wasmflag 对应一个packages/core/wasm/racommons.{js,wasm} # --core packages/llamacpp/wasm/racommons-llamacpp.{js,wasm} # --llamacpp (CPU) packages/llamacpp/wasm/racommons-llamacpp-webgpu.{js,wasm} # --webgpu packages/onnx/wasm/racommons-onnx-sherpa.{js,wasm} # --onnx (CPU/pthread) packages/onnx/wasm/racommons-onnx-sherpa-webgpu.{js,wasm} # --onnx-webgpu (ORT WebGPU EP)前四对是强制性的ONNX WebGPU 双胞胎在启用语音加速时发布。CPU 与 WebGPU 是同一个 npm 包拥有的两套独立 llama.cpp 构建ONNX Runtime 与 Sherpa-ONNX 共享一个后端产物因为 Sherpa 使用 ONNX Runtime。两条容易在无意中违反的不变量值得特别重申packages/onnx绝不发布wasm/sherpa/**——那个独立产物已被移除通过racommons-onnx-sherpa.wasm的 proto-byte 路径是唯一的 Sherpa 面。绿色typecheck/lint/build只是冒烟验证。声称某个发布覆盖某模态LLM、VLM、STT、TTS、VAD、Voice Agent、RAG……必须在一个真实的、启用了 COOP/COEP 的浏览器中端到端驱动它——参见npm run test:browser:release与tests/browser/release-app.e2e.spec.ts。每个包的prepack会重建其声明并拒绝缺失、为空、语法无效或损坏的规范资产发布前可用npm pack --dry-run -w packages/core等检查最终 npm 文件清单。WASM 与 WebGPU 的分工一句话概括详见 bindings/web/docs/WASM_AND_WEBGPU.mdWebGPU 加速数学WASM 运行拥有模型的引擎。层职责WASM浏览器内可移植的 C 运行时加载 GGUF/ONNX、分词、会话状态、流式回调、pthread 池、OPFS 水合。没有它就得用 JS 重写整个引擎。WebGPU浏览器 GPU API。llama.cpp 的 ggml-webgpu以及 ONNX Runtime 的 WebGPU EP从那个 WASM内部提交 shader。它不替代引擎。BackendWorkerDedicatedWorker让推理不阻塞 UI 线程托管 WASM 堆。WebGPU 单独无法胜任它没有 Whisper/Piper/GGUF 加载器、没有 Sherpa transducer 解码、没有 llama.cpp 采样循环——这些都在 C 里。把 C 编译成 WASM 是让 Web 与 iOS/Android/桌面共享同一套代码库的方式。原生移动端通过不同 EPCoreML/NNAPI/Metal从同一份 C使用 GPU在 Web 上 EP 是 CPUSIMD/线程或 WebGPU。八、浏览器支持与部署要求支持矩阵依据 bindings/web/docs/BROWSER_SUPPORT.mdChrome / Edge主要生产目标启用跨源隔离后支持SharedArrayBuffer、pthread WASM 与 CPU 版 llama.cpp 和 ONNX/Sherpa 产物。加速现状llama.cpp 在 BackendWorker 中 WebGPU-firstshader-f16可用时ONNX/Sherpa 在 ORT WebGPU 探针成功时用 WebGPU否则 CPU 线程。Firefox支持 CPU WebAssembly 路径与跨源隔离下的 pthreadsWebGPU 按能力依赖对待不作为基线要求。Safari / WebKit需要跨源隔离才能跑线程化 WASM不支持Cross-Origin-Embedder-Policy: credentialless必须部署require-corp并确保每个跨源资源都提供 CORS 或 CORP 响应。注意RunAnywhere.runtime.active/setAcceleration是LLM 作用域的语音诊断在RunAnywhere.runtime.speech与sdk.speechAcceleration事件上。不要把 WebGPU LLM 徽标当成语音 GPU。ONNX/Sherpa 产物使用 pthreads注册前应用必须验证crossOriginIsolated为 false 时给出可操作的错误例如提示配置 COOP/COEP 后刷新。生产应用中注册语音时建议强制 workerawait ONNX.register({ acceleration: auto, // 浏览器 ORT EP 探针 OK 则 WebGPU否则 CPU threads: 2, requireBackendWorker: true, });ONNX.accelerationMode/RunAnywhere.runtime.speech.acceleration只有在 ORT WebGPU EP 附加探针成功时才是webgpu——绝不仅仅因为存在-webgpuWASM 双胞胎就声称加速。部署契约依据 bindings/web/docs/DEPLOYMENT.md必需的隔离头HTML 文档及相关静态资源Cross-Origin-Opener-Policy: same-origin Cross-Origin-Embedder-Policy: credentiallessSafari/WebKit 改用Cross-Origin-Embedder-Policy: require-corp并让每个跨源子资源 CORS/CORP 兼容生产环境验证crossOriginIsolated true。静态 WASM 资产.wasm以Content-Type: application/wasm提供每个二进制旁都要提供规范的 Emscripten glue并把这两类扩展名排除在 SPA 重写之外。当前发布的部署负载是五对十个文件racommons、racommons-llamacpp、racommons-llamacpp-webgpu、racommons-onnx-sherpa、racommons-onnx-sherpa-webgpu。缺失或被 HTML 重写的规范资产可能让 pthread 初始化看起来像挂起——宁可让部署验证失败也不要静默继续。Content Security Policy起点script-src self wasm-unsafe-eval; worker-src self blob:;再按应用适配connect-src、img-src、media-src与模型托管源不要放宽script-src允许任意第三方代码。环境变量VITE_*会被嵌入每个浏览器拿到的 JS 中是公开配置而非机密存储绝不放 API 密钥。内存与下载WASM32 是 4 GiB 地址空间SDK 通过RunAnywhere.runtime.memoryBudget暴露按模块的软预算非硬性预留下载前展示模型大小、预留解压与临时下载开销配额不足时提供恢复路径。生产冒烟部署后用RA_E2E_BASE_URLhttps://your-production-origin npm run test:browser跑 Playwright 冒烟套件。九、发布验证与质量门槛静态门槛严格 TS、外部数据unknown开始、无any/ts-ignorenpm run typecheck npm run lint npm run test npm run build npm run verify:package -w packages/core npm run verify:package -w packages/llamacpp npm run verify:package -w packages/onnx浏览器发布验证必须启动构建好的示例COOP/COEP 开启然后为每一个声称覆盖的模态证明模型下载、模型加载、真实推理、可见输出、恢复/取消。完整发布旅程覆盖 LLM CPU 与 WebGPU、VLM、STT 批处理与流式、TTS 播放、VAD、语音代理、RAG/文档、存储持久化、模型切换、Settings 重初始化以及错误/重试状态对应实现见 bindings/web/tests/browser/release-app.e2e.spec.ts 等浏览器 e2e 套件。语音 WebGPU 发布有额外门槛依据 bindings/web/docs/ONNX_WEBGPU.md两对语音 WASM 非空demo 的release.sh要求dist中存在 WebGPU 对浏览器 COI 显示Speech/Embeddings: WebGPU且ONNX.lastFallbackReason null强制webgpu在双胞胎/探针损坏时必须抛错。构建语音相关产物前需要先运行source emsdk/emsdk_env.sh npm run vendor:wasm:speechCPU ORT WebGPU ORT Sherpa。十、给集成者的关键清单应用代码只 importrunanywhere/web与runanywhere/web/browser的根门面后端包只依赖runanywhere/web/backend两者都远离internal。按官方顺序引导initialize()→ 后端register()→completeServicesInitialization()模型目录由应用注册SDK 按需下载加载。推理默认交给 BackendWorkerWebGPU 优先、CPU 兜底主线程只做 I/Oworker 失败绝不静默回退主线程。对外部边界做unknown→ 校验 → 收窄抛结构化的SDKException状态机区分 idle/loading/ready/success/error/cancelled。部署时配置 COOP/COEP 头、按规范服务五对 WASM/glue 资产、收紧 CSP并在生产源上跑npm run test:browser冒烟。发布任何模态前用npm run test:browser:release在真实浏览器中端到端验证而不是只信绿色构建。更完整的构建、测试、发布与浏览器验证 runbook 见 bindings/web/docs/DEVELOPMENT.md 与 bindings/web/docs/DEPLOYMENT.md。赞分享AI模型推理服务推理引擎本地部署多模态【免费下载链接】runanywhere-sdksProduction ready toolkit to run AI locally项目地址https://gitcode.com/gh_mirrors/ru/runanywhere-sdks点击查看免费下载相关推荐RunAnywhere Web SDK 实战指南在浏览器中运行严格类型化的端侧 AIRunAnywhere Web SDK 实战指南在浏览器中运行严格类型化的端侧 AI RunAnywhere Web SDK 是一套面向浏览器应用的、严格类型AI模型推理服务推理引擎本地部署多模态RunAnywhere Web SDK 的 ONNX WebGPU 双构建方案浏览器端 STT/TTS/VAD 与 Embeddings 的 GPU 加速实战RunAnywhere Web SDK 的 ONNX WebGPU 双构建方案浏览器端 STT/TTS/VAD 与 Embeddings 的 GPU 加速实战AI模型推理服务推理引擎本地部署多模态ruflo Agent 自动孵化Auto-Spawning实战指南让 Claude Flow 在正确时机自动拉起正确 Agentruflo Agent 自动孵化Auto Spawning实战指南让 Claude Flow 在正确时机自动拉起正确 Agent ruflo 定位为“agAI模型推理服务推理引擎本地部署多模态上一篇Highway项目维护与未来发展一个已停止维护但仍强大的动画库下一篇解锁Switch系统注入TegraRcmGUI工具探秘与实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/24 15:29:42 · 阅读 1.2k RunAnywhere Web SDK 架构与实战指南：基于 WASM + WebGPU 的浏览器端本地 AI 运行方案
AI模型推理服务推理引擎本地部署多模态【免费下载链接】runanywhere-sdksProduction ready toolkit to run AI locally项目地址https://gitcode.com/gh_mirrors/ru/runanywhere-sdks点击查看免费下载导读RunAnywhere Web SDK 是 RunAnywhere 项目在浏览器端的官方实现它以 Swift 对齐的 TypeScript 门面facade覆盖底层的 RACommons C/C 核心将 iOS/Android/桌面端同源的 AI 引擎通过 Emscripten 编译为 WASM 在浏览器中运行。本文以 bindings/web/CLAUDE.md 为核心骨架结合仓库内的源码、构建脚本与文档系统讲解 Web SDK 的包结构、Commons-First 设计原则、初始化流程、构建命令与部署验证要求。读完本文你将掌握如何在浏览器应用中集成runanywhere/web系列包理解 WASM 与 WebGPU 的分工边界并能按官方规范完成构建、部署与发布验证。一、架构总览三个 npm 包各自独立的 WASM 产物Web SDK 不是一个单一的 npm 包而是由三个可发布的包组成的体系。每个后端包都自带一个自包含的 Emscripten WASM 产物公共代码commons被嵌入到每一个后端 WASM 内部不存在跨 WASM 的符号共享——应用只需要加载自己真正用到的 WASM而不是一次性下载全部引擎。browser app - runanywhere/web - runanywhere/web/browser - runanywhere/web-llamacpp and/or runanywhere/web-onnx runanywhere/web-llamacpp - runanywhere/web/backend runanywhere/web-onnx - runanywhere/web/backend runanywhere/web - runanywhere/proto-ts backend-neutral commons各入口的定位依据 bindings/web/packages/core/src/index.ts、bindings/web/packages/core/src/backend.ts 源码确认入口职责runanywhere/web公开的 Swift 形状核心门面、生成的 proto 类型以及仅含 commons 的racommons.{js,wasm}供RunAnywhere.initialize()使用runanywhere/web/backend窄而类型化的后端集成契约模块安装、能力路由、生命周期钩子、安全日志runanywhere/web/internal更宽泛的核心内部实现导出应用和后端包都不得依赖此入口runanywhere/web/browser浏览器专用辅助工具音频采集/播放、视频采集、能力检测等runanywhere/web-llamacppLLM GGUF 文本嵌入 VLM LoRA 工具调用 结构化输出后端内置两套执行变体runanywhere/web-onnxONNX 嵌入 STT TTS VAD 后端注册onnx与sherpa两个 vtable二者共享 ONNX Runtime应用代码应当停留在根RunAnywhere门面上后端包只通过runanywhere/web/backend集成浏览器应用可以从runanywhere/web/browser导入 UI/设备辅助函数。WASM 产物与执行变体runanywhere/web-llamacpp携带两种执行模式racommons-llamacpp.{js,wasm}CPU和racommons-llamacpp-webgpu.{js,wasm}WebGPU Asyncify。两者都携带统一的 llama.cpp vtable模型框架路由使其嵌入能力可以与 ONNX 共存。runanywhere/web-onnx由racommons-onnx-sherpa.{js,wasm}CPU/pthread和racommons-onnx-sherpa-webgpu.{js,wasm}ORT WebGPU EP支撑。语音加速与 LLM WebGPU 相互独立ONNX.register({ acceleration, threads })与RunAnywhere.runtime.speech各自管理。浏览器中默认使用 fail-closed 的 BackendWorker。关于「为什么同时存在 WASM 与 WebGPU」的详细论证见 bindings/web/docs/WASM_AND_WEBGPU.md语音/ONNX 的 WebGPU 双胞胎产物细节见 bindings/web/docs/ONNX_WEBGPU.md。二、Commons-First业务逻辑归 CTypeScript 保持轻薄这是 Web SDK 最重要的设计原则。Commons 拥有业务与模型逻辑校验、模态modality流水线、工具调用/结构化输出/LoRA/RAG/混合路由/语音代理会话规则、流式状态机全部位于runanywhere-commonsC/C并且只通过生成 proto 的 C ABIrac_*_proto、生命周期、事件在每个后端 WASM 内部被消费。TypeScript 只允许做四件事不能更多编码/解码 proto 字节并通过ccall或 BackendWorker RPC 调用rac_*拥有浏览器 I/O麦克风、扬声器、权限、DOM、fetch、OPFS/IndexedDB 协调托管 BackendWorker并把请求路由到拥有模型的模块暴露 Swift/Kotlin 形状的RunAnywhere.*门面。当 commons 已有对应导出时不要在 TS 中重新实现 commons 流水线。应优先使用原生会话 ABICrossWasm/TS 回退只是降级路径绝不能成为生产路径。一切推理都离开 UI 线程所有 commons/WASM 推理与模型变更都运行在 BackendWorker 中主线程只做 I/O 与轻薄门面。加速策略是 WebGPU 优先当引擎与设备支持时即存在navigator.gpu且支持shader-f16否则退回 CPU worker当必需 worker 失败时绝不静默回退到主线程推理。三、包边界与依赖方向三个可发布的包之外runanywhere/web/backend、runanywhere/web/internal、runanywhere/web/browser都是核心包的入口entrypoints不是额外的包。边界约束如下核心包不得导入任何后端包不得包含 llama.cpp、ONNX Runtime、Sherpa 或 WebGPU 的实现决策。它只拥有契约、生命周期、路由钩子、生成的 wire 适配器与浏览器无关的基础设施。后端包只实现并注册自己 WASM 能服务的能力。它们只能使用文档化的核心backend入口不得导入internal、不得互相导入、不得深度导入包源码文件。示例/应用代码使用公开包根不得导入runanywhere/web/internal也不得在视图中重建 SDK 业务规则。这些约束在 bindings/web/packages/core/src/backend.ts 中有直接体现该文件刻意保持窄面仅导出registerWasmModule/unregisterWasmModule、BackendWorkerHost、运行时配置设置器setAccelerationSwitcher、setActiveAccelerationMode、setSpeechAccelerationMode等以及各类适配器后端包的全部集成都收敛在这一个入口上。四、初始化流程与公开 API 面标准引导序列import { RunAnywhere, SDKEnvironment } from runanywhere/web; import { LlamaCPP } from runanywhere/web-llamacpp; import { ONNX } from runanywhere/web-onnx; await RunAnywhere.initialize({ environment: SDKEnvironment.SDK_ENVIRONMENT_DEVELOPMENT, }); await LlamaCPP.register({ acceleration: auto }); // 加载 racommons-llamacpp.wasm await ONNX.register(); // 加载 racommons-onnx-sherpa.wasm await RunAnywhere.completeServicesInitialization();各步骤的实际行为依据 bindings/web/example/src/main.ts 与 bindings/web/packages/core/src/Public/API/RunAnywhere.tsRunAnywhere.initialize()加载racommons.wasm仅 commons并记录核心 SDK 状态。InitializeOptions支持apiKey缺省即 keyless 本地模式、baseUrl、environmentproduction | development、appIdentifier/appName/appVersion等字段。每个后端的register()加载自己的专属 WASM对该模块调用rac_init()向插件注册表注册自己的 vtable并把自身安装到核心 proto 字节适配器上使后续操作正确路由。ONNX.register()接受可选的wasmUrl覆盖旧的skipProtoBytePlugins/skipStandaloneSpeech选项已移除——proto-byte 是唯一路径。completeServicesInitialization()完成第二阶段后台服务。在示例中该调用是保留的 no-op 兼容转发器因为initialize()已合并了两个阶段但文档化的两阶段引导顺序仍是initialize()→ 后端注册 →completeServicesInitialization()→ 模型目录注册/水合。公开 API 形状根门面刻意保持小巧且 Swift 形状化完整方法清单见 bindings/web/docs/reference/PUBLIC_API_SURFACE.md。要点模型生命周期/注册表loadModel、unloadModel、currentModel、listModels、queryModels、getModel、downloadedModels、downloadModel、importModel。LLM / 结构化输出 / 工具调用generate、generateStream、cancelGeneration、generateStructured、generateStructuredStream、extractStructuredOutput、generateWithTools。语音 / VLM / 语音代理 / RAGtranscribe、transcribeStream、synthesize、synthesizeStream、speak、detectVoiceActivity、streamVAD、processImage、processImageStream、initializeVoiceAgent、processVoiceTurn、streamVoiceAgent、ragCreatePipeline、ragIngest、ragQuery等。命名空间只在 Swift 也有的地方保留RunAnywhere.solutions、RunAnywhere.pluginLoader。从源码看RunAnywhere还聚合了llm、vlm、stt、tts、vad、embeddings、rerank、images、diarization、segmentation、voice、rag、models、lora等能力命名空间以及跨 SDK 对齐的CUA计算机使用代理脚手架见 bindings/web/packages/core/src/index.ts 的导出面。一个最小可运行的流式生成示例来自 bindings/web/example/src/main.tsconst events RunAnywhere.llm.generateStream(prompt, { model: smollm2-360m-q8_0, maxOutputTokens: 256, }); for await (const event of events) { if (event.type textDelta || event.type reasoningDelta) { outputEl.textContent event.text; } else if (event.type completed) { setStatus(Done — ${event.result.outputTokens} tokens at ${event.result.tokensPerSecond.toFixed(1)} tok/s.); } else if (event.type failed) { setStatus(Generation failed: ${event.error.message}); } else if (event.type cancelled) { setStatus(Generation cancelled.); } }模型目录由应用自己持有SDK 会在首次使用时按需下载并加载模型但它只能解析自己已知的 id。示例通过RunAnywhere.models.register({ id, name, category, framework, format, url, sizeBytes, memoryRequiredBytes, contextLength })注册目录条目。Demo 启动顺序与运行时诚实性示例的启动顺序严格为RunAnywhere.initialize()→ 后端注册 →completeServicesInitialization()第二阶段→ 模型目录注册/水合。生产身份identity在本地 shell 就绪之后异步完成绝不能阻塞本地就绪。BackendWorkerHost是生产环境的 LlamaCPP 推理路径当Worker可用时LlamaCPP.register()安装backendWorker.ts在 worker 中加载模型优先采用无 pthread 的 WebGPU WASM并把RunAnywhere.runtime.executionContext设为worker。握手失败时runtime.degradedReason会解释主线程回退的原因。将 pthread CPU 产物嵌套进 DedicatedWorker 需要mainScriptUrlOrBlob以便em-pthread子进程启动。Diffusion 通过runanywhere/web核心暴露Swift/Kotlin 对齐在它发布自己的 WASM 产物之前不存在单独的runanywhere/web-diffusion包——不要把它与四个规范的 JS/WASM 对并列打包。混合 STT 只在ONNX.register()之后才注册Cloud.registerBackend()缺失可选的云端引擎不得让本地 ONNX/Sherpa 不可用。五、类型、校验与错误规则TypeScript 严格模式不得引入any、ts-ignore、未检查的 JSON 断言或重复手写 wire DTO。外部数据一律从unknown开始经过校验后刻意收窄。ESM 发布规范这些包发布 ESM。相对 TS 导入/导出必须写出产出的.js路径例如./runtime/EmscriptenModule.js包括动态导入与 barrel 导出。仅靠 bundler 的扩展名推断会掩盖坏掉的 NodeNext 声明与运行时入口保持npm run check:esm-specifiers与npm run verify:nodenext通过。类型来源模型、生命周期、存储、事件、模态、环境与错误类型都来自生成的runanywhere/proto-ts模块。本地类型只适合 Web 专属的调用点选项或 IDL 中不存在的判别式 UI/运行时状态。边界校验在进入 WASM 之前校验每一个外部边界URL、凭据、模型元数据、下载字节、JSON、浏览器媒体、持久化状态。抛出/返回 SDK 的结构化错误形状带上可操作的字段或操作不要把堆栈跟踪当作用户消息泄漏。SDK 的错误体系在 bindings/web/packages/core/src/Foundation/SDKException.ts 中实现runanywhere/web导出SDKException、isSDKException、ProtoErrorCategory、ProtoErrorCode、ProtoErrorSeverity携带生成的 proto 错误分类法。六、安全与「诚实的运行时状态」凭据红线绝不记录或持久化 API 密钥、bearer token、授权头、含凭据的请求体或含秘密的 URL包括 localStorage、OPFS、IndexedDB、截图、trace、.env文件。VITE_*值是公开的浏览器 bundle 配置永远不是服务器机密——完整部署契约见 bindings/web/docs/DEPLOYMENT.md。同源与固定目标当上游未发布 CORS 时浏览器控制平面访问必须同源。中继目的地保持固定并在白名单内绝不让来自 Settings、查询参数或请求体的 URL 成为代理目标。运行时状态必须诚实UI 与就绪探针必须报告真实的 registered/loaded/inference 状态。缺失后端、WebGPU 路径不可用、模型加载失败、模态失败都是明确的 unavailable/error 状态——不是假开关、静默回退、占位成功或「已下载」通过。动态流程要暴露区分明确的 idle/loading/ready/success/error/cancelled 状态typed union 或生成枚举错误必须留下重试或恢复路径。这一点在 bindings/web/packages/core/src/Public/API/RunAnywhere.ts 中有代码级印证capabilitiesSnapshot()从Runtime.modalities对已注册后端的实时探测生成能力快照而不是从「本模块存在哪些命名空间」推导EXPLICITLY_ABSENT_CAPABILITIES明确声明agents、wakeword、realtime不在 v4 公开 API 面上。七、构建命令与 WASM 产物以下命令在bindings/web/下运行npm run typecheck npm run build npm run lint npm run test npm run check:esm-specifiers npm run verify:nodenext # 发布的声明 Node ESM 入口 npm run test:browser npm run test:browser:release # 可选的完整真实模型发布旅程 # WASM 构建——每个 flag 只向所属包输出 ONE 个产物 npm run build:wasm -- --core # packages/core/wasm/racommons.{js,wasm} npm run build:wasm -- --llamacpp # packages/llamacpp/wasm/racommons-llamacpp.{js,wasm} (CPU) npm run build:wasm -- --webgpu # packages/llamacpp/wasm/racommons-llamacpp-webgpu.{js,wasm} npm run build:wasm -- --onnx # packages/onnx/wasm/racommons-onnx-sherpa.{js,wasm} npm run build:wasm -- --onnx-webgpu # packages/onnx/wasm/racommons-onnx-sherpa-webgpu.{js,wasm} npm run build:wasm:all # core llama CPU/WebGPU onnx CPU/WebGPU npm run vendor:wasm:speech # CPU ORT WebGPU ORT Sherpa发布前必需 npm run build:wasm:debug npm run clean:wasm # 移除所有 WASM 构建目录与生成的 glue/binaries npm run build:wasm:clean ./scripts/package-sdk.sh最小示例仓库内的验证 harness完整 demo 应用位于独立的 runanywhere-web 仓库cd example npm install npm run typecheck npm run build npm run dev产物对应关系与发布门槛依据 bindings/web/docs/DEVELOPMENT.md发布期望的 JavaScript/WebAssembly 对每个build:wasmflag 对应一个packages/core/wasm/racommons.{js,wasm} # --core packages/llamacpp/wasm/racommons-llamacpp.{js,wasm} # --llamacpp (CPU) packages/llamacpp/wasm/racommons-llamacpp-webgpu.{js,wasm} # --webgpu packages/onnx/wasm/racommons-onnx-sherpa.{js,wasm} # --onnx (CPU/pthread) packages/onnx/wasm/racommons-onnx-sherpa-webgpu.{js,wasm} # --onnx-webgpu (ORT WebGPU EP)前四对是强制性的ONNX WebGPU 双胞胎在启用语音加速时发布。CPU 与 WebGPU 是同一个 npm 包拥有的两套独立 llama.cpp 构建ONNX Runtime 与 Sherpa-ONNX 共享一个后端产物因为 Sherpa 使用 ONNX Runtime。两条容易在无意中违反的不变量值得特别重申packages/onnx绝不发布wasm/sherpa/**——那个独立产物已被移除通过racommons-onnx-sherpa.wasm的 proto-byte 路径是唯一的 Sherpa 面。绿色typecheck/lint/build只是冒烟验证。声称某个发布覆盖某模态LLM、VLM、STT、TTS、VAD、Voice Agent、RAG……必须在一个真实的、启用了 COOP/COEP 的浏览器中端到端驱动它——参见npm run test:browser:release与tests/browser/release-app.e2e.spec.ts。每个包的prepack会重建其声明并拒绝缺失、为空、语法无效或损坏的规范资产发布前可用npm pack --dry-run -w packages/core等检查最终 npm 文件清单。WASM 与 WebGPU 的分工一句话概括详见 bindings/web/docs/WASM_AND_WEBGPU.mdWebGPU 加速数学WASM 运行拥有模型的引擎。层职责WASM浏览器内可移植的 C 运行时加载 GGUF/ONNX、分词、会话状态、流式回调、pthread 池、OPFS 水合。没有它就得用 JS 重写整个引擎。WebGPU浏览器 GPU API。llama.cpp 的 ggml-webgpu以及 ONNX Runtime 的 WebGPU EP从那个 WASM内部提交 shader。它不替代引擎。BackendWorkerDedicatedWorker让推理不阻塞 UI 线程托管 WASM 堆。WebGPU 单独无法胜任它没有 Whisper/Piper/GGUF 加载器、没有 Sherpa transducer 解码、没有 llama.cpp 采样循环——这些都在 C 里。把 C 编译成 WASM 是让 Web 与 iOS/Android/桌面共享同一套代码库的方式。原生移动端通过不同 EPCoreML/NNAPI/Metal从同一份 C使用 GPU在 Web 上 EP 是 CPUSIMD/线程或 WebGPU。八、浏览器支持与部署要求支持矩阵依据 bindings/web/docs/BROWSER_SUPPORT.mdChrome / Edge主要生产目标启用跨源隔离后支持SharedArrayBuffer、pthread WASM 与 CPU 版 llama.cpp 和 ONNX/Sherpa 产物。加速现状llama.cpp 在 BackendWorker 中 WebGPU-firstshader-f16可用时ONNX/Sherpa 在 ORT WebGPU 探针成功时用 WebGPU否则 CPU 线程。Firefox支持 CPU WebAssembly 路径与跨源隔离下的 pthreadsWebGPU 按能力依赖对待不作为基线要求。Safari / WebKit需要跨源隔离才能跑线程化 WASM不支持Cross-Origin-Embedder-Policy: credentialless必须部署require-corp并确保每个跨源资源都提供 CORS 或 CORP 响应。注意RunAnywhere.runtime.active/setAcceleration是LLM 作用域的语音诊断在RunAnywhere.runtime.speech与sdk.speechAcceleration事件上。不要把 WebGPU LLM 徽标当成语音 GPU。ONNX/Sherpa 产物使用 pthreads注册前应用必须验证crossOriginIsolated为 false 时给出可操作的错误例如提示配置 COOP/COEP 后刷新。生产应用中注册语音时建议强制 workerawait ONNX.register({ acceleration: auto, // 浏览器 ORT EP 探针 OK 则 WebGPU否则 CPU threads: 2, requireBackendWorker: true, });ONNX.accelerationMode/RunAnywhere.runtime.speech.acceleration只有在 ORT WebGPU EP 附加探针成功时才是webgpu——绝不仅仅因为存在-webgpuWASM 双胞胎就声称加速。部署契约依据 bindings/web/docs/DEPLOYMENT.md必需的隔离头HTML 文档及相关静态资源Cross-Origin-Opener-Policy: same-origin Cross-Origin-Embedder-Policy: credentiallessSafari/WebKit 改用Cross-Origin-Embedder-Policy: require-corp并让每个跨源子资源 CORS/CORP 兼容生产环境验证crossOriginIsolated true。静态 WASM 资产.wasm以Content-Type: application/wasm提供每个二进制旁都要提供规范的 Emscripten glue并把这两类扩展名排除在 SPA 重写之外。当前发布的部署负载是五对十个文件racommons、racommons-llamacpp、racommons-llamacpp-webgpu、racommons-onnx-sherpa、racommons-onnx-sherpa-webgpu。缺失或被 HTML 重写的规范资产可能让 pthread 初始化看起来像挂起——宁可让部署验证失败也不要静默继续。Content Security Policy起点script-src self wasm-unsafe-eval; worker-src self blob:;再按应用适配connect-src、img-src、media-src与模型托管源不要放宽script-src允许任意第三方代码。环境变量VITE_*会被嵌入每个浏览器拿到的 JS 中是公开配置而非机密存储绝不放 API 密钥。内存与下载WASM32 是 4 GiB 地址空间SDK 通过RunAnywhere.runtime.memoryBudget暴露按模块的软预算非硬性预留下载前展示模型大小、预留解压与临时下载开销配额不足时提供恢复路径。生产冒烟部署后用RA_E2E_BASE_URLhttps://your-production-origin npm run test:browser跑 Playwright 冒烟套件。九、发布验证与质量门槛静态门槛严格 TS、外部数据unknown开始、无any/ts-ignorenpm run typecheck npm run lint npm run test npm run build npm run verify:package -w packages/core npm run verify:package -w packages/llamacpp npm run verify:package -w packages/onnx浏览器发布验证必须启动构建好的示例COOP/COEP 开启然后为每一个声称覆盖的模态证明模型下载、模型加载、真实推理、可见输出、恢复/取消。完整发布旅程覆盖 LLM CPU 与 WebGPU、VLM、STT 批处理与流式、TTS 播放、VAD、语音代理、RAG/文档、存储持久化、模型切换、Settings 重初始化以及错误/重试状态对应实现见 bindings/web/tests/browser/release-app.e2e.spec.ts 等浏览器 e2e 套件。语音 WebGPU 发布有额外门槛依据 bindings/web/docs/ONNX_WEBGPU.md两对语音 WASM 非空demo 的release.sh要求dist中存在 WebGPU 对浏览器 COI 显示Speech/Embeddings: WebGPU且ONNX.lastFallbackReason null强制webgpu在双胞胎/探针损坏时必须抛错。构建语音相关产物前需要先运行source emsdk/emsdk_env.sh npm run vendor:wasm:speechCPU ORT WebGPU ORT Sherpa。十、给集成者的关键清单应用代码只 importrunanywhere/web与runanywhere/web/browser的根门面后端包只依赖runanywhere/web/backend两者都远离internal。按官方顺序引导initialize()→ 后端register()→completeServicesInitialization()模型目录由应用注册SDK 按需下载加载。推理默认交给 BackendWorkerWebGPU 优先、CPU 兜底主线程只做 I/Oworker 失败绝不静默回退主线程。对外部边界做unknown→ 校验 → 收窄抛结构化的SDKException状态机区分 idle/loading/ready/success/error/cancelled。部署时配置 COOP/COEP 头、按规范服务五对 WASM/glue 资产、收紧 CSP并在生产源上跑npm run test:browser冒烟。发布任何模态前用npm run test:browser:release在真实浏览器中端到端验证而不是只信绿色构建。更完整的构建、测试、发布与浏览器验证 runbook 见 bindings/web/docs/DEVELOPMENT.md 与 bindings/web/docs/DEPLOYMENT.md。赞分享AI模型推理服务推理引擎本地部署多模态【免费下载链接】runanywhere-sdksProduction ready toolkit to run AI locally项目地址https://gitcode.com/gh_mirrors/ru/runanywhere-sdks点击查看免费下载相关推荐RunAnywhere Web SDK 实战指南在浏览器中运行严格类型化的端侧 AIRunAnywhere Web SDK 实战指南在浏览器中运行严格类型化的端侧 AI RunAnywhere Web SDK 是一套面向浏览器应用的、严格类型AI模型推理服务推理引擎本地部署多模态RunAnywhere Web SDK 的 ONNX WebGPU 双构建方案浏览器端 STT/TTS/VAD 与 Embeddings 的 GPU 加速实战RunAnywhere Web SDK 的 ONNX WebGPU 双构建方案浏览器端 STT/TTS/VAD 与 Embeddings 的 GPU 加速实战AI模型推理服务推理引擎本地部署多模态ruflo Agent 自动孵化Auto-Spawning实战指南让 Claude Flow 在正确时机自动拉起正确 Agentruflo Agent 自动孵化Auto Spawning实战指南让 Claude Flow 在正确时机自动拉起正确 Agent ruflo 定位为“agAI模型推理服务推理引擎本地部署多模态上一篇Highway项目维护与未来发展一个已停止维护但仍强大的动画库下一篇解锁Switch系统注入TegraRcmGUI工具探秘与实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考