OpenAI CTO

向量存储

Beta

向量存储用于存储文件，以供 file_search 工具使用。

相关指南: 文件搜索

创建向量存储

Beta
创建一个向量存储库。

POST https://api.openai.com/v1/vector_stores

请求体

file_ids

类型：array

可选

一个文件ID列表，向量存储库应该使用。对于工具如file_search，可以访问文件。

name

类型：string

可选

向量存储库的名称。

expires_after

类型：object

可选

向量存储库的过期策略。

duration

类型：integer

要求

过期策略的持续时间，以秒为单位。

metadata

类型：map

可选

可以附加到对象的16个键值对集合。这对于以结构化格式存储有关对象的附加信息非常有用。键最多可以是64个字符长，值最多可以是512个字符长。

返回

一个向量存储库对象。

示例请求

curl https://api.openai.com/v1/vector_stores \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2" \
  -d '{
    "name": "Support FAQ"
  }'

响应

{
  "id": "vs_abc123",
  "object": "vector_store",
  "created_at": 1699061776,
  "name": "Support FAQ",
  "bytes": 139920,
  "file_counts": {
    "in_progress": 0,
    "completed": 3,
    "failed": 0,
    "cancelled": 0,
    "total": 3
  }
}

列表向量存储

Beta
返回向量存储库的列表。

GET https://api.openai.com/v1/vector_stores

查询参数

limit

类型：integer

可选

默认值：20

一个对象返回的限制。限制可以在1到100之间，默认为20。

order

类型：string

可选

默认值：desc

按对象的created_at时间戳排序的顺序。asc表示升序，desc表示降序。

after

类型：string

可选

用于分页的游标。after是一个对象ID，定义了您在列表中的位置。例如，如果您进行列表请求并收到100个对象，以obj_foo结尾，则后续调用可以包含after=obj_foo以获取列表的下一页。

before

类型：string

可选

用于分页的游标。before是一个对象ID，定义了您在列表中的位置。例如，如果您进行列表请求并收到100个对象，以obj_foo结尾，则后续调用可以包含before=obj_foo以获取列表的上一页。

返回

一个向量存储库对象的列表。

示例请求

curl https://api.openai.com/v1/vector_stores \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2"

响应

{
  "object": "list",
  "data": [
    {
      "id": "vs_abc123",
      "object": "vector_store",
      "created_at": 1699061776,
      "name": "Support FAQ",
      "bytes": 139920,
      "file_counts": {
        "in_progress": 0,
        "completed": 3,
        "failed": 0,
        "cancelled": 0,
        "total": 3
      }
    },
    {
      "id": "vs_abc456",
      "object": "vector_store",
      "created_at": 1699061776,
      "name": "Support FAQ v2",
      "bytes": 139920,
      "file_counts": {
        "in_progress": 0,
        "completed": 3,
        "failed": 0,
        "cancelled": 0,
        "total": 3
      }
    }
  ],
  "first_id": "vs_abc123",
  "last_id": "vs_abc456",
  "has_more": false
}

获取向量存储

GET https://api.openai.com/v1/vector_stores/{vector_store_id}

概述

检索指定ID的向量存储。

路径参数

参数名称类型必选描述
vector_store_idstring必须要检索的向量存储的ID。

返回值

返回与指定ID匹配的向量存储对象。

示例请求

curl https://api.openai.com/v1/vector_stores/vs_abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2"

示例响应

{
  "id": "vs_abc123",
  "object": "vector_store",
  "created_at": 1699061776
}

修改向量存储

POST https://api.openai.com/v1/vector_stores/{vector_store_id}

概述

修改指定ID的向量存储。

路径参数

参数名称类型必选描述
vector_store_idstring必须要修改的向量存储的ID。

请求体

参数名称类型必选描述
namestring or null可选向量存储的名称。
expires_afterobject可选向量存储的过期策略。
metadatamap可选一组16个键值对，可以附加到对象上。这对于以结构化格式存储有关对象的附加信息非常有用。键最大长度为64个字符，值最大长度为512个字符。

返回值

返回修改后的向量存储对象。

示例请求

curl https://api.openai.com/v1/vector_stores/vs_abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2" \
  -d '{
    "name": "Support FAQ"
  }'

示例响应

{
  "id": "vs_abc123",
  "object": "vector_store",
  "created_at": 1699061776,
  "name": "Support FAQ",
  "bytes": 139920,
  "file_counts": {
    "in_progress": 0,
    "completed": 3,
    "failed": 0,
    "cancelled": 0,
    "total": 3
  }
}

删除向量存储

DELETE https://api.openai.com/v1/vector_stores/{vector_store_id}

概述

删除指定ID的向量存储。

路径参数

参数名称类型必选描述
vector_store_idstring必须要删除的向量存储的ID。

返回值

返回删除状态。

示例请求

curl https://api.openai.com/v1/vector_stores/vs_abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2" \
  -X DELETE

示例响应

{
  "id": "vs_abc123",
  "object": "vector_store.deleted",
  "deleted": true
}

向量存储对象

向量存储是可以由 file_search 工具使用的已处理文件的集合。

属性

属性名称类型描述
idstring标识符，可以在API端点中引用。
objectstring对象类型，总是 vector_store。
created_atinteger向量存储创建时的Unix时间戳（以秒为单位）。
namestring向量存储的名称。
usage_bytesinteger向量存储中文件使用的总字节数。
file_countsobject文件计数，包括 in_progress、completed、cancelled 和 failed。
statusstring向量存储的状态，可以是 expired、in_progress 或 completed。状态为 completed 表示向量存储已准备好使用。
expires_afterobject向量存储的过期策略。
expires_atinteger or null向量存储过期时的Unix时间戳（以秒为单位）。
last_active_atinteger or null向量存储最后活动的Unix时间戳（以秒为单位）。
metadatamap可以附加到对象的一组16个键值对。这对于以结构化格式存储有关对象的附加信息非常有用。键最大长度为64个字符，值最大长度为512个字符。

示例对象

{
  "id": "vs_123",
  "object": "vector_store",
  "created_at": 1698107661,
  "usage_bytes": 123456,
  "last_active_at": 1698107661,
  "name": "my_vector_store",
  "status": "completed",
  "file_counts": {
    "in_progress": 0,
    "completed": 100,
    "cancelled": 0,
    "failed": 0,
    "total": 100
  },
  "metadata": {},
  "last_used_at": 1698107661
}

Was this page helpful?