createVikingdbCollection--向量数据库VikingDB-火山引擎

文档中心

导航

createVikingdbCollection

最近更新时间：2025.11.03 12:22:36首次发布时间：2025.11.03 12:22:36

概述

接口用于对向量数据库的创建，单账号下最多创建200个数据集。

方法定义

public CreateVikingdbCollectionResponse createVikingdbCollection(CreateVikingdbCollectionRequest body) throws ApiException

请求参数

下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共参数。

参数	类型	是否必选	描述
projectName	String	否	项目的名称。对应火山引擎“项目”（project）的概念。不填则默认当做default处理。
collectionName	String	是	数据集的名称。限制：英文字母、数字、或下划线。且必须以英文字母开头。长度不超过64Byte。
description	String	否	数据集的描述。限制：英文字母、数字、或下划线。且必须以英文字母开头。长度不超过64Byte。
fields	List	是	数据集中的字段。限制：数据集内最多128个字段。
vectorize	VectorizeForCreateVikingdbCollectionInput	否	数据集的向量化配置。

FieldForCreateVikingdbCollectionInput 参数结构

参数	类型	是否必选	描述
fieldName	String	是	字段名。限制：英文字母、数字、或下划线。且必须以英文字母开头。长度不超过64Byte。
fieldType	FieldTypeEnum（枚举类型）	是	字段类型。
defaultValue	Object	否	字段内容默认值。注意：vector/sparse_vector/text/image/video类型字段不支持默认值。
dim	Integer	否	若字段类型是vector，该参数指定稠密向量的维度。支持4-4096且为4的整数倍。
isPrimaryKey	Boolean	否	是否为主键字段。可以为数据集指定1个主键字段（string或int64类型）。若没有指定，则使用自动生成的主键，字段名为"AUTO_ID"。

VectorizeForCreateVikingdbCollectionInput 参数结构

参数	类型	是否必选	描述
dense	DenseForCreateVikingdbCollectionInput	是	稠密向量化模型配置
sparse	SparseForCreateVikingdbCollectionInput	否	稀疏向量化模型配置

DenseForCreateVikingdbCollectionInput 和 SparseForCreateVikingdbCollectionInput 参数结构

参数	类型	是否必选	描述
modelName	ModelNameEnum（枚举类型）	是	模型名称。枚举值见embedding模型列表。
modelVersion	String	否	模型版本。若为doubao系模型，则必选模型版本。若为bge系模型，默认为default。
dim	Integer	否	稠密向量维度。各模型支持的维度见embedding模型列表。
textField	String	否	文本向量化字段名称。
imageField	String	否	图片向量化字段名称。
videoField	String	否	视频向量化字段名称。

field_type

字段类型	格式	可为主键	说明
int64	整型数值	是	整数
float32	浮点数值	否	浮点数
string	字符串	是	字符串。内容限制256byte
bool	true/false	否	布尔类型
list	字符串数组	否	字符串数组
list	整型数组	否	整数数组
vector	向量（浮点数数组） float32/float64压缩为bytes后的base64编码	否	稠密向量
sparse_vector	输入格式<token_id ,token_weight>的字典列表，来表征稀疏稀疏向量的非零位下标及其对应的值, 其中 token_id 是 string 类型, token_weight 是float 类型	否	稀疏向量
text	字符串	否	若为向量化字段，则值不能为空。（若否，可以为空）
image	字符串	否	若为向量化字段，则值不能为空。（若否，可以为空）图片tos链接 `tos://{bucket}/{object}` http/https格式链接
video	Object	否	{ "value": `tos://{bucket}/{object}`，http/https格式url链接，该字段必填 "fps": 0.2 （取值0.2-5，选填） }
date_time	string	否	分钟级别： `yyyy-MM-ddTHH:mmZ`或`yyyy-MM-ddTHH:mm±HH:mm` 秒级别： `yyyy-MM-ddTHH:mm:ssZ`或`yyyy-MM-ddTHH:mm:ss±HH:mm` 毫秒级别： `yyyy-MM-ddTHH:mm:ss.SSSZ`或`yyyy-MM-ddTHH:mm:ss.SSS±HH:mm` 例如："2025-08-12T11:33:56+08:00"
geo_point	string	否	地理坐标`longitude,latitude`，其中`longitude`取值(-180,180)，`latitude`取值(-90,90) 例如："116.408108,39.915023"

模型列表

