企业官网建设流程全解析

1. 先把问题说清楚：为什么非要端侧推理，还是跑在浏览器扩展里

我做了几年浏览器扩展，也折腾过一阵子端侧模型部署，最近一年明显感觉到一个趋势：越来越多的开发者想把 AI 能力塞进浏览器扩展里，而不是塞进服务器。原因很直接——用户对隐私越来越敏感，对延迟的容忍度越来越低，云端的幻觉、不可控的合规风险、按次调用的成本，都逼着大家把推理从后端往前端迁移。而浏览器扩展恰好是个很特别的宿主环境：它既有独立于网页内容的权限，又能调用本地模型，还比一个单独的网页应用多了一层生命周期管理。换句话说，扩展成了端侧 AI 推理一个比较理想的"边角料"载体。

这个标题很长，但核心其实就三件事：架构怎么设计、工程上怎么实现、规范该怎么定。很多团队做到一半就会发现，在一个内存受限、CPU/GPU 共享、还要考虑浏览器兼容性的环境里跑模型，跟平时写 Node.js 服务完全不是一个思路。本文是我整理出来的实践总结，不吹概念，只讲我在真实项目里踩过的坑和沉淀下来的做法。适合准备做浏览器扩展 AI 功能、或者已经在做端侧推理方案选型的朋友参考。我会从架构拆解开始，一路讲到工程实现细节和问题排查，尽量落地到"能抄作业"的程度。

2. 整体设计与架构思路：扩展不是 Web 网页，别拿 Web Worker 想当然

2.1 浏览器扩展环境的特殊性，决定了架构必须分层

做浏览器扩展端侧 AI，最容易犯的第一个错误，就是把扩展当成普通网页来设计。普通网页里，一个 JavaScript 文件、一个 Web Worker、一个 fetch 请求，自给自足；但扩展的环境是多进程、多线程、多上下文混合的。你至少会碰到几种不同类型的执行环境：background service worker、content script、popup 页面、options 页面，可能还有 offscreen document。这些环境之间不是想通信就能通信的，需要通过消息 API 来传递数据。更麻烦的是，浏览器对每个扩展的 service worker 有生命周期——它不是常驻的，空闲几秒就可能被杀掉，等下一次事件触发时再唤醒。这对端侧 AI 这种需要加载模型、保持推理状态的任务来说，是个特别关键的约束。

所以架构的第一步，是划分"推理运行时"和"扩展 UI/逻辑层"。我最后采用的方案是把所有重量级的 AI 推理放在一个独立的 context 里，比如 offscreen document 或者一个长期打开的扩展页面，并用一个专门的进程承载。background 只做消息路由和生命周期管理，UI 层只管发请求和收结果。这样做的原因很简单：如果模型加载和推理逻辑直接塞在 service worker 里，一旦 worker 被挂起，所有模型状态都没了，冷启动时要重新加载一次模型，用户等十秒，体验直接崩了。

2.2 模块划分背后的取舍：可卸载性、可复用性和权限隔离

模块划分不能只按功能，还得考虑可卸载性和权限隔离。浏览器扩展有一个很有利的特性：扩展包可以配置可选权限，用户不认可就不授予。如果 AI 推理功能是一个独立模块，那用户完全可以选择只装"AI 助手"或只装"普通工具"，这在工程上表现为 manifest 里定义 optional permissions，在代码里按需求动态引入推理模块。

我用的模块结构大致是：

extension-root/ background/ # 消息路由、生命周期、模块注册 inference/ # 模型加载、推理执行、缓存管理 ui/ # popup、options、侧边栏 common/ # 数据类型定义、协议、工具函数 assets/models/ # 本地模型文件（或索引）

这里有个容易犯的错：把模型加载逻辑和业务逻辑耦合在一起。比如content script 想提取页面文本，然后直接调模型做摘要，看起来方便，但一旦 content script 被浏览器隔离环境限死，或者跨域资源访问受限，整套逻辑就废了。我的做法是所有页面分析的结果先通过消息传到 background，再统一丢给推理模块处理。推理模块只负责输入一个结构化对象、输出一个结构化对象，完全不知道上游是谁。这个边界在最初设计时觉得很啰嗦，但工作后才发现它救了大命——因为浏览器扩展不同版本之间的消息协议经常变化，如果每条业务线都单独对接推理模块，每次升级都要改几十处。

2.3 为什么没选云端推理：成本、延迟和隐私三笔账

