对象存储 OSS：OSS Vectors 快速入门

步骤一：创建向量Bucket

创建一个向量Bucket，作为存储所有向量数据和索引的容器。

1. 在向量Bucket页面，单击创建向量 Bucket。

2. 配置Bucket信息：

   • 向量 Bucket 名称：为Bucket指定一个同主账号在同地域内全局唯一的名称。命名规则：3-32个字符，仅包含小写字母、数字和短横线(-)，且不能以短横线开头或结尾。

   • 地域：选择您业务所在的地域，例如“华南1（深圳）”。

3. 单击确定，完成创建。

步骤二：创建向量索引

Bucket 创建成功后，需要在其内部创建一个向量索引。索引定义了向量的结构（如维度）和检索方式（如距离度量），是存储和查询向量数据的基础。向量索引分为 Standard Mode 与 Fusion Mode 两种模式，您可以通过控制台、OSS SDK、ossutil 或 API 创建索引。

配置索引参数时，无论创建哪种模式的索引，均需先指定索引表名称，再选择索引模式，然后根据所选模式配置对应的关键参数：

• 索引表名称：为索引指定一个在 Bucket 内唯一的名称。命名规则：1-63 个字符，由字母和数字组成，且首字母必须为英文字母。

• 索引模式：根据业务场景选择 Standard Mode 或 Fusion Mode。

两种模式的关键参数与创建入口对比如下：

步骤三：上传向量数据

索引准备就绪后，下一步是将向量数据上传到指定的向量索引，以便后续进行检索。

1. 在索引列表中，找到您刚创建的索引，单击其右侧的查看数据。

2. 在索引页面，单击向量数据插入。

3. 配置向量数据，可以同时添加多条向量数据：

   • 主键值：为向量设置唯一标识符。

   • 向量数据：输入向量数值数组，格式为用逗号分隔的数字。向量的维度（数值个数）必须与步骤二中设置的向量维度完全一致。

   • 元数据：可添加元数据信息，如类别、标题、时间戳等，可在检索中用作精确过滤条件。

4. 单击确定完成数据插入。

步骤四：执行向量检索

完成数据准备后，整个流程的核心环节——向量检索便可以执行了。通常，会在自己的应用程序中通过SDK调用API，执行向量检索操作，快速定位目标数据。

以下Python SDK示例演示了如何检索与目标向量最相似、且type字段不为 "comedy" 或 "documentary" 的前 10 条数据。

import argparse
import alibabacloud_oss_v2 as oss
import alibabacloud_oss_v2.vectors as oss_vectors

parser = argparse.ArgumentParser(description="vector query vectors sample")
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
parser.add_argument('--bucket', help='The name of the bucket.', required=True)
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')
parser.add_argument('--index_name', help='The name of the vector index.', required=True)
parser.add_argument('--account_id', help='The account id.', required=True)

def main():
    args = parser.parse_args()

    # Loading credentials values from the environment variables
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Using the SDK's default configuration
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    cfg.region = args.region
    cfg.account_id = args.account_id
    cfg.use_internal_endpoint = True  # 如需通过公网访问，请将此处设置为False或删除此行
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    vector_client = oss_vectors.Client(cfg)

    query_filter = {
        "$and": [{
            "type": {
                "$nin": ["comedy", "documentary"]
            }
        }]
    }

    query_vector = {"float32": [0.1] * 128}

    result = vector_client.query_vectors(oss_vectors.models.QueryVectorsRequest(
        bucket=args.bucket,
        index_name=args.index_name,
        filter=query_filter,
        query_vector=query_vector,
        return_distance=True,
        return_metadata=True,
        top_k=10
    ))

    print(f'status code: {result.status_code},'
          f' request id: {result.request_id},'
          )

    if result.vectors:
        for vector in result.vectors:
            print(f'vector: {vector}')


if __name__ == "__main__":
    main()

若您使用的是 Fusion Mode 索引表，可调用 QueryVectorsFusion 接口执行混合检索。以下 Python SDK 示例演示了在向量近邻检索（knn）的基础上，结合 title 字段的全文检索，并通过 year 字段（大于等于 2020）进行标量过滤，返回相关性最高的前 10 条数据。

import argparse
import base64
import hashlib
import json

from requests.structures import CaseInsensitiveDict

import alibabacloud_oss_v2 as oss
import alibabacloud_oss_v2.vectors as oss_vectors
from alibabacloud_oss_v2 import OperationInput


parser = argparse.ArgumentParser(description="query vectors fusion sample")
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
parser.add_argument('--bucket', help='The name of the vector bucket.', required=True)
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')
parser.add_argument('--index_name', help='The name of the fusion vector index.', required=True)
parser.add_argument('--account_id', help='The account id.', required=True)


def main():
    args = parser.parse_args()

    # Loading credentials values from the environment variables
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Using the SDK's default configuration
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    cfg.region = args.region
    cfg.account_id = args.account_id
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    client = oss_vectors.Client(cfg)

    # Query vectors fusion
    json_data = json.dumps({
        'indexName': args.index_name,
        'knn': {
            'field': 'text_vector',
            'queryVector': [0.1, 0.2, 0.3, 0.4],
            'topK': 10,
            'numCandidates': 100,
            'filter': {
                'year': {
                    '$gte': 2020,
                },
            },
        },
        'query': {
            'title': {
                '$textMatch': {
                    'value': 'vector search',
                    'boost': 2.0,
                },
            },
        },
        'returnMetadata': True,
        'returnMetadataFields': ['title', 'category', 'year'],
        'limit': 10,
        'sort': [
            {
                '_score': {
                    'order': 'desc',
                },
            },
        ],
    })
    body = json_data.encode()
    content_md5 = base64.b64encode(hashlib.md5(body).digest()).decode()
    op_input = OperationInput(
        op_name='QueryVectorsFusion',
        method='POST',
        headers=CaseInsensitiveDict({
            'Content-Type': 'application/json',
            'Content-MD5': content_md5,
        }),
        parameters={
            'queryVectorsFusion': '',
        },
        bucket=args.bucket,
        body=body,
    )
    op_output = client.invoke_operation(op_input)
    print(f'QueryVectorsFusion status code: {op_output.status_code},'
          f' request id: {op_output.headers.get("x-oss-request-id", "")},'
          f' content: {op_output.http_response.content},')


if __name__ == "__main__":
    main()

后续步骤

向量 Bucket 的全流程操作均可通过控制台、OSS SDK、ossutil 或直接发起API调用完成。本快速入门仅展示上手最快的操作路径，完整配置与进阶用法见：

• 向量Bucket

• 向量Index

• 向量Vectors

• 访问控制和日志监控