如何在浏览器里运行大语言模型:MiniSearch 的 Wllama + WebGPU 推理管线深度解析

原创2026-11-15 11:16:431,870 阅读

如何在浏览器里运行大语言模型:MiniSearch 的 Wllama + WebGPU 推理管线深度解析

MiniSearch 是一个极简的自托管搜索平台,最大特色就是在浏览器里直接运行大语言模型(LLM):它内置 Wllama 推理引擎,借助 WebGPU 加速或 WebAssembly CPU 回退,把 AI 回答完全留在你的设备本地——不需要 API 密钥,不需要云推理服务器,你的查询和答案一个字节都不离开这台机器。这篇文章带你逐层拆解它的浏览器端推理管线:从 WebGPU 能力探测、GGUF 模型目录,到流式 token 生成的完整链路,帮助你在几分钟内亲手跑起来。

为什么要在浏览器里跑大模型?

大多数 AI 搜索工具都要把查询发给云端大模型,而 MiniSearch 选择了另一条路:

  • 🔒 隐私优先:AI 推理在浏览器标签页内完成,没有第三方能看到你的提问;
  • 🆓 零门槛:内置模型开箱即用,不配任何后端也能生成带引用的回答;
  • ⚡ GPU 加速:有 WebGPU 的浏览器把模型层全部卸载到 GPU,没有则自动回退到 CPU(WebAssembly),速度约为 GPU 模式的 1/2~1/5。

它支持四种推理后端(浏览器、OpenAI 兼容 API、AI Horde、自托管 Internal API),通过懒加载只引入你选中的那一个。完整对比见 docs/ai-integration.md。本文聚焦最独特的 browser(Wllama) 路径。

管线总览:从搜索词到 token 流

MiniSearch 的执行流程是「搜索先行、生成随后」:

  1. 查询发给容器内的 SearXNG 聚合引擎,结果经本地 cross-encoder 重排序;
  2. 搜索结果(可选附加网页正文摘录)被注入系统提示词;
  3. Wllama 实例加载模型,流式输出 token,UI 以约每秒 12 次的节流频率刷新;
  4. 回答连同引用写入本地 IndexedDB 历史库。

整个编排入口在 client/modules/textGeneration.ts,浏览器推理的调度表 inferenceStrategyLoaders 就定义在这里。

第一层:WebGPU 探测——不是有 API 就能用

一个容易被忽略的细节:navigator.gpu 存在 不等于 你的浏览器能跑 GPU 推理。Wllama 的着色器依赖 WGSL 的 subgroups 特性和 subgroup_id 内建变量,某些浏览器(例如 Chrome 137)暴露了 WebGPU API 却编译不了这些着色器,强行上 GPU 会导致所有模型中止。

因此 client/modules/webGpu.ts 里的 detectWebGpuSupport 会做四道检查,全部通过才启用 GPU:

检查项 不通过时的处理
navigator.gpu 存在 回退 CPU
wgslLanguageFeatures 含 subgroup_id 回退 CPU
requestAdapter() 在 5 秒内返回且非软件回退适配器 回退 CPU
适配器特性含 subgroups 回退 CPU

检测结果在每次页面加载时只算一次,之后所有调用方(模型加载、默认模型选择)共享同一个结论,失败原因也会写进应用日志,方便排查。

第二层:模型目录——GGUF 分片与 OPFS 缓存

可运行的模型清单集中定义在 client/modules/wllama.ts 的 wllamaModels 中,从 160 MB 的 LFM2.5 230M 到 2.4 GB 的 Qwen 3.5 4B 共二十余个条目,全部以 GGUF 分片格式存放在 HuggingFace 仓库。这里有两个浏览器特有的硬约束:

  • 必须分片:Chromium 的 Origin Private File System(OPFS)会悄悄截断超过 2000 MiB 的单文件,未分片的大 GGUF 下载到浏览器就是坏的;分片还让进度条可以平滑推进;
  • 4 GiB 内存天花板:Wasm 线性内存上限决定了约 3.5 GB 以上的模型会在缓冲区预留时 OOM,所以目录的实际上限约为 3.7 GB 权重。

