Vector Embeddings
Generate vector embeddings with AxilJS and search them with the built-in VectorStore: cosine, dot and euclidean scores, filters, and JSON persistence.
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.
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.
1const result = await ai.embed({
2 input: [
3 'text one',
4 'text two'
5 ]
6})
7
8result.embeddings.length // 2This is useful when processing documents, batches of text, or multiple records that need to be converted into vectors.
Embedding Options
| Option | Description |
|---|---|
input | A string or an array of strings to embed |
model | Embedding model; defaults to the provider's embedding model (see below) |
signal | AbortSignal that cancels the request and any pending retries |
timeoutMs | Overall deadline in milliseconds across all retries and batches |
Embedding Providers and Default Models
| Provider | Default embedding model | Notes |
|---|---|---|
OpenAIProvider | text-embedding-3-small | One request per call |
GeminiProvider | text-embedding-004 | Uses batchEmbedContents, 100 texts per request |
OllamaProvider | nomic-embed-text | Uses batched /api/embed; falls back to the legacy /api/embeddings on Ollama older than 0.3.4 |
AnthropicProvider | none | Anthropic has no embeddings API; embed() always throws |
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.
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].scoreStore Options
| Option | Default | Description |
|---|---|---|
metric | 'cosine' | Similarity metric: 'cosine', 'dot', or 'euclidean' |
maxDocuments | unlimited | When exceeded, the oldest documents are removed |
Search Options
| Option | Default | Description |
|---|---|---|
topK | 5 | Maximum number of results |
minScore | no threshold | Drop results scoring below this value (on the metric's scale) |
filter | none | Only 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:
| Metric | score |
|---|---|
cosine (default) | Raw cosine similarity, -1 to 1 (1 = same direction, 0 = unrelated, -1 = opposite) |
dot | Raw dot product (equals cosine for unit-length vectors) |
euclidean | 1 / (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
| Method | Description |
|---|---|
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 |
size | Number of stored documents |
Persistence
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 maxDocumentsEmbeddings 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.
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.
Was this page helpful?