AI Platform

Vector Embeddings

Generate vector embeddings with AxilJS and search them with the built-in VectorStore: cosine, dot and euclidean scores, filters, and JSON persistence.

5 min readUpdated DocumentationEdit this page
On this page12

AxilJS provides an embedding API for converting text into vector embeddings that can be used by TypeScript and Node.js AI applications.

Vector embeddings represent text as numerical vectors, making them useful for semantic search, similarity matching, retrieval-augmented generation (RAG), and other AI workflows.

Generate an Embedding

Use ai.embed() to generate an embedding for a single text input.

TypeScript
TS
1const result = await ai.embed({
2  input: 'What is JavaScript?'
3})
4
5result.embeddings[0] // number[]
6result.model         // embedding model used
7result.usage         // { totalTokens }

The returned embeddings array contains one vector per input. For a single input, the vector is result.embeddings[0].

Generate Multiple Embeddings

input also accepts an array of strings. AxilJS returns one embedding per input, in the same order.

TypeScript
TS
1const result = await ai.embed({
2  input: [
3    'text one',
4    'text two'
5  ]
6})
7
8result.embeddings.length // 2

This is useful when processing documents, batches of text, or multiple records that need to be converted into vectors.

Embedding Options

OptionDescription
inputA string or an array of strings to embed
modelEmbedding model; defaults to the provider's embedding model (see below)
signalAbortSignal that cancels the request and any pending retries
timeoutMsOverall deadline in milliseconds across all retries and batches

Embedding Providers and Default Models

ProviderDefault embedding modelNotes
OpenAIProvidertext-embedding-3-smallOne request per call
GeminiProvidertext-embedding-004Uses batchEmbedContents, 100 texts per request
OllamaProvidernomic-embed-textUses batched /api/embed; falls back to the legacy /api/embeddings on Ollama older than 0.3.4
AnthropicProvidernoneAnthropic has no embeddings API; embed() always throws
TypeScript
TS
1import { OllamaProvider } from '@axiljs/ai'
2
3const embedder = new OllamaProvider()   // http://localhost:11434
4
5const result = await embedder.embed({
6  input: ['first chunk', 'second chunk'],
7  model: 'nomic-embed-text'
8})

Tip

If your application uses Claude for chat, pair AnthropicProvider with OpenAI, Gemini, or Ollama for embeddings. RAGPipeline supports this directly through its embeddingProvider option; see RAG.

Vectors from different models (and usually different providers) have different dimensions and are not comparable. Always embed stored documents and queries with the same model.

Vector Store

VectorStore is an in-memory vector database for similarity search over embeddings.

TypeScript
TS
1import { OpenAIProvider, VectorStore } from '@axiljs/ai'
2
3const ai = new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY! })
4const store = new VectorStore({ metric: 'cosine' })
5
6const texts = ['JavaScript is great', 'Python is also great']
7const { embeddings } = await ai.embed({ input: texts })
8
9await store.add(texts.map((content, i) => ({
10  id: String(i + 1),
11  content,
12  embedding: embeddings[i],
13  metadata: { lang: 'en' }
14})))
15
16const query = await ai.embed({ input: 'Which language is great?' })
17
18const results = await store.search(query.embeddings[0], {
19  topK: 3,
20  minScore: 0.3,
21  filter: { lang: 'en' }
22})
23
24results[0].document.content
25results[0].score

Store Options

OptionDefaultDescription
metric'cosine'Similarity metric: 'cosine', 'dot', or 'euclidean'
maxDocumentsunlimitedWhen exceeded, the oldest documents are removed

Search Options

OptionDefaultDescription
topK5Maximum number of results
minScoreno thresholdDrop results scoring below this value (on the metric's scale)
filternoneOnly match documents whose metadata fields equal these values

VectorStore.search() has no default score threshold: without minScore it returns the top topK documents regardless of score. (RAGPipeline passes its own minScore, default 0.3.)

Similarity Scores

Results are sorted by score, higher meaning more similar. The scale depends on the metric:

Metricscore
cosine (default)Raw cosine similarity, -1 to 1 (1 = same direction, 0 = unrelated, -1 = opposite)
dotRaw dot product (equals cosine for unit-length vectors)
euclidean1 / (1 + distance), 0 to 1 (1 = identical)

All metrics throw on a vector dimension mismatch.

Warning

Changed in 0.3.3: cosine scores are no longer rescaled. Up to 0.3.2 they were reported as (cos + 1) / 2 (0 to 1, with 0.5 meaning unrelated). A threshold t chosen on the old scale corresponds to 2t - 1 now.

Managing Documents

MethodDescription
add(docs) / upsert(docs)Add documents; an existing ID is replaced in place
addOne(doc)Add a single document
get(id)Return a document or null
delete(id)Remove a document; resolves to true if it existed
clear()Remove all documents
getAll()Return all documents
sizeNumber of stored documents

Persistence

TypeScript
TS
1await store.save('./data/vectors.json')              // atomic write, creates directories
2await new VectorStore().load('./data/vectors.json')  // replaces documents, keeps own metric
3
4const copy = VectorStore.fromJSON(store.toJSON())    // keeps metric and maxDocuments

Embeddings over HTTP

aiEmbed() creates a route handler that accepts input (and optionally model) in the request body and responds with embeddings, model, usage, and dimensions.

TypeScript
TS
import { aiEmbed } from '@axiljs/ai'

app.post('/embed', aiEmbed({ provider: ai, model: 'text-embedding-3-small' }))

Embeddings in AI Applications

Embeddings are commonly used as a building block for applications that need to compare the semantic meaning of text.

Typical use cases include:

  • Semantic search
  • Retrieval-augmented generation (RAG)
  • Document retrieval
  • Similarity matching
  • Knowledge-base search
  • Recommendation systems
  • Text clustering
  • Duplicate or related-content detection

A typical RAG workflow uses embeddings to convert document chunks into vectors and later retrieve the most semantically relevant chunks for an AI model.

Text
AxilJS Embedding API
Vector Embedding
VectorStore
Similarity Search
Relevant Context

Was this page helpful?

Help improve the documentation

AxilJS is open source and documentation improvements are welcome.

AxilJS DocumentationMIT License · Built by SyntaxilitY