---

name: 嵌入向量 description: “向量嵌入配置和语义搜索” emoji: “🧬”

嵌入向量 - 完整API参考

配置嵌入提供商，管理向量存储，并执行语义搜索。

---

聊天命令

查看配置

/嵌入向量                                 显示当前设置
/嵌入向量状态                          提供商状态
/嵌入向量统计                           缓存统计信息

配置提供商

/嵌入向量提供商openai                使用OpenAI嵌入向量
/嵌入向量提供商voyage                使用Voyage AI
/嵌入向量提供商local                 使用本地模型
/嵌入向量模型text-embedding-3-small    设置模型

缓存管理

/嵌入向量缓存统计                     查看缓存统计
/嵌入向量缓存清除                     清除缓存
/嵌入向量缓存大小                      总缓存大小

测试

/嵌入向量测试 "样本文本"              生成测试嵌入向量
/嵌入向量相似性 "文本1" "文本2"      比较相似性

---

TypeScript API参考

创建嵌入向量服务

import { createEmbeddingsService } from 'clodds/embeddings';

const embeddings = createEmbeddingsService({
  // 提供商
  provider: 'openai',  // 'openai' | 'voyage' | 'local' | 'cohere'
  apiKey: process.env.OPENAI_API_KEY,

  // 模型
  model: 'text-embedding-3-small',
  dimensions: 1536,

  // 缓存
  cache: true,
  cacheBackend: 'sqlite',
  cachePath: './embeddings-cache.db',

  // 批处理
  batchSize: 100,
  maxConcurrent: 5,
});

生成嵌入向量

// 单个文本
const embedding = await embeddings.embed('Hello world');
console.log(`维度: ${embedding.length}`);

// 多个文本（批量）
const vectors = await embeddings.embedBatch([
  '第一份文档',
  '第二份文档',
  '第三份文档',
]);

语义搜索

// 根据存储的向量进行搜索
const results = await embeddings.search({
  query: '交易策略',
  collection: 'documents',
  limit: 10,
  threshold: 0.7,
});

for (const result of results) {
  console.log(`${result.text} (得分: ${result.score})`);
}

相似性

// 比较两个文本
const score = await embeddings.similarity(
  '猫坐在垫子上',
  '一只猫躺在地毯上'
);

console.log(`相似度: ${score}`);  // 0.0 - 1.0

存储向量

// 存储带有元数据的嵌入向量
await embeddings.store({
  collection: 'documents',
  id: 'doc-1',
  text: '原始文本',
  embedding: vector,
  metadata: {
    source: 'wiki',
    date: '2024-01-01',
  },
});

// 存储批量
await embeddings.storeBatch({
  collection: 'documents',
  items: [
    { id: 'doc-1', text: '第一份文档' },
    { id: 'doc-2', text: '第二份文档' },
  ],
});

缓存管理

// 获取缓存统计信息
const stats = await embeddings.getCacheStats();
console.log(`缓存: ${stats.count} 嵌入向量`);
console.log(`大小: ${stats.sizeMB} MB`);
console.log(`命中率: ${stats.hitRate}%`);

// 清除缓存
await embeddings.clearCache();

// 清除特定条目
await embeddings.clearCache({ olderThan: '7d' });

提供商配置

// 切换提供商
embeddings.setProvider('voyage', {
  apiKey: process.env.VOYAGE_API_KEY,
  model: 'voyage-large-2',
});

// 使用本地模型（Transformers.js）
// 不需要API密钥 - 通过@xenova/transformers本地运行
embeddings.setProvider('local', {
  model: 'Xenova/all-MiniLM-L6-v2',  // 384维度
});

---

提供商

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

---

模型

OpenAI

模型	维度	最佳用途
text-embedding-3-small	1536	通用
text-embedding-3-large	3072	高精度

Voyage

模型	维度	最佳用途
voyage-large-2	1024	通用
voyage-code-2	1536	代码搜索

---

用例

语义记忆搜索

// 存储用户记忆
await embeddings.store({
  collection: 'memories',
  id: 'mem-1',
  text: '用户偏好保守交易',
});

// 搜索记忆
const relevant = await embeddings.search({
  query: '用户的风向偏好是什么',
  collection: 'memories',
  limit: 5,
});

文档相似性

// 查找相似文档
const similar = await embeddings.findSimilar({
  text: '如何交易期权',
  collection: 'docs',
  limit: 5,
});

---

最佳实践

1. 使用缓存 — 避免冗余的API调用
2. 批量请求 — 比单个调用更有效
3. 明智选择维度 — 平衡质量与存储
4. 监控成本 — 嵌入向量可能会累积
5. 本地开发 — 使用本地模型节省成本