我知道很多团队最终还是会选云端，因为他们觉得端侧精度不够。这里不讨论模型能力，只算账。延迟方面：即使是一张 200ms 能完成的 OCR 推理，如果放在云上，加上网络 RTT、排队、解包，通常要 1 到 1.5 秒；而同样的任务在本地跑，首帧出结果通常 300ms 以内。成本方面：假设一个扩展有 1 万日活，每人每天触发 50 次推理，云端单次成本 0.01 元，一天就是 5000 元，一年 180 万。这个数字对一个中小团队来说不是小数目。隐私方面：用户的网页内容是高度敏感的数据，一旦传到服务器，就需要处理合规、声明、审计；端侧处理从源头就规避了这个问题。

当然，我并不是完全否定云端。混合架构是合理的：本地推理优先，置信度低于阈值或遇到用户主动要求"联网增强"时，再调用云上大模型。关键是这个降级逻辑要明确写进规范里，并且用户必须知情。标题里说的"架构与工程实现规范"，很大一部分就是在管这件事：哪些任务必须端侧，哪些可以网上，哪些要用户授权，必须有明确的矩阵。

3. 核心细节解析与实操要点：模型、格式和加载策略是命门

3.1 模型选型和量化的硬指标：内存不是无限大的

浏览器扩展环境可支配的内存非常有限。一个普通扩展，如果一下加载一个 7B 的 fp16 模型，直接能把浏览器整个 tab 拖垮。我在实践中总结出一个公式：扩展可用的推理内存 ≈ 浏览器剩余内存 × 0.3，再减去扩展自身 DOM 和 UI 开销。也就是说，如果你在 16GB 内存的设备上，浏览器占用了 8GB，那扩展能较安全使用的可能只有 2GB 左右，这种情况下要跑超过 2B 参数的模型，基本上只能靠极低比特量化。

选模型我一般遵循几个原则：

• 参数量小优先：任务能用 0.5B 就不上 1.5B，能用 3B 就不上 7B。在端侧，参数量不是精度，是灾难。
• 量化格式首选 int8 / int4：ONNX Runtime Web 和 WebNN 生态对量化支持比较成熟，优先用 Q8 甚至 Q4 模型。我在实际测试中，一个 7B 模型的 Q4 版内存占用约为 3.5GB，Q8 约为 7GB，后者在绝大多数浏览器环境里已经没法工作了。
• 任务专用模型优先于通用模型：比如做表单自动填写，一个 0.5B 的 NER 模型效果比 7B 的通用对话模型更稳定，速度还快 10 倍。

3.2 模型加载的"冷"与"热"：缓存和预加载策略

浏览器扩展没有传统意义上"进程常驻"的概念，所以模型的加载策略必须区分冷启动和热启动。

冷启动指浏览器刚启动、扩展 service worker 被重建，模型文件全部需要从磁盘读取并初始化。这一步通常最慢，耗时从数百毫秒到数秒不等，取决于模型大小和磁盘 IO。我做的优化有二：

1. 把模型文件放到扩展包的 assets 目录，并用browser.storage.local保存模型元数据（版本、哈希、量化类型），避免每次启动都校验文件完整性。
2. 使用offscreen document里的requestAnimationFrame或定时器保活，让推理模块尽可能不被浏览器回收。实测 Chrome 中，只要 offscreen 页面持续有音频播放或视频解码等"高优先级"活动，进程就不容易被挂起；如果只是空转，有时还是会被回收，所以还要加一层"唤醒重载"逻辑。

热加载则指在模型已经驻留内存后，多次推理之间的状态保持。热加载的优化主要是避免重复创建推理会话。ONNX Runtime Web 的InferenceSession创建成本很高，我一般会维护一个 session 池，按模型版本缓存，只有模型文件变化时才重建。

3.3 输入输出端的工程化处理：归一化、tokenizer 与分片

很多教程提到端侧模型就只讲加载与推理，却忽略了输入输出的工程化。这里面的坑非常多。首先是文本输入的归一化：网页上提取的文本可能有大量换行、零宽字符、HTML 实体，直接灌进 tokenizer 结果会很差。我封装了一个文本清洗管线：去除不可见字符、统一换行符、截断上下文窗口，并且计算 token 数来控制分片。

