企业官网建设流程全解析

在浏览器里运行大语言模型，已经不止是前端圈的“技术玩具”了。现在常见的大模型本地部署方案有三类：第一类是 llama.cpp、Ollama 这类本地推理框架；第二类是直接调用云厂商的模型服务；第三类就是把大模型直接塞进浏览器，用 WebGPU 调用本地 GPU 完成推理，整个过程不经过后端服务。今天要展开说的就是第三条路线。

这类方案里比较有代表性的实现包括 Transformers.js、WebLLM，以及 llama.cpp 的 WebAssembly 版本。它们的共同特点是不需要装 Python、不需要买云 GPU、不需要准备显存特别大的服务器，只需要打开一个支持 WebGPU 的浏览器，就能把中小参数的 LLM 模型加载进页面，完成文本生成、对话、摘要、信息抽取等任务。对于内网环境、隐私敏感场景、以及没有独立 GPU 但想快速验证大模型能力的团队来说，这条路线值得认真测一测。

需要提前说明一点：浏览器内推理不是一个单一项目，而是一类技术方案。后面会提到的模型名、加载参数、调用方式，都需要以你实际使用的开源库版本为准。文章给的是完整链路和验证思路，不会把不确定的显存数字或适配器型号写成结论。

这篇文章的操作目标非常清晰：验证浏览器 WebGPU 是否可用，完成一个浏览器内 LLM 本地推理示例，然后总结批量调用、资源占用和排错方法。你不用先准备 GPU 服务器，只要有一台装了现代浏览器的普通电脑就能开始。

1. 核心能力速览

先把浏览器内 LLM 本地推理的能力边界和门槛整理成一张表，方便你判断是否需要继续往下看。

从这张表能看出，浏览器内推理最大的优势不是跑大参数模型，而是把“部署门槛”压到了最低。它适合跑 0.5B、1B、3B 这类中小参数模型，也适合跑经过量化处理的更大模型，但你要接受它在推理速度、内存占用和并发能力上的限制。

2. 适用场景与使用边界

这部分要讲清楚两件事：这个方案适合谁，不合适谁。

适合的场景主要有三类。

第一类是内网或离线环境。很多企业的数据不能出内网，但业务方又想快速体验大模型能力。浏览器推理方案把模型权重放在本地页面里，推理时即使断网也能继续运行，只要浏览器和模型文件已经准备好。

第二类是前端快速原型验证。你想知道某一个开源小模型的效果如何，又不想为了跑一个 demo 去装一整套 Python 环境和 CUDA 工具链。用浏览器方案，一个 HTML 文件加一个本地服务就能验证。

第三类是隐私敏感的个人工具。比如本地笔记助手、文本改写、敏感信息脱敏检查，直接在浏览器里完成，不把正文内容发送到云端。数据不出设备这一点，让它的隐私边界天然比其他方案更清晰。

不适合的场景也很多。

不适合跑参数量很大的模型。几十B级别的模型即使量化后，也可能远超浏览器标签页可用的内存上限。更稳妥的选择是把这类重量级模型交给本地推理框架或云服务。

不适合对并发有强要求的正式生产服务。浏览器页面的资源限制决定了它适合单用户或少量用户同时使用，不适合做成高并发 API 网关。

不适合用于未获授权的数据加工。如果你要处理的是他人的人脸照片、声音录音、版权文本或敏感个人信息，必须在获得明确授权后再使用，并做好数据删除和访问控制。本地推理降低了技术门槛，但不等于可以绕过授权和隐私保护义务。

3. 环境准备与 WebGPU 可用性验证

浏览器内跑通 LLM 本地推理，前置条件并不复杂，但有一个硬门槛：浏览器必须支持 WebGPU。

3.1 浏览器与系统要求

以 2025 年的实际情况来看，WebGPU 已经在主流浏览器的正式版本中逐步开放。最稳妥的做法是使用最新版的 Chrome 或 Edge，这两个浏览器对 WebGPU 的支持最稳定。Firefox 的 WebGPU 也处于可用状态，但不同版本的默认策略不完全一致，测试前先确认你用的版本是否打开 WebGPU。

操作系统方面，Windows、macOS、Linux 都能跑。GPU 不是硬性要求，因为 WebGPU 在没有独立显卡时可以用软件适配器降级到 CPU，但推理速度会明显变慢。从实际体验看，有独立显卡或性能较好的核显，推理速度会快很多。

