向量Vectors - 对象存储 OSS

向量数据是向量Bucket的核心资源，由三个部分组成：

Key（主键）：向量的唯一标识符
Data（向量数据）：高维数值数组
Metadata（元数据）：Key-Value结构，用于存储向量的附加属性信息（如类别、来源、时间戳等），可用于查询时的后置过滤。

每个向量都存储在特定的向量索引中，继承索引的维度、数据类型和距离度量配置。

写入向量数据

将向量数据及其元数据上传到指定的向量索引中。

单个向量索引表最多可存储 20 亿行向量数据。
写入向量数据的 API （PutVectors）的 QPS 上限为 1000，单并发最大支持批量写入 500 条，所有并发批量最多写入 2500 条。

说明

PutVectors 接口对 Standard 模式和 Fusion 模式的向量索引通用，在 Fusion 模式下部分请求参数和返回字段会有所不同，具体请参见 PutVectors。

控制台

在向量Bucket页面，单击已创建的向量Bucket。
在刚创建的索引行，单击查看数据，单击向量数据插入。
配置向量数据，可以同时添加多条向量数据：
- 主键值：为向量设置唯一标识符。
- 向量数据：输入向量数值数组，格式为 JSON 数组，如：[0.1, 0.2, 0.3, 0.4, 0.5]。向量维度需要和选择的 embedded 模型的维度一致。
- 元数据：可添加元数据信息，如类别、标题、时间戳等。总大小最大支持 200KB。
  - 支持添加的元数据类型为 String、Number、Boolean、List。
  - 单行向量最多支持添加共 100 个可过滤元数据和不可过滤元数据字段。
  - 不可过滤元数据key的大小是 1 ~ 63字符。
  - 单个向量的单个可筛选元数据大小上限：2 KB。
  - 根据可过滤元数据进行标量后过滤时，单次过滤指令中的可过滤元数据长度最大为 20KB，单次过滤指令中的可过滤元数据数量最多为 1024 个，过滤指令最多支持 8 层，且支持过滤内容为空。
单击确定完成数据插入。

SDK

Python

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

parser = argparse.ArgumentParser(description="vector put 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)

    vectors = [
        {
            "data": {"float32":  [0.1] * 128},
            "key": "key1",
            "metadata": {"metadata1": "value1", "metadata2": "value2"}
        },
        {
            "data": {"float32": [0.2] * 128},
            "key": "key2",
            "metadata": {"metadata3": "value3", "metadata4": "value4"}
        }
    ]

    result = vector_client.put_vectors(oss_vectors.models.PutVectorsRequest(
        bucket=args.bucket,
        index_name=args.index_name,
        vectors=vectors,
    ))

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

if __name__ == "__main__":
    main()

Go

package main

import (
	"context"
	"flag"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/vectors"
)

var (
	region     string
	bucketName string
	accountId  string
)

func init() {
	flag.StringVar(&region, "region", "", "The region in which the vector bucket is located.")
	flag.StringVar(&bucketName, "bucket", "", "The name of the vector bucket.")
	flag.StringVar(&accountId, "account-id", "", "The id of vector account.")
}

func main() {
	flag.Parse()
	if len(bucketName) == 0 || len(region) == 0 || len(accountId) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters")
	}

	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region).WithAccountId(accountId).
		// 如需通过公网访问，请将此处设置为false或删除此行
		WithUseInternalEndpoint(true)

	client := vectors.NewVectorsClient(cfg)

	request := &vectors.PutVectorsRequest{
		Bucket:    oss.Ptr(bucketName),
		IndexName: oss.Ptr("exampleIndex"),

		Vectors: [ ]map[string]any{

			{
				"key": "vector1",
				"data": map[string]any{

					"float32": [ ]float32{1.2, 2.5, 3},

				},
				"metadata": map[string]any{
					"Key1": "value2",

					"Key2": [ ]string{"1", "2", "3"},

				},
			},
		},
	}
	result, err := client.PutVectors(context.TODO(), request)
	if err != nil {
		log.Fatalf("failed to put vectors %v", err)
	}
	log.Printf("put vectors result:%#v\n", result)
}

Java