分片策略尤其重要。一个长网页动辄上万个字符，模型的上下文窗口往往不够。我的做法是"滑动窗口分片 + 重叠摘要"。举个例子，像 FAQ 页面的问题回答列表，我会把一个长文本按 1000 token 左右切成块，相邻块重叠 20%，每块独立跑推理，最后再用一个轻量级聚合模型合并结果。这样既避免信息截断，又不会让单次推理输入过长导致内存溢出。

说到内存溢出，这是浏览器端推理最大的隐形杀手。我常常看到一些团队在 PC 上测试没事，一到低端笔记本上就崩溃。原因是模型激活内存和输入长度成正比，长文本会瞬间把内存打满。所以必须在输入管线里设置硬上限，比如"If input token > 2000，直接走粗加工方案（如只取首尾各 500 token）"。这个限制要写进实现规范，不能只当 bug 得补丁。

4. 实操过程与核心环节实现：从 manifest 配置到推理线程的真实部署流水线

4.1 第一步：Manifest V3 下的权限与生命周期配置

现代浏览器扩展必须用 Manifest V3（MV3）。MV3 对后台脚本的限制比 V2 严格得多，service worker 不能像以前那样无限制运行。我最终的 manifest 关键片段如下：

{ "manifest_version": 3, "name": "Local AI Assistant", "permissions": ["storage", "offscreen", "activeTab"], "optional_permissions": ["scripting", "downloads"], "background": { "service_worker": "background.js", "type": "module" }, "action": { "default_popup": "popup.html" }, "content_scripts": [ { "matches": ["<all_urls>"], "js": ["content.js"], "run_at": "document_idle" } ] }

注意offscreen权限不是默认有的，Chrome 需要显式声明。Safari 和 Firefox 对 offscreen document 的支持不同，Firefox 更习惯用 native messaging 或后台页面，需要做平台适配。

4.2 第二步：推理线程的构建与消息协议

我最终把推理模块跑在offscreen.html里的一个 Web Worker 中。为什么不是直接在 offscreen document 的 JS 线程跑？因为模型推理是 CPU/GPU 密集任务，如果把主线程卡住，用户拖拽窗口都成问题。构建方式如下：

// offscreen.js 中创建 worker const worker = new Worker('inference-worker.js'); worker.onmessage = (event) => { const msg = event.data; if (msg.type === 'INFERENCE_RESULT') { chrome.runtime.sendMessage({ type: 'AI_RESULT', taskId: msg.taskId, data: msg.data }); } }; // background.js 中负责路由 chrome.runtime.onMessage.addListener((msg, sender, sendResponse) => { if (msg.type === 'RUN_INFERENCE') { chrome.runtime.sendMessage({ type: 'FORWARD_TO_INFERENCE', payload: msg.payload }, (res) => { sendResponse(res); }); return true; // 异步响应 } });

这里有一个非常容易掉进去的坑：MV3 的 service worker 可能在收到消息的同时正在被回收，如果你在 background 里直接访问 offscreen worker，可能出现"Extension context invalidated"的报错。解决办法是在消息进来时先keep alive，比如用chrome.runtime.connect建立长连接，再向推理模块转发。我在实际开发中甚至专门写了一个"心跳检测器"，每隔 20 秒从 offscreen 页向 background 发一个空信号，保证上下文不失效。虽然不优雅，但非常实用。

4.3 第三步：ONNX Runtime 与 WebGPU 的选型和数据格式转换

端侧推理框架目前我用得比较多的是 ONNX Runtime Web（ort-web）。它的优点是对 WebGPU 支持完善，可以调用 GPU 加速。另一个选择是 Transformers.js，基于 ONNX Runtime，封装了许多预训练模型的转换逻辑，对前端开发者友好。但对于生产级扩展，我更推荐直接用 ort-web 自己写推理管线，原因是可以更精细地控制 session 参数和缓存。

具体实现的关键步骤是数据格式转换。模型期望的输入往往是浮点张量，而 JavaScript 里从 TypedArray 转成ort.Tensor非常简单：