开发阶段还需要 Node.js，建议安装 LTS 版本。如果你不想引入 Node.js，也可以直接使用浏览器打开本地 HTML 文件，但会碰到模块加载和跨域限制，所以我更推荐起一个本地静态服务。

3.2 用 navigator.gpu 验证 WebGPU

验证浏览器 WebGPU 是否可用的方法很简单：按 F12 打开开发者工具，在 Console 里执行下面这段代码。

// 在浏览器控制台执行，验证 WebGPU API 是否存在 if ('gpu' in navigator) { const adapter = await navigator.gpu.requestAdapter(); if (adapter) { console.log('WebGPU 可用，已获取适配器'); console.log(adapter.info || adapter); } else { console.log('存在 navigator.gpu，但未获取到适配器'); } } else { console.log('当前浏览器不支持 navigator.gpu'); }

如果输出WebGPU 可用，说明硬件和浏览器层面的 WebGPU 路径已经打通。如果输出当前浏览器不支持 navigator.gpu，优先考虑升级浏览器版本，或者到浏览器的实验特性设置里确认 WebGPU 相关开关是否打开。

3.3 从系统层面确认 GPU 状态

在 Chrome 地址栏输入chrome://gpu，可以看到浏览器对当前 GPU 的识别情况。关键看 WebGPU 和 WebGL 相关条目是否显示为Hardware accelerated。如果显示Software only，说明浏览器没有启用硬件加速，推理时会走软件路径，速度会比较慢。

如果已经启用硬件加速但navigator.gpu.requestAdapter()仍然返回空，可以检查显卡驱动是否需要更新，以及浏览器是否在省电模式下限制了 GPU 资源。部分远程桌面或虚拟机环境也会导致 WebGPU 适配器不可用，遇到这种情况不用纠结，换一台物理机再试。

3.4 准备好模型文件

浏览器内推理依赖量化后的模型权重。以 Transformers.js 为例，它会从 Hugging Face 模型仓库中加载 ONNX 格式的模型文件，你可以直接用公网仓库地址，也可以把模型文件下载到本地静态服务目录下。

更稳妥的做法是在第一次测试时使用公网仓库，确认链路没问题后再把模型放到内网。需要注意，同一个模型在不同运行时框架下需要的格式不一样，不能把 llama.cpp 的 GGUF 文件直接放到 Transformers.js 里用，反之亦然。

4. 一键部署：本地启动与模型加载

下面用 Transformers.js 作为例子，演示从零创建一个浏览器 LLM 本地推理页面。这套流程的核心是本地静态服务和模型加载 API。

4.1 创建项目并安装依赖

打开终端，执行下面的命令。如果你已经有 Node.js 环境，整个过程只需要几分钟。

mkdir browser-llm-demo cd browser-llm-demo npm create vite@latest . -- --template vanilla npm install npm install @huggingface/transformers

这里使用 Vite 作为开发服务器。它速度快，热更新稳定，而且开箱即用地处理了静态资源和本地跨域问题。

执行完成后，项目目录下会有index.html和src目录。接下来把默认的src/main.js改成下面这种结构，直接验证浏览器内推理链路。

4.2 加载文本生成模型

在src/main.js中写入以下代码。注意，模型 ID 只是一个占位示例，你需要替换成实际存在的 ONNX 模型仓库地址。初次加载时，浏览器会按需下载模型文件，所以页面会有一段等待时间。

import { pipeline } from '@huggingface/transformers'; // 创建一个文本生成管线 const generator = await pipeline( 'text-generation', '你的模型仓库ID/模型名称', { device: 'webgpu', dtype: 'q4f16', } ); // 加载完成后输出提示 console.log('模型加载完成，开始推理');

这里有几个参数需要解释。

device: 'webgpu'表示优先使用 GPU 适配器；如果不传，Transformers.js 会使用默认的 WASM 后端，也就是 CPU 推理。dtype: 'q4f16'是量化参数，意思是权重用 4 bit 量化，计算时用 FP16 精度。这个参数不是所有模型都支持，如果加载失败，可以先去掉dtype配置，让运行时使用默认精度。

4.3 启动本地服务

依赖安装和代码写好之后，启动开发服务器。

npm run dev