import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider;
import com.aliyun.sdk.service.oss2.vectors.OSSVectorsClient;
import com.aliyun.sdk.service.oss2.vectors.models.PutVectorsRequest;
import com.aliyun.sdk.service.oss2.vectors.models.PutVectorsResult;
import java.util.*;

public class PutVectorsSample {
    public static void main(String[] args) throws Exception {
        CredentialsProvider provider = new EnvironmentVariableCredentialsProvider();
        try (OSSVectorsClient client = OSSVectorsClient.newBuilder()
                .region("cn-hangzhou")
                .accountId("1234567890")
                .credentialsProvider(provider)
                .build()) {
            List<Map<String, Object>> vectors = Arrays.asList(
                    createVector("key1", new Float[]{1.0f, 2.0f, 3.0f}, "description1"),
                    createVector("key2", new Float[]{4.0f, 5.0f, 6.0f}, "description2"));
            PutVectorsRequest request = PutVectorsRequest.newBuilder()
                    .bucket("examplebucket")
                    .indexName("exampleindex")
                    .vectors(vectors)
                    .build();
            PutVectorsResult result = client.putVectors(request);
            System.out.printf("status code: %d, request id: %s%n", result.statusCode(), result.requestId());
        }
    }

    private static Map<String, Object> createVector(String key, Float[] data, String description) {
        Map<String, Object> vector = new HashMap<>();
        vector.put("key", key);
        Map<String, Object> vectorData = new HashMap<>();
        vectorData.put("float32", Arrays.asList(data));
        vector.put("data", vectorData);
        Map<String, String> meta = new HashMap<>();
        meta.put("description", description);
        vector.put("metadata", meta);
        return vector;
    }
}

ossutil

在名为 examplebucket 的向量Bucket中，向名为 index 的向量索引添加一个向量，该向量的数据为 1，向量主键为 vector1，元数据为 {"Key1": "32"}。

使用JSON配置文件，vectors.json内容如下：

[
  {
    "data": {
      "float32": [1]
    },
    "key": "vector1",
    "metadata": {
      "Key1": "32"
    }
  }
]

命令示例：

ossutil vectors-api put-vectors --bucket examplebucket --index-name index --vectors file://vectors.json

使用JSON配置参数：

ossutil vectors-api put-vectors --bucket examplebucket --index-name index --vectors "[{\"data\":{\"float32\":[1]},\"key\":\"vector1\",\"metadata\":{\"Key1\":\"32\"}}]"

API

调用PutVectors接口以写入向量数据。

执行向量检索

使用语义内容、元数据等条件，执行向量检索操作，快速定位目标数据。具备亚秒级检索性能，召回率为 90% 左右。

Standard Mode

Standard 模式索引使用 QueryVectors 接口进行向量相似性检索。

控制台

当前使用控制台进行向量数据查询仅支持单行向量相似检索，多次循环检索请使用 API 或 SDK。

在向量Bucket页面，单击已创建的向量Bucket。
在刚创建的索引行，单击查看数据，单击向量数据查询。
配置检索参数：
- 向量数据：输入查询向量数据，格式为 JSON 数组，如：[0.15, 0.25, 0.35, 0.45, 0.55]
- 可过滤元数据：通过元数据进行结果过滤，如类别、时间范围等。
- TopK（返回数量）：设置返回最相似结果的数量，默认范围：1～30。
- 返回相似距离：选择是否返回相似度距离值
- 返回元数据：选择是否返回向量的元数据信息
单击确定执行查询

系统返回按相似度排序的向量列表。

SDK

Python

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()

Go

package main

import (
	"context"
	"flag"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/vectors"
)

var (
	region     string
	bucketName string
	accountId  string
	indexName  string
)

func init() {
	flag.StringVar(&region, "region", "", "The region in which the vector bucket is located.")
	flag.StringVar(&bucketName, "bucket", "", "The name of the vector bucket.")
	flag.StringVar(&accountId, "account-id", "", "The id of vector account.")
	flag.StringVar(&indexName, "index", "", "The name of vector index.")
}

