对象存储
对象存储
对象存储
文档指南
请输入
产品动态
产品公告
产品计费
快速入门
用户指南
存储桶管理
基础设置
容错与容灾
ObjectSet
文件管理
监控与告警
权限配置
IAM 策略管理
典型配置场景
IAM 子用户授权
使用工具及 SDK 的授权说明
接入点
单区域接入点（SRAP）
内容感知与处理（SenseFlow）
TOS Agent
数据处理
分层命名空间（HNS）
TOS Vectors
API 参考
向量桶
SDK 参考
Python-Vectors
向量桶
向量索引
Java-Vectors
向量桶
向量索引
Node.js-Vectors
向量桶
向量索引
工具指南
tosutil
常用命令
辅助命令
TOS Browser
FSX
TOS PyTorch Connector
tosfsspec
API 参考
签名机制
存储桶
桶基础操作
自定义域名
数据处理
媒体处理
视频转码
音频转码
ObjectSet
生命周期
对象
基础操作
分片上传
SDK 参考
Java
存储桶接口
管理桶配置
ObjectSet
对象接口
下载对象
数据处理
视频处理
日志配置
分层命名空间
Python
数据处理
存储桶接口
对象接口
上传对象
C++
存储桶接口
对象接口
Go
对象接口
存储桶接口
管理桶配置
ObjectSet
数据处理
日志配置
Node.js
存储桶接口
对象接口
上传对象
数据处理
Browser.js
上传对象
.NET
对象接口
PHP
对象接口
异常处理
Android
对象接口
iOS
对象接口
Harmony
存储桶接口
对象接口
上传对象
Rust
存储桶接口
桶基础操作
桶清单
自定义域名
对象接口
基础操作
错误码
01-SERVICE_ERROR
02-AUTH
03-ACCESS_CONTROL
04-QOS
05-REQUEST
06-BUCKET
07-LIFECYCLE
08-ACL
09-CORS
10-POLICY
11-MIRROR
12-REPLICATION
13-WEBSITE
14-NOTIFICATION
15-ENCRYPT
16-CUSTOMDOMAIN
17-OBJECT
18-TAG
19-MULTIPART
20-STORAGE_CLASS
21-CALLBACK
22-DATA_PROCESS
23-BATCH
24-STORAGE_LENS
25-INVENTORY
26-DIRECTORY_BUCKET
32-WORM
常见问题
最佳实践
AIGC-豆包大模型最佳实践
校验数据一致性
- 文档首页
对象存储TOS VectorsSDK 参考Python-Vectors向量ListVectors（TOS Vectors Python SDK）
复制全文
下载 pdfListVectors（TOS Vectors Python SDK）
文档反馈
问问助手 IAM 用户 IAM 用户list_vectors 接口用于列举指定集合中的向量数据，本文介绍如何通过 TOS Vectors Python SDK 的 list_vectors 接口获取向量列表。
注意事项
- 您需要根据实际情况，填写示例代码中的地域和访问域名，详细介绍，请参见 地域和访问域名（Endpoint）。
- 为了防止密钥泄露，本文示例代码需要从环境变量中读取 Access Key ID 和 Secret Access Key。因此使用 SDK 前，您需要配置长期访问凭证，详细介绍，请参见 配置长期访问凭证。
- TOS Vectors Python SDK 支持使用临时访问凭证；也支持配置超时机制、重试策略等多种机制，您可以根据业务需求灵活设置，提升应用安全性，详细介绍，请参见 常见配置场景。
- TOS Vectors 底层支持向量 float32 精度，如果传入高于此精度的向量，可能会导致精度损失。
权限说明
主账号默认拥有全部权限，但是 IAM 用户默认没有任何权限。如果您需要使用 IAM 用户执行 list_vectors 操作，主账号需通过 IAM策略和桶策略为该 IAM 用户授予以下权限：tosvectors:ListVectors
代码示例
列举向量基本用法
# 列举向量基本用法
import os
import tos
# 从环境变量获取 AK 和 SK 信息。
ak = os.getenv('TOS_ACCESS_KEY')
sk = os.getenv('TOS_SECRET_KEY')
# your endpoint 填写 Bucket 所在区域对应的 Endpoint，your region 填写对应的区域 Region。# 以华北2(北京)为例，your endpoint 填写 https://tosvectors-cn-beijing.volces.com，your region 填写 cn-beijing。
endpoint = 'Provide your endpoint'
region = 'Provide your region'
vector_bucket_name = 'Provide your bucket name'
account_id = os.getenv('TOS_ACCOUNT_ID')
try:
# 创建 VectorClient 对象，对向量的操作都通过 VectorClient 实现
client = tos.VectorClient(ak, sk, endpoint, region)
# 设置向量索引名称和账号ID
index_name = "test"
# 列举向量并返回数据和元数据
print("\n=== 列举向量（返回数据和元数据）===")
result_with_data = client.list_vectors(
vector_bucket_name=vector_bucket_name,
index_name=index_name,
account_id=account_id,
return_data=True, # 返回向量数据
return_metadata=True # 返回向量元数据
)
print(f"请求ID: {result_with_data.request_id}")
print(f"返回向量数量: {len(result_with_data.vectors)}")
# 打印详细向量信息
if result_with_data.vectors:
vector = result_with_data.vectors[0]
print(f"第一个向量的详细信息:")
print(f" Key: {vector.key}")
if vector.data and vector.data.float32:
print(f" Data长度: {len(vector.data.float32)}")
print(f" Data的值: {vector.data.float32}")
if vector.metadata:
print(f" Metadata: {vector.metadata}")
# 限制返回数量
print("\n=== 限制返回数量 ===")
result_limited = client.list_vectors(
vector_bucket_name=vector_bucket_name,
index_name=index_name,
account_id=account_id,
max_results=3 # 最多返回3条向量
)
print(f"请求ID: {result_limited.request_id}")
print(f"返回向量数量: {len(result_limited.vectors)}")
except tos.exceptions.TosClientError as e:
# 操作失败，捕获客户端异常，一般情况为非法请求参数或网络异常
print('fail with client error, message:{}, cause: {}'.format(e.message, e.cause))
except tos.exceptions.TosServerError as e:
# 操作失败，捕获服务端异常，可从返回信息中获取详细错误信息
print('fail with server error, code: {}'.format(e.code))
# request id 可定位具体问题，强烈建议日志中保存
print('error with request id: {}'.format(e.request_id))
print('error with message: {}'.format(e.message))
print('error with http code: {}'.format(e.status_code))
print('error with ec: {}'.format(e.ec))
print('error with request url: {}'.format(e.request_url))
except Exception as e:
print('fail with unknown error: {}'.format(e))
分页列举向量
# 分页列举向量
import os
import tos
# 从环境变量获取 AK 和 SK 信息。
ak = os.getenv("TOS_ACCESS_KEY")
sk = os.getenv("TOS_SECRET_KEY")
# your endpoint 和 your region 填写Bucket 所在区域对应的Endpoint。# 以华北2(北京)为例，your endpoint 填写 https://tosvectors-cn-beijing.volces.com，your region 填写 cn-beijing。
endpoint = os.getenv("TOS_ENDPOINT")
region = os.getenv("TOS_REGION")
vector_bucket_name = os.getenv("TOS_BUCKET")
try:
# 创建 VectorClient 对象，对向量的操作都通过 VectorClient 实现
client = tos.VectorClient(ak, sk, endpoint, region)
# 设置向量索引名称和账号ID
index_name = "test"
account_id = os.getenv("TOS_ACCOUNT_ID")
# 分页参数设置
page_size = 5 # 每页返回5条向量
all_vectors = [] # 存储所有获取到的向量
page_count = 0 # 页数计数器
print("=== 开始分页列举向量 ===")
# 第一页请求
page_count += 1
print(f"\n--- 第 {page_count} 页 ---")
result = client.list_vectors(
vector_bucket_name=vector_bucket_name,
index_name=index_name,
account_id=account_id,
max_results=page_size, # 每页返回数量
return_data=True, # 返回向量数据
return_metadata=True, # 返回向量元数据
)
print(f"请求ID: {result.request_id}")
print(f"状态码: {result.status_code}")
print(f"本页返回向量数量: {len(result.vectors)}")
# 保存第一页的向量
all_vectors.extend(result.vectors)
# 打印第一页向量的基本信息
for i, vector in enumerate(result.vectors):
print(f"向量 {i+1}: Key={vector.key}")
if vector.data and vector.data.float32:
print(f" Data维度: {len(vector.data.float32)}")
if vector.metadata:
print(f" Metadata: {vector.metadata}")
# 检查是否有下一页
next_token = result.next_token
# 如果存在下一页token，继续获取后续页面
while next_token and len(result.vectors) > 0:
page_count += 1
print(f"\n--- 第 {page_count} 页 ---")
result = client.list_vectors(
vector_bucket_name=vector_bucket_name,
index_name=index_name,
account_id=account_id,
max_results=page_size,
next_token=next_token, # 使用上一页返回的token进行翻页
return_data=True,
return_metadata=True,
)
print(f"请求ID: {result.request_id}")
print(f"本页返回向量数量: {len(result.vectors)}")
# 保存当前页的向量
all_vectors.extend(result.vectors)
# 打印当前页向量的基本信息
for i, vector in enumerate(result.vectors):
print(f"向量 {i+1}: Key={vector.key}")
# 更新next_token，如果为None或返回空结果则停止
next_token = result.next_token
# 如果返回的向量数量少于page_size，说明是最后一页
if len(result.vectors) < page_size:
print("已到达最后一页")
break
# 汇总结果
print(f"\n=== 分页列举完成 ===")
print(f"总页数: {page_count}")
print(f"总向量数量: {len(all_vectors)}")
# 验证向量key的唯一性
vector_keys = [v.key for v in all_vectors]
unique_keys = set(vector_keys)
print(f"唯一向量Key数量: {len(unique_keys)}")
# 展示部分向量的详细信息
if all_vectors:
print(f"\n向量的详细信息:")
for i in range(len(all_vectors)):
vector = all_vectors[i]
print(f"向量 {i+1}:")
print(f" Key: {vector.key}")
if vector.data and vector.data.float32:
print(f" Data长度: {len(vector.data.float32)}")
print(f" Data的值: {vector.data.float32}")
if vector.metadata:
print(f" Metadata: {vector.metadata}")
except tos.exceptions.TosClientError as e:
# 操作失败，捕获客户端异常，一般情况为非法请求参数或网络异常
print("fail with client error, message:{}, cause: {}".format(e.message, e.cause))
except tos.exceptions.TosServerError as e:
# 操作失败，捕获服务端异常，可从返回信息中获取详细错误信息
print("fail with server error, code: {}".format(e.code))
# request id 可定位具体问题，强烈建议日志中保存
print("error with request id: {}".format(e.request_id))
print("error with message: {}".format(e.message))
print("error with http code: {}".format(e.status_code))
print("error with ec: {}".format(e.ec))
print("error with request url: {}".format(e.request_url))
except Exception as e:
print("fail with unknown error: {}".format(e))
相关文档
最近更新时间：2026.09.29 10:36:10
这个页面对您有帮助吗？
有用
有用
无用
无用