24MB 搞定语义搜索:runonweb 用 MiniLM 在浏览器本地生成文本嵌入向量

原创2026-11-01 19:23:541,349 阅读

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),把"语义搜索"的最小闭环演示得很直白:

  1. 输入框左侧填一条查询,例如 How do I reset my password?;
  2. 右侧每行填一个候选文本(支持工单、菜谱、函数名等各种语料);
  3. 点击 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 的开发者来说,这大概是成本最低的方案了。

登录后查看全文
runonweb.ai