func main() {
	flag.Parse()
	if len(bucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, bucket name required")
	}

	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}

	if len(accountId) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, accounId required")
	}

	if len(indexName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, index required")
	}

	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region).WithAccountId(accountId).
		// 如需通过公网访问，请将此处设置为false或删除此行
		WithUseInternalEndpoint(true)

	client := vectors.NewVectorsClient(cfg)

	request := &vectors.QueryVectorsRequest{
		Bucket:    oss.Ptr(bucketName),
		IndexName: oss.Ptr(indexName),
		Filter: map[string]any{
			"$and": []map[string]any{
				{
					"type": map[string]any{
						"$in": []string{"comedy", "documentary"},
					},
				},
			},
		},
		QueryVector: map[string]any{
			"float32": []float32{float32(32)},
		},
		ReturnMetadata: oss.Ptr(true),
		ReturnDistance: oss.Ptr(true),
		TopK:           oss.Ptr(10),
	}
	result, err := client.QueryVectors(context.TODO(), request)
	if err != nil {
		log.Fatalf("failed to query vectors %v", err)
	}
	log.Printf("query vectors result:%#v\n", result)
}

Java

import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider;
import com.aliyun.sdk.service.oss2.vectors.OSSVectorsClient;
import com.aliyun.sdk.service.oss2.vectors.models.QueryVectorsRequest;
import com.aliyun.sdk.service.oss2.vectors.models.QueryVectorsResult;
import java.util.*;

public class QueryVectorsSample {
    public static void main(String[] args) throws Exception {
        CredentialsProvider provider = new EnvironmentVariableCredentialsProvider();
        try (OSSVectorsClient client = OSSVectorsClient.newBuilder()
                .region("cn-hangzhou")
                .accountId("1234567890")
                .credentialsProvider(provider)
                .build()) {
            Map<String, Object> queryVector = new HashMap<>();
            queryVector.put("float32", new float[]{0.1f, 0.2f, 0.3f});
            QueryVectorsRequest request = QueryVectorsRequest.newBuilder()
                    .bucket("examplebucket")
                    .indexName("exampleindex")
                    .queryVector(queryVector)
                    .topK(10)
                    .returnDistance(true)
                    .returnMetadata(false)
                    .build();
            QueryVectorsResult result = client.queryVectors(request);
            System.out.printf("status code: %d, request id: %s%n", result.statusCode(), result.requestId());
        }
    }
}

ossutil

在名为examplebucket的向量Bucket中名为 index 的向量索引里，type为comedy和documentary的向量中与查询向量最相似的前 10 条。

ossutil vectors-api query-vectors --bucket examplebucket --index-name index --filter "{\"$and\":[{\"type\":{\"$in\":[\"comedy\",\"documentary\"]}}]}" --query-vector "{\"float32\":[32]}" --top-k 10

API

调用QueryVectors接口以进行向量相似性检索。

Fusion Mode

Fusion 模式索引使用 QueryVectorsFusion 接口进行检索，支持向量检索、标量过滤、全文检索以及多路召回融合。相比 QueryVectors 按距离（distance）返回结果，QueryVectorsFusion 按相关性得分（score）返回结果，score 越大表示相关性越高。当前 Fusion 模式暂不支持通过控制台进行检索，请使用 SDK、ossutil 或 API。

SDK

Python

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 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()

Go

package main

import (
	"bytes"
	"context"
	"encoding/json"
	"flag"
	"fmt"
	"io"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/vectors"
)

var (
	region     string
	bucketName string
	accountId  string
	indexName  string
)

func init() {
	flag.StringVar(&region, "region", "", "The region in which the vector bucket is located.")
	flag.StringVar(&bucketName, "bucket", "", "The name of the vector bucket.")
	flag.StringVar(&accountId, "account-id", "", "The id of vector account.")
	flag.StringVar(&indexName, "index", "", "The name of vector index.")
}

