Object Storage Service：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

• 存取控制和日誌監控