启动成功后，终端会输出一个本地地址，通常是http://localhost:5173。在浏览器打开这个地址，页面会在控制台输出模型加载状态。

如果你的机器没有独立显卡，或者 WebGPU 适配器不可用，把第 4.2 节代码中的device改成wasm，同样可以跑通本地推理。两者的差别是：WASM 模式用 CPU 计算，速度比 WebGPU 模式慢，但兼容性更好。

4.4 一个完整的页面示例

下面是一个更完整的示例，在页面里放一个输入框和一个生成按钮。用户在输入框输入文本，点击按钮后调用文本生成管线，输出结果展示到页面上。

<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8" /> <title>浏览器 LLM 本地推理示例</title> </head> <body> <h1>浏览器 LLM 本地推理</h1> <textarea id="prompt" rows="4" cols="60">介绍一下 WebGPU 在浏览器端的作用</textarea> <br /> <button id="run">开始生成</button> <pre id="output">等待输入...</pre> <script type="module" src="/src/main.js"></script> </body> </html>

对应的src/main.js可以写成这样，核心是等待模型初始化完成后，串行处理用户请求。

import { pipeline } from '@huggingface/transformers'; const runBtn = document.getElementById('run'); const promptEl = document.getElementById('prompt'); const outputEl = document.getElementById('output'); const generator = await pipeline( 'text-generation', '你的模型仓库ID/模型名称', { device: 'webgpu' } ); runBtn.addEventListener('click', async () => { const prompt = promptEl.value.trim(); if (!prompt) return; outputEl.textContent = '生成中...'; const result = await generator(prompt, { max_new_tokens: 256, }); outputEl.textContent = result[0].generated_text; runBtn.disabled = false; });

按钮在处理过程中置灰，可以避免用户重复点击造成并发调用。测试时先把max_new_tokens设置成 128 或 256，等稳定后再调大。

5. 功能测试与效果验证

模型能加载只是第一步，真正要看的是推理输出。下面给出几条可复用的测试用例，每个用例包含测试目的、操作步骤和判断标准。

5.1 基础文本生成测试

• 测试目的：确认模型能正常生成文本，不是 blank 输出或重复死循环。
• 输入示例：介绍 WebGPU 的核心特性。
• 操作步骤：在页面输入框填入文本，点击生成，等待输出。
• 预期结果：输出一段通顺的中文或英文介绍，内容与 WebGPU 相关。
• 判断标准：输出不为空，且不包含大量重复的“n”或未初始化的 token。
• 失败排查：如果输出只有标点符号或重复字符，优先检查模型 ID 是否正确、量化参数是否匹配、浏览器控制台是否出现 ERR 日志。

5.2 中文提示词测试

很多 ONNX 模型对中文的支持程度不同。测试时要专门跑几条中文提示词，比如“写一封请假邮件”“总结这篇文章的要点”。如果模型输出英文或乱码，说明模型本身不是针对中文语料优化的，换一个中文支持更好的模型即可。

5.3 长文本生成测试

把max_new_tokens从 128 调到 512，再运行一次相同的提示词。观察两个指标：

• 页面是否在长时间生成过程中出现卡死；
• 生成到 300 token 之后内容是否开始循环。

浏览器端模型受上下文长度限制，当生成 token 数接近模型最大上下文时，输出质量会明显下降。这是正常现象，不代表部署有误。

5.4 多次调用稳定性测试

连续点击生成按钮 10 次左右，记录每次生成的结果和耗时。重点观察两点：

• 第一次生成需要下载模型，所以明显更慢，这是正常的；
• 从第二次开始，如果每次都在同一位置报错，说明模型或运行时存在稳定性问题，需要看控制台具体报错。

5.5 上下文窗口测试

浏览器内推理的上下文窗口由模型本身和运行时共同决定。你可以测试模型在短提示词和长提示词下的表现差异。比如先提问一个简单问题，再粘贴一段 2000 字文本让它总结。如果长文本导致内存占用过高或浏览器崩溃，就要考虑使用更小的模型或更短输入。

6. 接口 API 与批量任务思路

浏览器端推理天然是 JavaScript API，不是远程 HTTP API。但你可以把它封装成自己的工具函数，也可以加上一层本地服务，暴露给其他设备或脚本调用。

6.1 封装推理函数

在main.js里，可以把推理逻辑抽成一个generate(prompt, options)函数，这样页面按钮、控制台、批量任务都可以复用。