func main() {
	flag.Parse()
	if len(bucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, bucket name required")
	}
	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}
	if len(accountId) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, accountId required")
	}
	if len(indexName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, index required")
	}

	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region).WithAccountId(accountId)

	client := vectors.NewVectorsClient(cfg)

	// 手动构造 QueryVectorsFusion 的 JSON 请求体
	// knn（向量检索）与 query（标量与全文过滤）可组合使用；knn 为对象数组，最多配置 3 个。
	bodyMap := map[string]any{
		"indexName": indexName,
		"knn": []map[string]any{
			{
				"field":         "text_vector",
				"queryVector":   []float32{float32(32)},
				"topK":          10,
				"numCandidates": 9,
				"filter": map[string]any{
					"meta_field_1": map[string]any{
						"$eq": "abc",
					},
				},
				"boost": 1,
			},
		},
		"query": map[string]any{
			"$and": []map[string]any{
				{"type": map[string]any{"$in": []string{"a", "b"}}},
				{"year": map[string]any{"$gte": 2020}},
			},
		},
		"returnMetadata":       true,
		"returnMetadataFields": []string{"key1", "key2"},
		"partitionKeys":        []string{"key1", "key2"},
		"limit":                10,
		"sort": []map[string]any{
			{
				"field_a":     map[string]any{"order": "asc"},
				"_score":      map[string]any{"order": "desc"},
				"_primaryKey": map[string]any{"order": "asc"},
			},
		},
	}

	bodyBytes, err := json.Marshal(bodyMap)
	if err != nil {
		log.Fatalf("failed to marshal body: %v", err)
	}

	// 手动构造 OperationInput
	input := &oss.OperationInput{
		OpName: "QueryVectorsFusion",
		Method: "POST",
		Headers: map[string]string{
			"Content-Type": "application/json",
		},
		Parameters: map[string]string{
			"queryVectorsFusion": "",
		},
		Bucket: oss.Ptr(bucketName),
		Body:   bytes.NewReader(bodyBytes),
	}

	// 直接调用 InvokeOperation
	output, err := client.InvokeOperation(context.TODO(), input)
	if err != nil {
		log.Fatalf("failed to query vectors fusion: %v", err)
	}
	defer func() {
		if output.Body != nil {
			output.Body.Close()
		}
	}()

	// 读取并解析响应
	body, err := io.ReadAll(output.Body)
	if err != nil {
		log.Fatalf("failed to read response body: %v", err)
	}

	var result map[string]any
	if err := json.Unmarshal(body, &result); err != nil {
		log.Fatalf("failed to unmarshal response: %v", err)
	}
	fmt.Printf("query vectors fusion result: %#v\n", result)
}

Java

import com.aliyun.sdk.service.oss2.OperationInput;
import com.aliyun.sdk.service.oss2.OperationOptions;
import com.aliyun.sdk.service.oss2.OperationOutput;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider;
import com.aliyun.sdk.service.oss2.transport.BinaryData;
import com.aliyun.sdk.service.oss2.utils.Base64Utils;
import com.aliyun.sdk.service.oss2.vectors.OSSVectorsClient;

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.HashMap;
import java.util.Map;

public class QueryVectorsFusionSample {
    public static void main(String[] args) throws Exception {
        CredentialsProvider provider = new EnvironmentVariableCredentialsProvider();
        try (OSSVectorsClient client = OSSVectorsClient.newBuilder()
                .region("cn-hangzhou")
                .accountId("1234567890")
                .credentialsProvider(provider)
                .build()) {

            String bucket = "examplebucket";
            String indexName = "exampleindex";

                        // 构造 QueryVectorsFusion 的 JSON 请求体
            String queryVectorsJson = "{
" +
                    "  \"indexName\": \"" + indexName + "\",
" +
                    "  \"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
" +
                    "}";

            Map<String, String> queryVectorsHeaders = new HashMap<>();
            queryVectorsHeaders.put("Content-Type", "application/json");
            queryVectorsHeaders.put("Content-MD5", calculateContentMD5(queryVectorsJson));

            Map<String, String> queryVectorsParameters = new HashMap<>();
            queryVectorsParameters.put("queryVectorsFusion", "");

            OperationInput queryVectorsInput = OperationInput.newBuilder()
                    .opName("QueryVectorsFusion")
                    .method("POST")
                    .bucket(bucket)
                    .headers(queryVectorsHeaders)
                    .parameters(queryVectorsParameters)
                    .body(BinaryData.fromString(queryVectorsJson))
                    .build();

            OperationOutput queryVectorsOutput = client.invokeOperation(queryVectorsInput, OperationOptions.defaults());

            System.out.println("QueryVectorsFusion status code: " + queryVectorsOutput.statusCode() +
                    ", request id: " + queryVectorsOutput.headers().get("x-oss-request-id") +
                    ", content: " + new String(queryVectorsOutput.body().get().toBytes(), StandardCharsets.UTF_8));
        }
    }

