存储向量

Insert and update vector embeddings with metadata using the JavaScript SDK or Postgres.

此功能处于测试阶段

预计会有快速变化、功能有限，并可能出现破坏性更新。随着我们改进体验并扩大访问，欢迎分享反馈。

🌐 Expect rapid changes, limited features, and possible breaking updates. Share feedback as we refine the experience and expand access.

一旦你创建了桶和索引，就可以开始存储向量了。向量可以包含可选的元数据，用于在查询时进行过滤和增强。

🌐 Once you've created a bucket and index, you can start storing vectors. Vectors can include optional metadata for filtering and enrichment during queries.

基础向量插入 #

🌐 Basic vector insertion

1
import { createClient } from '@supabase/supabase-js'
2
3
const supabase = createClient('https://your-project-id.supabase.co', 'your-service-key')
4
5
// Get bucket and index
6
const bucket = supabase.storage.vectors.from('embeddings')
7
const index = bucket.index('documents-openai')
8
9
// Insert vectors
10
const { error } = await index.putVectors({
11
  vectors: [
12
    {
13
      key: 'doc-1',
14
      data: {
15
        float32: [0.1, 0.2, 0.3 /* ... rest of embedding ... */],
16
      },
17
      metadata: {
18
        title: 'Getting Started with Vector Buckets',
19
        source: 'documentation',
20
      },
21
    },
22
    {
23
      key: 'doc-2',
24
      data: {
25
        float32: [0.4, 0.5, 0.6 /* ... rest of embedding ... */],
26
      },
27
      metadata: {
28
        title: 'Advanced Vector Search',
29
        source: 'blog',
30
      },
31
    },
32
  ],
33
})
34
35
if (error) {
36
  console.error('Error storing vectors:', error)
37
} else {
38
  console.log('✓ Vectors stored successfully')
39
}

存储来自 Embeddings API 的向量 #

🌐 Storing vectors from Embeddings API

使用大型语言模型 API 生成嵌入并直接存储：

🌐 Generate embeddings using an LLM API and store them directly:

1
import { createClient } from '@supabase/supabase-js'
2
import OpenAI from 'openai'
3
4
const supabase = createClient('https://your-project-id.supabase.co', 'your-service-key')
5
6
const openai = new OpenAI({
7
  apiKey: process.env.OPENAI_API_KEY,
8
})
9
10
// Documents to embed and store
11
const documents = [
12
  { id: '1', title: 'How to Train Your AI', content: 'Guide for training models...' },
13
  { id: '2', title: 'Vector Search Best Practices', content: 'Tips for semantic search...' },
14
  {
15
    id: '3',
16
    title: 'Building RAG Systems',
17
    content: 'Implementing retrieval-augmented generation...',
18
  },
19
]
20
21
// Generate embeddings
22
const embeddings = await openai.embeddings.create({
23
  model: 'text-embedding-3-small',
24
  input: documents.map((doc) => doc.content),
25
})
26
27
// Prepare vectors for storage
28
const vectors = documents.map((doc, index) => ({
29
  key: doc.id,
30
  data: {
31
    float32: embeddings.data[index].embedding,
32
  },
33
  metadata: {
34
    title: doc.title,
35
    source: 'knowledge_base',
36
    created_at: new Date().toISOString(),
37
  },
38
}))
39
40
// Store vectors in batches (max 500 per request)
41
const bucket = supabase.storage.vectors.from('embeddings')
42
const vectorIndex = bucket.index('documents-openai')
43
44
for (let i = 0; i < vectors.length; i += 500) {
45
  const batch = vectors.slice(i, i + 500)
46
  const { error } = await vectorIndex.putVectors({ vectors: batch })
47
48
  if (error) {
49
    console.error(`Error storing batch ${i / 500 + 1}:`, error)
50
  } else {
51
    console.log(`✓ Stored batch ${i / 500 + 1} (${batch.length} vectors)`)
52
  }
53
}

更新向量 #

🌐 Updating vectors

1
const index = bucket.index('documents-openai')
2
3
// Update a vector (same key)
4
const { error } = await index.putVectors({
5
  vectors: [
6
    {
7
      key: 'doc-1',
8
      data: {
9
        float32: [0.15, 0.25, 0.35 /* ... updated embedding ... */],
10
      },
11
      metadata: {
12
        title: 'Getting Started with Vector Buckets - Updated',
13
        updated_at: new Date().toISOString(),
14
      },
15
    },
16
  ],
17
})
18
19
if (!error) {
20
  console.log('✓ Vector updated successfully')
21
}

