TOS 向量服务技能

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

快速开始

初始化客户端

python
import os
import tos

从环境变量获取凭证

ak = os.getenv(TOSACCESSKEY) sk = os.getenv(TOSSECRETKEY) accountid = os.getenv(TOSACCOUNT_ID)

配置终端节点和区域

endpoint = https://tosvectors-cn-beijing.volces.com region = cn-beijing

创建客户端

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

基本工作流程

python

1. 创建向量桶（类似数据库）

client.createvectorbucket(my-vectors)

2. 创建向量索引（类似数据表）

client.create_index( accountid=accountid, vectorbucketname=my-vectors, index_name=embeddings-768d, data_type=tos.DataType.DataTypeFloat32, dimension=768, distance_metric=tos.DistanceMetricType.DistanceMetricCosine )

3. 插入向量

vectors = [ tos.models2.Vector( key=doc-1, data=tos.models2.VectorData(float32=[0.1] * 768), metadata={title: 文档1, category: 技术} ) ] client.put_vectors( vectorbucketname=my-vectors, accountid=accountid, index_name=embeddings-768d, vectors=vectors )

4. 搜索相似向量

query_vector = tos.models2.VectorData(float32=[0.1] * 768) results = client.query_vectors( vectorbucketname=my-vectors, accountid=accountid, index_name=embeddings-768d, queryvector=queryvector, top_k=5, return_distance=True, return_metadata=True )

核心操作

向量桶管理

创建桶
python
client.createvectorbucket(bucket_name)

列出桶
python
result = client.listvectorbuckets(max_results=100)
for bucket in result.vector_buckets:
print(bucket.vectorbucketname)

删除桶（必须为空）
python
client.deletevectorbucket(bucketname, accountid)

向量索引管理

创建索引
python
client.create_index(
accountid=accountid,
vectorbucketname=bucket_name,
index_name=my-index,
data_type=tos.DataType.DataTypeFloat32,
dimension=128,
distance_metric=tos.DistanceMetricType.DistanceMetricCosine
)

列出索引
python
result = client.listindexes(bucketname, account_id)
for index in result.indexes:
print(f{index.index_name}: {index.dimension}维)

向量数据操作

插入向量（批量最多500个）
python
vectors = []
for i in range(100):
vector = tos.models2.Vector(
key=fvec-{i},
data=tos.models2.VectorData(float32=[...]),
metadata={category: 示例}
)
vectors.append(vector)

client.put_vectors(
vectorbucketname=bucket_name,
accountid=accountid,
indexname=indexname,
vectors=vectors
)

查询相似向量（KNN搜索）
python
results = client.query_vectors(
vectorbucketname=bucket_name,
accountid=accountid,
indexname=indexname,
queryvector=queryvector,
top_k=10,
filter={$and: [{category: 技术}]}, # 可选的元数据过滤
return_distance=True,
return_metadata=True
)

for vec in results.vectors:
print(f键: {vec.key}, 距离: {vec.distance})

按键获取向量
python
result = client.get_vectors(
vectorbucketname=bucket_name,
accountid=accountid,
indexname=indexname,
keys=[vec-1, vec-2],
return_data=True,
return_metadata=True
)

删除向量
python
client.delete_vectors(
vectorbucketname=bucket_name,
accountid=accountid,
indexname=indexname,
keys=[vec-1, vec-2]
)

常见用例

1. 语义搜索

为文档构建语义搜索系统：

python

索引文档

for doc in documents:
embedding = get_embedding(doc.text) # 您的嵌入模型
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(
vectorbucketname=bucket_name,
accountid=accountid,
indexname=indexname,
vectors=vectors
)

搜索

queryembedding = getembedding(user_query) results = client.query_vectors( vectorbucketname=bucket_name, accountid=accountid, indexname=indexname, queryvector=tos.models2.VectorData(float32=queryembedding), top_k=5, return_metadata=True )

2. RAG（检索增强生成）

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

python

检索相关文档

questionembedding = getembedding(user_question)
searchresults = client.queryvectors(
vectorbucketname=bucket_name,
accountid=accountid,
index_name=knowledge-base,
queryvector=tos.models2.VectorData(float32=questionembedding),
top_k=3,
return_metadata=True
)

构建上下文

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

使用LLM生成答案

prompt = f上下文:\n{context}\n\n问题: {user_question}

3. 推荐系统

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

python

使用元数据过滤查询

results = client.query_vectors(
vectorbucketname=bucket_name,
accountid=accountid,
index_name=products,
queryvector=userpreference_vector,
top_k=10,
filter={$and: [{category: 电子产品}, {price_range: 中档}]},
return_metadata=True
)

最佳实践

命名规范

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

批量操作

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

错误处理

python try: result = client.createvectorbucket(bucket_name) except tos.exceptions.TosClientError as e: print(f客户端错误: {e.message}) except tos.exceptions.TosServerError as e: print(f服务器错误: {e.code}, 请求ID: {e.request_id})

性能建议

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

重要限制

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

其他资源

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