async function generate(prompt, options = {}) { const result = await generator(prompt, { max_new_tokens: options.max_new_tokens || 128, }); return result[0].generated_text; } // 单条调用 await generate('写一句欢迎语'); // 批量调用 const prompts = [ '解释一下什么是 WebGPU', '写一段 Promise 使用示例', '给出一份浏览器端 LLM 的优缺点清单' ]; for (let i = 0; i < prompts.length; i++) { const output = await generate(prompts[i], { max_new_tokens: 128 }); console.log(`第 ${i + 1} 条：`, output); }

批量任务最简单的实现方式就是for循环加await。它看起来不够花哨，但对浏览器内推理来说却是最安全的形态，因为所有请求都是串行执行的，不会同时抢占 GPU 和内存。

6.2 串行队列 vs 并发

有人会想用Promise.all一次性提交多个提示词，比如下面的写法。

const results = await Promise.all(prompts.map((p) => generator(p)));

这种写法在浏览器端很危险。一个标签页能使用的内存和 GPU 资源有限，多个generator同时执行轻则导致系统卡顿，重则直接让浏览器崩溃。除非你明确知道模型很小、输入文本很短，否则推荐始终使用串行队列。

如果要控制吞吐，可以自己实现一个简单队列：

async function runBatch(prompts, concurrency = 1) { const results = []; for (let i = 0; i < prompts.length; i += concurrency) { const batch = prompts.slice(i, i + concurrency); const batchResults = await Promise.all( batch.map((p) => generate(p)) ); results.push(...batchResults); } return results; }

这个函数虽然用了Promise.all，但批次大小为 1 时等同于串行执行。你可以按需调整concurrency，但第一次测试请从 1 开始。

6.3 通过本地服务暴露 HTTP 接口

如果要在局域网内让其他设备访问，可以在 Vite 项目里加一层后端代理，或者单独用 Express 写一个轻量服务。下面是 Express 的伪代码模板，实际路径和参数需要按你的代码结构调整。

