TOS Vectors 技能

用于管理向量存储、索引和相似性搜索的综合技能，使用 TOS Vectors 服务——一个专为 AI 应用优化的云向量数据库。

快速开始

初始化客户端

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)

基本工作流

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

核心操作

向量存储桶管理

创建存储桶

client.create_vector_bucket(bucket_name)

列出存储桶

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

删除存储桶（必须为空）

client.delete_vector_bucket(bucket_name, account_id)

向量索引管理

创建索引

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
)

列出索引

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

向量数据操作

插入向量（批量最多 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
)

查询相似向量（KNN 搜索）

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}")

通过键获取向量

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
)

删除向量

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

常见用例

1. 语义搜索

构建一个用于文档的语义搜索系统：

# 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（检索增强生成）

为LLM提示检索相关上下文：

# 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. 推荐系统

基于用户偏好查找相似项目：

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

最佳实践

命名约定

• 存储桶名称：3-32个字符，仅限小写字母、数字、连字符
• 索引名称：3-63个字符
• 向量键：1-1024个字符，使用有意义的标识符

批量操作

• 每次调用最多插入500个向量
• 每次调用最多删除100个向量
• 列表操作使用分页

错误处理

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}')

性能提示

• 选择合适的向量维度（平衡准确性与性能）
• 使用元数据过滤以减少搜索空间
• 对归一化向量使用余弦相似度
• 对绝对距离使用欧几里得距离

重要限制

• 向量桶: 每个账户最多100个
• 向量维度: 1-4096
• 批量插入: 每次调用1-500个向量
• 批量获取/删除: 每次调用1-100个向量
• 查询TopK: 1-30个结果

附加资源

详细的API参考，请参阅REFERENCE.md完整的工作流程，请参阅WORKFLOWS.md示例脚本，请参见scripts/目录