WebLLM Subgroups 能力路由实战在 Web 应用中按 WebGPU 子组特性动态切换 WASM 模型库【免费下载链接】web-llmHigh-performance In-browser LLM Inference Engine项目地址: https://gitcode.com/GitHub_Trending/we/web-llm导读本文基于 WebLLM 仓库中的examples/subgroups-usage示例讲解如何在 Web 应用里实现能力路由capability-based routing运行时探测 WebGPU adapter 是否支持subgroups特性并据此在 baseline 与 subgroupSG32两种 WebGPU WASM 构建之间动态切换模型库。读完本文你将掌握 WebGPU 子组特性的探测逻辑、model_lib路径改写方法以及如何把该示例改造成指向自己的模型与模型库。示例背景为什么要按能力路由WebLLM 是高性能的浏览器端 LLM 推理引擎模型权重与编译产物以 WebGPU WASM 形式分发。为了让推理更快MLC 团队会针对支持 WebGPU 子组subgroup特性的设备提供优化后的 WASM 构建而不支持该特性的设备则继续使用 baseline 构建。子组特性WGSLSubgroups对应的subgroups功能允许一个工作组内的线程以硬件原生方式协作从而降低同步与内存开销。问题在于同一份应用无法预先知道用户设备的 WebGPU 能力。examples/subgroups-usage正是为此提供一个最小可运行 demo——启动时探测 adapter 能力再决定加载哪种 WASM避免在不支持的设备上加载 subgroup 构建导致运行失败也避免在支持的设备上错过性能优化。仓库根目录的 examples/README.md 将其概括为 capability-based routing between baseline and subgroup WebGPU WASM builds。快速运行示例示例目录自带独立的package.json使用 Parcel 作为开发服务器与打包器依赖mlc-ai/web-llm示例当前锁定^0.2.84见 examples/subgroups-usage/package.json。在示例目录下执行npm install npm startnpm start实际执行的是parcel src/subgroups_usage.html --port 8888随后浏览器打开http://localhost:8888即可。页面本身非常精简见 examples/subgroups-usage/src/subgroups_usage.html只有一个初始化进度标签init-label其余输出模型加载日志、对话回复、usage统计都在浏览器控制台查看。运行前提浏览器需支持 WebGPU 并处于启用状态如 Chrome/Edge 的 WebGPU 支持示例运行时需要联网下载模型权重与 WASM 模型库。核心机制一探测 WebGPU 子组能力示例的探测逻辑位于 examples/subgroups-usage/src/subgroups_usage.ts 的main()中。它通过navigator.gpu.requestAdapter()请求一个优先高性能的 adapter然后读取其特性与限制const adapter await (navigator as any).gpu?.requestAdapter({ powerPreference: high-performance, }); if (adapter null) { throw Error(Unable to request a WebGPU adapter.); } const adapterInfo adapter.info || (await (adapter as any).requestAdapterInfo()); const subgroupMinSize adapterInfo.subgroupMinSize; const subgroupMaxSize adapterInfo.subgroupMaxSize; const supportsSubgroups adapter.features.has(subgroups) subgroupMinSize ! undefined subgroupMinSize 32 subgroupMaxSize ! undefined 32 subgroupMaxSize adapter.limits.maxComputeInvocationsPerWorkgroup 1024;这段代码揭示了 SG32 构建的硬件适配条件全部满足才算支持子组路由adapter.features.has(subgroups)adapter 暴露了subgroups功能子组大小范围必须覆盖 32subgroupMinSize 32且subgroupMaxSize 32即设备能以 32 线程为单位的子组运行计算adapter.limits.maxComputeInvocationsPerWorkgroup 1024单工作组最多可容纳 1024 个调用这是运行对应 compute shader 的必要上限。从源码结构看SG32 即 32 线程子组的优化构建只有当硬件子组大小允许 32SG32时才切换否则停留在 baseline。开发者若想支持其他子组大小如 SG64可以在此基础上扩展判断条件与路径改写规则。核心机制二动态改写 model_lib 路径toSg32ModelLib()是路由的核心工具函数它把 baseline 的 WASM 路径改写为 subgroup 变体function toSg32ModelLib(modelLib: string): string { const modelLibUrl new URL(modelLib); const pathParts modelLibUrl.pathname.split(/); const wasmFileIndex pathParts.length - 1; const variantDirIndex wasmFileIndex - 1; if (variantDirIndex 0 || pathParts[variantDirIndex] ! base) { throw Error( Expected model_lib path variant directory to be base: ${modelLib}, ); } pathParts[variantDirIndex] sg32; modelLibUrl.pathname pathParts.join(/); return modelLibUrl.toString(); }其约定如下model_libURL 的目录结构中必须存在一个名为base的变体目录且它紧邻 WASM 文件名。改写时仅把base替换为sg32其余路径保持不变。例如baseline.../v0_2_84/base/Llama-3_1-8B-Instruct-q4f32_1-ctx4k_cs1k-webgpu.wasm改写后.../v0_2_84/sg32/Llama-3_1-8B-Instruct-q4f32_1-ctx4k_cs1k-webgpu.wasm如果目录名不是base例如指向了自定义路径函数会抛出明确错误防止静默加载错误构建。核心机制三构造带路由的 appConfigWebLLM 的模型配置由AppConfig描述其中model_list是ModelRecord数组定义见 src/config.ts。ModelRecord的关键字段包括model模型权重仓库地址Hugging Face 风格 URL 或本地路径model_id模型的唯一标识供CreateMLCEngine()引用model_lib该模型使用的 WASM 模型库地址overrides可选的ChatConfig覆盖项例如调整 KV Cache 设置context_window_size等见 src/config.tsvram_required_MB、low_resource_required、required_features等辅助字段用于资源预估与特性校验。示例首选从 WebLLM 内置的prebuiltAppConfig位于 src/config.ts中取出目标模型记录再按能力探测结果决定是否替换model_libconst selectedModel Llama-3.1-8B-Instruct-q4f32_1-MLC; const modelRecord webllm.prebuiltAppConfig.model_list.find( (entry: webllm.ModelRecord) entry.model_id selectedModel, ); const appConfig supportsSubgroups modelRecord ! undefined ? { model_list: [ { ...modelRecord, model_lib: toSg32ModelLib(modelRecord.model_lib), }, ], } : undefined;这段代码体现了默认安全、按能力升级的设计不支持子组时appConfig保持undefined引擎自动使用prebuiltAppConfigbaseline 构建支持时才注入替换过model_lib的配置。...modelRecord展开保留了model、overrides等其余字段仅覆盖model_lib一项。若想指向自己的模型示例注释给出了 Option 2 的完整模板手工构造model_lib使用webllm.modelLibURLPrefix webllm.modelVersion /...拼接预构建库地址。其中modelVersion表示当前 npm 包兼容的预构建模型库版本示例对应v0_2_84/basemodelLibURLPrefix指向模型库发布前缀二者定义见 src/config.ts拼接结果形如.../v0_2_84/base/模型名-webgpu.wasm。引擎创建与 KV Cache 定制探测与配置就绪后通过CreateMLCEngine()创建引擎API 定义见 src/engine.tsconst engine: webllm.MLCEngineInterface await webllm.CreateMLCEngine( selectedModel, { appConfig: appConfig, initProgressCallback: initProgressCallback, logLevel: INFO, // specify the log level }, // customize kv cache, use either context_window_size or sliding_window_size (with attention sink) { context_window_size: 2048, // sliding_window_size: 1024, // attention_sink_size: 4, }, );三个参数分别对应selectedModel要加载的model_idMLCEngineConfigappConfig传入路由后的配置initProgressCallback把加载进度report.text实时写到页面标签logLevel控制控制台日志级别可选的 KV Cache 定制参数context_window_size: 2048限定上下文窗口或改用sliding_window_sizeattention_sink_size滑窗 注意力锚点方案。这些字段对应ChatConfig中的 KV Cache 设置见 src/config.ts最终会覆盖模型的mlc-chat-config.json默认值。示例注释还给出了第三种用法先new webllm.MLCEngine({...})再单独调用engine.reload(selectedModel)。路由效果的验证方式加载完成后示例发起一次带logit_bias的生成请求用于验证模型工作正常const reply0 await engine.chat.completions.create({ messages: [{ role: user, content: List three US states. }], n: 3, temperature: 1.5, max_tokens: 256, logit_bias: { 46510: -100, 7188: -100, 8421: 5, 51325: 5, }, logprobs: true, top_logprobs: 2, }); console.log(reply0); console.log(reply0.usage);其中logit_bias特意把 California 的两个 token46510、7188压到 -100、把 Texas 的两个 token8421、51325抬到 5从而让输出更倾向 Texas 而绝不出现 California。这是验证路由构建可正常推理的巧妙手段同时展示了logprobs/top_logprobs、n、temperature等 OpenAI 兼容参数的用法。验证路由是否生效的关键观察点打开浏览器控制台查看supportsSubgroups的日志值并确认 DevTools Network 面板中实际下载的 WASM 文件名。若设备支持子组应为.../sg32/....wasm否则为.../base/....wasm。两种情况下模型都应正常完成对话生成说明路由切换未破坏推理链路。改造指南指向自己的模型与构建README 明确指出编辑 examples/subgroups-usage/src/subgroups_usage.ts 即可指向自己的模型路径与 baselinemodel_lib。改造要点更换模型把selectedModel改为自己的model_id并确保该模型存在于prebuiltAppConfig.model_list或改用 Option 2 手工配置model_list更换 model_lib将model_lib指向自己托管的 WASM 地址注意保持目录结构满足.../variant/name-webgpu.wasm且变体目录名为base否则toSg32ModelLib()会抛错——这是-subgroups后缀路由机制的前提约定注意modelVersion兼容性若手工拼接预构建库须保证路径中的版本与当前 npm 包的modelVersion匹配见 src/config.ts否则可能加载到不兼容的 WASM。进阶hack WebLLM 核心包README 特别提示如果你希望修改 WebLLM 核心包本身可以将示例的依赖改为本地路径并跟随仓库源码构建dependencies: { mlc-ai/web-llm: file:../.. }即把examples/subgroups-usage/package.json中的依赖替换为file:../..指向仓库根目录再按照仓库的从源码构建说明docs/developer/building_from_source.rst本地构建 webllm。构建完成后重新npm install即可让示例使用本地核心包。README 强调该方式仅推荐给需要修改 WebLLM 核心包的开发者仅使用示例本身时保持 npm 依赖即可。小结subgroups-usage示例用约百行 TypeScript 演示了完整的 WebGPU 能力路由链路探测subgroups特性 → 校验 SG32 硬件条件 → 改写model_lib变体目录 → 按结果构造appConfig→ 创建引擎并验证推理。这一模式可推广到其他能力差异化分发场景如 shader-f16 特性、不同 KV Cache 策略是构建一套代码、多端适配的浏览器端 LLM 应用的实用参考模板。【免费下载链接】web-llmHigh-performance In-browser LLM Inference Engine项目地址: https://gitcode.com/GitHub_Trending/we/web-llm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考