博客助手使用教程：浏览器配置、模型缓存与常见问题

功能说明

博客助手运行在访客自己的浏览器中。首次启用时，页面会从 Hugging Face 下载 ONNX 模型，保存到当前博客来源的 Cache Storage，然后使用 WebGPU 或 WASM 在本地生成回答。

它可以检索本站文章、流式回答中文问题，并在回答下方附上原文链接。对话问题和生成过程不需要发送到博客服务端，但浏览器仍需联网下载页面资源、文章索引和模型文件。

这是一项实验功能。第一次使用前需要确认浏览器、磁盘空间和站点存储配置，首次下载通常需要较长时间。

下载量与运行模式

当前使用的固定模型版本如下：

模型：w10110/qwen3-0.6b-zh-blog-style-onnx
版本：a41c0b941ee4ca797b1e750e683eb4ef36ea1992

页面提供两种运行模式：

模式	首次下载估算	浏览器要求	建议自定义配额
WebGPU	约 663 MB	支持 WebGPU，显卡支持 shader-f16	至少 700 MB，建议 800 MB
WASM 兼容模式	约 765 MB	支持 WebAssembly	至少 850 MB，建议 900 MB
两种模式都保留	约 1.4 GB	曾分别下载两套权重	建议 1.6 GB 以上

下载估算包含模型配置、分词器和权重，不包含浏览器推理运行库及当前来源原有的其他数据。Chrome 的自定义配额表示当前来源可使用的总量，不是剩余量。例如这个来源已经使用 200 MB，再设置 700 MB，只剩约 500 MB 可用。

WebGPU 速度通常更好，页面会优先检测它。若 WebGPU 初始化失败，页面只显示原因，不会立即下载 WASM 权重；确认后再点击“切换兼容模式”，可以避免无意中连续下载两套模型。

首次使用前的浏览器设置

推荐使用最新版桌面版 Chrome 普通窗口。无痕窗口、访客模式和退出时自动删除站点数据的配置不适合保存数百 MB 的模型文件。

允许站点保留本地数据

打开 Chrome 设置，进入“隐私和安全”相关的站点数据设置，检查以下内容：

• 允许当前博客来源在设备上保存数据；
• 当前域名不在“关闭所有窗口时删除站点数据”的列表中；
• 系统磁盘有足够空间，至少为准备下载的模式预留 1 GB；
• 本地调试和线上博客分别检查，因为它们是两个独立来源。

Chrome 设置页面的名称可能随版本变化。可以在设置顶部直接搜索“站点数据”或“设备上的网站数据”。

配置 Simulate custom storage quota

按 F12 打开 DevTools，依次进入 Application → Storage。在这里可以看到当前来源的已用空间和配额，也可以使用 Simulate custom storage quota 模拟指定额度。

按下面的规则设置：

1. 如果该选项已经勾选，WebGPU 模式至少填写 700 MB，更建议填写 800 MB。
2. 准备使用 WASM 兼容模式时，建议填写 900 MB。
3. 需要同时保留 WebGPU 和 WASM 两套模型时，建议填写 1600 MB 或更高。
4. 若当前来源已经保存了其他数据，应把这些用量加到模型所需空间上。
5. 如果并不需要模拟配额，可以取消勾选，让 Chrome 使用正常的站点配额策略。

该选项是 DevTools 的调试覆盖项。它会让 Chrome 按填写的 MB 数执行当前来源的配额限制，但不会增加物理磁盘空间，也不能代替正常的浏览器站点数据设置。重新打开浏览器或 DevTools 后，应再次确认该选项是否仍符合预期。

如果这里只设置 281 MB，即使系统磁盘还有很多空间，约 663 MB 的 WebGPU 模型也会在写入一部分后抛出 QuotaExceededError。

首次启用步骤

1. 从博客顶部菜单打开“博客助手”。
2. 页面显示 WebGPU 可用时，点击“下载并启用”。
3. 保持页面打开，等待网络下载、缓存写入和模型初始化全部完成。
4. 状态显示“本地 WebGPU 已就绪”后再发送问题。
5. 如果 WebGPU 失败，先阅读页面给出的原因，再决定是否点击“切换兼容模式”。

首次加载会依次经历不同状态：

检查运行环境
→ 从网络下载文件
→ 写入浏览器缓存
→ 文件已就绪，正在初始化模型
→ 本地模型已就绪

下载进度达到 100% 不代表整个过程已经结束。大文件还需要写入 Cache Storage，ONNX Runtime 也需要创建推理会话。看到最终“已就绪”状态后才能开始对话。

如果页面提示“浏览器缓存不可用，本次仍可运行”，说明模型文件已经交给当前推理会话，但没有完整保存。刷新或下次打开时仍可能重新下载。

如何确认缓存完整

在同一个博客页面打开 DevTools，进入 Application → Cache Storage → transformers-cache。

