SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillscos-vectors

cos-vectors

Data & analytics

View repository

Updated 10-15 17:26

About this skill

Tencent Cloud COS vector bucket full-featured management skill

Manage the complete lifecycle of Tencent Cloud COS vector buckets through the CosVectorsClient of cos-python-sdk-v5.

Capabilities Overview

Category Capability Script
Vector Bucket Management Create Vector Bucket create_vector_bucket.py
Delete Vector Bucket delete_vector_bucket.py
Query Vector Bucket Information get_vector_bucket.py
List All Vector Buckets list_vector_buckets.py
Bucket Policy Management Set Bucket Policy put_vector_bucket_policy.py
Get Bucket Policy get_vector_bucket_policy.py
Delete Bucket Policy delete_vector_bucket_policy.py
Index Management Create Index create_index.py
Query Index Information get_index.py
List All Indexes list_indexes.py
Delete Index delete_index.py
Vector Data Operations Insert/Update Vectors put_vectors.py
Get Specified Vector get_vectors.py
List Vector List list_vectors.py
Delete Vector delete_vectors.py
Similarity Search query_vectors.py

First Use — Environment Check

Step 1: Check the Python SDK

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

If it fails, install the SDK:

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

Step 2: Check credentials

Confirm that the following environment variables are set (or prepare to pass them in via command-line parameters):

  • COS_VECTORS_SECRET_ID — Tencent Cloud API Secret ID
  • COS_VECTORS_SECRET_KEY — Tencent Cloud API Secret Key

If they are not set, guide the user to provide credentials:

Please provide Tencent Cloud credentials to connect to the COS vector storage service:

  1. SecretId — Tencent Cloud API Secret ID
  2. SecretKey — Tencent Cloud API Secret Key
  3. Region — Bucket region (e.g. ap-guangzhou)
  4. Bucket — Vector bucket name (format BucketName-APPID, e.g. examplebucket-1250000000)

Key acquisition:Tencent Cloud Console > Access Management > API Key Management

Common Parameters

All scripts support the following common parameters:

Parameter Required Description
--secret-id ✅ Tencent Cloud SecretId (or environment variable COS_VECTORS_SECRET_ID）
--secret-key ✅ Tencent Cloud SecretKey (or environment variable COS_VECTORS_SECRET_KEY）
--region ✅ Region, e.g. ap-guangzhou
--bucket ✅ Vector bucket name, format BucketName-APPID
--scheme ❌ Protocol,http(default) or https

I. Vector Bucket Management

1. Create Vector Bucket

python3 {baseDir}/scripts/create_vector_bucket.py \
  --secret-id "<SecretId>" \
  --secret-key "<SecretKey>" \
  --region "<Region>" \
  --bucket "<BucketName-APPID>" \
  [--sse-type AES256]
Specific Parameters Description
--sse-type Optional, encryption type, currently only supports AES256

2. Delete Vector Bucket

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

3. Query Vector Bucket Information

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

4. List All Vector Buckets

python3 {baseDir}/scripts/list_vector_buckets.py \
  --secret-id "<SecretId>" \
  --secret-key "<SecretKey>" \
  --region "<Region>" \
  --bucket "<BucketName-APPID>" \
  [--max-results 10] \
  [--prefix "my-"]
Specific Parameters Description
--max-results Optional, maximum number to return
--prefix Optional, bucket name prefix filter

II. Bucket Policy Management

5. Set Bucket Policy

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

6. Get Bucket Policy

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

7. Delete bucket policy

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

III. Index management

8. Create index

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]
Specific parameters Required Description
--index ✅ Index name
--dimension ✅ Vector dimension, range 1-4096
--data-type ❌ Data type, default float32
--distance-metric ❌ Distance metric,cosine(default) or euclidean
--non-filterable-keys ❌ Non-filter metadata keys, comma-separated

9. Query index information

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

10. List all indexes

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

11. Delete index

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

IV. Vector data operations

12. Insert/update vectors

# 方式 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
Specific parameters Description
--index Required, index name
--vectors Vector data JSON string
--vectors-file Vector data JSON file path (choose one of --vectors)

Vector JSON format：

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

13. Get specified vectors

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]
Specific parameters Description
--index Required, index name
--keys Required, vector key list, comma-separated
--return-data Optional, return vector data
--return-metadata Optional, return metadata

14. List vector list

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]
Specific parameters Description
--index Required, index name
--max-results Optional, maximum return count
--return-data Optional, return vector data
--return-metadata Optional, return metadata
--segment-count Optional, total number of segments
--segment-index Optional, segment index (starting from 0)

15. Delete vectors

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. Similarity search (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
Specific parameters Required Description
--index ✅ Index name
--query-vector ✅* Query vector JSON array
--query-vector-file ✅* Query vector file (choose one of --query-vector)
--top-k ✅ Return the most similar K results
--filter ❌ Filter condition JSON, such as {"category": {"$eq": "AI"}}
--return-distance ❌ Return distance/similarity value
--return-metadata ❌ Return metadata

Key technical details

  1. CosVectorsClient: vector bucket dedicated client, different from the ordinary CosS3Client
  2. Endpoint configuration: use the Endpoint parameter (vectors.<Region>.coslake.com), the SDK will automatically concatenate the bucket prefix
  3. Protocol: default use http protocol
  4. Bucket name format: must be BucketName-APPID format, such as examplebucket-1250000000
  5. Bucket name rules: only lowercase letters, numbers, and hyphens are supported -, length 3-63 characters
  6. Vector dimension: range 1-4096
  7. Data type: currently supports float32
  8. Distance metric: supports cosine(cosine similarity) and euclidean(Euclidean distance)
  9. Encryption type: optional AES256 server-side encryption

Common module

All scripts share the common.py common module, providing:

  • base_parser() — Create a basic parser containing credential parameters
  • create_client() — Initialize CosVectorsClient
  • success_output() — Unified success output format (JSON)
  • fail() — Unified error output format and exit
  • handle_error() — Unified exception handling (CosServiceError / CosClientError)
  • run() — Wrap the main function and catch exceptions

Error handling

  • CosServiceError: Server-side errors (such as bucket already exists, insufficient permissions, etc.)
  • CosClientError: Client-side errors (such as network issues, parameter errors, etc.)

All scripts output in a unified JSON format:

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

When a call fails, first check:

  1. Whether the credentials are correct
  2. Whether the Region is correct
  3. Whether the Bucket name format meets the requirements
  4. Whether the network is connected

API reference

For detailed API parameter definitions, see references/api_reference.md。