cos-vectors

# 腾讯云 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>" ``` --- ## 三、索引管理 ### 8. 创建索引 ```bash 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. 查询索引信息 ```bash python3 {baseDir}/scripts/get_index.py \ --secret-id "<SecretId>" \ --secret-key "<SecretKey>" \ --region "<Region>" \ --bucket "<BucketName-APPID>" \ --index "<IndexName>" ``` ### 10. 列出所有索引 ```bash python3 {baseDir}/scripts/list_indexes.py \ --secret-id "<SecretId>" \ --secret-key "<SecretKey>" \ --region "<Region>" \ --bucket "<BucketName-APPID>" \ [--max-results 10] \ [--prefix "demo-"] ``` ### 11. 删除索引 ```bash python3 {baseDir}/scripts/delete_index.py \ --secret-id "<SecretId>" \ --secret-key "<SecretKey>" \ --region "<Region>" \ --bucket "<BucketName-APPID>" \ --index "<IndexName>" ``` --- ## 四、向量数据操作 ### 12. 插入/更新向量 ```bash # 方式 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 格式**： ```json [ { "key": "doc-001", "data": {"float32": [0.1, 0.2, 0.3, "..."]}, "metadata": {"title": "文档标题", "category": "分类"} } ] ``` ### 13. 获取指定向量 ```bash 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. 列出向量列表 ```bash 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` | 可选，返回向量数据 |