Skip to content
Storage

使用向量索引

Create, manage, and optimize vector indexes for efficient similarity search.

向量索引会把嵌入按一致的维度和距离度量组织在一个桶里。每个索引都定义了如何在你的向量中进行相似度搜索。

🌐 Vector indexes organize embeddings within a bucket with consistent dimensions and distance metrics. Each index defines how similarity searches are performed across your vectors.

了解向量索引 #

🌐 Understanding vector indexes

索引指定了：

🌐 An index specifies:

  • 索引名称 - 桶内的唯一标识符
  • 维度 - 向量嵌入的大小（例如，OpenAI 为 1536）
  • 距离度量 - 相似度计算方法（余弦、欧几里得或 L2）
  • 数据类型 - 向量格式（目前是 float32）

把索引想象成传统数据库里的一个表。它有一个模式（维度）和一个查询策略（距离度量）。

🌐 Think of an index as a table in a traditional database. It has a schema (dimension) and a query strategy (distance metric).

创建索引 #

🌐 Creating indexes

通过仪表板 #

🌐 Via Dashboard

  1. 在 Supabase 仪表板中打开你的向量桶。
  2. 点击 创建索引。
  3. 输入一个索引名称（例如，documents-openai）。
  4. 设置与你的嵌入向量匹配的维度（例如，对于 OpenAI 的 text-embedding-3-small，使用 1536）。
  5. 选择距离度量（cosine、euclidean 或 l2）。
  6. 点击创建。

通过 SDK #

🌐 Via SDK

1
import { createClient } from '@supabase/supabase-js'
2
3
const supabase = createClient('https://your-project-id.supabase.co', 'your-service-key')
4
5
const bucket = supabase.storage.vectors.from('embeddings')
6
7
// Create an index
8
const { data, error } = await bucket.createIndex({
9
  indexName: 'documents-openai',
10
  dataType: 'float32',
11
  dimension: 1536,
12
  distanceMetric: 'cosine',
13
})
14
15
if (error) {
16
  console.error('Error creating index:', error)
17
} else {
18
  console.log('Index created:', data)
19
}

选择合适的指标 #

🌐 Choosing the right metric

大多数现代嵌入模型在 余弦 距离下表现最好：

🌐 Most modern embedding models work best with cosine distance:

  • OpenAI（text-embedding-3-small, text-embedding-3-large）：余弦
  • Cohere (embed-english-v3.0)：余弦
  • Hugging Face（句子转换器）：余弦
  • 谷歌 (text-embedding-004)：余弦
  • Llama 2 嵌入：余弦相似度或 L2

提示：查看你的嵌入模型文档，了解推荐的距离度量方法。

重要：使用错误的维度创建索引会导致插入和查询操作失败。

管理多个索引 #

🌐 Managing multiple indexes

为不同的用例或嵌入模型创建多个索引：

🌐 Create multiple indexes for different use cases or embedding models:

1
const bucket = supabase.storage.vectors.from('embeddings')
2
3
// Index for OpenAI embeddings
4
await bucket.createIndex({
5
  indexName: 'documents-openai',
6
  dimension: 1536,
7
  distanceMetric: 'cosine',
8
  dataType: 'float32',
9
})
10
11
// Index for Cohere embeddings
12
await bucket.createIndex({
13
  indexName: 'documents-cohere',
14
  dimension: 1024,
15
  distanceMetric: 'cosine',
16
  dataType: 'float32',
17
})
18
19
// Index for different use case
20
await bucket.createIndex({
21
  indexName: 'images-openai',
22
  dimension: 1536,
23
  distanceMetric: 'cosine',
24
  dataType: 'float32',
25
})
26
27
// List all indexes
28
const { data: indexes } = await bucket.listIndexes()
29
console.log('All indexes:', indexes)

多个索引的使用场景 #

🌐 Use cases for multiple indexes

  • 不同的嵌入模型 - 分别存储来自 OpenAI、Cohere 和本地模型的向量
  • 不同的字段 - 为文档、图片、产品等维护单独的索引。
  • A/B 测试 - 并排比较不同的嵌入模型
  • 多语言 - 保持不同语言的嵌入分开

列出并查看索引 #

🌐 Listing and inspecting indexes

列出桶里的所有索引 #

🌐 List all indexes in a bucket

1
const bucket = supabase.storage.vectors.from('embeddings')
2
3
const { data: indexes, error } = await bucket.listIndexes()
4
5
if (!error) {
6
  indexes?.forEach((index) => {
7
    console.log(`Index: ${index.name}`)
8
    console.log(`  Dimension: ${index.dimension}`)
9
    console.log(`  Distance: ${index.distanceMetric}`)
10
  })
11
}

获取索引详情 #

🌐 Get index details

1
const { data: indexDetails, error } = await bucket.getIndex('documents-openai')
2
3
if (!error && indexDetails) {
4
  console.log(`Index: ${indexDetails.name}`)
5
  console.log(`Created at: ${indexDetails.createdAt}`)
6
  console.log(`Dimension: ${indexDetails.dimension}`)
7
  console.log(`Distance metric: ${indexDetails.distanceMetric}`)
8
}

删除索引 #

🌐 Deleting indexes

删除索引以释放存储空间：

🌐 Delete an index to free storage space:

1
const bucket = supabase.storage.vectors.from('embeddings')
2
3
const { error } = await bucket.deleteIndex('documents-openai')
4
5
if (error) {
6
  console.error('Error deleting index:', error)
7
} else {
8
  console.log('Index deleted successfully')
9
}

在删除索引之前 #

🌐 Before deleting an index

警告：删除索引是永久性的，无法撤销。

  • 备份重要数据 - 如有需要，在删除前导出向量
  • 更新应用 - 确保没有代码引用已删除的索引
  • 检查依赖 - 确认没有正在运行的查询使用该索引
  • 计划删除 - 在流量较低的时间进行

不可变属性 #

🌐 Immutable properties

一旦创建，这些属性无法更改：

🌐 Once created, these properties cannot be changed:

  • 维度 - 必须使用不同的维度创建新索引
  • 距离度量 - 创建后无法更改
  • 数据类型 - 目前仅支持 float32

优化索引性能 #

🌐 Optimizing index performance

1
// Good - Appropriate batch size
2
const batch = vectors.slice(0, 250)
3
await index.putVectors({ vectors: batch })
4
5
// Good - Filter metadata before query
6
const { data } = await index.queryVectors({
7
  queryVector,
8
  topK: 5,
9
  filter: { category: 'electronics' },
10
})
11
12
// Avoid - Single vector inserts
13
for (const vector of vectors) {
14
  await index.putVectors({ vectors: [vector] })
15
}
16
17
// Avoid - Returning unnecessary data
18
const { data } = await index.queryVectors({
19
  queryVector,
20
  topK: 1000, // Too many results
21
  returnData: true, // Include large embeddings
22
})

下一步 #

🌐 Next steps