volcengine-tos-vectors-skills

Manage vector storage and similarity search using TOS Vectors service. Use when working with embeddings, semantic search, RAG systems, recommendation engines, or when the user mentions vector databases, similarity search, or TOS Vectors operations.

Security Scan

The skill implements a coherent TOS Vectors client and scripts, but the registry metadata omits required credentials (TOS_ACCESS_KEY, TOS_SECRET_KEY, TOS_ACCOUNT_ID) and package install guidance — that mismatch is concerning and should be resolved before trusting the skill.

Purpose & Capability

Name, description, SKILL.md, README, WORKFLOWS.md, and the three scripts consistently implement vector-bucket, index, insert, and query operations for a TOS Vectors service. The code and documentation align with the stated purpose.

Instruction Scope

SKILL.md and the scripts explicitly instruct the agent to read environment variables for credentials, create buckets/indexes, insert/query/delete vectors, and call the TOS endpoint. Those instructions stay within the stated purpose and do not reference unrelated system files or exotic endpoints. However, the instructions rely on environment variables and a Python SDK that are not declared in the registry metadata.

Install Mechanism

There is no install spec in the registry (instruction-only), which reduces install-time risk. But the README and SKILL.md require the `tos` Python SDK (specific beta version mentioned). The absence of an install spec means the skill assumes the runtime already has that dependency; this is a documentation/metadata gap rather than obviously malicious behavior.

Credentials

The scripts and SKILL.md require TOS_ACCESS_KEY, TOS_SECRET_KEY, and TOS_ACCOUNT_ID (used to initialize tos.VectorClient), but the registry metadata lists no required env vars and no primary credential. Requesting full API keys is proportionate to a cloud vector DB client, but the metadata omission is an incoherence that could mislead users and automated installers about needed secrets.

Persistence & Privilege

The skill does not request always:true, does not declare persistence or modify other skills, and does not require system-wide privileges. It only runs client operations against an external TOS endpoint when invoked.

What to consider before installing

