Embeddings - Complete API Reference
Configure embedding providers, manage vector storage, and perform semantic search.
Chat Commands
View Config
/embeddings Show current settings /embeddings status Provider status /embeddings stats Cache statistics
Configure Provider
/embeddings provider openai Use OpenAI embeddings /embeddings provider voyage Use Voyage AI /embeddings provider local Use local model /embeddings model text-embedding-3-small Set model
Cache Management
/embeddings cache stats View cache stats /embeddings cache clear Clear cache /embeddings cache size Total cache size
Testing
/embeddings test "sample text" Generate test embedding /embeddings similarity "text1" "text2" Compare similarity
TypeScript API Reference
Create Embeddings Service
import { createEmbeddingsService } from 'clodds/embeddings';
const embeddings = createEmbeddingsService({ // Provider provider: 'openai', // 'openai' | 'voyage' | 'local' | 'cohere' apiKey: process.env.OPENAI_API_KEY,
// Model model: 'text-embedding-3-small', dimensions: 1536,
// Caching cache: true, cacheBackend: 'sqlite', cachePath: './embeddings-cache.db',
// Batching batchSize: 100, maxConcurrent: 5, });
Generate Embeddings
// Single text
const embedding = await embeddings.embed('Hello world');
console.log(Dimensions: ${embedding.length});
// Multiple texts (batched) const vectors = await embeddings.embedBatch([ 'First document', 'Second document', 'Third document', ]);
Semantic Search
// Search against stored vectors const results = await embeddings.search({ query: 'trading strategies', collection: 'documents', limit: 10, threshold: 0.7, });
for (const result of results) {
console.log(${result.text} (score: ${result.score}));
}
Similarity
// Compare two texts const score = await embeddings.similarity( 'The cat sat on the mat', 'A feline rested on the rug' );
console.log(Similarity: ${score}); // 0.0 - 1.0
Store Vectors
// Store embedding with metadata await embeddings.store({ collection: 'documents', id: 'doc-1', text: 'Original text', embedding: vector, metadata: { source: 'wiki', date: '2024-01-01', }, });
// Store batch await embeddings.storeBatch({ collection: 'documents', items: [ { id: 'doc-1', text: 'First doc' }, { id: 'doc-2', text: 'Second doc' }, ], });
Cache Management
// Get cache stats
const stats = await embeddings.getCacheStats();
console.log(Cached: ${stats.count} embeddings);
console.log(Size: ${stats.sizeMB} MB);
console.log(Hit rate: ${stats.hitRate}%);
// Clear cache await embeddings.clearCache();
// Clear specific entries await embeddings.clearCache({ olderThan: '7d' });
Provider Configuration
// Switch provider embeddings.setProvider('voyage', { apiKey: process.env.VOYAGE_API_KEY, model: 'voyage-large-2', });
// Use local model (Transformers.js) // No API key required - runs locally via @xenova/transformers embeddings.setProvider('local', { model: 'Xenova/all-MiniLM-L6-v2', // 384 dimensions });
Providers
Provider Models Quality Speed Cost
OpenAI text-embedding-3-small/large Excellent Fast $0.02/1M
Voyage voyage-large-2 Excellent Fast $0.02/1M
Cohere embed-english-v3 Good Fast $0.10/1M
Local (Transformers.js) Xenova/all-MiniLM-L6-v2 Good Medium Free
Models
OpenAI
Model Dimensions Best For
text-embedding-3-small
1536 General use
text-embedding-3-large
3072 High accuracy
Voyage
Model Dimensions Best For
voyage-large-2
1024 General use
voyage-code-2
1536 Code search
Use Cases
Semantic Memory Search
// Store user memories await embeddings.store({ collection: 'memories', id: 'mem-1', text: 'User prefers conservative trading', });
// Search memories const relevant = await embeddings.search({ query: 'what is user risk preference', collection: 'memories', limit: 5, });
Document Similarity
// Find similar documents const similar = await embeddings.findSimilar({ text: 'How to trade options', collection: 'docs', limit: 5, });
Best Practices
-
Use caching — Avoid redundant API calls
-
Batch requests — More efficient than single calls
-
Choose dimensions wisely — Balance quality vs storage
-
Monitor costs — Embeddings can add up
-
Local for development — Use local model to save costs