@brndnjs/create-embedding

@brndnjs/create-embedding

Create text embeddings locally in Node using Google's EmbeddingGemma model via ONNX. No API keys, no network calls after the first model download.

Install

npm install @brndnjs/create-embedding

The model weights (~300MB, q8 quantized) download to your Hugging Face cache on first use and are reused afterward.

Usage

import { createEmbedding } from "@brndnjs/create-embedding";

const doc = await createEmbedding("Mars is known as the Red Planet.");
// { embedding: number[768], modelId: "embedding-gemma-onnx" }

const query = await createEmbedding("Which planet is red?", { kind: "query" });

Embeddings are 768-dimensional and normalized, so cosine similarity is just the dot product:

const similarity = doc.embedding.reduce(
  (sum, value, i) => sum + value * query.embedding[i],
  0,
);

API

createEmbedding(text, options?)

Param	Type	Default	Description
text	string	—	Text to embed.
options.kind	"query" | "document"	"document"	Selects the task prefix (see below).

Returns Promise<{ embedding: number[]; modelId: string }>.

Why kind matters

EmbeddingGemma requires a task-specific prefix on the input, and embedding quality measurably drops without the right one. Use kind: "document" for text you are indexing and kind: "query" for search queries. The two are only directly comparable when each side used its matching prefix.

modelId is always "embedding-gemma-onnx". Persist it alongside stored vectors so you can detect when an embedding was produced by a different model.

License

MIT