24MB 搞定语义搜索:runonweb 用 MiniLM 在浏览器本地生成文本嵌入向量
24MB 搞定语义搜索:runonweb 用 MiniLM 在浏览器本地生成文本嵌入向量
runonweb 是一个开源的浏览器本地 AI SDK,它的 embed 模块内置了经典的小模型 MiniLM,首次使用仅下载约 24MB 的模型权重,就能把文字变成 384 维的向量——无需 API Key、无需后端、无需上传数据,直接在浏览器里完成语义搜索、去重和聚类的核心一步:生成文本嵌入(Text Embedding)。
为什么语义搜索比关键词搜索更好用
传统搜索是"字面匹配":用户搜"忘记密码怎么办",而文档里写的是"重置登录凭据",关键词对不上,就搜不到。
文本嵌入把每段文字映射成一个数字向量,意思越接近的两段文字,向量距离越近。于是:
- "忘记密码怎么办" ↔ "重置登录凭据" → 高相似度(约 0.7)
- "忘记密码怎么办" ↔ "今天天气如何" → 几乎为 0
这一招是语义搜索、相似问题推荐、内容去重、聚类的基础能力。以前它依赖云端 Embedding API(有费用、有延迟、还要把数据传出去);而 runonweb 让这件事完全发生在用户浏览器里。
24MB 的 MiniLM 模型:本地嵌入模型有多大?
embed 模块默认使用 sentence-transformers 家族的 all-MiniLM-L6-v2(Apache-2.0 许可),输出 384 维 向量。模型本体很小:
| 运行后端 | 精度 | 首次下载体积 |
|---|---|---|
| WebGPU(有显卡加速时) | fp16 | 约 46 MB |
| WASM(通用回退) | q8 量化 | 约 23.7 MB |
这也是官方把该功能命名为 "Semantic search in 24 MB" 的由来。实测性能同样友好:WebGPU 下约 14 ms/句,WASM 下约 40 ms/句,属于毫秒级的本地推理。完整的模型体积清单见 MODELS.md。
三步在浏览器生成本地文本嵌入向量
第 1 步:安装
npm install runonweb
第 2 步:把文字变成向量
import { embed, cosineSimilarity } from 'runonweb/embed'
const { embeddings, dimensions } = await embed([
'How do I reset my password?',
'I forgot my login credentials',
'What is the weather today?',
])
// dimensions = 384
第 3 步:用余弦相似度比较"意思"
cosineSimilarity(embeddings[0], embeddings[1]) // ~0.7
cosineSimilarity(embeddings[0], embeddings[2]) // ~0.0
就这么简单。向量默认做了 L2 归一化,所以余弦相似度可以直接理解为"语义接近程度"。如果需要反复嵌入大量文本,建议复用 TextEmbedder 实例并在结束时调用 dispose() 释放显存:
import { TextEmbedder } from 'runonweb/embed'
const embedder = new TextEmbedder()
await embedder.load()
// ... 多次调用 embedder.embed(...)
embedder.dispose()
核心实现只有 200 行左右,入口是 embed/index.ts,包含 TextEmbedder 类、embed() 便捷函数和 cosineSimilarity()。
实战:在浏览器里做语义相似度排序
项目内置了一个演示页(embed.astro),把"语义搜索"的最小闭环演示得很直白:
- 输入框左侧填一条查询,例如
How do I reset my password?; - 右侧每行填一个候选文本(支持工单、菜谱、函数名等各种语料);
- 点击 Rank by similarity,页面会先加载模型,然后把所有候选文本与查询一起嵌入,按相似度从高到低排序展示。
演示脚本见 embed.ts,它正是上文三步流程的完整应用。页面还提供了 Support tickets(客服工单)、Recipes(菜谱匹配)、Code search(按自然语言搜函数)三个一键样例,点一下即可看到 MiniLM 如何理解"意思相近但用词不同"的文本。
顺带一提,嵌入向量不只服务于纯文本:把图片的描述文本(比如用 caption 模块生成的说明)嵌入后,就能实现"用文字搜图片"这类多模态检索,而数据始终留在本地。
模型缓存机制:首次下载,之后免费
runonweb 的模型权重走浏览器原生 Cache Storage,统一存放在 transformers-cache 缓存桶中(见 cache.ts)。也就是说:
- 首次使用
embed时下载约 24MB 权重; - 之后打开同一站点直接命中缓存,无需重复下载;
- 网页自带存储面板可以查看和清理这些本地模型。
适用场景与注意事项
- ✅ 语义搜索 / 相似问题推荐:客服工单去重、知识库检索
- ✅ 聚类与去重:把评论、反馈按含义分组
- ✅ 本地隐私友好:文本不出浏览器,适合处理敏感内容
- ⚠️ 默认模型对英文效果最好;如需多语言,可通过
model参数传入多语言嵌入模型(源码见 embed/index.ts 的EmbedOptions) - ⚠️ WebGPU 下使用 q8 量化会得到错误的相似度,SDK 已自动按后端选择精度(WebGPU 用 fp16、WASM 用 q8),无需手动干预
快速上手小结
| 事项 | 说明 |
|---|---|
| 安装 | npm install runonweb |
| 导入 | import { embed, cosineSimilarity } from 'runonweb/embed' |
| 向量维度 | 384 |
| 体积 | 约 24 MB(WASM)/ 46 MB(WebGPU) |
| 速度 | 14~40 ms/句 |
| 许可 | 模型 Apache-2.0,代码 MIT |
从安装到跑通语义排序,总共不到十行代码。对于想在自己的网页里加"按意思找"功能,又不想接云端 API 的开发者来说,这大概是成本最低的方案了。

