腾讯云 COS 向量桶全功能管理技能

通过 cos-python-sdk-v5 的 CosVectorsClient 管理腾讯云 COS 向量桶的完整生命周期。

能力总览

类别	能力	脚本
向量桶管理	创建向量桶	createvectorbucket.py

删除向量桶 | deletevectorbucket.py | | | 查询向量桶信息 | getvectorbucket.py | | | 列出所有向量桶 | listvectorbuckets.py | | 桶策略管理 | 设置桶策略 | putvectorbucket_policy.py | | | 获取桶策略 | getvectorbucket_policy.py | | | 删除桶策略 | deletevectorbucket_policy.py | | 索引管理 | 创建索引 | create_index.py | | | 查询索引信息 | get_index.py | | | 列出所有索引 | list_indexes.py | | | 删除索引 | delete_index.py | | 向量数据操作 | 插入/更新向量 | put_vectors.py | | | 获取指定向量 | get_vectors.py | | | 列出向量列表 | list_vectors.py | | | 删除向量 | delete_vectors.py | | | 相似度搜索 | query_vectors.py |

---

首次使用 — 环境检查

步骤 1：检查 Python SDK

bash
python3 -c from qcloud_cos import CosConfig, CosVectorsClient; print(OK)

如果失败，安装 SDK：

bash
pip3 install cos-python-sdk-v5 --upgrade

步骤 2：检查凭证

确认以下环境变量已设置（或准备通过命令行参数传入）：

• - COSVECTORSSECRETID — 腾讯云 API 密钥 ID
• COSVECTORSSECRETKEY — 腾讯云 API 密钥 Key

如果未设置，引导用户提供凭证：

请提供腾讯云凭证来连接 COS 向量存储服务：

1. 1. SecretId — 腾讯云 API 密钥 ID
2. SecretKey — 腾讯云 API 密钥 Key
3. Region — 存储桶区域（如 ap-guangzhou）
4. Bucket — 向量桶名称（格式 BucketName-APPID，如 examplebucket-1250000000）

密钥获取：腾讯云控制台 > 访问管理 > API密钥管理

公共参数

所有脚本都支持以下公共参数：

参数	必需	说明
--secret-id	✅	腾讯云 SecretId（或环境变量 COSVECTORSSECRETID）
--secret-key

✅ | 腾讯云 SecretKey（或环境变量 COSVECTORSSECRETKEY） |
| --region | ✅ | 地域，如 ap-guangzhou |
| --bucket | ✅ | 向量桶名称，格式 BucketName-APPID |
| --scheme | ❌ | 协议，http（默认）或 https |

---

一、向量桶管理

1. 创建向量桶

bash
python3 {baseDir}/scripts/createvectorbucket.py \
--secret-id \
--secret-key \
--region \
--bucket \
[--sse-type AES256]

专有参数	说明
--sse-type	可选，加密类型，当前仅支持 AES256

2. 删除向量桶

bash
python3 {baseDir}/scripts/deletevectorbucket.py \
--secret-id \
--secret-key \
--region \
--bucket

3. 查询向量桶信息

bash
python3 {baseDir}/scripts/getvectorbucket.py \
--secret-id \
--secret-key \
--region \
--bucket

4. 列出所有向量桶

bash
python3 {baseDir}/scripts/listvectorbuckets.py \
--secret-id \
--secret-key \
--region \
--bucket \
[--max-results 10] \
[--prefix my-]

专有参数	说明
--max-results	可选，最大返回数量
--prefix

可选，桶名前缀过滤 |

---

二、桶策略管理

5. 设置桶策略

bash
python3 {baseDir}/scripts/putvectorbucket_policy.py \
--secret-id \
--secret-key \
--region \
--bucket \
--policy {Statement: [...]}

专有参数	说明
--policy	必需，策略 JSON 字符串

6. 获取桶策略

bash
python3 {baseDir}/scripts/getvectorbucket_policy.py \
--secret-id \
--secret-key \
--region \
--bucket

7. 删除桶策略

bash
python3 {baseDir}/scripts/deletevectorbucket_policy.py \
--secret-id \
--secret-key \
--region \
--bucket

---

三、索引管理

8. 创建索引

bash
python3 {baseDir}/scripts/create_index.py \
--secret-id \
--secret-key \
--region \
--bucket \
--index \
--dimension \
[--data-type float32] \
[--distance-metric cosine] \
[--non-filterable-keys key1,key2]

专有参数	必需	说明
--index	✅	索引名称
--dimension

✅ | 向量维度，范围 1-4096 | | --data-type | ❌ | 数据类型，默认 float32 | | --distance-metric | ❌ | 距离度量，cosine（默认）或 euclidean | | --non-filterable-keys | ❌ | 非过滤元数据键，逗号分隔 |

9. 查询索引信息

bash
python3 {baseDir}/scripts/get_index.py \
--secret-id \
--secret-key \
--region \
--bucket \
--index

10. 列出所有索引

bash
python3 {baseDir}/scripts/list_indexes.py \
--secret-id \
--secret-key \
--region \
--bucket \
[--max-results 10] \
[--prefix demo-]

11. 删除索引

bash
python3 {baseDir}/scripts/delete_index.py \
--secret-id \
--secret-key \
--region \
--bucket \
--index

---

四、向量数据操作

12. 插入/更新向量

bash

方式 1：直接传 JSON

python3 {baseDir}/scripts/put_vectors.py \
--secret-id \
--secret-key \
--region \
--bucket \
--index \
--vectors [{key:doc-001,data:{float32:[0.1,0.2,...]},metadata:{title:标题}}]

方式 2：通过文件传入

python3 {baseDir}/scripts/put_vectors.py \ --secret-id \ --secret-key \ --region \ --bucket \ --index \