模型只需下载一次,之后缓存在浏览器的 OPFS 中(clearWllamaCache 可清空);初始化时 Wllama 还会先做一轮单线程热身(n_threads: 1、max_tokens: 1)验证模型能出词,再退出并以完整线程数重新加载——这一步保证了推理正式开始前模型确实可用。

第三层:推理配置——99999 个 GPU 层的玄机

真正发起生成的是 client/modules/textGenerationWithWllama.ts。initializeWllamaInstance 组装的参数值得逐个看:

参数 取值 作用
n_gpu_layers WebGPU 可用时 99999,否则 0 数字超过总层数即等效「全部上 GPU」
n_threads 用户在设置里选的 CPU 线程数 仅 CPU 路径生效
n_batch / n_ctx 512 / 模型上下文大小 批量与上下文窗口
flash_attn + cache_type_k/v: "f16" 开启 降低 KV 缓存显存占用
reasoning_budget_tokens 思考型模型为 1024 思维链超长时强制收尾作答

生成以流式 createChatCompletion 进行,逐块累积答案;思考型模型的思维链走独立的 reasoning_content 通道,由 composeStreamedText 包裹进可配置的思考标记后交给 UI 的推理区块展示。若用户中途切换查询,状态机进入 interrupted,AbortController 立即掐断流。生成结束(或失败)后,finally 块确保 wllama.exit() 释放实例,不留内存泄漏。

如何选模型:GPU 与 CPU 各有默认

新配置的默认模型按硬件自动分流,常量见 shared/serverConfig.ts:

  • 有 WebGPU → gemma-3-4b(Gemma 3 4B,约 2380 MB):它在 11 语言问答基准中两轮全部拿满 116 分,是 GPU 端的性能标杆;
  • 无 WebGPU → littlelamb-290m(LittleLamb 290M,约 231 MB):CPU 上跑得动,也是整个目录的质量地板——评分低于它的模型会被移出目录。

手动切换时,设置菜单的下拉框(client/components/AiResponse/WllamaModelSelect.tsx)按文件大小升序排列,每个选项都标注体积,方便你按内存预算取舍。基准怎么打的、每个模型考了多少分,完整记录在 docs/wllama-model-evaluation.md。

上手体验:三步跑通浏览器推理

1️⃣ 启动 MiniSearch(自托管 Docker 部署):

docker run -p 7860:7860 ghcr.io/felladrin/minisearch

若要从源码构建,先克隆仓库:

git clone https://gitcode.com/gh_mirrors/mini/MiniSearch
cd MiniSearch
docker compose -f docker-compose.production.yml up --build

2️⃣ 打开 http://localhost:7860,进入菜单 → AI 设置,把 AI Processing Location 选为 Browser(这也是默认值);

3️⃣ 选择模型并提问。首次生成会先出现模型下载进度卡(如 120 MB / 2380 MB),之后缓存命中即秒级加载;无 WebGPU 时还可以调「CPU threads to use」平衡速度与卡顿。

常见问题(FAQ)

Q:我的机器没有独显,能跑吗? 能。WebGPU 检测失败会自动回退 CPU(WebAssembly),默认切到 231 MB 的 LittleLamb 290M,体验是「慢但能用」。

Q:模型存在哪里?会重复下载吗? 存在浏览器 OPFS 缓存里,每个分片只下载一次;换标签页、重启电脑都不用重下,直到你主动清缓存或浏览器清除站点数据。

Q:为什么有的模型会显示「thinking」区块? Granite 4.2、Qwen 3 等思考型模型会把思维链走独立通道流式输出,MiniSearch 用 1024 token 的 reasoning_budget_tokens 兜底,防止模型「想了半天不给答案」。

Q:能在 4B 以上跑更大的模型吗? 受 Wasm 4 GiB 线性内存上限约束,当前目录上限约 3.7 GB 权重;更大规模请改用 OpenAI 兼容或自托管 API 后端。


总结:MiniSearch 的浏览器推理管线是一套很克制的工程组合——四道 WebGPU 探测避免「假加速」、GGUF 分片 + OPFS 缓存解决下载体验、n_gpu_layers: 99999 一键满血 GPU、热身加载与资源释放保证稳定性。对想在本地、私密、零配置地跑大语言模型的用户来说,这条 Wllama + WebGPU 管线值得作为参考范本。

登录后查看全文
MiniSearch