删除向量 #

🌐 Deleting vectors

1
const index = bucket.index('documents-openai')
2
3
// Delete specific vectors
4
const { error } = await index.deleteVectors({
5
  keys: ['doc-1', 'doc-2'],
6
})
7
8
if (!error) {
9
  console.log('✓ Vectors deleted successfully')
10
}

元数据最佳实践 #

🌐 Metadata best practices

元数据让向量更有用，因为它可以实现过滤和提供上下文：

🌐 Metadata makes vectors more useful by enabling filtering and context:

1
const vectors = [
2
  {
3
    key: 'product-001',
4
    data: { float32: [...] },
5
    metadata: {
6
      product_id: 'prod-001',
7
      category: 'electronics',
8
      price: 299.99,
9
      in_stock: true,
10
      tags: ['laptop', 'portable'],
11
      description: 'High-performance ultrabook'
12
    }
13
  },
14
  {
15
    key: 'product-002',
16
    data: { float32: [...] },
17
    metadata: {
18
      product_id: 'prod-002',
19
      category: 'electronics',
20
      price: 99.99,
21
      in_stock: true,
22
      tags: ['headphones', 'wireless'],
23
      description: 'Noise-cancelling wireless headphones'
24
    }
25
  }
26
]
27
28
const { error } = await index.putVectors({ vectors })

元数据字段指南 #

🌐 Metadata field guidelines

保持轻量 - 查询结果会返回元数据，因此大值会增加响应大小
使用一致的类型 - 在不同向量中使用相同的数据类型存储相同的字段
索引关键字段 - 标记你要筛选的字段以提升查询性能
避免嵌套对象 - 虽然支持，但扁平结构更容易过滤

批量处理大数据集 #

🌐 Batch processing large datasets

为了高效存储大量向量：

🌐 For storing large numbers of vectors efficiently:

1
import { createClient } from '@supabase/supabase-js'
2
import fs from 'fs'
3
4
const supabase = createClient(...)
5
const index = supabase.storage.vectors
6
  .from('embeddings')
7
  .index('documents-openai')
8
9
// Read embeddings from file
10
const embeddingsFile = fs.readFileSync('embeddings.jsonl', 'utf-8')
11
const lines = embeddingsFile.split('\n').filter(line => line.trim())
12
13
const vectors = lines.map((line, idx) => {
14
  const { key, embedding, metadata } = JSON.parse(line)
15
  return {
16
    key,
17
    data: { float32: embedding },
18
    metadata
19
  }
20
})
21
22
// Process in batches
23
const BATCH_SIZE = 500
24
let processed = 0
25
26
for (let i = 0; i < vectors.length; i += BATCH_SIZE) {
27
  const batch = vectors.slice(i, i + BATCH_SIZE)
28
29
  try {
30
    const { error } = await index.putVectors({ vectors: batch })
31
32
    if (error) throw error
33
34
    processed += batch.length
35
    console.log(`Progress: ${processed}/${vectors.length}`)
36
  } catch (error) {
37
    console.error(`Batch failed at offset ${i}:`, error)
38
    // Optionally implement retry logic
39
  }
40
}
41
42
console.log('✓ All vectors stored successfully')

性能优化 #

🌐 Performance optimization

批量操作 #

🌐 Batch operations

为了更好的性能，尽量使用批量操作：

🌐 Always use batch operations for better performance:

1
// ❌ Inefficient - Multiple requests
2
for (const vector of vectors) {
3
  await index.putVectors({ vectors: [vector] })
4
}
5
6
// ✅ Efficient - Single batch operation
7
await index.putVectors({ vectors })

元数据注意事项 #

🌐 Metadata considerations

保持元数据简洁：

🌐 Keep metadata concise:

1
// ❌ Large metadata
2
metadata: {
3
  full_document_text: 'Very long document content...',
4
  detailed_analysis: { /* large object */ }
5
}
6
7
// ✅ Lean metadata
8
metadata: {
9
  doc_id: 'doc-123',
10
  category: 'news',
11
  summary: 'Brief summary'
12
}

下一步 #

🌐 Next steps