Mastra FastEmbed 1.x 演进全解本地 Embedding、多语言 E5 模型与模型缓存机制【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastramastra/fastembed是 Mastra 框架中基于 ONNX Runtime 的本地向量化Embedding集成包让 Agent、Memory 与 RAG 工作流可以在不调用任何云端 API 的情况下在本地生成高质量文本向量。本文以该包的CHANGELOG.md见 packages/fastembed/CHANGELOG.md为主线结合 包源码、模型缓存实现 与测试用例系统梳理从 0.0.2 到 1.3.1 的关键演进多语言 E5 模型支持、v1/v2/v3 多版本 AI SDK 兼容、warmup 预下载、模型复用缓存以及供应链安全修复。读完本文你将理解该包的版本设计取舍掌握其在 Memory 与 RAG 场景中的正确用法并能避开向量维度不匹配、并发下载竞态等常见坑。一、包定位本地 Embedding 的标准接入方式mastra/fastembed的定位在 README.md 中写得很明确Local embedding model integration for Mastra, powered by ONNX Runtime。它并非调用远程 Embedding API而是把 ONNX 模型下载到本地通过onnxruntime-node在进程内执行推理。从 package.json 可以确认其核心依赖onnxruntime-node当前锁定 1.26.0本地 ONNX 推理引擎huggingface/hub用于从 Hugging Face 拉取稀疏模型文件anush008/tokenizers分词器Tokenizer运行时tar、progress模型压缩包解压与下载进度展示。该包要求 Node.js22.13.0engines字段这一点对应 1.0.0 版本中Bump minimum required Node.js version to 22.13.0的 Major Change。快速上手npm install mastra/fastembedimport { Memory } from mastra/memory; import { fastembed } from mastra/fastembed; const memory new Memory({ // ... other memory options embedder: fastembed, });当Memory配置了fastembed作为embedder后语义召回semantic recall将完全在本地完成无需配置 OpenAI 等外部 Embedding API。官方文档中关于该用法的详细说明见 docs/src/content/en/docs/memory/semantic-recall.mdx。二、版本脉络一张表看懂 1.x 的关键演进CHANGELOG.md完整记录了从 0.0.2包创建到 1.3.1当前稳定版的全部变更核心节点如下版本类型核心变更1.3.1PatchREADME 更新从 npm 产物中移除 CHANGELOG.md减小包体积1.3.0Minor新增多语言 E5 Large 模型拆分为 Passage / Query 两个角色模型1024 维1.1.3Patcheasy-day-js 供应链事件安全修复发布干净版本并推进latestdist-tag1.1.2Patch修复重复 Embedding 调用重复加载模型的问题改为复用已加载模型1.1.1Patch移除 zod 必选 peer dependency内部 schema 改用纯 JSON Schema1.1.0Minor用自维护的 vendored 实现替换已停止维护的fastembednpm 依赖API 与模型全部不变无需迁移1.0.1Patch依赖升级至fastembed^2.1.0新增warmup()导出预下载模型避免并发下载竞态导致Z_BUF_ERROR1.0.0MajorNode 最低版本提升至 22.13.0升级 AI SDK v5spec v2提供 legacy v1 导出标记为稳定npm 包内嵌文档SKILL.md / SOURCE_MAP.json / 主题文件夹0.10.xPatchESM 声明文件兼容修复、ai4.x依赖升级、mastra/corepeerdeps 修复0.0.2首版基于mastra/core中的默认 embedder 创建独立包默认 embedder 将在破坏性变更中移除三、1.3.0多语言 E5 Large 与角色化 Embedding1.3.0 是 1.x 中功能增量最大的一次 Minor 版本为 FastEmbed 增加了多语言 Embedding 能力。multilingual E5 Large 模型以两个角色化模型的形式开放multilingualE5LargePassage用于入库/索引的文本multilingualE5LargeQuery用于搜索/查询的文本。两者都产出1024 维向量因此使用前必须确保向量索引Vector Store以匹配的维度创建。为什么 E5 要拆成两个模型E5 系列是**非对称asymmetric**模型查询与文档在语义空间中的分布不同必须在输入文本前添加不同的前缀才能获得正确的相似度。源码 packages/fastembed/src/index.ts 中的generatePrefixedEmbeddings清楚地实现了这一点// E5 models are asymmetric: queries and passages must be embedded with different prefixes. async function generatePrefixedEmbeddings( values: string[], modelType: FastEmbedModelType, prefix: query | passage, ) { return generateEmbeddings( values.map(value ${prefix}: ${value}), modelType, ); }在底层两个模型共享同一个 ONNX 模型文件MLE5Large只是通过不同的前缀调用测试 fastembed_mle5large.test.ts 验证了 MLE5Large 的 1024 维输出以及queryEmbed自动加query:前缀与passageEmbed自动加passage:前缀两种方法。在 Memory 中使用多语言模型CHANGELOG 中给出的官方示例import { Memory } from mastra/memory; import { fastembed } from mastra/fastembed; const memory new Memory({ embedder: fastembed.multilingualE5LargePassage, });官方文档 semantic-recall.mdx 进一步给出了最佳实践提示Memory 在存储与召回消息时使用同一个 embedder因此二选一即可multilingualE5LargeQuery只应在你能同时控制索引侧与查询侧的场景中使用——典型场景是 RAG 工作流索引阶段用multilingualE5LargePassage检索阶段用multilingualE5LargeQuery且两侧必须使用同一个模型族否则向量空间不一致会导致检索失效。index.test.ts用测试锁定了这一行为fastembed.multilingualE5LargeQuery.doEmbed({ values: [مرحبا, hello] })会把输入改写成[query: مرحبا, query: hello]再交给MLE5Large模型见 packages/fastembed/src/index.test.ts。四、模型缓存与 warmup从重复加载到并发安全1.1.2模型复用修复1.1.2 修复了一个真实存在的性能问题重复的 Embedding 调用此前会每次都加载一个新模型。现在的实现通过 model-cache.ts 中的getCachedModel完成按模型类型的单例缓存const modelCache new MapFastEmbedModelType, PromiseFlagEmbedding(); export function getCachedModel(modelType: FastEmbedModelType) { let modelPromise modelCache.get(modelType); if (!modelPromise) { modelPromise (async () FlagEmbedding.init({ model: EmbeddingModel[modelType], cacheDir: await getModelCachePath(), }))(); void modelPromise.catch(() { modelCache.delete(modelType); }); modelCache.set(modelType, modelPromise); } return modelPromise; }两个细节值得注意缓存的是 Promise 而非实例并发请求会共享同一个初始化中的 PromisePromise天然具备去重语义同时初始化失败时 Promise 会从缓存中移除允许下次重试。测试 model-cache.test.ts 专门验证了并发请求共享 pending 初始化这一行为。模型文件缓存在用户主目录getModelCachePath返回~/.cache/mastra/fastembed-models见 model-cache.ts首次使用时自动创建目录。1.0.1warmup() 与 Z_BUF_ERROR模型首次使用需要从远程下载压缩包并解压。CHANGELOG 记录了此前的一个隐患多个消费者并行调用FlagEmbedding.init()时会并发下载同一个模型归档可能损坏模型文件并触发Z_BUF_ERRORgzip 解压失败。为此 1.0.1 新增了warmup()导出见 index.ts/** * Pre-download fastembed models without creating ONNX sessions. * Call this before running tests in parallel to avoid concurrent download races. */ export async function warmup() { await warmupFastEmbedModels(); }底层实现 model-cache.ts 调用FlagEmbedding.retrieveModel只下载、不创建 ONNX 会话export async function warmupFastEmbedModels() { const cacheDir await getModelCachePath(); await FlagEmbedding.retrieveModel(EmbeddingModel.BGESmallENV15, cacheDir, false); await FlagEmbedding.retrieveModel(EmbeddingModel.BGEBaseENV15, cacheDir, false); }retrieveModel的下载逻辑见 fastembed.ts本身也有防御性设计模型目录已存在时直接返回避免重复下载下载完成后立即删除.tar.gz临时文件。官方建议在并行测试等场景中先调用warmup()把下载步骤收敛到单线程再进入并发推理阶段。单元测试 model-cache.test.ts 验证了warmup只触发retrieveModel而不会触发init。五、1.1.0从废弃依赖到自维护的 vendored 实现这是 1.x 中最具工程意义的一次 Minor 变更上游fastembed-js项目已归档停止维护1.1.0 将上游源码直接 vendor 进包内mastra/fastembed不再依赖无人维护的fastembednpm 包。源码头部注释完整记录了这一决策见 fastembed.tsForked from fastembed-js (https://github.com/Anush008/fastembed-js) — The upstream project has been archived / abandoned. This fork is maintained as part of the Mastra monorepo so that mastra/fastembed no longer depends on the unmaintained npmfastembedpackage.这次替换对使用者完全透明CHANGELOG 明确说明public API and all embedding models remain unchanged — no migration needed。包内保留了LICENSE-fastembed上游为 MIT 协议以符合开源合规要求。对依赖方而言这消除了一个供应链风险不再通过 npm 间接引入一个无人维护、可能长期不更新安全补丁的传递依赖。当前 package.json 的依赖列表中已经完全没有fastembed取而代之的是onnxruntime-node、huggingface/hub、anush008/tokenizers等受维护的底层库。六、1.0.0AI SDK v5/v6 兼容与稳定化1.0.0 是包从 0.x 走向稳定的里程碑包含三个相互关联的变更1. AI SDK v5specificationVersion v2升级为与mastra/core保持兼容包升级到 AI SDK v5。默认导出改用 v2 规范同时通过fastembed.smallLegacy和fastembed.baseLegacy保留 v1 规范导出用于向后兼容。从 index.ts 可以看到包内部维护了三套 Provider 定义分别对应 AI SDK 的三个规范版本fastEmbedLegacyProviderv1smallLegacy/baseLegacyfastEmbedProviderV2v2smallV2/baseV2fastEmbedProviderV3v3默认的fastembed以及small、base、multilingualE5LargeQuery、multilingualE5LargePassage。最终导出对象通过Object.assign把各版本模型拼装在一起export const fastembed: EmbeddingModelV3 { small: EmbeddingModelV3; base: EmbeddingModelV3; multilingualE5LargeQuery: EmbeddingModelV3; multilingualE5LargePassage: EmbeddingModelV3; smallV2: EmbeddingModelV2string; baseV2: EmbeddingModelV2string; smallLegacy: EmbeddingModelV1string; baseLegacy: EmbeddingModelV1string; } Object.assign(fastEmbedProviderV3.embeddingModel(bge-small-en-v1.5), { ... });这一设计保证了无论下游代码基于哪个 AI SDK 版本编写都能拿到类型匹配的 Embedding 模型。2. AI SDK v6specificationVersion v3支持1.0.0 同时加入了 AI SDK v6 Embedding 模型spec v3支持并修复了一个 TypeScript 类型错误ModelRouterEmbeddingModel此前尝试实现一个联合类型而非直接实现EmbeddingModelV2。3. 内嵌文档Embedded Documentation1.0.0 起发布的 npm 包在dist/docs/下携带内嵌文档使编码 Agent 与 AI 助手可以直接读取node_modules中的文档来理解框架。每个包包含SKILL.md说明包用途与能力的入口文件SOURCE_MAP.json将导出映射到类型与实现文件的机器可读索引主题文件夹按功能领域组织的概念文档。文档通过 MDX frontmatter 中的packages字段关联到对应包CI 校验确保每个文档都包含该字段。4. 其他稳定化变更Node.js 最低版本提升至22.13.0包被标记为stable稳定内嵌 AI 类型以修复 peerdeps 不匹配问题。七、工程化细节安全修复、依赖瘦身与包体积1.1.3供应链安全修复CHANGELOG 记录了针对2026-06-17 easy-day-js 供应链事件的修复通过补丁发布干净版本并把latestdist-tag 前移取代那些声明了恶意easy-day-js依赖的受影响版本。这是包维护者在供应链安全上的主动响应——对使用方而言升级到 1.1.3 及以上版本即可避开受影响版本。1.1.1移除 zod 必选依赖此前 zod 是包的必选 peer dependency1.1.1 将其移除内部 schema 改为使用纯 JSON Schema 对象而非 zod 运行时校验。这既减小了安装体积也降低了与下游 zod 版本v3/v4冲突的可能。1.3.1包体积优化1.3.1 将CHANGELOG.md从发布到 npm 的产物中移除对应 package.json 中files字段只保留dist与LICENSE-fastembed进一步缩减包体积同时更新 README 使其信息准确、及时。八、底层原理FlagEmbedding 如何工作若要深入使用例如自定义模型或稀疏向量检索需要理解 fastembed.ts 中的核心类与枚举。支持的稠密模型与维度EmbeddingModel枚举与listSupportedModels()提供了全部内置稠密模型模型枚举值维度说明BGESmallEN384Fast English modelBGESmallENV15384v1.5默认的快速英文模型BGEBaseEN768Base English modelBGEBaseENV15768v1.5 Base English 模型BGESmallZH512v1.5 中文模型AllMiniLML6V2384Sentence-Transformer MiniLM-L6-v2MLE5Large1024多语言 e5-large非英文内容推荐FlagEmbedding.init 的初始化选项static async init({ model EmbeddingModel.BGESmallENV15, // 默认英文小模型 executionProviders [ExecutionProvider.CPU], // 默认 CPU maxLength 512, // 最大序列长度 cacheDir local_cache, // 模型缓存目录 showDownloadProgress true, // 是否显示下载进度条 modelAbsoluteDirPath , // 自定义模型目录 modelName , // 自定义模型文件名 }: PartialInitOptions {})executionProviders支持ExecutionProvider枚举CPU/CUDA/WebGL/WASM/XNNPACK默认 CPU若选择model: EmbeddingModel.CUSTOM则必须提供modelAbsoluteDirPath与modelName分词器会从模型目录读取tokenizer.json、config.json、tokenizer_config.json、special_tokens_map.json并按config[pad_token_id]配置 padding、按model_max_length截断取maxLength与模型上限的较小值模型文件命名有约定MLE5Large与AllMiniLML6V2使用model.onnx其余模型使用model_optimized.onnx。批量 Embedding 与规范化embed()是异步生成器默认每批 256 条文本分批编码tokenize后拼成int64张量交给 ONNX 会话推理最后对每个向量做L2 归一化见normalize()fastembed.ts第 71-75 行。MLE5Large 模型输入不含token_type_ids源码中做了显式剔除if (this.model EmbeddingModel.MLE5Large) { delete inputs.token_type_ids; }稀疏向量SparseTextEmbedding包还支持稀疏检索模型SparseTextEmbedding内置SpladePPEnV1词表 30522。其推理输出经过SPLADE 后处理log(1 ReLU(logits))只保留正值权重产出{ values, indices }形式的稀疏向量见fastembed.ts第 574-611 行。这一能力与稠密向量配合可用于混合检索场景。九、验证与测试如何确认包行为正确仓库为该包提供了多层测试可作行为契约参考index.test.ts验证 v3 Provider 上注册了角色化多语言模型multilingualE5LargeQuery/multilingualE5LargePassage、前缀应用逻辑、bge 模型不加前缀model-cache.test.ts验证模型复用、并发请求共享初始化、small/base 分离缓存、warmup 不触发 initfastembed_mle5large.test.ts真实模型集成测试包括 init、单条/批量/小批量 embed、queryEmbed、passageEmbed以及hello world 前 10 个维度的规范值断言[0.00961, 0.00443, ...]确保模型输出与预期一致其余fastembed_*.test.tsbge-small / bge-base / bge-small-zh / all-minilm / splade / custom分别覆盖各内置模型与自定义模型路径。包级测试命令为见 package.json# 单元测试 npm test # 真实模型集成测试会下载模型 npm run test:models十、总结与选型建议回顾mastra/fastembed的版本史可以提炼出四条对使用者有价值的经验多语言场景1.3.0处理非英文内容时优先使用multilingualE5LargePassage/multilingualE5LargeQuery牢记二者都是 1024 维向量索引维度需对齐只在能同时控制索引与查询两侧的 RAG 流水线中使用成对模型。并发与初始化1.0.1 / 1.1.2模型首次下载务必通过warmup()预热以避免并发下载竞态运行时getCachedModel会按模型类型复用 ONNX 会话重复调用 Embedding 不会再重复加载模型。版本兼容1.0.0默认导出基于 AI SDK v6spec v3老代码可用smallV2/baseV2v2与smallLegacy/baseLegacyv1平滑过渡。Node.js 需 ≥ 22.13.0。供应链安全1.1.3务必使用 ≥ 1.1.3 的版本避开 easy-day-js 事件影响的旧版本1.1.0 起包已自维护 vendored 实现不再依赖废弃的fastembednpm 包。对于想要深度定制自定义 ONNX 模型、CUDA 推理、SPLADE 稀疏检索的读者fastembed.ts 是首选阅读入口其初始化选项、模型枚举与批量推理逻辑即为包的全部核心行为。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Mastra FastEmbed 1.x 演进全解：本地 Embedding、多语言 E5 模型与模型缓存机制
Mastra FastEmbed 1.x 演进全解本地 Embedding、多语言 E5 模型与模型缓存机制【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastramastra/fastembed是 Mastra 框架中基于 ONNX Runtime 的本地向量化Embedding集成包让 Agent、Memory 与 RAG 工作流可以在不调用任何云端 API 的情况下在本地生成高质量文本向量。本文以该包的CHANGELOG.md见 packages/fastembed/CHANGELOG.md为主线结合 包源码、模型缓存实现 与测试用例系统梳理从 0.0.2 到 1.3.1 的关键演进多语言 E5 模型支持、v1/v2/v3 多版本 AI SDK 兼容、warmup 预下载、模型复用缓存以及供应链安全修复。读完本文你将理解该包的版本设计取舍掌握其在 Memory 与 RAG 场景中的正确用法并能避开向量维度不匹配、并发下载竞态等常见坑。一、包定位本地 Embedding 的标准接入方式mastra/fastembed的定位在 README.md 中写得很明确Local embedding model integration for Mastra, powered by ONNX Runtime。它并非调用远程 Embedding API而是把 ONNX 模型下载到本地通过onnxruntime-node在进程内执行推理。从 package.json 可以确认其核心依赖onnxruntime-node当前锁定 1.26.0本地 ONNX 推理引擎huggingface/hub用于从 Hugging Face 拉取稀疏模型文件anush008/tokenizers分词器Tokenizer运行时tar、progress模型压缩包解压与下载进度展示。该包要求 Node.js22.13.0engines字段这一点对应 1.0.0 版本中Bump minimum required Node.js version to 22.13.0的 Major Change。快速上手npm install mastra/fastembedimport { Memory } from mastra/memory; import { fastembed } from mastra/fastembed; const memory new Memory({ // ... other memory options embedder: fastembed, });当Memory配置了fastembed作为embedder后语义召回semantic recall将完全在本地完成无需配置 OpenAI 等外部 Embedding API。官方文档中关于该用法的详细说明见 docs/src/content/en/docs/memory/semantic-recall.mdx。二、版本脉络一张表看懂 1.x 的关键演进CHANGELOG.md完整记录了从 0.0.2包创建到 1.3.1当前稳定版的全部变更核心节点如下版本类型核心变更1.3.1PatchREADME 更新从 npm 产物中移除 CHANGELOG.md减小包体积1.3.0Minor新增多语言 E5 Large 模型拆分为 Passage / Query 两个角色模型1024 维1.1.3Patcheasy-day-js 供应链事件安全修复发布干净版本并推进latestdist-tag1.1.2Patch修复重复 Embedding 调用重复加载模型的问题改为复用已加载模型1.1.1Patch移除 zod 必选 peer dependency内部 schema 改用纯 JSON Schema1.1.0Minor用自维护的 vendored 实现替换已停止维护的fastembednpm 依赖API 与模型全部不变无需迁移1.0.1Patch依赖升级至fastembed^2.1.0新增warmup()导出预下载模型避免并发下载竞态导致Z_BUF_ERROR1.0.0MajorNode 最低版本提升至 22.13.0升级 AI SDK v5spec v2提供 legacy v1 导出标记为稳定npm 包内嵌文档SKILL.md / SOURCE_MAP.json / 主题文件夹0.10.xPatchESM 声明文件兼容修复、ai4.x依赖升级、mastra/corepeerdeps 修复0.0.2首版基于mastra/core中的默认 embedder 创建独立包默认 embedder 将在破坏性变更中移除三、1.3.0多语言 E5 Large 与角色化 Embedding1.3.0 是 1.x 中功能增量最大的一次 Minor 版本为 FastEmbed 增加了多语言 Embedding 能力。multilingual E5 Large 模型以两个角色化模型的形式开放multilingualE5LargePassage用于入库/索引的文本multilingualE5LargeQuery用于搜索/查询的文本。两者都产出1024 维向量因此使用前必须确保向量索引Vector Store以匹配的维度创建。为什么 E5 要拆成两个模型E5 系列是**非对称asymmetric**模型查询与文档在语义空间中的分布不同必须在输入文本前添加不同的前缀才能获得正确的相似度。源码 packages/fastembed/src/index.ts 中的generatePrefixedEmbeddings清楚地实现了这一点// E5 models are asymmetric: queries and passages must be embedded with different prefixes. async function generatePrefixedEmbeddings( values: string[], modelType: FastEmbedModelType, prefix: query | passage, ) { return generateEmbeddings( values.map(value ${prefix}: ${value}), modelType, ); }在底层两个模型共享同一个 ONNX 模型文件MLE5Large只是通过不同的前缀调用测试 fastembed_mle5large.test.ts 验证了 MLE5Large 的 1024 维输出以及queryEmbed自动加query:前缀与passageEmbed自动加passage:前缀两种方法。在 Memory 中使用多语言模型CHANGELOG 中给出的官方示例import { Memory } from mastra/memory; import { fastembed } from mastra/fastembed; const memory new Memory({ embedder: fastembed.multilingualE5LargePassage, });官方文档 semantic-recall.mdx 进一步给出了最佳实践提示Memory 在存储与召回消息时使用同一个 embedder因此二选一即可multilingualE5LargeQuery只应在你能同时控制索引侧与查询侧的场景中使用——典型场景是 RAG 工作流索引阶段用multilingualE5LargePassage检索阶段用multilingualE5LargeQuery且两侧必须使用同一个模型族否则向量空间不一致会导致检索失效。index.test.ts用测试锁定了这一行为fastembed.multilingualE5LargeQuery.doEmbed({ values: [مرحبا, hello] })会把输入改写成[query: مرحبا, query: hello]再交给MLE5Large模型见 packages/fastembed/src/index.test.ts。四、模型缓存与 warmup从重复加载到并发安全1.1.2模型复用修复1.1.2 修复了一个真实存在的性能问题重复的 Embedding 调用此前会每次都加载一个新模型。现在的实现通过 model-cache.ts 中的getCachedModel完成按模型类型的单例缓存const modelCache new MapFastEmbedModelType, PromiseFlagEmbedding(); export function getCachedModel(modelType: FastEmbedModelType) { let modelPromise modelCache.get(modelType); if (!modelPromise) { modelPromise (async () FlagEmbedding.init({ model: EmbeddingModel[modelType], cacheDir: await getModelCachePath(), }))(); void modelPromise.catch(() { modelCache.delete(modelType); }); modelCache.set(modelType, modelPromise); } return modelPromise; }两个细节值得注意缓存的是 Promise 而非实例并发请求会共享同一个初始化中的 PromisePromise天然具备去重语义同时初始化失败时 Promise 会从缓存中移除允许下次重试。测试 model-cache.test.ts 专门验证了并发请求共享 pending 初始化这一行为。模型文件缓存在用户主目录getModelCachePath返回~/.cache/mastra/fastembed-models见 model-cache.ts首次使用时自动创建目录。1.0.1warmup() 与 Z_BUF_ERROR模型首次使用需要从远程下载压缩包并解压。CHANGELOG 记录了此前的一个隐患多个消费者并行调用FlagEmbedding.init()时会并发下载同一个模型归档可能损坏模型文件并触发Z_BUF_ERRORgzip 解压失败。为此 1.0.1 新增了warmup()导出见 index.ts/** * Pre-download fastembed models without creating ONNX sessions. * Call this before running tests in parallel to avoid concurrent download races. */ export async function warmup() { await warmupFastEmbedModels(); }底层实现 model-cache.ts 调用FlagEmbedding.retrieveModel只下载、不创建 ONNX 会话export async function warmupFastEmbedModels() { const cacheDir await getModelCachePath(); await FlagEmbedding.retrieveModel(EmbeddingModel.BGESmallENV15, cacheDir, false); await FlagEmbedding.retrieveModel(EmbeddingModel.BGEBaseENV15, cacheDir, false); }retrieveModel的下载逻辑见 fastembed.ts本身也有防御性设计模型目录已存在时直接返回避免重复下载下载完成后立即删除.tar.gz临时文件。官方建议在并行测试等场景中先调用warmup()把下载步骤收敛到单线程再进入并发推理阶段。单元测试 model-cache.test.ts 验证了warmup只触发retrieveModel而不会触发init。五、1.1.0从废弃依赖到自维护的 vendored 实现这是 1.x 中最具工程意义的一次 Minor 变更上游fastembed-js项目已归档停止维护1.1.0 将上游源码直接 vendor 进包内mastra/fastembed不再依赖无人维护的fastembednpm 包。源码头部注释完整记录了这一决策见 fastembed.tsForked from fastembed-js (https://github.com/Anush008/fastembed-js) — The upstream project has been archived / abandoned. This fork is maintained as part of the Mastra monorepo so that mastra/fastembed no longer depends on the unmaintained npmfastembedpackage.这次替换对使用者完全透明CHANGELOG 明确说明public API and all embedding models remain unchanged — no migration needed。包内保留了LICENSE-fastembed上游为 MIT 协议以符合开源合规要求。对依赖方而言这消除了一个供应链风险不再通过 npm 间接引入一个无人维护、可能长期不更新安全补丁的传递依赖。当前 package.json 的依赖列表中已经完全没有fastembed取而代之的是onnxruntime-node、huggingface/hub、anush008/tokenizers等受维护的底层库。六、1.0.0AI SDK v5/v6 兼容与稳定化1.0.0 是包从 0.x 走向稳定的里程碑包含三个相互关联的变更1. AI SDK v5specificationVersion v2升级为与mastra/core保持兼容包升级到 AI SDK v5。默认导出改用 v2 规范同时通过fastembed.smallLegacy和fastembed.baseLegacy保留 v1 规范导出用于向后兼容。从 index.ts 可以看到包内部维护了三套 Provider 定义分别对应 AI SDK 的三个规范版本fastEmbedLegacyProviderv1smallLegacy/baseLegacyfastEmbedProviderV2v2smallV2/baseV2fastEmbedProviderV3v3默认的fastembed以及small、base、multilingualE5LargeQuery、multilingualE5LargePassage。最终导出对象通过Object.assign把各版本模型拼装在一起export const fastembed: EmbeddingModelV3 { small: EmbeddingModelV3; base: EmbeddingModelV3; multilingualE5LargeQuery: EmbeddingModelV3; multilingualE5LargePassage: EmbeddingModelV3; smallV2: EmbeddingModelV2string; baseV2: EmbeddingModelV2string; smallLegacy: EmbeddingModelV1string; baseLegacy: EmbeddingModelV1string; } Object.assign(fastEmbedProviderV3.embeddingModel(bge-small-en-v1.5), { ... });这一设计保证了无论下游代码基于哪个 AI SDK 版本编写都能拿到类型匹配的 Embedding 模型。2. AI SDK v6specificationVersion v3支持1.0.0 同时加入了 AI SDK v6 Embedding 模型spec v3支持并修复了一个 TypeScript 类型错误ModelRouterEmbeddingModel此前尝试实现一个联合类型而非直接实现EmbeddingModelV2。3. 内嵌文档Embedded Documentation1.0.0 起发布的 npm 包在dist/docs/下携带内嵌文档使编码 Agent 与 AI 助手可以直接读取node_modules中的文档来理解框架。每个包包含SKILL.md说明包用途与能力的入口文件SOURCE_MAP.json将导出映射到类型与实现文件的机器可读索引主题文件夹按功能领域组织的概念文档。文档通过 MDX frontmatter 中的packages字段关联到对应包CI 校验确保每个文档都包含该字段。4. 其他稳定化变更Node.js 最低版本提升至22.13.0包被标记为stable稳定内嵌 AI 类型以修复 peerdeps 不匹配问题。七、工程化细节安全修复、依赖瘦身与包体积1.1.3供应链安全修复CHANGELOG 记录了针对2026-06-17 easy-day-js 供应链事件的修复通过补丁发布干净版本并把latestdist-tag 前移取代那些声明了恶意easy-day-js依赖的受影响版本。这是包维护者在供应链安全上的主动响应——对使用方而言升级到 1.1.3 及以上版本即可避开受影响版本。1.1.1移除 zod 必选依赖此前 zod 是包的必选 peer dependency1.1.1 将其移除内部 schema 改为使用纯 JSON Schema 对象而非 zod 运行时校验。这既减小了安装体积也降低了与下游 zod 版本v3/v4冲突的可能。1.3.1包体积优化1.3.1 将CHANGELOG.md从发布到 npm 的产物中移除对应 package.json 中files字段只保留dist与LICENSE-fastembed进一步缩减包体积同时更新 README 使其信息准确、及时。八、底层原理FlagEmbedding 如何工作若要深入使用例如自定义模型或稀疏向量检索需要理解 fastembed.ts 中的核心类与枚举。支持的稠密模型与维度EmbeddingModel枚举与listSupportedModels()提供了全部内置稠密模型模型枚举值维度说明BGESmallEN384Fast English modelBGESmallENV15384v1.5默认的快速英文模型BGEBaseEN768Base English modelBGEBaseENV15768v1.5 Base English 模型BGESmallZH512v1.5 中文模型AllMiniLML6V2384Sentence-Transformer MiniLM-L6-v2MLE5Large1024多语言 e5-large非英文内容推荐FlagEmbedding.init 的初始化选项static async init({ model EmbeddingModel.BGESmallENV15, // 默认英文小模型 executionProviders [ExecutionProvider.CPU], // 默认 CPU maxLength 512, // 最大序列长度 cacheDir local_cache, // 模型缓存目录 showDownloadProgress true, // 是否显示下载进度条 modelAbsoluteDirPath , // 自定义模型目录 modelName , // 自定义模型文件名 }: PartialInitOptions {})executionProviders支持ExecutionProvider枚举CPU/CUDA/WebGL/WASM/XNNPACK默认 CPU若选择model: EmbeddingModel.CUSTOM则必须提供modelAbsoluteDirPath与modelName分词器会从模型目录读取tokenizer.json、config.json、tokenizer_config.json、special_tokens_map.json并按config[pad_token_id]配置 padding、按model_max_length截断取maxLength与模型上限的较小值模型文件命名有约定MLE5Large与AllMiniLML6V2使用model.onnx其余模型使用model_optimized.onnx。批量 Embedding 与规范化embed()是异步生成器默认每批 256 条文本分批编码tokenize后拼成int64张量交给 ONNX 会话推理最后对每个向量做L2 归一化见normalize()fastembed.ts第 71-75 行。MLE5Large 模型输入不含token_type_ids源码中做了显式剔除if (this.model EmbeddingModel.MLE5Large) { delete inputs.token_type_ids; }稀疏向量SparseTextEmbedding包还支持稀疏检索模型SparseTextEmbedding内置SpladePPEnV1词表 30522。其推理输出经过SPLADE 后处理log(1 ReLU(logits))只保留正值权重产出{ values, indices }形式的稀疏向量见fastembed.ts第 574-611 行。这一能力与稠密向量配合可用于混合检索场景。九、验证与测试如何确认包行为正确仓库为该包提供了多层测试可作行为契约参考index.test.ts验证 v3 Provider 上注册了角色化多语言模型multilingualE5LargeQuery/multilingualE5LargePassage、前缀应用逻辑、bge 模型不加前缀model-cache.test.ts验证模型复用、并发请求共享初始化、small/base 分离缓存、warmup 不触发 initfastembed_mle5large.test.ts真实模型集成测试包括 init、单条/批量/小批量 embed、queryEmbed、passageEmbed以及hello world 前 10 个维度的规范值断言[0.00961, 0.00443, ...]确保模型输出与预期一致其余fastembed_*.test.tsbge-small / bge-base / bge-small-zh / all-minilm / splade / custom分别覆盖各内置模型与自定义模型路径。包级测试命令为见 package.json# 单元测试 npm test # 真实模型集成测试会下载模型 npm run test:models十、总结与选型建议回顾mastra/fastembed的版本史可以提炼出四条对使用者有价值的经验多语言场景1.3.0处理非英文内容时优先使用multilingualE5LargePassage/multilingualE5LargeQuery牢记二者都是 1024 维向量索引维度需对齐只在能同时控制索引与查询两侧的 RAG 流水线中使用成对模型。并发与初始化1.0.1 / 1.1.2模型首次下载务必通过warmup()预热以避免并发下载竞态运行时getCachedModel会按模型类型复用 ONNX 会话重复调用 Embedding 不会再重复加载模型。版本兼容1.0.0默认导出基于 AI SDK v6spec v3老代码可用smallV2/baseV2v2与smallLegacy/baseLegacyv1平滑过渡。Node.js 需 ≥ 22.13.0。供应链安全1.1.3务必使用 ≥ 1.1.3 的版本避开 easy-day-js 事件影响的旧版本1.1.0 起包已自维护 vendored 实现不再依赖废弃的fastembednpm 包。对于想要深度定制自定义 ONNX 模型、CUDA 推理、SPLADE 稀疏检索的读者fastembed.ts 是首选阅读入口其初始化选项、模型枚举与批量推理逻辑即为包的全部核心行为。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考