embeddings

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Embeddings - Complete API Reference

Embeddings - 完整API参考

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

/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

/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

/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

/embeddings test "sample text"              Generate test embedding
/embeddings similarity "text1" "text2"      Compare similarity

TypeScript API Reference

TypeScript API参考

Create Embeddings Service

创建Embeddings服务

typescript

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,
});

typescript

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

生成嵌入向量

typescript

// 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',
]);

typescript

// 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

语义搜索

typescript

// 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})`);
}

typescript

// 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

相似度对比

typescript

// 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

typescript

// 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

存储向量

typescript

// 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' },
  ],
});

typescript

// 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

缓存管理

typescript

// 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' });

typescript

// 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

提供商配置

typescript

// 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
});

typescript

// 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

提供商	模型	质量	速度	成本
OpenAI	text-embedding-3-small/large	优秀	快速	$0.02/1M
Voyage	voyage-large-2	优秀	快速	$0.02/1M
Cohere	embed-english-v3	良好	快速	$0.10/1M
Local (Transformers.js)	Xenova/all-MiniLM-L6-v2	良好	中等	免费

Models

模型

OpenAI

Model	Dimensions	Best For
`text-embedding-3-small`	1536	General use
`text-embedding-3-large`	3072	High accuracy

模型	维度	适用场景
`text-embedding-3-small`	1536	通用场景
`text-embedding-3-large`	3072	高精度需求

Voyage

Model	Dimensions	Best For
`voyage-large-2`	1024	General use
`voyage-code-2`	1536	Code search

模型	维度	适用场景
`voyage-large-2`	1024	通用场景
`voyage-code-2`	1536	代码搜索

Use Cases

使用场景

Semantic Memory Search

语义记忆搜索

typescript

// 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,
});

typescript

// 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

文档相似度匹配

typescript

// Find similar documents
const similar = await embeddings.findSimilar({
  text: 'How to trade options',
  collection: 'docs',
  limit: 5,
});

typescript

// 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

使用缓存 — 避免重复API调用
批量请求 — 比单个请求更高效
合理选择维度 — 平衡质量与存储成本
监控开销 — 嵌入服务成本可能累积
开发环境使用本地模型 — 使用本地模型节省成本