    private static String calculateContentMD5(String content) {
        try {
            MessageDigest md = MessageDigest.getInstance("MD5");
            byte[] digest = md.digest(content.getBytes(StandardCharsets.UTF_8));
            return Base64Utils.encodeToString(digest);
        } catch (NoSuchAlgorithmException e) {
            throw new RuntimeException("Failed to calculate MD5", e);
        }
    }
}

ossutil

命令格式

ossutil vectors-api invoke-operation --op-name queryVectorsFusion --method POST --parameters queryVectorsFusion --bucket value --body value

参数说明

参数	类型	说明
--op-name	string	操作名称，固定为`query-vectors-fusion`。
--method	string	HTTP请求方法，固定为`POST`。
--parameters	stringArray	查询参数，固定为`query-vectors-fusion`。
--bucket	string	向量Bucket名称。
--body	string	请求体，JSON格式，用于描述Fusion模式向量检索的条件。body中各字段的含义请参见QueryVectorsFusion接口文档。

说明

本命令通过ossutil的泛化命令invoke-operation调用QueryVectorsFusion接口发起请求。
关于支持的全局命令行选项，请参见支持的全局命令行选项。

使用示例

在名为examplebucket的向量Bucket中，对名为my_index的Fusion模式向量索引进行检索，返回与查询向量最相似的前 10 条向量及其元数据。

ossutil vectors-api invoke-operation --op-name queryVectorsFusion --method POST --parameters queryVectorsFusion --bucket examplebucket --body '{"indexName":"my_index","knn":[{"field":"text_vector","queryVector":[0.1,0.2,0.3],"topK":10,"numCandidates":100}],"returnMetadata":true}'

API

调用QueryVectorsFusion接口对 Fusion 模式的向量索引进行检索。

获取向量数据

说明

GetVectors 接口对 Standard 模式和 Fusion 模式的向量索引通用，在 Fusion 模式下部分请求参数和返回字段会有所不同，具体请参见 GetVectors。

控制台

在向量Bucket页面，单击已创建的向量Bucket，进入索引列表页面，单击索引名称，可以进入向量数据页面查看向量信息。

SDK

Python

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

parser = argparse.ArgumentParser(description="vector get 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)

    keys = ['key1', 'key2']

    result = vector_client.get_vectors(oss_vectors.models.GetVectorsRequest(
        bucket=args.bucket,
        index_name=args.index_name,
        keys=keys,
        return_data=True,
        return_metadata=True
    ))

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

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


if __name__ == "__main__":
    main()

Go

package main

import (
	"context"
	"flag"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/vectors"
)

var (
	region     string
	bucketName string
	accountId  string
)

func init() {
	flag.StringVar(&region, "region", "", "The region in which the vector bucket is located.")
	flag.StringVar(&bucketName, "bucket", "", "The name of the vector bucket.")
	flag.StringVar(&accountId, "account-id", "", "The id of vector account.")
}

func main() {
	flag.Parse()
	if len(bucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, bucket name required")
	}

	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}

	if len(accountId) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, accounId required")
	}

	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region).WithAccountId(accountId).
		// 如需通过公网访问，请将此处设置为false或删除此行
		WithUseInternalEndpoint(true)

	client := vectors.NewVectorsClient(cfg)

	request := &vectors.GetVectorsRequest{
		Bucket:         oss.Ptr(bucketName),
		IndexName:      oss.Ptr("index"),
		Keys:           []string{"key1", "key2", "key3"},
		ReturnData:     oss.Ptr(true),
		ReturnMetadata: oss.Ptr(false),
	}
	result, err := client.GetVectors(context.TODO(), request)
	if err != nil {
		log.Fatalf("failed to get vectors %v", err)
	}
	log.Printf("get vectors result:%#v\n", result)
}

Java

import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider;
import com.aliyun.sdk.service.oss2.vectors.OSSVectorsClient;
import com.aliyun.sdk.service.oss2.vectors.models.GetVectorsRequest;
import com.aliyun.sdk.service.oss2.vectors.models.GetVectorsResult;
import java.util.*;