模型名称	模型版本	支持向量化类型	默认稠密向量维度	可选稠密向量维度	文本截断长度	支持稀疏向量	可支持instruction
bge-large-zh	(default)	text	1024	1024	512	否	是
bge-m3	(default)	text	1024	1024	8192	是	否
bge-visualized-m3	(default)	text、image及其组合	1024	1024	8192	否	否
doubao-embedding	240715	text	2048	512, 1024, 2048	4096	否	是
doubao-embedding-large	240915	text	2048	512, 1024, 2048, 4096	4096	否	是
doubao-embedding-vision	250328	text、image及其组合	2048	2048, 1024	8192	否	是
doubao-embedding-vision	250615	兼容241215和250328的用法。另外，支持full_modal_seq（文/图/视频序列）	2048	2048, 1024	128k	否	是

返回参数

下表仅列出本接口特有的返回参数。更多信息请参见返回结构。

参数	类型	描述
message	String	有关请求状态的消息。
resourceId	String	新数据集的ID。

请求示例

创建带vector字段的数据集

import com.volcengine.ApiClient;
import com.volcengine.ApiException;
import com.volcengine.sign.Credentials;
import com.volcengine.vikingdb.VikingdbApi;
import com.volcengine.vikingdb.model.*;
import java.util.Arrays;

public class TestCreateVikingdbCollectionWithVector {
    public static void main(String[] args) {
        String ak = System.getenv("AK"); // input your ak
        String sk = System.getenv("SK"); // input your sk
        String endpoint = "vikingdb.cn-beijing.volcengineapi.com"; // 填写向量库控制面v2的域名  https://www.volcengine.com/docs/84313/1792715
        String region = "cn-beijing"; // 服务区域

        ApiClient apiClient = new ApiClient()
                .setEndpoint(endpoint)
                .setCredentials(Credentials.getCredentials(ak, sk))
                .setRegion(region);

        VikingdbApi api = new VikingdbApi(apiClient);

        CreateVikingdbCollectionRequest request = new CreateVikingdbCollectionRequest()
                .collectionName("test_coll_for_java_sdk_with_vector")
                .description("this is a test collection of vikingdb")
                .fields(Arrays.asList(
                        new FieldForCreateVikingdbCollectionInput().fieldName("f_int64_id").fieldType(FieldForCreateVikingdbCollectionInput.FieldTypeEnum.INT64).isPrimaryKey(true), // 主键字段
                        new FieldForCreateVikingdbCollectionInput().fieldName("f_string_1").fieldType(FieldForCreateVikingdbCollectionInput.FieldTypeEnum.STRING),
                        new FieldForCreateVikingdbCollectionInput().fieldName("f_int64_1").fieldType(FieldForCreateVikingdbCollectionInput.FieldTypeEnum.INT64),
                        new FieldForCreateVikingdbCollectionInput().fieldName("f_float_1").fieldType(FieldForCreateVikingdbCollectionInput.FieldTypeEnum.FLOAT32),
                        new FieldForCreateVikingdbCollectionInput().fieldName("f_list_string_1").fieldType(FieldForCreateVikingdbCollectionInput.FieldTypeEnum.LIST_STRING_),
                        new FieldForCreateVikingdbCollectionInput().fieldName("f_vector").fieldType(FieldForCreateVikingdbCollectionInput.FieldTypeEnum.VECTOR).dim(4), // 稠密向量字段，并设置维度
                        new FieldForCreateVikingdbCollectionInput().fieldName("f_sparse_vector").fieldType(FieldForCreateVikingdbCollectionInput.FieldTypeEnum.SPARSE_VECTOR) // 稀疏向量字段
                ));

        try {
            CreateVikingdbCollectionResponse response = api.createVikingdbCollection(request);
            System.out.println("all response content: " + response);
            System.out.println("response getResponseMetadata: " + response.getResponseMetadata());
            System.out.println("response getResponseMetadata: " + response.getResponseMetadata().getAction());
            System.out.println("response getMessage: " + response.getMessage());
            System.out.println("response getResourceId: " + response.getResourceId());

            System.out.println("response RequestId: " + response.getResponseMetadata().getRequestId());
            System.out.println("response Action: " + response.getResponseMetadata().getAction());
            System.out.println("response Region: " + response.getResponseMetadata().getRegion());
            System.out.println("response Service: " + response.getResponseMetadata().getService());
        } catch (ApiException e) {
            System.out.println("exception http code: " + e.getCode());
            System.out.println("exception RequestId: " + e.getResponseMetadata().getRequestId());
            System.out.println("exception Action: " + e.getResponseMetadata().getAction());
            System.out.println("exception Region: " + e.getResponseMetadata().getRegion());
            System.out.println("exception Service: " + e.getResponseMetadata().getService());
            System.out.println("exception Error.Code: " + e.getResponseMetadata().getError().getCode());
            System.out.println("exception Error.Message: " + e.getResponseMetadata().getError().getMessage());
            System.out.println("exception http response body: " + e.getResponseBody());
        }
    }
}