大权重使用 16 MiB 分块保存，完整缓存通常包含：

• 多条以 __blog_ai_chunk= 结尾的 .onnx_data 分块；
• 原始 .onnx_data URL 对应的一条小型完整性清单；
• config.json、分词器和 ONNX 主文件等条目。

只有分块、没有原始 .onnx_data 清单，表示上次下载或缓存写入没有完整结束。页面不会把这种状态当成可复用的完整模型。

验证缓存复用可以按以下步骤进行：

1. 首次加载到“已就绪”；
2. 刷新同一个来源的 /chat/ 页面；
3. 再次点击启用；
4. 在 Network 面板观察 .onnx_data 是否仍发生数百 MB 的实际传输；
5. 页面按钮应显示“从本地缓存启用”，随后进入初始化。

Network 中出现文件名并不一定代表重新下载，关键要看传输大小和页面缓存状态。若每次都有数百 MB 的实际传输，缓存没有成功复用。

清理损坏或不完整的缓存

配额不足或中途关闭页面后，transformers-cache 中可能保留一部分分块。它们不能组成完整模型，却会继续占用当前来源空间。

需要重新开始时，可以在 Application → Cache Storage 中删除整个 transformers-cache，然后刷新页面重新下载。这个操作会同时删除已经完整缓存的另一种运行模式，因此执行前先确认是否确实需要全部清理。

也可以在 Application → Storage 使用“Clear site data”，但它会清除该来源的更多数据，包括本地存储和会话信息，影响范围更大。

对话功能怎么用

模型就绪后，在输入框中询问博客文章相关问题即可。页面会先检索本站文章，再把相关片段交给本地模型生成回答。

• 回答会逐字显示；
• 开启思考输出后，可以展开查看对应内容；
• 回答下方的引用链接可以跳转到原文；
• 点击停止会保留已经生成的部分；
• 点击重试会使用该问题当时的上下文重新生成；
• 点击清空会删除当前标签页保存的对话记录。

最近 20 条界面消息保存在 sessionStorage。刷新当前标签页可以恢复，关闭标签页后不保证继续存在。问题和回答不会跨浏览器同步。

本地小模型可能出现事实错误，涉及命令、版本、配置值或操作风险时，应打开回答后的原文引用再次核对。

常见问题

每次打开都重新下载 .onnx_data

依次检查：

1. Application → Storage 中的实际配额是否大于模型和已有数据之和；
2. Simulate custom storage quota 是否误设为较小值；
3. transformers-cache 是否有完整清单，而不只是若干分块；
4. Chrome 是否在关闭窗口时删除当前站点数据；
5. 本次访问的协议、域名和端口是否与上次一致。

http://localhost:4000、http://127.0.0.1:4000 和线上 HTTPS 域名是三个不同来源，缓存不能互相复用。

页面显示 QuotaExceededError

这表示 Chrome 拒绝继续向当前来源写入数据。错误中的“已保存字节”和“失败分块”可以帮助判断中断位置。

先增大或取消 DevTools 自定义配额，再检查站点数据策略和磁盘空间。若旧分块占满额度，删除不完整的 transformers-cache 后重新加载。

页面显示约 10 GB 剩余，仍然在 281 MB 左右失败

navigator.storage.estimate() 返回的是估算值，不是一次大文件写入的保证。Chrome 可能模糊报告值，临时或 session-only 来源也可能受到更小的实际限制。以 Application → Storage 的实际用量、缓存写入结果和 QuotaExceededError 为准。

出现 ONNX Runtime 节点分配警告

类似下面的日志通常是性能提示：

Some nodes were not assigned to the preferred execution providers

ONNX Runtime 可能主动把形状计算等节点放到 CPU。只要后面能够完成初始化和生成，不需要把这条警告当作加载失败。

若同时出现明确的 ERROR_CODE、数据类型错误或页面进入失败状态，应以最后一条实际错误为准。当前版本已经处理 q4f16 logits 在采样前转换为 float32 的兼容问题；部署更新后仍出现旧错误时，先重新执行 AI 构建并强制刷新脚本资源。

WebGPU 不可用

页面会检查 WebGPU、显卡适配器和 shader-f16。不满足条件时可以使用 WASM 兼容模式，但首次需要下载约 765 MB 的另一套权重，生成速度通常也更慢。

不要在 WebGPU 权重下载一半时直接切换。先取消当前加载，确认页面回到可操作状态，再点击兼容模式。

普通 HTTP 域名无法使用缓存

生产环境应通过 HTTPS 访问。localhost 是本地开发特例，可以使用 http://localhost:4000；普通 HTTP 域名不属于安全上下文，相关存储或 WebGPU 能力可能不可用。

参考资料

• Chrome DevTools Application 面板
• Chrome DevTools 自定义存储配额
• Chrome DevTools 查看 Cache Storage
• MDN Storage API
• MDN StorageManager
• Hugging Face 模型文件