创建索引

最近更新时间:2026-01-22 17:15:02

我的收藏

简介

本文介绍通过 Python SDK 实现创建索引功能的示例代码和描述。

功能说明

在向量桶中创建一个新的向量索引。

方法原型

create_index(self, Bucket, Index, DataType, Dimension, DistanceMetric, NonFilterableMetadataKeys=None, **kwargs)

使用案例

创建索引

# -*- coding=utf-8
import sys
import os
from pprint import pprint
from qcloud_cos import CosServiceError
from qcloud_cos import CosConfig
from qcloud_cos import CosVectorsClient
import logging

# 正常情况日志级别使用 INFO,需要定位时可以修改为 DEBUG,此时 SDK 会打印和服务端的通信信息
logging.basicConfig(level=logging.INFO, stream=sys.stdout)

# 1. 设置用户属性, 包括 secret_id, secret_key, region 等。Appid 已在 CosConfig 中移除,请在参数 Bucket 中带上 Appid。Bucket 由 BucketName-Appid 组成
secret_id = os.getenv("COS_VECTORS_SECRET_ID") # 用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
secret_key = os.getenv("COS_VECTORS_SECRET_KEY") # 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
region = 'ap-guangzhou' # 替换为用户的 region,已创建桶归属的 region 可以在控制台查看,https://console.cloud.tencent.com/cos/bucket
# COS 支持的所有 region 列表参见 https://cloud.tencent.com/document/product/436/6224
token = None # 如果使用永久密钥不需要填入 token,如果使用临时密钥需要填入,临时密钥生成和使用指引参见 https://cloud.tencent.com/document/product/436/14048
scheme = 'http' # 指定使用 http/https 协议来访问 COS,默认为 https,可不填

config = CosConfig(
Region=region,
SecretId=secret_id,
SecretKey=secret_key,
Scheme=scheme,
Domain="vectors.ap-guangzhou.coslake.com",
Token=token,
)
client = CosVectorsClient(config)

try:
resp, data = client.create_index(
Bucket='examplebucket-1250000000',
Index='my-index',
DataType='float32', # 向量数据类型
Dimension=128, # 向量维度(1-4096)
DistanceMetric='cosine' # 距离度量方式
)
print('索引创建成功')
print('响应头:', resp)
print('索引信息:', data)
except CosServiceError as e:
if e.get_error_code() == "NotFoundException":
print("资源不存在")
print(f'创建失败: {e}')

带元数据配置

# -*- coding=utf-8
import sys
import os
from pprint import pprint
from qcloud_cos import CosServiceError
from qcloud_cos import CosConfig
from qcloud_cos import CosVectorsClient
import logging

# 正常情况日志级别使用 INFO,需要定位时可以修改为 DEBUG,此时 SDK 会打印和服务端的通信信息
logging.basicConfig(level=logging.INFO, stream=sys.stdout)

# 1. 设置用户属性, 包括 secret_id, secret_key, region 等。Appid 已在 CosConfig 中移除,请在参数 Bucket 中带上 Appid。Bucket 由 BucketName-Appid 组成
secret_id = os.getenv("COS_VECTORS_SECRET_ID") # 用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
secret_key = os.getenv("COS_VECTORS_SECRET_KEY") # 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
region = 'ap-guangzhou' # 替换为用户的 region,已创建桶归属的 region 可以在控制台查看,https://console.cloud.tencent.com/cos/bucket
# COS 支持的所有 region 列表参见 https://cloud.tencent.com/document/product/436/6224
token = None # 如果使用永久密钥不需要填入 token,如果使用临时密钥需要填入,临时密钥生成和使用指引参见 https://cloud.tencent.com/document/product/436/14048
scheme = 'http' # 指定使用 http/https 协议来访问 COS,默认为 https,可不填

config = CosConfig(
Region=region,
SecretId=secret_id,
SecretKey=secret_key,
Scheme=scheme,
Domain="vectors.ap-guangzhou.coslake.com",
Token=token,
)
client = CosVectorsClient(config)


try:
resp, data = client.create_index(
Bucket='examplebucket-1250000000',
Index='my-index',
DataType='float32',
Dimension=256,
DistanceMetric='euclidean', # 欧氏距离
NonFilterableMetadataKeys=['tag', 'category'] # 指定不可过滤的元数据键
)
print('索引创建成功(含元数据配置)')
except CosServiceError as e:
if e.get_error_code() == "NotFoundException":
print("资源不存在")
print(f'创建失败: {e}')

参数说明

参数
描述
类型
是否必选
Bucket
向量桶名称,<BucketName-APPID>格式,例如 examplebucket-1250000000,支持小写字母、数字和 - ,长度限制3-63字符
string
Index
索引名称
string
DataType
向量数据类型,支持 float32
string
Dimension
向量维度,范围1-4096
int
DistanceMetric
相似性搜索的距离度量。可选值 euclidean(欧氏距离) 或者 cosine(余弦距离)
string
NonFilterableMetadataKeys
非过滤元数据键列表
list

返回结果说明

返回值

resp (dict): 响应头信息。
data (dict): 响应数据,包含索引Qcs,详细结构可参考 CreateIndex

错误处理

如果请求失败,将会抛出 CosServiceError 或者 CosClientError 异常,详细介绍请参见 异常处理