创建带vectorize(向量化)的数据集

import com.volcengine.ApiClient;
import com.volcengine.ApiException;
import com.volcengine.sign.Credentials;

import com.volcengine.vikingdb.VikingdbApi;
import com.volcengine.vikingdb.model.*;

import java.util.Arrays;

public class TestCreateVikingdbCollectionWithVectorize {
    public static void main(String[] args) {
        String ak = System.getenv("AK"); // input your ak
        String sk = System.getenv("SK"); // input your sk
        String endpoint = "vikingdb.cn-beijing.volcengineapi.com"; // 填写向量库控制面v2的域名  https://www.volcengine.com/docs/84313/1792715
        String region = "cn-beijing"; // 服务区域

        ApiClient apiClient = new ApiClient()
                .setEndpoint(endpoint)
                .setCredentials(Credentials.getCredentials(ak, sk))
                .setRegion(region);

        VikingdbApi api = new VikingdbApi(apiClient);

        CreateVikingdbCollectionRequest request = new CreateVikingdbCollectionRequest()
                .collectionName("test_coll_for_java_sdk_with_vectorize")
                .description("this is a test collection of vikingdb")
                .fields(Arrays.asList(
                        new FieldForCreateVikingdbCollectionInput().fieldName("f_int64_id").fieldType(FieldForCreateVikingdbCollectionInput.FieldTypeEnum.INT64).isPrimaryKey(true), // 主键字段
                        new FieldForCreateVikingdbCollectionInput().fieldName("f_string_1").fieldType(FieldForCreateVikingdbCollectionInput.FieldTypeEnum.STRING),
                        new FieldForCreateVikingdbCollectionInput().fieldName("f_int64_1").fieldType(FieldForCreateVikingdbCollectionInput.FieldTypeEnum.INT64),
                        new FieldForCreateVikingdbCollectionInput().fieldName("f_float_1").fieldType(FieldForCreateVikingdbCollectionInput.FieldTypeEnum.FLOAT32),
                        new FieldForCreateVikingdbCollectionInput().fieldName("f_list_string_1").fieldType(FieldForCreateVikingdbCollectionInput.FieldTypeEnum.LIST_STRING_),
                        new FieldForCreateVikingdbCollectionInput().fieldName("f_text_1").fieldType(FieldForCreateVikingdbCollectionInput.FieldTypeEnum.TEXT),
                        new FieldForCreateVikingdbCollectionInput().fieldName("f_image_1").fieldType(FieldForCreateVikingdbCollectionInput.FieldTypeEnum.IMAGE)
                ))
                .vectorize(new VectorizeForCreateVikingdbCollectionInput()
                        .dense(new DenseForCreateVikingdbCollectionInput()
                                .modelName(DenseForCreateVikingdbCollectionInput.ModelNameEnum.DOUBAO_EMBEDDING_VISION)
                                .modelVersion("250615")
                                .dim(1024)
                                .textField("f_text_1")
                                .imageField("f_image_1")
                        )
                        .sparse(new SparseForCreateVikingdbCollectionInput()
                                .modelName(SparseForCreateVikingdbCollectionInput.ModelNameEnum.BGE_M3)
                                .modelVersion("default")
                                .textField("f_text_1")
                        )
                );

        try {
            CreateVikingdbCollectionResponse response = api.createVikingdbCollection(request);
            System.out.println("all response content: " + response);
            System.out.println("response getMessage: " + response.getMessage());
            System.out.println("response getResourceId: " + response.getResourceId());

            System.out.println("response RequestId: " + response.getResponseMetadata().getRequestId());
            System.out.println("response Action: " + response.getResponseMetadata().getAction());
            System.out.println("response Region: " + response.getResponseMetadata().getRegion());
            System.out.println("response Service: " + response.getResponseMetadata().getService());
        } catch (ApiException e) {
            System.out.println("exception http code: " + e.getCode());
            System.out.println("exception RequestId: " + e.getResponseMetadata().getRequestId());
            System.out.println("exception Action: " + e.getResponseMetadata().getAction());
            System.out.println("exception Region: " + e.getResponseMetadata().getRegion());
            System.out.println("exception Service: " + e.getResponseMetadata().getService());
            System.out.println("exception Error.Code: " + e.getResponseMetadata().getError().getCode());
            System.out.println("exception Error.Message: " + e.getResponseMetadata().getError().getMessage());
            System.out.println("exception http response body: " + e.getResponseBody());
        }
    }
}