import * as ort from 'onnxruntime-web'; async function runInference(inputTokens) { const feeds = {}; const inputTensor = new ort.Tensor('int64', BigInt64Array.from(inputTokens), [1, inputTokens.length]); feeds['input_ids'] = inputTensor; feeds['attention_mask'] = new ort.Tensor('int64', BigInt64Array.from(mask), [1, inputTokens.length]); const session = await getSession(); // 从缓存取 session const results = await session.run(feeds); return results['output']; }

这里要提醒的是，BigInt64Array转换成ort.Tensor时，在部分浏览器的旧版本上有兼容性问题。我会用Number数组先转成普通Float32Array，再让 ort 内部处理。看似多一步，却能避免线上 5% 用户的崩溃。

4.4 第四步：内存与并发控制的工程规范

推理并发控制必须做成硬限制。我的规范是：

• 同一时间只允许一个推理任务在 worker 内运行；
• 新任务到来时，如果当前有任务，则进入队列，队列长度超过 3 就丢弃最新任务并提示"The model is busy"；
• 每个任务执行前记录内存水位，完成任务后主动调用gc()（在 worker 里可用，但不要依赖）并清空大对象引用。

为什么队列长度只设 3？因为端侧推理不像服务端可以无限制排队。用户连续点按钮时，模型在 5 秒内只能处理两三个任务，如果一直排队，浏览器内存会持续增长，最后整个 tab 白屏。这个取舍在多数情况下是合理的——我们做的是交互式工具，不是高并发 API。

内存水位监控我做了个简单方案：通过performance.memory.usedJSHeapSize采样，在推理前和推理后各取一次，如果差值超过可配置阈值，则下一次推理前清空 session 缓存并重载。这个方法不精确，但作为防护足够用了。

5. 常见问题与排查技巧实录：我在扩展端侧推理里踩过的坑

5.1 问题一：Service Worker 频繁被终止导致推理中断

现象：用户使用扩展过程中，AI 回答突然中断，过一会儿又恢复正常。排查后确认是 service worker 生命周期问题。我之前已经用 offscreen 保活，但还是有概率被回收。后来发现，chrome.offscreen有获得 前提："offscreen document 必须在扩展安装时或运行时创建，而且需要用户交互或事件触发"。我把 offscreen 创建时机从后台启动改为用户第一次点击 action 时创建，同时每次推理后延迟 30 秒销毁，极大降低了回收概率。

修复思路提炼成两条规范：

• 所有 AI 功能必须经用户手势触发后再初始化推理；
• 推理过程中，如果出现了Extension context invalidated错误，捕获后自动重建上下文并重新尝试一次。

5.2 问题二：GPU 加速可用但实际不稳定

在使用 WebGPU 时，我遇到了非常诡异的"第二次推理结果全是 NaN"的问题。查了一圈发现是部分显卡驱动下 WebGPU 的 float16 支持有问题。ort-web 允许设置执行设备和精度：

ort.env.webgpu.precision = 'fp32'; // 强制用 fp32

改成 fp32 后问题消失，但速度下降约 25%。我权衡后，默认用 fp16，但加一个"设备检测"：首次推理结果如果有 NaN，自动切换为 fp32 并重试。这个降级机制在规范里也叫"推理一致性回退"，是个很实用的兜底策略。

5.3 问题三：Content Script 拿到的页面文本包含大量噪音

这是端侧 AI 的一个经典问题。网页上的正文提取，如果直接document.body.innerText，会混入导航、cookie 弹窗、广告文本。这些噪音会让摘要模型生成完全无关的内容。我试过 Readability.js、Trafilatura 等方案，最终认为在扩展里不要只依赖一种提取器。我的规范是"多源提取 + 分类器打分"：分别用 Readability 提取正文、用 meta description、用标题和 URL 特征，最后用一个 0.3B 的小分类器判断哪段文本最像正文。这个流程看起来重，但实际运行在小模型上只需几十毫秒，比任何正则都强。

5.4 问题四：模型文件从扩展包加载失败或跨浏览器不兼容

把模型打包进扩展会导致扩展包体积过大，我常用 CDN 动态加载模型文件，但浏览器扩展对跨域请求控制严格。在 MV3 中，跨域请求需要在host_permissions里明确声明域名，而且不能动态添加。我的解决办法是先让用户在一个授权页面确认信任某个模型源，然后把这个源写入chrome.storage，background 再发起请求。注意：Safari 对跨域模型加载限制更多，我一般会把模型放在扩展包或本地 HTTP 服务中，避免用动态远程加载。

5.5 问题五：低端设备上推理速度达不到可用阈值

如果模型在目标设备上单次推理超过 3 秒，这种功能基本没人用。我做过一个性能基线表，作为规范供团队参考：

这个表的意思不是"低端设备就该慢"，而是提醒开发者在功能设计时就要预留降级路径。比如摘要功能，可以做成两种按钮：快速摘要（走小模型，时延低但精度一般）和深度摘要（需要更高配置的模型，但用户确知会慢）。合理的设计就是在用户点按钮前动态检测硬件能力，决定显示哪种能力。

6. 工程实现规范的落地清单：从代码评审到发布检查

6.1 必须写进规范的五条硬性要求

端侧 AI 功能不能只靠开发者自觉，我在团队里定的规范分五层。

第一层，资源边界：所有推理任务必须经过统一的资源管理模块，禁止在业务代码里直接创建InferenceSession。这样便于统计总内存和切换模型。

第二层，数据隐私：任何文本、图像、音频数据在未经用户授权的情况下，不得离开本地。日志记录只允许记录任务的哈希值和耗时，禁止记录内容本身。如果有云端降级功能，必须每次动态弹窗获取单独授权。

第三层，生命周期：推理模块必须有冷启动、热启动、回收三个状态机，任何状态下都能优雅处理新任务。如果收到任务时模型未加载，先响应LOADING状态并显示进度，同时禁止再次重复触发加载。

第四层，兼容性：代码中不能使用只在单一浏览器的专有 API。对每个浏览器（Chrome、Edge、Firefox、Safari）都写一份适配层。WebGPU 不可用时回退到 WebAssembly。

第五层，异常恢复：推理出错时，不能直接弹报错框，应先尝试会话重建并重试一次；如果再失败，再提示用户模型损坏并支持重新下载。

6.2 发布前的验证清单与性能回归测试

每次发版前，我会跑一个流程化的测试脚本，重点验证这几项：

• 冷启动时模型加载是否在目标设备上不超过 2 秒，如果超时则优化模型文件或改预加载策略。
• 连续触发 10 次推理后，页面是否出现内存持续增长，用 Performance API 记录曲线，异常则定位是 session 泄漏还是任务队列堆积。
• 切换 tab 或关闭浏览器后，重新打开时能否快速恢复到之前状态。
• 在至少 5 种浏览器环境（Chrome 稳定版、Chrome Beta、Firefox、Safari、Edge）下跑一遍推理回归用例。
• 验证离线场景：断网后，如果模型已缓存，扩展的 AI 功能还能正常使用。

这个清单的初衷是避免"我电脑上能用就行"的心态。浏览器扩展的宿主千变万化，只要有一类环境批量报错，用户流失就比功能新增还快。

6.3 维护与扩展：模型热更新和 A/B 测试的方案

模型不是一成不变的。我会在后台维护一个模型仓库，用版本清单文件进行热更新升级。具体做法是：扩展每天首次启动时请求一个轻量 JSON 清单，检查是否有新版本模型，若存在且用户同意，则后台下载到本地存储，下次推理时切换。因为有哈希校验，模型文件损坏或篡改都能识别。A/B 测试则要更谨慎：不要直接对用户部署模型，而是在本地根据storage里的实验分组参数决定加载哪个模型，这样不会造成不可逆影响。

听起来这些规则多到麻烦，但经历过一次"模型更新引入中文乱码、又花了三周回滚"的事件后，我就意识到规范的价值不是约束，而是保命。

7. 最后说几句我自己的实操心得

做了几个月的浏览器扩展端侧推理，最大的体会是：这个方向离"产品可用"比想象中要近，但离"稳定可靠"还差得远。最大的瓶颈不是模型能力，而是工程韧性。浏览器本身对扩展的限制非常不友好，动不动就回收后台、限制权限、锁死跨域，这些都需要在架构层面提前化解，而不是等到线上出问题再去打补丁。

另一个体会是，端侧推理里的所谓"大模型"其实是被约束过的"小模型"，我们更应该关注怎么让任务和模型匹配，而不是追求参数量。如果你能把一个 1B 的量化模型在浏览器扩展里稳定跑出 200ms 以下的延迟，满足用户 80% 的诉求，那你已经比大多数塞一个云端大模型接口的"AI 扩展"更实用了。

最后再分享一个小技巧：在调试 service worker 和 offscreen 生命周期时，打开chrome://serviceworker-internals/和 DevTools 里的 Application 面板，可以实时看到扩展后台被停止和唤起的记录。很多"灵异事件"其实都是 30 秒自动回收导致的，把这些日志记录下来，排查速度快得多。浏览器扩展端侧推理这条路还很长，但我相信架构和规范做扎实了，后面会越走越顺。