@mastra/fastembed

@mastra/fastembed

Local embedding model integration for Mastra, powered by ONNX Runtime.

This package is a maintained fork of fastembed-js (now archived). The upstream source has been vendored directly into this package so that @mastra/fastembed no longer depends on the unmaintained fastembed npm package.

Installation

pnpm add @mastra/fastembed

Usage

Default (AI SDK v3)

import { Memory } from '@mastra/memory';
import { fastembed } from '@mastra/fastembed';

const memory = new Memory({
  // ... other memory options
  embedder: fastembed,
});

Available Models

import { fastembed } from '@mastra/fastembed';

// Default export (bge-small-en-v1.5 with v3 spec)
const embedder = fastembed;

// Named exports for v3 models
const small = fastembed.small; // bge-small-en-v1.5
const base = fastembed.base; // bge-base-en-v1.5

// Multilingual E5 (1024 dimensions), one model per role
const e5Query = fastembed.multilingualE5LargeQuery; // multilingual-e5-large-query
const e5Passage = fastembed.multilingualE5LargePassage; // multilingual-e5-large-passage

// V2 models (for AI SDK v5 compatibility)
const smallV2 = fastembed.smallV2;
const baseV2 = fastembed.baseV2;

// Legacy v1 models (for backwards compatibility)
const smallLegacy = fastembed.smallLegacy; // bge-small-en-v1.5 (v1 spec)
const baseLegacy = fastembed.baseLegacy; // bge-base-en-v1.5 (v1 spec)

Direct Usage with AI SDK

import { embed } from 'ai';
import { fastembed } from '@mastra/fastembed';

const result = await embed({
  model: fastembed,
  value: 'Text to embed',
});

console.log(result.embedding); // number[]

Supported Models

Model	Dimensions	Description
bge-small-en-v1.5	384	Fast, default English model
bge-base-en-v1.5	768	Base English model
bge-small-en	384	Fast English model
bge-base-en	768	Base English model
bge-small-zh-v1.5	512	Fast Chinese model
all-MiniLM-L6-v2	384	Sentence Transformer model
multilingual-e5-large-query	1024	Multilingual model, for embedding search text
multilingual-e5-large-passage	1024	Multilingual model, for embedding indexed text

Using multilingual E5

E5 is asymmetric: it applies a query: prefix to search text and a passage: prefix to indexed text. The two roles are exposed as separate models and must be used as a pair — index your documents with multilingualE5LargePassage and embed searches with multilingualE5LargeQuery. Mixing the roles, or mixing E5 vectors with BGE vectors in one index, silently degrades retrieval quality. The target vector index must be created with 1024 dimensions.

Attribution

The core embedding engine is forked from fastembed-js by Anush008, licensed under MIT. See LICENSE-fastembed for the original license.