This skill appears to be a legitimate TOS Vectors helper, but the package metadata is incomplete: the scripts and SKILL.md require three environment variables (TOS_ACCESS_KEY, TOS_SECRET_KEY, TOS_ACCOUNT_ID) and the `tos` Python SDK, yet the registry lists none. Before installing or enabling this skill: - Verify the skill source and author (owner id present but homepage/source is unknown). Prefer skills with a known homepage or repo. - Don’t supply high-privilege TOS keys unless you trust the skill and its source. Use least-privilege keys and an account dedicated to testing if possible. - Confirm the endpoint domains (https://tosvectors-cn-beijing.volces.com and https://tosvectors-cn-beijing.ivolces.com) are legitimate for your provider; if unsure, contact the provider or use an official SDK/endpoint. - If you plan to use the CLI scripts, ensure the `tos` SDK version (README suggests a beta) is appropriate and audit that package separately before pip installing. - Ask the publisher/maintainer to update registry metadata to declare required env vars and any install steps so automated tooling and users are not misled. Given the clear metadata mismatch (credentials required but not declared) the skill is suspicious—not necessarily malicious—but you should validate the origin and limit credentials before use.

TOS Vectors Skill

Comprehensive skill for managing vector storage, indexing, and similarity search using the TOS Vectors service - a cloud-based vector database optimized for AI applications.

Quick Start

Initialize Client

import os
import tos

# Get credentials from environment
ak = os.getenv('TOS_ACCESS_KEY')
sk = os.getenv('TOS_SECRET_KEY')
account_id = os.getenv('TOS_ACCOUNT_ID')

# Configure endpoint and region
endpoint = 'https://tosvectors-cn-beijing.volces.com'
region = 'cn-beijing'

# Create client
client = tos.VectorClient(ak, sk, endpoint, region)

Basic Workflow

# 1. Create vector bucket (like a database)
client.create_vector_bucket('my-vectors')

# 2. Create vector index (like a table)
client.create_index(
    account_id=account_id,
    vector_bucket_name='my-vectors',
    index_name='embeddings-768d',
    data_type=tos.DataType.DataTypeFloat32,
    dimension=768,
    distance_metric=tos.DistanceMetricType.DistanceMetricCosine
)

# 3. Insert vectors
vectors = [
    tos.models2.Vector(
        key='doc-1',
        data=tos.models2.VectorData(float32=[0.1] * 768),
        metadata={'title': 'Document 1', 'category': 'tech'}
    )
]
client.put_vectors(
    vector_bucket_name='my-vectors',
    account_id=account_id,
    index_name='embeddings-768d',
    vectors=vectors
)

# 4. Search similar vectors
query_vector = tos.models2.VectorData(float32=[0.1] * 768)
results = client.query_vectors(
    vector_bucket_name='my-vectors',
    account_id=account_id,
    index_name='embeddings-768d',
    query_vector=query_vector,
    top_k=5,
    return_distance=True,
    return_metadata=True
)

Core Operations

Vector Bucket Management

Create Bucket

client.create_vector_bucket(bucket_name)

List Buckets

result = client.list_vector_buckets(max_results=100)
for bucket in result.vector_buckets:
    print(bucket.vector_bucket_name)

Delete Bucket (must be empty)

client.delete_vector_bucket(bucket_name, account_id)

Vector Index Management

Create Index

client.create_index(
    account_id=account_id,
    vector_bucket_name=bucket_name,
    index_name='my-index',
    data_type=tos.DataType.DataTypeFloat32,
    dimension=128,
    distance_metric=tos.DistanceMetricType.DistanceMetricCosine
)

List Indexes

result = client.list_indexes(bucket_name, account_id)
for index in result.indexes:
    print(f"{index.index_name}: {index.dimension}d")

Vector Data Operations

Insert Vectors (batch up to 500)

vectors = []
for i in range(100):
    vector = tos.models2.Vector(
        key=f'vec-{i}',
        data=tos.models2.VectorData(float32=[...]),
        metadata={'category': 'example'}
    )
    vectors.append(vector)

client.put_vectors(
    vector_bucket_name=bucket_name,
    account_id=account_id,
    index_name=index_name,
    vectors=vectors
)

Query Similar Vectors (KNN search)

results = client.query_vectors(
    vector_bucket_name=bucket_name,
    account_id=account_id,
    index_name=index_name,
    query_vector=query_vector,
    top_k=10,
    filter={"$and": [{"category": "tech"}]},  # Optional metadata filter
    return_distance=True,
    return_metadata=True
)

for vec in results.vectors:
    print(f"Key: {vec.key}, Distance: {vec.distance}")

Get Vectors by Keys

result = client.get_vectors(
    vector_bucket_name=bucket_name,
    account_id=account_id,
    index_name=index_name,
    keys=['vec-1', 'vec-2'],
    return_data=True,
    return_metadata=True
)

Delete Vectors

client.delete_vectors(
    vector_bucket_name=bucket_name,
    account_id=account_id,
    index_name=index_name,
    keys=['vec-1', 'vec-2']
)

Common Use Cases

1. Semantic Search

Build a semantic search system for documents:

# Index documents
for doc in documents:
    embedding = get_embedding(doc.text)  # Your embedding model
    vector = tos.models2.Vector(
        key=doc.id,
        data=tos.models2.VectorData(float32=embedding),
        metadata={'title': doc.title, 'content': doc.text[:500]}
    )
    vectors.append(vector)

client.put_vectors(
    vector_bucket_name=bucket_name,
    account_id=account_id,
    index_name=index_name,
    vectors=vectors
)

# Search
query_embedding = get_embedding(user_query)
results = client.query_vectors(
    vector_bucket_name=bucket_name,
    account_id=account_id,
    index_name=index_name,
    query_vector=tos.models2.VectorData(float32=query_embedding),
    top_k=5,
    return_metadata=True
)

2. RAG (Retrieval Augmented Generation)

Retrieve relevant context for LLM prompts:

# Retrieve relevant documents
question_embedding = get_embedding(user_question)
search_results = client.query_vectors(
    vector_bucket_name=bucket_name,
    account_id=account_id,
    index_name='knowledge-base',
    query_vector=tos.models2.VectorData(float32=question_embedding),
    top_k=3,
    return_metadata=True
)

# Build context
context = "\n\n".join([
    v.metadata.get('content', '') for v in search_results.vectors
])

# Generate answer with LLM
prompt = f"Context:\n{context}\n\nQuestion: {user_question}"

3. Recommendation System

Find similar items based on user preferences:

# Query with metadata filtering
results = client.query_vectors(
    vector_bucket_name=bucket_name,
    account_id=account_id,
    index_name='products',
    query_vector=user_preference_vector,
    top_k=10,
    filter={"$and": [{"category": "electronics"}, {"price_range": "mid"}]},
    return_metadata=True
)

Best Practices

Naming Conventions

• Bucket names: 3-32 chars, lowercase letters, numbers, hyphens only
• Index names: 3-63 chars
• Vector keys: 1-1024 chars, use meaningful identifiers

Batch Operations

• Insert up to 500 vectors per call
• Delete up to 100 vectors per call
• Use pagination for listing operations

Error Handling

try:
    result = client.create_vector_bucket(bucket_name)
except tos.exceptions.TosClientError as e:
    print(f'Client error: {e.message}')
except tos.exceptions.TosServerError as e:
    print(f'Server error: {e.code}, Request ID: {e.request_id}')

Performance Tips

• Choose appropriate vector dimensions (balance accuracy vs performance)
• Use metadata filtering to reduce search space
• Use cosine similarity for normalized vectors
• Use Euclidean distance for absolute distances

Important Limits

• Vector buckets: Max 100 per account
• Vector dimensions: 1-4096
• Batch insert: 1-500 vectors per call
• Batch get/delete: 1-100 vectors per call
• Query TopK: 1-30 results

Additional Resources

For detailed API reference, see REFERENCE.md For complete workflows, see WORKFLOWS.md For example scripts, see the scripts/ directory