ClawHub

cos-vectors-skill

腾讯云 COS 向量桶全功能管理技能。覆盖向量桶、索引、向量数据的全生命周期管理，包括创建/删除/查询向量桶、创建/管理索引、插入/查询/搜索/删除向量数据、策略管理等 16 个核心能力。Trigger phrases: vector bucket, vector index, vector search, 向量桶, 向量索引, 向量搜索, 向量存储, 插入向量, 相似度搜索, COS vector.

Audits

Pending
ClawScanReview

Agentic behavior and permission review.

Static analysisPass

Pattern checks against bundled files.

VirusTotalPending

Multi-engine malware detections and file reputation.

Install

openclaw skills install cos-vectors-skill

腾讯云 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可选，返回向量数据
--return-metadata可选，返回元数据
--segment-count可选，分段总数
--segment-index可选，分段索引（从0开始）

15. 删除向量

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

16. 相似度搜索（query_vectors）

# 方式 1：直接传查询向量
python3 {baseDir}/scripts/query_vectors.py \
  --secret-id "<SecretId>" \
  --secret-key "<SecretKey>" \
  --region "<Region>" \
  --bucket "<BucketName-APPID>" \
  --index "<IndexName>" \
  --query-vector '[0.1, 0.2, ...]' \
  --top-k 5 \
  [--filter '{"category": {"$eq": "AI"}}'] \
  [--return-distance] \
  [--return-metadata]

# 方式 2：通过文件传入查询向量
python3 {baseDir}/scripts/query_vectors.py \
  ... \
  --query-vector-file query.json \
  --top-k 5
专有参数必需说明
--index✅索引名称
--query-vector✅*查询向量 JSON 数组
--query-vector-file✅*查询向量文件（与 --query-vector 二选一）
--top-k✅返回最相似的 K 个结果
--filter❌过滤条件 JSON，如 {"category": {"$eq": "AI"}}
--return-distance❌返回距离/相似度值
--return-metadata❌返回元数据

关键技术细节

  1. CosVectorsClient：向量桶专用客户端，不同于普通的 CosS3Client
  2. Endpoint 配置：使用 Endpoint 参数（vectors.<Region>.coslake.com），SDK 会自动拼接 bucket 前缀
  3. 协议：默认使用 http 协议
  4. 桶名格式：必须为 BucketName-APPID 格式，如 examplebucket-1250000000
  5. 桶名规则：仅支持小写字母、数字和中划线 -，长度 3-63 个字符
  6. 向量维度：范围 1-4096
  7. 数据类型：当前支持 float32
  8. 距离度量：支持 cosine（余弦相似度）和 euclidean（欧氏距离）
  9. 加密类型：可选 AES256 服务端加密

公共模块

所有脚本共享 common.py 公共模块，提供：

  • base_parser() — 创建包含凭证参数的基础解析器
  • create_client() — 初始化 CosVectorsClient
  • success_output() — 统一的成功输出格式（JSON）
  • fail() — 统一的错误输出格式并退出
  • handle_error() — 统一的异常处理（CosServiceError / CosClientError）
  • run() — 包装主函数并捕获异常

错误处理

  • CosServiceError：服务端错误（如桶已存在、权限不足等）
  • CosClientError：客户端错误（如网络问题、参数错误等）

所有脚本输出统一 JSON 格式：

{"success": true, "action": "...", ...}   // 成功
{"success": false, "error": "..."}        // 失败

调用失败时先检查：

  1. 凭证是否正确
  2. Region 是否正确
  3. Bucket 名称格式是否符合要求
  4. 网络是否连通

API 参考

详细 API 参数定义见 references/api_reference.md。