Turbopuffer Vector 存储

TurbopufferVector 类使用 Turbopuffer 提供 Vector 搜索。Turbopuffer 是一个针对 RAG 应用优化的高性能 Vector 数据库，提供快速的 Vector 相似度搜索、高级过滤功能和高效的存储管理。

构造函数选项

apiKey:

string

用于向 Turbopuffer 进行身份验证的 API key

baseUrl?:

string

= https://api.turbopuffer.com

Turbopuffer API 的基础 URL

connectTimeout?:

number

= 10000

建立连接的超时时间（毫秒）。仅适用于 Node 和 Deno。

connectionIdleTimeout?:

number

= 60000

socket 空闲超时时间（毫秒）。仅适用于 Node 和 Deno。

warmConnections?:

number

= 0

创建新客户端时最初打开的连接数。

compression?:

boolean

= true

是否压缩请求并接受压缩响应。

consistency?:

'strong' | 'eventual'

= strong

查询的默认一致性级别。可为每次查询单独覆盖。"strong" 会以更高延迟为代价，保证查询能看到查询开始前写入的所有数据。"eventual" 延迟更低，但最近写入的数据可能尚不可见。

schemaConfigForIndex?:

function

一个回调函数，接收索引名称并返回该索引的配置对象。你可以为每个索引定义显式 schema。

方法

createIndex()

indexName:

string

要创建的索引名称

dimension:

number

Vector 维度（必须与你的嵌入模型匹配）

metric?:

'cosine' | 'euclidean' | 'dotproduct'

= cosine

用于相似度搜索的距离度量

upsert()

vectors:

number[][]

嵌入 Vector 数组

metadata?:

Record<string, any>[]

每个 Vector 的元数据

ids?:

string[]

可选的 Vector ID（未提供时自动生成）

query()

indexName:

string

要查询的索引名称

queryVector:

number[]

用于查找相似 Vector 的查询 Vector

topK?:

number

= 10

要返回的结果数量

filter?:

Record<string, any>

查询所用的元数据过滤条件

includeVector?:

boolean

= false

是否在结果中包含 Vector

consistency?:

'strong' | 'eventual'

本次查询的一致性级别。会覆盖构造函数中设置的一致性级别。默认为 "strong"。

listIndexes()

以字符串数组形式返回索引名称。

describeIndex()

indexName:

string

要描述的索引名称

返回：

interface IndexStats {
  dimension: number
  count: number
  metric: 'cosine' | 'euclidean' | 'dotproduct'
}

deleteIndex()

indexName:

string

要删除的索引名称

updateVector()

按 ID 或元数据过滤条件更新单个 Vector。必须提供 id 或 filter，但不能同时提供两者。

indexName:

string

包含该 Vector 的索引名称

id?:

string

要更新的 Vector ID（与 filter 互斥）

filter?:

Record<string, any>

用于标识待更新 Vector 的元数据过滤条件（与 id 互斥）

update:

{ vector?: number[]; metadata?: Record<string, any>; }

包含待更新 Vector 和/或元数据的对象

deleteVector()

indexName:

string

包含该 Vector 的索引名称

id:

string

要删除的 Vector ID

deleteVectors()

按 ID 或元数据过滤条件删除多个 Vector。必须提供 ids 或 filter，但不能同时提供两者。

indexName:

string

包含待删除 Vector 的索引名称

ids?:

string[]

要删除的 Vector ID 数组（与 filter 互斥）

filter?:

Record<string, any>

用于标识待删除 Vector 的元数据过滤条件（与 ids 互斥）

响应类型

查询结果以以下格式返回：

interface QueryResult {
  id: string
  score: number
  metadata: Record<string, any>
  vector?: number[] // Only included if includeVector is true
}

Schema 配置

schemaConfigForIndex 选项允许你为不同索引定义显式 schema：

schemaConfigForIndex: (indexName: string) => {
  // Mastra's default embedding model and index for memory messages:
  if (indexName === 'memory_messages_384') {
    return {
      dimensions: 384,
      schema: {
        thread_id: {
          type: 'string',
          filterable: true,
        },
      },
    }
  } else {
    throw new Error(`TODO: add schema for index: ${indexName}`)
  }
}

错误处理

该存储会抛出可捕获的类型化错误：

try {
  await store.query({
    indexName: 'index_name',
    queryVector: queryVector,
  })
} catch (error) {
  if (error instanceof VectorStoreError) {
    console.log(error.code) // 'connection_failed' | 'invalid_dimension' | etc
    console.log(error.details) // Additional error context
  }
}

相关内容

• 元数据过滤器