fastembed review
Pinning fastembed 3.0.0 does not pin its downloaded model files. This npm package turns text into vectors in Node.js using ONNX Runtime. Its dense API supports batch embedding, query and passage helpers, and custom local model files. This guide covers npm fastembed, distinct from Python FastEmbed. Your application still owns document IDs, vector storage and search. The examples illustrate the supplied implementation; they were not executed.
Consider fastembed for a Node embedding worker when you can own the model files and validate inference in your deployment image. Before building an index, run a small passage-and-query fixture and record the model artifacts, preprocessing and observed output dimensions.
Answers from our run
fastembed or @huggingface/transformers: which should you use?
@huggingface/transformers: Consider @huggingface/transformers for browser inference. Its registry description says it runs Transformers directly in the browser; validate your chosen model and deployment separately. Consider fastembed for a Node embedding worker when you can own the model files and validate inference in your deployment image.
When should you not use fastembed?
You need browser inference. This package depends on onnxruntime-node and loads model files through Node filesystem APIs.
Use it if
- Your Node service needs local text vectors and you can deploy ONNX Runtime and the required model files.
- You want to consume output batches with for await.
- You can evaluate a specific model and record its artifacts alongside your stored vectors.
- You need an explicit model cache directory for a worker or container.
- You need browser inference. This package depends on onnxruntime-node and loads model files through Node filesystem APIs.
- You need training or a complete search service. The examples here cover inference and application-owned scoring.
- Your deployment cannot download model files and you cannot supply compatible local files.
- You require latency, memory or GPU compatibility measurements before choosing a dependency. None are supplied here.
Setup reality
Install the exact package with npm install --save-exact fastembed@3.0.0 and commit the lockfile. The published package depends on onnxruntime-node 1.21.0 and @anush008/tokenizers. Validate installation and an embedding call in your deployment image. This review inspected the supplied registry record and the source commit identified by its gitHead. It did not inspect the published archive, install the runtime, download weights, execute the examples or benchmark retrieval quality. Bundle size was not assessed.
Dense initialization defaults to BGESmallENV15, CPU execution, local_cache and a maximum length of 512 tokens. Set the model and cache directory explicitly. Initialization retrieves the model and tokenizer/configuration files before creating the inference session. Existing destination files are skipped. The dense downloader requests Hugging Face resolve/main paths. Pinning the npm package therefore does not freeze the downloaded model revision. Preserve reviewed model artifacts separately when reproducibility matters.
Custom dense initialization requires modelAbsoluteDirPath and modelName. Use an absolute deployment path containing the ONNX file, tokenizer.json, config.json, tokenizer_config.json and special_tokens_map.json. Choose the pooling method required by that model. The implementation supplies input_ids, attention_mask and token_type_ids for custom models and reads last_hidden_state from the output. Supplying a directory does not establish model compatibility.
passageEmbed() adds a passage: prefix to every input; queryEmbed() adds query: and returns one vector. Supply unprefixed text to those helpers. embed() yields normalized vector batches without adding either prefix. The tokenizer uses the smaller of maxLength and its configured model_max_length, so split long documents deliberately. Keep model artifacts and preprocessing consistent between indexed passages and queries.
The scores use a documentation-based 1-5 rubric. A 1 means the supplied evidence gives little usable support; 2 means a partial path with substantial gaps; 3 means a documented path with concrete limits; 4 requires broader corroboration for the dimension; 5 requires comprehensive evidence. API stability considers the exposed contract, not just types. Documentation quality considers whether that contract and its limits are explained. Maintenance considers shipped changes and continuity evidence. Ecosystem considers distribution and documented integration paths. A score of 3 here is a limited editorial assessment, not measured reliability, adoption or compatibility. npm reports 104,506 downloads for November 4-10, 2026. Downloads do not identify unique users or successful deployments.
Patterns
Initialize an explicit CPU model initialize-dense-model
import { EmbeddingModel, ExecutionProvider, FlagEmbedding } from 'fastembed'
const model = await FlagEmbedding.init({
model: EmbeddingModel.BGESmallENV15,
executionProviders: [ExecutionProvider.CPU],
cacheDir: '/tmp/fastembed-models',
showDownloadProgress: false,
})Unexecuted source-based illustration for Node ES modules with fastembed 3.0.0 installed. Run the following dense examples after this initialization. The cache path is a trial location; choose a deployment cache lifecycle deliberately. Disabling progress does not disable downloads.
Consume raw text batches embed-plain-text
const texts = ['Replace the toner cartridge.', 'Clear the paper tray.']
for await (const batch of model.embed(texts, 2)) {
console.log(batch)
}embed() yields number[][] batches and normalizes the dense outputs. It adds no retrieval prefixes. The last batch can contain fewer items than the requested batch size. This illustration was not executed.
Encode passages without manual prefixes embed-passages
const passages = ['The tray holds plain paper.', 'Toner produces the printed image.']
const vectors = []
for await (const batch of model.passageEmbed(passages, 2)) {
vectors.push(...batch)
}passageEmbed() prepends passage: to each input before calling embed(). Supply unprefixed text. This example collects every vector in memory for the small ranking fixture below; it was not executed.
Encode one query embed-query
const query = await model.queryEmbed('What makes the printed image?')
console.log(query.length)queryEmbed() prepends query: and returns a Promise resolving to one number[]. Use it after initializing model. Neither this unexecuted example nor the helper name establishes retrieval quality.
Rank the small passage fixture rank-small-fixture
const ranked = vectors.map((vector, index) => {
if (vector.length !== query.length) throw new Error('Dimension mismatch')
const score = vector.reduce((sum, value, i) => sum + value * query[i], 0)
return { text: passages[index], score }
}).sort((a, b) => b.score - a.score)
console.log(ranked)Run after the passage and query examples in the same scope. This application code computes dot products over the normalized dense outputs and scans every supplied vector. It is not a fastembed search API, an executed test or evidence of a particular ranking.
Validate the batch size bound-inference-batches
const batchSize = 8
if (!Number.isInteger(batchSize) || batchSize < 1) {
throw new Error('batchSize must be a positive integer')
}
for await (const batch of model.embed(texts, batchSize)) {
console.log(batch.length)
}Uses model and texts from the earlier examples. The implementation advances its loop by batchSize without validating that argument. A positive integer avoids an invalid batch or a nonadvancing loop. The default is 256; no memory measurement supports recommending a particular size. This guard was not executed.
Set a truncation limit set-token-limit
const shortModel = await FlagEmbedding.init({
model: EmbeddingModel.BGESmallENV15,
cacheDir: '/tmp/fastembed-models',
maxLength: 256,
})Uses the imports from the initialization example. The tokenizer takes the smaller of maxLength and its configured model_max_length. This is a token limit, not a character limit. It creates another session rather than changing model. The example was not executed.
Configure compatible local model files load-custom-dense-model
import { Pooling } from 'fastembed'
const localModel = await FlagEmbedding.init({
model: EmbeddingModel.CUSTOM,
modelAbsoluteDirPath: '/opt/models/reviewed-encoder',
modelName: 'model.onnx',
pooling: Pooling.Mean,
})Uses FlagEmbedding and EmbeddingModel from the first example. The directory and filename are placeholders, not supplied model artifacts. Supply the four configuration/tokenizer files listed above and a model accepting input_ids, attention_mask and token_type_ids with a compatible last_hidden_state output. Mean pooling is an illustrative choice. No compatible custom model or executed result is claimed.
Read catalog dimensions inspect-model-dimensions
const catalog = model.listSupportedModels()
const selected = catalog.find(item => item.model === EmbeddingModel.BGESmallENV15)
console.log(selected?.dim)Uses the initialized model and earlier imports. The instance method returns a built-in catalog, not an inspection of the loaded weights. Verify actual output dimensions before creating an index, especially for a custom model. This illustration was not executed.
Alternatives
| Package | Registry | Pick it when |
|---|---|---|
| @huggingface/transformers | npm | Consider @huggingface/transformers for browser inference. Its registry description says it runs Transformers directly in the browser; validate your chosen model and deployment separately. |
| openai | npm | Consider openai if you want the official TypeScript library for the OpenAI API. This is an API-client alternative to operating the local runtime; the supplied evidence does not establish model quality, latency or cost comparisons. |
More ai / ml guides
@types/node · openai · @modelcontextprotocol/sdk · mcp · huggingface-hub · @anthropic-ai/sdk · the whole shelf →
How this guide is made: grounded in the library's documentation, release notes, changelog, and issue history, on a fixed rubric — not a hands-on install of every release. The 50 most-downloaded entries are additionally install-verified in clean containers. Corrections: contact the desk.