cos-vectors

The saved excerpt is a snapshot from when this skill was listed. The external source remains the complete and most current version.

---
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

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

如果失败，安装 SDK：

```bash
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密钥管理](https://console.cloud.tencent.com/cam/capi)

### 公共参数

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

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

---

## 一、向量桶管理

### 1. 创建向量桶

```bash
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. 删除向量桶

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

### 3. 查询向量桶信息

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

### 4. 列出所有向量桶

```bash
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. 设置桶策略

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

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

### 6. 获取桶策略

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

### 7. 删除桶策略

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