cos-vectors

name	cos-vectors
description	Manage Tencent Cloud COS vector buckets via cos-python-sdk-v5 CosVectorsClient. Full lifecycle: create/delete/list vector buckets, manage bucket policies, create/query/list/delete indexes, insert/update/get/list/delete vectors, and similarity search. Use when user mentions COS向量, 向量桶, vector bucket, or similarity search on Tencent Cloud.
description_zh	腾讯云 COS 向量桶管理（索引、存储、相似度搜索）
description_en	Tencent Cloud COS vector bucket management & similarity search

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

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

能力总览

类别	能力	脚本
向量桶管理	创建向量桶	create_vector_bucket.py
	删除向量桶	delete_vector_bucket.py
	查询向量桶信息	get_vector_bucket.py
	列出所有向量桶	list_vector_buckets.py
桶策略管理	设置桶策略	put_vector_bucket_policy.py
	获取桶策略	get_vector_bucket_policy.py
	删除桶策略	delete_vector_bucket_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

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

如果失败，安装 SDK：

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

步骤 2：检查凭证

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

• COS_VECTORS_SECRET_ID — 腾讯云 API 密钥 ID
• COS_VECTORS_SECRET_KEY — 腾讯云 API 密钥 Key

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

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

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

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

公共参数

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

参数	必需	说明
--secret-id	✅	腾讯云 SecretId（或环境变量 COS_VECTORS_SECRET_ID）
--secret-key	✅	腾讯云 SecretKey（或环境变量 COS_VECTORS_SECRET_KEY）
--region	✅	地域，如 ap-guangzhou
--bucket	✅	向量桶名称，格式 BucketName-APPID
--scheme	❌	协议，http（默认）或 https

---

一、向量桶管理

1. 创建向量桶

python3 {baseDir}/scripts/create_vector_bucket.py \
  --secret-id "<SecretId>" \
  --secret-key "<SecretKey>" \
  --region "<Region>" \
  --bucket "<BucketName-APPID>" \
  [--sse-type AES256]

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

2. 删除向量桶

python3 {baseDir}/scripts/delete_vector_bucket.py \
  --secret-id "<SecretId>" \
  --secret-key "<SecretKey>" \
  --region "<Region>" \
  --bucket "<BucketName-APPID>"

3. 查询向量桶信息

python3 {baseDir}/scripts/get_vector_bucket.py \
  --secret-id "<SecretId>" \
  --secret-key "<SecretKey>" \
  --region "<Region>" \
  --bucket "<BucketName-APPID>"

4. 列出所有向量桶

python3 {baseDir}/scripts/list_vector_buckets.py \
  --secret-id "<SecretId>" \
  --secret-key "<SecretKey>" \
  --region "<Region>" \
  --bucket "<BucketName-APPID>" \
  [--max-results 10] \
  [--prefix "my-"]

专有参数	说明
--max-results	可选，最大返回数量
--prefix	可选，桶名前缀过滤

---

二、桶策略管理

5. 设置桶策略

python3 {baseDir}/scripts/put_vector_bucket_policy.py \
  --secret-id "<SecretId>" \
  --secret-key "<SecretKey>" \
  --region "<Region>" \
  --bucket "<BucketName-APPID>" \
  --policy '{"Statement": [...]}'

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

6. 获取桶策略

python3 {baseDir}/scripts/get_vector_bucket_policy.py \
  --secret-id "<SecretId>" \
  --secret-key "<SecretKey>" \
  --region "<Region>" \
  --bucket "<BucketName-APPID>"

7. 删除桶策略

python3 {baseDir}/scripts/delete_vector_bucket_policy.py \
  --secret-id "<SecretId>" \
  --secret-key "<SecretKey>" \
  --region "<Region>" \
  --bucket "<BucketName-APPID>"

---

三、索引管理

8. 创建索引

python3 {baseDir}/scripts/create_index.py \
  --secret-id "<SecretId>" \
  --secret-key "<SecretKey>" \
  --region "<Region>" \
  --bucket "<BucketName-APPID>" \
  --index "<IndexName>" \
  --dimension <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. 查询索引信息

python3 {baseDir}/scripts/get_index.py \
  --secret-id "<SecretId>" \
  --secret-key "<SecretKey>" \
  --region "<Region>" \
  --bucket "<BucketName-APPID>" \
  --index "<IndexName>"

10. 列出所有索引

python3 {baseDir}/scripts/list_indexes.py \
  --secret-id "<SecretId>" \
  --secret-key "<SecretKey>" \
  --region "<Region>" \
  --bucket "<BucketName-APPID>" \
  [--max-results 10] \
  [--prefix "demo-"]

11. 删除索引

python3 {baseDir}/scripts/delete_index.py \
  --secret-id "<SecretId>" \
  --secret-key "<SecretKey>" \
  --region "<Region>" \
  --bucket "<BucketName-APPID>" \
  --index "<IndexName>"

---

四、向量数据操作

12. 插入/更新向量

# 方式 1：直接传 JSON
python3 {baseDir}/scripts/put_vectors.py \
  --secret-id "<SecretId>" \
  --secret-key "<SecretKey>" \
  --region "<Region>" \
  --bucket "<BucketName-APPID>" \
  --index "<IndexName>" \
  --vectors '[{"key":"doc-001","data":{"float32":[0.1,0.2,...]},"metadata":{"title":"标题"}}]'

# 方式 2：通过文件传入
python3 {baseDir}/scripts/put_vectors.py \
  --secret-id "<SecretId>" \
  --secret-key "<SecretKey>" \
  --region "<Region>" \
  --bucket "<BucketName-APPID>" \
  --index "<IndexName>" \
  --vectors-file vectors.json

专有参数	说明
--index	必需，索引名称
--vectors	向量数据 JSON 字符串
--vectors-file	向量数据 JSON 文件路径（与 --vectors 二选一）

向量 JSON 格式：

[
  {
    "key": "doc-001",
    "data": {"float32": [0.1, 0.2, 0.3, "..."]},
    "metadata": {"title": "文档标题", "category": "分类"}
  }
]

13. 获取指定向量

python3 {baseDir}/scripts/get_vectors.py \
  --secret-id "<SecretId>" \
  --secret-key "<SecretKey>" \
  --region "<Region>" \
  --bucket "<BucketName-APPID>" \
  --index "<IndexName>" \
  --keys "doc-001,doc-002" \
  [--return-data] \
  [--return-metadata]

专有参数	说明
--index	必需，索引名称
--keys	必需，向量键列表，逗号分隔
--return-data	可选，返回向量数据
--return-metadata	可选，返回元数据

14. 列出向量列表

python3 {baseDir}/scripts/list_vectors.py \
  --secret-id "<SecretId>" \
  --secret-key "<SecretKey>" \
  --region "<Region>" \
  --bucket "<BucketName-APPID>" \
  --index "<IndexName>" \
  [--max-results 10] \
  [--return-data] \
  [--return-metadata]

专有参数	说明
--index	必需，索引名称
--max-results	可选，最大返回数量
--return-data	可选，返回向量数据