public class GetVectorsSample {
    public static void main(String[] args) throws Exception {
        CredentialsProvider provider = new EnvironmentVariableCredentialsProvider();
        try (OSSVectorsClient client = OSSVectorsClient.newBuilder()
                .region("cn-hangzhou")
                .accountId("1234567890")
                .credentialsProvider(provider)
                .build()) {
            GetVectorsRequest request = GetVectorsRequest.newBuilder()
                    .bucket("examplebucket")
                    .indexName("exampleindex")
                    .keys(Arrays.asList("key1", "key2"))
                    .returnData(true)
                    .returnMetadata(true)
                    .build();
            GetVectorsResult result = client.getVectors(request);
            System.out.printf("status code: %d, request id: %s%n", result.statusCode(), result.requestId());
        }
    }
}

ossutil

获取名为 examplebucket 的向量Bucket中索引名为index，主键为key和key1的向量属性。

ossutil vectors-api get-vectors --bucket examplebucket --index-name index --keys key,key1

API

调用GetVectors接口以获取指定的向量数据。

列举向量数据

说明

ListVectors 接口对 Standard 模式和 Fusion 模式的向量索引通用，在 Fusion 模式下部分请求参数和返回字段会有所不同，具体请参见 ListVectors。

控制台

在向量Bucket页面，单击已创建的向量Bucket，进入索引列表页面，单击索引名称。

SDK

Python

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

parser = argparse.ArgumentParser(description="list vectors sample")

parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')
parser.add_argument('--account_id', help='The account id.', required=True)
parser.add_argument('--bucket', help='The name of the bucket.', required=True)
parser.add_argument('--index_name', help='The name of the vector index.', 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

    client = oss_vectors.Client(cfg)

    # Create the Paginator for the ListVectors operation
    paginator = client.list_vectors_paginator()

    # Create request with bucket and index name
    request = oss_vectors.models.ListVectorsRequest(
        bucket=args.bucket,
        index_name=args.index_name
    )

    # Iterate through the vectors pages
    for page in paginator.iter_page(request):
        for o in page.vectors:
            print(f'Vector: {o}')

if __name__ == "__main__":
    main()

Go

package main

import (
	"context"
	"flag"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/vectors"
)

var (
	region     string
	bucketName string
	accountId  string
	indexName  string
)

func init() {
	flag.StringVar(&region, "region", "", "The region in which the vector bucket is located.")
	flag.StringVar(&bucketName, "bucket", "", "The name of the vector bucket.")
	flag.StringVar(&accountId, "account-id", "", "The id of vector account.")
	flag.StringVar(&indexName, "index", "", "The name of vector index.")
}

func main() {
	flag.Parse()
	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}

	if len(bucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, bucket name required")
	}

	if len(accountId) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, accounId required")
	}

	if len(indexName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, index required")
	}

	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region).WithAccountId(accountId).
		// 如需通过公网访问，请将此处设置为false或删除此行
		WithUseInternalEndpoint(true)

	client := vectors.NewVectorsClient(cfg)

	request := &vectors.ListVectorsRequest{
		Bucket:         oss.Ptr(bucketName),
		IndexName:      oss.Ptr(indexName),
		ReturnMetadata: oss.Ptr(true),
		ReturnData:     oss.Ptr(false),
	}

	p := client.NewListVectorsPaginator(request)

	var i int
	log.Println("Vectors:")
	for p.HasNext() {
		i++

		page, err := p.NextPage(context.TODO())
		if err != nil {
			log.Fatalf("failed to get page %v, %v", i, err)
		}

		for _, v := range page.Vectors {
			log.Printf("vector:%v\n", v)
		}
	}
}

Java

import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider;
import com.aliyun.sdk.service.oss2.vectors.OSSVectorsClient;
import com.aliyun.sdk.service.oss2.vectors.models.ListVectorsRequest;
import com.aliyun.sdk.service.oss2.vectors.models.ListVectorsResult;

public class ListVectorsSample {
    public static void main(String[] args) throws Exception {
        CredentialsProvider provider = new EnvironmentVariableCredentialsProvider();
        try (OSSVectorsClient client = OSSVectorsClient.newBuilder()
                .region("cn-hangzhou")
                .accountId("1234567890")
                .credentialsProvider(provider)
                .build()) {
            ListVectorsRequest request = ListVectorsRequest.newBuilder()
                    .bucket("examplebucket")
                    .indexName("exampleindex")
                    .build();
            ListVectorsResult result = client.listVectors(request);
            System.out.printf("status code: %d, request id: %s%n", result.statusCode(), result.requestId());
        }
    }
}

