Embeddings - PraisonAI

Generate text embeddings with AI SDK and native fallback providers.

Quick Start

Simple Usage

import { Agent } from 'praisonai';

const agent = new Agent({
  instructions: 'You are a helpful assistant',
  llm: 'openai/gpt-4o-mini'
});

// Embed single text
const embedding = await agent.embed('Hello world');
console.log('Dimensions:', embedding.length); // 1536

// Embed multiple texts
const embeddings = await agent.embed(['Hello', 'World']);
console.log('Count:', embeddings.length); // 2

Direct Embedding API

For more control, use the embedding functions directly:

import { embed, embedMany, createEmbeddingProvider } from 'praisonai';

// Single embedding
const result = await embed('Hello world', {
  model: 'text-embedding-3-small',
  backend: 'ai-sdk' // or 'native' or 'auto'
});
console.log('Embedding:', result.embedding);
console.log('Tokens used:', result.usage?.tokens);

// Batch embeddings
const batchResult = await embedMany(
  ['First text', 'Second text', 'Third text'],
  { model: 'text-embedding-3-large' }
);
console.log('Embeddings:', batchResult.embeddings.length);

Embedding Models

OpenAI Models

Model	Dimensions	Description
`text-embedding-3-small`	1536	Fast, cost-effective (default)
`text-embedding-3-large`	3072	Higher quality
`text-embedding-ada-002`	1536	Legacy model

Google Models

Model	Dimensions	Description
`text-embedding-004`	768	Google embedding

Cohere Models

Model	Dimensions	Description
`embed-english-v3.0`	1024	English optimized
`embed-multilingual-v3.0`	1024	Multilingual support

Integration with Knowledge Base

Use embeddings with the KnowledgeBase for semantic search:

import { Agent, KnowledgeBase, createEmbeddingProvider } from 'praisonai';

// Create embedding provider
const embeddingProvider = createEmbeddingProvider({
  model: 'text-embedding-3-small'
});

// Create knowledge base with embeddings
const kb = new KnowledgeBase({
  embeddingProvider,
  similarityThreshold: 0.7,
  maxResults: 5
});

// Add documents
await kb.add({ id: '1', content: 'PraisonAI is an AI agent framework' });
await kb.add({ id: '2', content: 'Embeddings enable semantic search' });

// Search
const results = await kb.search('What is PraisonAI?');
console.log('Top match:', results[0].document.content);

Integration with Memory

Use embeddings for semantic memory search:

import { Memory, createEmbeddingProvider } from 'praisonai';

const memory = new Memory({
  embeddingProvider: createEmbeddingProvider(),
  maxEntries: 1000
});

// Add memories
await memory.add('User prefers dark mode', 'user');
await memory.add('User is interested in AI', 'user');

// Semantic search
const relevant = await memory.search('What does the user like?');

Backend Selection

PraisonAI automatically selects the best backend:

AI SDK (preferred): When ai package is installed
Native: Falls back to direct OpenAI client

Force Backend

// Force AI SDK
const result = await embed('Hello', { backend: 'ai-sdk' });

// Force native OpenAI
const result = await embed('Hello', { backend: 'native' });

// Auto-select (default)
const result = await embed('Hello', { backend: 'auto' });

Environment Variable

# Force backend globally
export PRAISONAI_BACKEND=ai-sdk  # or 'native' or 'auto'

Similarity Functions

Built-in similarity functions for comparing embeddings:

import { cosineSimilarity, euclideanDistance } from 'praisonai';

const emb1 = await embed('Hello');
const emb2 = await embed('Hi there');

// Cosine similarity (0-1, higher = more similar)
const similarity = cosineSimilarity(emb1.embedding, emb2.embedding);
console.log('Similarity:', similarity); // ~0.9

// Euclidean distance (lower = more similar)
const distance = euclideanDistance(emb1.embedding, emb2.embedding);
console.log('Distance:', distance);

Performance Tips

Batch embeddings: Use embedMany for multiple texts
Cache embeddings: Store embeddings to avoid re-computation
Choose model wisely: text-embedding-3-small is fast and cheap

// Efficient batch processing
const texts = documents.map(d => d.content);
const { embeddings } = await embedMany(texts);

// Store with documents
documents.forEach((doc, i) => {
  doc.embedding = embeddings[i];
});

Error Handling

try {
  const result = await embed('Hello');
} catch (error) {
  if (error.message.includes('API key')) {
    console.error('Missing OPENAI_API_KEY');
  } else if (error.message.includes('not installed')) {
    console.error('Install AI SDK: npm install ai @ai-sdk/openai');
  }
}

TypeScript Types

import type { 
  EmbeddingOptions, 
  EmbeddingResult, 
  EmbeddingBatchResult,
  EmbeddingProvider 
} from 'praisonai';

const options: EmbeddingOptions = {
  model: 'text-embedding-3-small',
  backend: 'auto',
  maxRetries: 2
};

const result: EmbeddingResult = await embed('Hello', options);

Embeddings CLI

Embeddings CLI overview

Knowledge Base

Knowledge Base overview

​Quick Start

​Direct Embedding API

​Embedding Models

​OpenAI Models

​Google Models

​Cohere Models

​Integration with Knowledge Base

​Integration with Memory

​Backend Selection

​Force Backend

​Environment Variable

​Similarity Functions

​Performance Tips

​Error Handling

​TypeScript Types

​Related