文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>对象存储>向量存储与检索>向量存储桶>Python SDK>向量操作>检索向量

检索向量

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

我的收藏

本页目录：

简介

本文介绍通过 Python SDK 实现检索向量功能的示例代码和描述。

功能说明

在一个向量索引中通过一个向量检索最相关的 TopK 个向量。

方法原型

query_vectors(self, Bucket, Index, QueryVector, TopK, Filter=None,
                      ReturnDistance=None, ReturnMetaData=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.query_vectors(
        Bucket='examplebucket-1250000000',
        Index='idx-dim3',
        QueryVector={"float32":[0.1, 0.2, 0.3]},
        TopK=10
    )
    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.query_vectors(
        Bucket='examplebucket-1250000000',
        Index='idx-dim3',
        QueryVector={"float32":[0.1, 0.2, 0.3]},
        TopK=10,
        Filter={
          "$and": [
            {
              "genre": {
                "$eq": "drama"
              }
            },
            {
              "year": {
                "$gte": 2020
              }
            }
          ]
        }
    )
    print('向量检索成功')
    print('响应头:', resp)
    print('响应体:', data)
except CosServiceError as e:
    if e.get_error_code() == "NotFoundException":
        print("资源不存在")
    print(f'检索失败: {e}')

参数说明

参数名称
描述
类型
是否必选
Index
向量索引名称
String
是
Bucket
向量存储桶名称，<BucketName-APPID>格式，例如 examplebucket-1250000000，支持小写字母、数字和 - ，长度限制3-63字符
String
是
QueryVector
查询向量，输入向量的维度和数据类型必须与创建向量索引时所指定的相匹配
VectorData
是
TopK
查询返回的近似最近邻搜索结果向量数目，取值范围为1～30
Int
是
Filter
查询向量时的预过滤器
Json Value
否
ReturnData
是否返回向量数据（默认值：false）
Boolean
否
ReturnMetadata
是否返回向量元数据（默认值：false）
Boolean
否
ReturnDistance
是否返回结果向量和查询向量的相似度距离（默认值：false）
Boolean
否
VectorData 结构 QueryVector 的内容 ：
参数名称
描述
类型
是否必选
float32
float32 类型的向量数据
float32 数组
是

返回结果说明

返回值

resp (dict): 响应头信息
data (dict): 响应数据，包含检索到的向量列表，每一项包含向量的基本信息，详细结构可参见 QueryVectors。

错误处理

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

中国站
目录