ossutil

列举名为 examplebucket 的向量Bucket中索引名为index下的所有向量。

ossutil vectors-api list-vectors --bucket examplebucket --index-name index

API

调用ListVectors接口以列举向量索引中的所有向量数据。

删除向量数据

支持批量删除向量数据。删除操作不可逆，请谨慎操作，确保已备份重要数据。

说明

DeleteVectors 接口对 Standard 模式和 Fusion 模式的向量索引通用，在 Fusion 模式下部分请求参数和返回字段会有所不同，具体请参见 DeleteVectors。

控制台

在向量Bucket页面，单击已创建的向量Bucket，进入索引列表页面，单击索引名称，进入向量数据页面查看向量信息，选择需要删除的向量数据完成删除操作。

SDK

Python

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

parser = argparse.ArgumentParser(description="vector delete 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)

    keys = ['key1', 'key2', 'key3']

    result = vector_client.delete_vectors(oss_vectors.models.DeleteVectorsRequest(
        bucket=args.bucket,
        index_name=args.index_name,
        keys=keys,
    ))

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

if __name__ == "__main__":
    main()

Go

package main

import (
	"context"
	"flag"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/vectors"
)

var (
	region     string
	bucketName string
	accountId  string
)

func init() {
	// 定义命令行参数
	flag.StringVar(&region, "region", "", "The region in which the vector bucket is located.")
	flag.StringVar(&bucketName, "bucket", "", "The name of the vector bucket.")
	flag.StringVar(&accountId, "account-id", "", "The id of vector account.")
}

func main() {
	// 解析命令行参数
	flag.Parse()
	
	// 验证必需参数
	if len(bucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, bucket name required")
	}

	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}

	if len(accountId) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, accountId required")
	}

	// 创建配置，设置凭证提供者、区域和账号ID
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region).
		WithAccountId(accountId).
		// 如需通过公网访问，请将此处设置为false或删除此行
		WithUseInternalEndpoint(true)

	// 创建向量存储客户端
	client := vectors.NewVectorsClient(cfg)

	// 构造删除向量数据的请求
	request := &vectors.DeleteVectorsRequest{
		Bucket:    oss.Ptr(bucketName),
		IndexName: oss.Ptr("index"),
		Keys: [ ]string{

			"key1", "key2",                          // 要删除的向量键列表
		},
	}
	
	// 执行删除向量数据的操作
	result, err := client.DeleteVectors(context.TODO(), request)
	if err != nil {
		log.Fatalf("failed to delete vectors %v", err)
	}

	// 输出操作结果
	log.Printf("delete vectors result:%#v\n", result)
}

Java

import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.EnvironmentVariableCredentialsProvider;
import com.aliyun.sdk.service.oss2.vectors.OSSVectorsClient;
import com.aliyun.sdk.service.oss2.vectors.models.DeleteVectorsRequest;
import com.aliyun.sdk.service.oss2.vectors.models.DeleteVectorsResult;
import java.util.*;

public class DeleteVectorsSample {
    public static void main(String[] args) throws Exception {
        CredentialsProvider provider = new EnvironmentVariableCredentialsProvider();
        try (OSSVectorsClient client = OSSVectorsClient.newBuilder()
                .region("cn-hangzhou")
                .accountId("1234567890")
                .credentialsProvider(provider)
                .build()) {
            DeleteVectorsRequest request = DeleteVectorsRequest.newBuilder()
                    .bucket("examplebucket")
                    .indexName("exampleindex")
                    .keys(Arrays.asList("key1", "key2"))
                    .build();
            DeleteVectorsResult result = client.deleteVectors(request);
            System.out.printf("status code: %d, request id: %s%n", result.statusCode(), result.requestId());
        }
    }
}

ossutil

删除向量存储空间examplebucket中向量名字为index，向量主键为key、key1的向量。

ossutil vectors-api delete-vectors --bucket examplebucket --index-name index --keys key,key1

API

调用DeleteVectors接口以删除向量数据。