对象存储
对象存储
对象存储
文档指南
请输入
产品动态
产品公告
产品计费
快速入门
用户指南
存储桶管理
基础设置
容错与容灾
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初始化客户端（TOS Vectors Python SDK） 
复制全文
下载 pdf初始化客户端（TOS Vectors Python SDK）
文档反馈
问问助手TOSVectorClient 提供了一系列接口用与 TOS 服务进行交互，以管理存储桶和对象等 TOS 服务上的资源。可通过AccessKey/SecretKey、STS (Security Token Service）等方式初始化 TOSVectorClient。在初始化时，可设置建立连接超时时间、超时重试次数和最大空闲连接数量等可选参数。本文介绍如何初始化 TOS Vectors Python SDK。
前提条件
注意事项
单进程多线程场景建议使用一个 VectorClient，避免重复初始化 VectorClient；多进程场景下需要创建多个 VectorClient，不能共享同一个 VectorClient，否则会有多进程并发安全问题，可能会导致读写请求数据错乱。
配置长期访问凭证
初始化 SDK 前，您需要先配置长期访问凭证。本章节介绍不同操作系统下配置长期访问凭证的操作步骤。
macOS
Linux
Windows
- 打开终端并执行以下命令打开文件。
nano ~/.bash_profile
- 在文件末尾添加 AKSK 信息。
export TOS_ACCESS_KEY=AKTPYmI1Z****
export TOS_SECRET_KEY=T1dJM01UU****
- 保存文件并退出。
- 执行以下命令生效配置信息。
source ~/.bash_profile
- 执行以下命令验证配置信息。
echo $TOS_ACCESS_KEY
echo $TOS_SECRET_KEY
如果配置成功，则返回如下示例：
AKTPYmI1Z****
T1dJM01UU****
- 打开终端并执行以下命令打开文件。
sudo vim /etc/profile
- 在文件末尾添加 AKSK 信息。
export TOS_ACCESS_KEY=AKTPYmI1Z****
export TOS_SECRET_KEY=T1dJM01UU****
- 保存文件并退出。
- 执行以下命令生效配置信息。
source /etc/profile
- 执行以下命令验证配置信息。
echo $TOS_ACCESS_KEY
echo $TOS_SECRET_KEY
如果配置成功，则返回如下示例：
AKTPYmI1Z****
T1dJM01UU****
- 打开命令行工具，执行以下命令，添加 AKSK 信息。
set TOS_ACCESS_KEY=AKTPYmI1Z****
set TOS_SECRET_KEY=T1dJM01UU****
- 执行以下命令生效配置信息。
setx TOS_ACCESS_KEY "%TOS_ACCESS_KEY%"
setx TOS_SECRET_KEY "%TOS_SECRET_KEY%"
- 重启命令行工具，然后执行以下命令验证配置信息。
echo %TOS_ACCESS_KEY%
echo %TOS_SECRET_KEY%
如果配置成功，则返回如下示例：
AKTPYmI1Z****
T1dJM01UU****
创建 VectorClient
使用必选参数初始化
以下代码用于使用 TOS 域名初始化。
说明
- Endpoint 为 TOS Vectors 对外服务的访问域名。TOS Vectors 支持的 Endpoint 信息，请参见地域和访问域名（Endpoint）。
- AKSK 信息可从环境变量获取，配置方式，请参见 配置长期访问凭证。
import os
import tos
# 从环境变量获取 AKSK 信息
ak = os.getenv('TOS_ACCESS_KEY')
sk = os.getenv('TOS_SECRET_KEY')
# your endpoint 和 your region 填写Bucket 所在区域对应的Endpoint。# 以华北2(北京)为例，your endpoint 填写 tosvectors-cn-beijing.volces.com，your region 填写 cn-beijing。
endpoint = "your endpoint"
region = "your region"
client = tos.VectorClient(ak, sk, endpoint, region)
使用可选参数
以下代码用于使用可选参数初始化。
import tos
import os
# ak和sk为临时访问凭证中的安全密钥（AccessKeyId、SecretAccessKey）
ak = os.getenv('TOS_ACCESS_KEY')
sk = os.getenv('TOS_SECRET_KEY')
sts_token = "your security token"
# your endpoint 和 your region 填写Bucket 所在区域对应的Endpoint。# 以华北2(北京)为例，your endpoint 填写 tosvectors-cn-beijing.volces.com，your region 填写 cn-beijing。
endpoint = "your endpoint"
region = "your region"
# 使用临时访问凭证中的认证信息初始化TosClient
client = tos.VectorClient(ak, sk, endpoint, region,
# 通过security_token可选参数设置STS
security_token=sts_token,
# 通过connection_time可选参数设置连接超时，单位：秒
connection_time=10,
# 通过socket_timeout可选参数设置Socket读写超时，单位：秒
socket_timeout=30)
常见配置场景
配置 STS
您可以通过 STS 服务向其他用户颁发临时访问凭证，在凭证有效期内，用户可访问您的 TOS Vectors 资源，而无需透露您的长期密钥，保障您 TOS Vectors 资源的安全性。
说明
您可以通过 STS 服务的 AssumeRole 接口获取临时访问凭证，临时访问凭证中包含安全密钥（AccessKeyId、SecretAccessKey）和安全令牌（SessionToken），后续您可以使用该信息访问 TOS Vectors 服务。关于搭建 STS 服务的基本操作，请参见 使用 STS 临时 AK/SK+Token 访问火山引擎 TOS。
以下代码用于使用 STS 初始化。
import os
import tos
# ak和sk为临时访问凭证中的安全密钥（AccessKeyId、SecretAccessKey）
ak = "your access key"
sk = "your secret key"
# sts_token为临时访问凭证中的安全令牌（SessionToken）
sts_token = "your security token"
# your endpoint 和 your region 填写Bucket 所在区域对应的Endpoint。# 以华北2(北京)为例，your endpoint 填写 tos-cn-beijing.volces.com，your region 填写 cn-beijing。
endpoint = "your endpoint"
region = "your region"
# 使用临时访问凭证中的认证信息初始化TosClient
client = tos.VectorClient(ak, sk, endpoint, region, security_token=sts_token)
配置超时机制
您可以在初始化 VectorClient 时，通过添加可选参数配置网络请求的超时时间，目前 TOS Vectors Python SDK支持配置连接超时 connection_time 和请求超时 socket_timeout。
以下代码用于初始化 TosClient 时配置超时时间。
import tos
import os
# 从环境变量获取 AKSK 信息。
ak = os.getenv('TOS_ACCESS_KEY')
sk = os.getenv('TOS_SECRET_KEY')
# your endpoint 和 your region 填写Bucket 所在区域对应的Endpoint。# 以华北2(北京)为例，your endpoint 填写 tos-cn-beijing.volces.com，your region 填写 cn-beijing。
endpoint = "your endpoint"
region = "your region"
# 创建 VectorClient 对象，并设置连接超时为30秒, Socket 读写超时时间为60秒
# connection_time为连接超时，socket_timeout为请求超时时间。
client = tos.VectorClient(ak, sk, endpoint, region, connection_time=30, socket_timeout=60)
配置重试策略
网络波动或短期 TOS Vectors 服务异常（返回 500 状态码）等场景会导致调用 TOS Vectors 服务失败，针对此问题 Python SDK 内部提供了重试机制，幂等操作的接口在失败后会使用指数避让策略进行重试，非幂接口则直接抛出对应异常。您可以在初始化 TosClient 时，添加可选参数配置重试次数。
import os
import tos
# 从环境变量获取 AKSK 信息
ak = os.getenv('TOS_ACCESS_KEY')
sk = os.getenv('TOS_SECRET_KEY')
# your endpoint 和 your region 填写Bucket 所在区域对应的Endpoint。# 以华北2(北京)为例，your endpoint 填写 tos-cn-beijing.volces.com，your region 填写 cn-beijing。
endpoint = "your endpoint"
region = "your region"
# 创建 VectorClient 对象，并设置超时重试次数为3次。重试策略为指数避让策略，基准时间为100ms，及第一次重试间隔100ms，第二次重试间隔200ms，第三次重试400ms
client = tos.VectorClient(ak, sk, endpoint, region, max_retry_count=3)
配置代理服务器
TOS Vectors Python SDK 支持配置代理服务器的方式访问 TOS Vectors 服务，您可以在初始化 VectorClient 时，添加可选参数配置代理服务器。
说明
目前只支持 HTTP 协议代理。
import os
import tos
# 从环境变量获取 AKSK 信息
ak = os.getenv('TOS_ACCESS_KEY')
sk = os.getenv('TOS_SECRET_KEY')
# your endpoint 和 your region 填写Bucket 所在区域对应的Endpoint。# 以华北2(北京)为例，your endpoint 填写 tos-cn-beijing.volces.com，your region 填写 cn-beijing。
endpoint = "your endpoint"
region = "your region"
# 创建 VectorClient 对象，通过可选参数proxy_host、proxy_port、proxy_username、proxy_password来配置代理
client = tos.VectorClient(ak, sk, endpoint, region, proxy_host='<your proxy host>', proxy_port=80, proxy_username='<your proxy user name>', proxy_password='<your proxy password>')
配置连接池
TOS Vectors Python SDK 支持连接池配置，您可以在初始化 VectorClient 时，添加可选参数配置连接池大小。
说明
连接池大小默认配置为 1024，单进程多线程场景建议您使用一个 VectorClient 实例。
import os
import tos
# 从环境变量获取 AKSK 信息
ak = os.getenv('TOS_ACCESS_KEY')
sk = os.getenv('TOS_SECRET_KEY')
# your endpoint 和 your region 填写Bucket 所在区域对应的Endpoint。# 以华北2(北京)为例，your endpoint 填写 tos-cn-beijing.volces.com，your region 填写 cn-beijing。
endpoint = "your endpoint"
region = "your region"
# 创建 VectorClient 对象，并设置max_connections=1024将连接池大小设置为1024
client = tos.VectorClient(ak, sk, endpoint, region, max_connections=1024)
初始化参数列表
初始化 VectorClient 支持参数如下。
参数 | 参数类型 | 是否必选 | 示例值 | 说明 |
参数 | 参数类型 | 是否必选 | 示例值 | 说明 |
ak | str | 是 | AKTPYmI1**** | Access Key ID，即密钥 ID。 |
sk | str | 是 | T1dJM01**** | SecretAccess Key，即私有访问密钥。 |
endpoint | str | 是 | tos-cn-beijing.volces.com | 访问域名。 |
region | str | 是 | cn-beijing | TOS 服务端所在地域。 |
security_token | str | 否 | STSeyJ**** | 临时访问凭证中的安全令牌。 |
enable_verify_ssl | bool | 否 | True | 配置是否开启 SSL 证书校验。 |
connection_timeout | int | 否 | 10 | 设置建立连接超时时间，单位为秒。 |
max_connections | int | 否 | 1024 | 设置连接池大小。 |
enable_crc | bool | 否 | True | 是否开启 CRC 数据校验。 |
max_retry_count | int | 否 | 3 | 请求失败最大重试次数。 |
dns_cache_time | int | 否 | 5 | DNS 缓存的有效期，单位：分钟。 默认为 0，小于等于 0 时代表关闭 DNS 缓存。 |
proxy_host | str | 否 | None | 代理服务器的主机地址，当前只支持 HTTP 协议。 |
proxy_port | int | 否 | None | 代理服务器的端口号。 |
proxy_username | str | 否 | None | 连接代理服务器的用户名。 |
proxy_password | str | 否 | None | 连接代理服务器使用的用户密码。 |
high_latency_log_threshold | int | 否 | 100 | 大于 0 时，代表开启高延迟日志，单位：KB。默认为 100，当单次请求传输总速率低于该值且总请求耗时大于 500 毫秒时打印 WARN 级别日志。 |
socket_timeout | int | 否 | 30 | 连接建立成功后，单个请求的 Socket 读写超时时间。 单位：秒，默认为 30 秒。 |
credentials_provider | object | 否 | None | 通过 credentials_provider 实现永久访问密钥、临时访问密钥、ECS 免密登录、环境变量获取访问密钥等方式。 |
最近更新时间：2026.02.02 18:12:09
这个页面对您有帮助吗？
有用
有用
无用
无用