import express from 'express'; const app = express(); app.use(express.json()); app.post('/generate', async (req, res) => { const { prompt, max_tokens = 128 } = req.body; // 这里调用你封装好的 generate 函数 const output = await generate(prompt, { max_new_tokens: max_tokens }); res.json({ output }); }); app.listen(8787, () => { console.log('推理服务已启动: http://127.0.0.1:8787'); });

这样封装后，可以通过 curl 测试接口：

curl -X POST http://127.0.0.1:8787/generate \ -H "Content-Type: application/json" \ -d '{"prompt": "介绍一下 WebGPU"}'

需要注意，这个本地接口默认没有鉴权。如果你把它绑定到非 localhost 地址，必须在前面加一层访问控制，否则局域网内任何设备都能调用你的模型服务，既浪费资源，也有数据泄露风险。

7. 资源占用与性能观察

浏览器内 LLM 推理的资源占用非常直观，但也很容易被忽略。下面给出三个观察入口和一套降负载思路。

7.1 观察浏览器任务管理器

Chrome 自带任务管理器，打开方式是菜单进入“更多工具”再选“任务管理器”。在这里可以看到当前标签页的内存占用、CPU 使用率和 GPU 进程占用情况。

推荐做两个对照测试：

• 第一次用device: 'wasm'加载模型，观察 CPU 占用；
• 第二次用device: 'webgpu'加载模型，观察 GPU 进程占用。

两次对比可以很清楚地看到 WebGPU 是否真的生效。如果 WebGPU 模式下的 GPU 进程占用没有明显上升，说明推理实际走了 CPU 或软渲染路径。

7.2 显存和总内存

浏览器端的“显存占用”数字不是固定的。它受以下因素影响：

• 模型参数量；
• 权重量化精度；
• 输入提示词长度；
• max_new_tokens设置；
• 浏览器是否同时运行多个标签页。

因此，我不会给出一个固定显存数字。更实用的做法是：在推理过程中观察任务管理器里的 GPU 进程内存，记下你的模型在典型输入下的稳定值，作为之后调参的基准。

7.3 降低资源占用的方法

如果推理过程中浏览器明显卡顿，或者任务管理器显示内存占用接近上限，按下面顺序优化：

1. 换更小的模型，比如把 3B 模型换成 1B 模型；
2. 使用更积极的量化参数，比如从 fp16 换成 q4f16；
3. 减小max_new_tokens，缩短单次生成长度；
4. 减小输入文本，裁剪不必要的上下文；
5. 关闭不必要的浏览器标签页，给模型任务腾出内存。

7.4 日志与性能埋点

在代码中加简单的计时逻辑，能快速判断模型推理速度和网络加载速度的占比。

const start = performance.now(); const output = await generate(prompt); const end = performance.now(); console.log('生成耗时(ms)：', end - start);

输出结果后，同步记录提示词长度、生成 token 数和耗时。多次记录后，你会得到一套针对当前机器的性能基线，后续换模型或调参数时可以直接对比。

8. 常见问题与排查方法

浏览器端推理的报错类型比较集中，我把最高频的问题整理成一张排查表。

如果你遇到表格之外的错误，一个通用排查方法是在控制台的 Network 面板看请求失败状态，以及在 Console 面板看完整错误堆栈。浏览器内推理的问题绝大多数集中在模型加载和资源超限两类，定位到这两类就能避免盲目尝试。

9. 最佳实践与后续建议

把浏览器内 LLM 本地推理从“能跑”推进到“能用”，要掌握下面这些原则。

9.1 第一轮测试永远用小模型和短文本

第一次跑通链路时，选参数量最小的模型，比如 0.5B 或 1B 级别，max_new_tokens设成 64 或 128。确认页面能完成“输入到输出”的全链路后，再逐步增大模型和生成长度。这样定位问题最方便，因为变量被控制在最小范围。

9.2 保留一套最小可运行配置

把成功跑通的配置固定下来，包括浏览器版本、模型仓库 ID、device参数、dtype参数和 Node.js 版本。后续改动模型或升级依赖时，先复制这套最小配置到新项目里验证，不要直接在生产项目里升级。

9.3 模型和素材分目录管理

项目中建议用类似下面的目录结构：

browser-llm-demo/ public/ models/ # 本地模型文件 inputs/ # 测试素材 outputs/ # 生成结果 src/ main.js inference.js index.html package.json

模型文件、输入素材、输出结果分开，既方便调试，也方便以后做批量任务和权限管理。

9.4 给批量任务加日志和重试机制

批量任务最容易出现的问题是跑到中间某一条失败后，整个任务直接中断。更好的做法是把每一条的提示词、生成结果和失败原因写入日志，失败的任务自动重试一次，重试仍失败就跳过并标记，最后统一汇总。

9.5 接口服务必须限制访问范围

如果按第 6.3 节的方式把推理方法封装成 HTTP 接口，发布到内网或公网时一定要做三层控制：绑定局域网 IP 而不是0.0.0.0、加简单鉴权、限制单次请求的输入长度。浏览器推理服务的资源本就有限，不加限制很容易被并发请求打崩。

9.6 合规和授权不能省略

本地推理不等于可以随便处理他人数据。无论何时何地，处理人脸照片、声音录音、版权文本或个人信息前，都必须先确认来源是否合法、是否获得授权、是否满足隐私保护要求。涉及商用场景时，还要复核模型权重和训练数据的开源协议，避免把不明确授权的模型集成到商业产品里。

10. 总结与下一步

浏览器内跑通 LLM 本地推理，最值得尝试的点是：零后端、零 Python、数据不出本机。你只需要一个支持 WebGPU 的浏览器、一个量化模型和一段不到 50 行的前端代码。

建议按这个顺序验证：

1. 先执行第 3.2 节的navigator.gpu检测代码，确认浏览器支持 WebGPU。
2. 用最小的量化模型跑通文本生成链路。
3. 完成单条测试后，再试批量串行调用。
4. 最后根据资源占用情况决定是否换更大的模型。

最容易踩的坑有三个：模型 ID 写错导致加载失败；量化参数与模型不匹配导致乱码；Promise.all并发调用导致浏览器崩溃。这三点在文章里都有对应排查方案。

下一步可以扩展的方向也很多：把浏览器内模型接入 RAG 知识库；在 Web Worker 中运行推理避免阻塞页面渲染；加流式输出让生成过程更接近 ChatGPT 体验；或者封装成浏览器插件，打造一个完全离线的本地 AI 助手。浏览器端 LLM 方兴未艾，先用这篇文章跑通第一条链路，后面的事就顺理成章了。