You need to enable JavaScript to run this app.
文档中心
向量数据库VikingDB

向量数据库VikingDB

请输入
  • 文档首页
    • 向量数据库VikingDBVikingDB 向量库向量库新版本（V2）SDK V2参考Java SDK控制面SDK数据集(collection)createVikingdbCollection
复制全文
下载 pdf
我的收藏
数据集(collection)
createVikingdbCollection
复制全文
下载 pdf
我的收藏
createVikingdbCollection

概述

createVikingdbCollection 用于创建向量数据库的数据集（Collection）。单个账号下最多可创建 200 个数据集，每个数据集最多包含 200 个字段。

每个 Collection 有且仅有一个主键。可以通过 fields.isPrimaryKey 显式指定一个 string 或 int64 类型的主键字段；未指定时，系统自动生成名为 AUTO_ID 的主键字段。

创建数据集时：

  • 已有向量数据时，在 fields 中定义 vector 或 sparse_vector 字段。
  • 需要由向量库对文本、图片或视频自动生成向量时，配置 vectorize。
  • 需要使用 BM25 全文检索时，为 text 字段配置 fullText。全文检索字段与向量化字段相互独立，同一个 text 字段可以同时配置向量化和全文检索。

方法定义 
public CreateVikingdbCollectionResponse createVikingdbCollection(
        CreateVikingdbCollectionRequest body
) throws ApiException

请求参数

参数概览

请求参数类型为 CreateVikingdbCollectionRequest。

参数必须类型备注
projectName否String项目名称。不传时按 default 处理。
collectionName是String数据集名称。必须以英文字母开头，可包含英文字母、数字、下划线和点号，不能以点号结尾；UTF-8 编码长度为 1-128 字节。同一账号下名称不能重复。
description否String数据集描述，长度小于 65535 字节。
fields是List<FieldForCreateVikingdbCollectionInput>字段列表。单个 Collection 最多包含 200 个字段。
vectorize否VectorizeForCreateVikingdbCollectionInput向量化模型配置。仅在需要由向量库自动生成向量时设置。
fullText否List<FullTextForCreateVikingdbCollectionInput>全文检索配置。最多可配置 5 个 text 字段，同一字段不能重复配置。

字段定义

fields 的元素类型为 FieldForCreateVikingdbCollectionInput。

参数必须类型备注
fieldName是String字段名称。必须以英文字母开头，只能包含英文字母、数字和下划线；UTF-8 编码长度为 1-128 字节。同一 Collection 下字段名不能重复。
fieldType是FieldForCreateVikingdbCollectionInput.FieldTypeEnum字段类型，支持的 Java 枚举值见下表。
dimfieldType 为 VECTOR 时必填Integer稠密向量维度，范围为 [4, 4096]。仅 VECTOR 字段可设置。使用 Int8 量化索引时，维度必须是 4 的倍数。
isPrimaryKey否Boolean是否为主键字段。仅 STRING 或 INT64 字段可作为主键，一个数据集最多指定一个主键。
defaultValue否Object字段默认值。主键及 VECTOR、SPARSE_VECTOR、tensor、TEXT、IMAGE、VIDEO 字段不允许显式设置。TEXT 的隐式默认值为空字符串。

FieldType

参数类型备注
INT64int64整数。作为主键时，字段值不能为 0。
FLOAT32float32浮点数。
STRINGstring字符串。用于枚举过滤时推荐不超过 128 字节；硬性限制为 65535 字节；作为主键时不超过 256 字节。
BOOLbool布尔值。
LIST_STRING_list<string>字符串数组。列表最多 20000 个元素，单元素不超过 1024 字节，总大小不超过 1 MB。
LIST_INT64_list<int64>整数数组，列表最多 1024 个元素。
VECTORvector稠密向量，维度范围为 [4, 4096]。
SPARSE_VECTORsparse_vector稀疏向量。
TEXTtext文本。单字段不超过 1 MB；一个数据集内所有 text 字段总大小不超过 4 MB。全文检索字段推荐单字段写入不超过 64 KB。
IMAGEimage图片，可使用 TOS、HTTP 或 HTTPS 地址。图片宽高需大于 14 px，像素总数小于 3600 万。
VIDEOvideo视频，可使用 TOS、HTTP 或 HTTPS 地址，大小不超过 50 MB。
DATE_TIMEdate_time日期时间，取值范围为 1970-01-01T00:00:00Z 至 3000-01-01T00:00:00Z。
GEO_POINTgeo_point地理坐标，格式为 longitude,latitude。longitude 范围为 (-180, 180)，latitude 范围为 (-90, 90)。

字段默认值

各可设置默认值的字段在省略 defaultValue 时使用以下值：

参数类型备注
INT64Long默认值为 0。
FLOAT32Float默认值为 0.0。
STRINGString默认值为 "default"。
BOOLBoolean默认值为 false。
LIST_INT64_List<Long>默认值为 [0]。
LIST_STRING_List<String>默认值为 ["default"]。
DATE_TIMEString默认值为 1970-01-01T00:00:00Z。
GEO_POINTString默认值为 "0, 0"。
LIST_GEO_POINT_List<String>默认值为空列表。

向量化设置

vectorize 的类型为 VectorizeForCreateVikingdbCollectionInput。

参数必须类型备注
dense是DenseForCreateVikingdbCollectionInput稠密向量化模型配置。
sparse否SparseForCreateVikingdbCollectionInput稀疏向量化模型配置。
tensor否TensorForCreateVikingdbCollectionInput张量化模型配置。

Dense

dense 的类型为 DenseForCreateVikingdbCollectionInput。

参数必须类型备注
modelName是DenseForCreateVikingdbCollectionInput.ModelNameEnum模型名称。当前 API 模型列表包括 BGE_LARGE_ZH、BGE_M3、BGE_VISUALIZED_M3 和 DOUBAO_EMBEDDING_VISION。
modelVersion否String模型版本。BGE 系模型默认使用 default；豆包模型应指定对应版本。
textField否String文本向量化字段名称。
imageField否String图片向量化字段名称。
videoField否String视频向量化字段名称。
dim否Integer稠密向量维度。必须是所选模型支持的可选维度；省略时使用模型默认维度。
instruction否InstructionForCreateVikingdbCollectionInputInstruction 配置。

Sparse

sparse 的类型为 SparseForCreateVikingdbCollectionInput。

参数必须类型备注
modelName是SparseForCreateVikingdbCollectionInput.ModelNameEnum模型名称。应选择当前 API 模型列表中支持稀疏向量的模型。
modelVersion否String模型版本。
textField否String文本向量化字段名称。
instruction否InstructionForCreateVikingdbCollectionInputInstruction 配置。

Tensor

tensor 的类型为 TensorForCreateVikingdbCollectionInput。

参数必须类型备注
modelName是TensorForCreateVikingdbCollectionInput.ModelNameEnum当前固定为 DOUBAO_EMBEDDING_VISION，并需与 dense.modelName 保持一致。
modelVersion否String当前固定为 251215，并需与 dense.modelVersion 保持一致。
textField否String文本张量化字段名称，需与 Dense 配置的对应字段一致。
imageField否String图片张量化字段名称，需与 Dense 配置的对应字段一致。
videoField否String视频张量化字段名称，需与 Dense 配置的对应字段一致。
ndim是Integer张量阶数，当前固定为 2。Java 链式方法名为 ndim(...)。
shape是List<Integer>张量维度，格式为 [M, N]。M 为 2-64；N 为 4-2048，且 N 大于 4 时必须是 8 的倍数。
instruction否InstructionForCreateVikingdbCollectionInputInstruction 配置。

Instruction

instruction 的类型为 InstructionForCreateVikingdbCollectionInput。

参数必须类型备注
autoFill是Boolean是否在写入数据时根据模态信息自动填充 Instruction。省略整个 instruction 配置时，等价于 autoFill=true。模型不支持 Instruction 时，该配置不生效。

模型列表

  • BGE_LARGE_ZH：模型版本为 default，支持文本稠密向量化；默认及可选维度均为 1024，文本截断长度为 512；支持 Instruction，不支持稀疏向量和张量。
  • BGE_M3：模型版本为 default，支持文本稠密及稀疏向量化；默认及可选维度均为 1024，文本截断长度为 8192；不支持张量和 Instruction。
  • BGE_VISUALIZED_M3：模型版本为 default，支持文本、图片及其组合；默认及可选维度均为 1024，文本截断长度为 8192；不支持稀疏向量、张量和 Instruction。
  • DOUBAO_EMBEDDING_VISION 版本 250615：支持文本、图片及 full-modal-seq；默认维度为 2048，可选 2048 或 1024，文本截断长度为 128k；支持 Instruction，不支持稀疏向量和张量。
  • DOUBAO_EMBEDDING_VISION 版本 251215：支持文本、图片、full-modal-seq、稀疏向量和张量；默认维度为 2048，可选 2048 或 1024，文本截断长度为 128k；支持 Instruction。

全文检索设置

fullText 的元素类型为 FullTextForCreateVikingdbCollectionInput。

参数必须类型备注
field是String全文检索字段名。该字段必须已在 fields 中定义，且字段类型必须为 TEXT。
analyzer是AnalyzerForCreateVikingdbCollectionInput全文检索解析器配置。

配置 fullText 后：

  • 写入数据时只需写入原始 text 字段，无需写入分词结果。
  • 后续调用 UpsertData 或 UpdateData 时，系统会自动完成文本解析。
  • 单个 Analyzer 输入推荐不超过 64 KB，最大不超过 1 MB。
  • 单个词项最大为 1 KB，超过限制的词项会被忽略。

Analyzer

analyzer 的类型为 AnalyzerForCreateVikingdbCollectionInput。

参数必须类型备注
tokenizer二选一String单分词器配置，不能与 tokenizers 同时设置。可选值为 standard、zh、whitespace、cjk_char_ngram_2、cjk_rare_char、pinyin。
tokenizers二选一List<String>多分词器配置。数组不能为空、不能包含重复项，且不能与 tokenizer 同时设置。每一项的可选值与 tokenizer 相同。
characterConverters否List<String>字符转换器。可选值为 en_lower_case、en_num_half_width。不传时默认使用两者；显式传空列表表示不启用字符转换。
stopWordsFilters否List<String>停用词过滤器。可选值为 symbol、symbol_simple、en、en_simple、zh、zh_simple。不传时默认使用 symbol、en、zh；显式传空列表表示不启用停用词过滤。

返回参数

返回类型为 CreateVikingdbCollectionResponse。

参数必须类型备注
message成功时返回String操作结果信息。成功时为 success。
resourceId成功时返回String新创建数据集的资源 ID。
responseMetadata是ResponseMetadata请求元数据，可通过 getResponseMetadata() 获取，包括 Request ID、Action、Region 和 Service 等信息。

请求示例

运行示例前，请完成以下准备：

  • 按“安装与 client 初始化”文档在 Java 项目中引入 VikingDB 控制面 SDK。
  • 在火山引擎控制台“密钥管理”中创建 AK/SK，并配置 AK、SK 环境变量。
  • 根据地域和访问域名替换示例中的 Endpoint 和 Region。

创建带 vector 字段的数据集 

import com.volcengine.ApiClient;
import com.volcengine.ApiException;
import com.volcengine.sign.Credentials;
import com.volcengine.vikingdb.VikingdbApi;
import com.volcengine.vikingdb.model.CreateVikingdbCollectionRequest;
import com.volcengine.vikingdb.model.CreateVikingdbCollectionResponse;
import com.volcengine.vikingdb.model.FieldForCreateVikingdbCollectionInput;

import java.util.Arrays;

public class CreateCollectionWithVector {
    public static void main(String[] args) {
        ApiClient apiClient = new ApiClient()
                .setEndpoint("vikingdb.cn-beijing.volcengineapi.com")
                .setCredentials(Credentials.getCredentials(
                        System.getenv("AK"),
                        System.getenv("SK")
                ))
                .setRegion("cn-beijing");

        VikingdbApi api = new VikingdbApi(apiClient);

        CreateVikingdbCollectionRequest request =
                new CreateVikingdbCollectionRequest()
                        .projectName("default")
                        .collectionName("<YOUR_COLLECTION_NAME>")
                        .description("Collection with vector fields")
                        .fields(Arrays.asList(
                                new FieldForCreateVikingdbCollectionInput()
                                        .fieldName("f_id")
                                        .fieldType(
                                                FieldForCreateVikingdbCollectionInput
                                                        .FieldTypeEnum.STRING
                                        )
                                        .isPrimaryKey(true),
                                new FieldForCreateVikingdbCollectionInput()
                                        .fieldName("f_int64")
                                        .fieldType(
                                                FieldForCreateVikingdbCollectionInput
                                                        .FieldTypeEnum.INT64
                                        )
                                        .defaultValue(-1L),
                                new FieldForCreateVikingdbCollectionInput()
                                        .fieldName("f_vector")
                                        .fieldType(
                                                FieldForCreateVikingdbCollectionInput
                                                        .FieldTypeEnum.VECTOR
                                        )
                                        .dim(1024),
                                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("message: " + response.getMessage());
            System.out.println("resourceId: " + response.getResourceId());
            System.out.println(
                    "responseMetadata: " + response.getResponseMetadata()
            );
            System.out.println(
                    "requestId: "
                            + response.getResponseMetadata().getRequestId()
            );
            System.out.println(
                    "action: " + response.getResponseMetadata().getAction()
            );
            System.out.println(
                    "region: " + response.getResponseMetadata().getRegion()
            );
            System.out.println(
                    "service: " + response.getResponseMetadata().getService()
            );
        } catch (ApiException e) {
            System.err.println("http code: " + e.getCode());
            System.err.println(
                    "requestId: " + e.getResponseMetadata().getRequestId()
            );
            System.err.println(
                    "action: " + e.getResponseMetadata().getAction()
            );
            System.err.println(
                    "region: " + e.getResponseMetadata().getRegion()
            );
            System.err.println(
                    "service: " + e.getResponseMetadata().getService()
            );
            System.err.println(
                    "error code: "
                            + e.getResponseMetadata().getError().getCode()
            );
            System.err.println(
                    "error message: "
                            + e.getResponseMetadata().getError().getMessage()
            );
            System.err.println("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.CreateVikingdbCollectionRequest;
import com.volcengine.vikingdb.model.CreateVikingdbCollectionResponse;
import com.volcengine.vikingdb.model.DenseForCreateVikingdbCollectionInput;
import com.volcengine.vikingdb.model.FieldForCreateVikingdbCollectionInput;
import com.volcengine.vikingdb.model.InstructionForCreateVikingdbCollectionInput;
import com.volcengine.vikingdb.model.SparseForCreateVikingdbCollectionInput;
import com.volcengine.vikingdb.model.TensorForCreateVikingdbCollectionInput;
import com.volcengine.vikingdb.model.VectorizeForCreateVikingdbCollectionInput;

import java.util.Arrays;

public class CreateCollectionWithVectorize {
    public static void main(String[] args) {
        ApiClient apiClient = new ApiClient()
                .setEndpoint("vikingdb.cn-beijing.volcengineapi.com")
                .setCredentials(Credentials.getCredentials(
                        System.getenv("AK"),
                        System.getenv("SK")
                ))
                .setRegion("cn-beijing");

        VikingdbApi api = new VikingdbApi(apiClient);

        InstructionForCreateVikingdbCollectionInput instruction =
                new InstructionForCreateVikingdbCollectionInput()
                        .autoFill(true);

        CreateVikingdbCollectionRequest request =
                new CreateVikingdbCollectionRequest()
                        .projectName("default")
                        .collectionName("<YOUR_COLLECTION_NAME>")
                        .description("Collection with automatic vectorization")
                        .fields(Arrays.asList(
                                new FieldForCreateVikingdbCollectionInput()
                                        .fieldName("f_id")
                                        .fieldType(
                                                FieldForCreateVikingdbCollectionInput
                                                        .FieldTypeEnum.INT64
                                        )
                                        .isPrimaryKey(true),
                                new FieldForCreateVikingdbCollectionInput()
                                        .fieldName("f_text")
                                        .fieldType(
                                                FieldForCreateVikingdbCollectionInput
                                                        .FieldTypeEnum.TEXT
                                        ),
                                new FieldForCreateVikingdbCollectionInput()
                                        .fieldName("f_image")
                                        .fieldType(
                                                FieldForCreateVikingdbCollectionInput
                                                        .FieldTypeEnum.IMAGE
                                        )
                        ))
                        .vectorize(
                                new VectorizeForCreateVikingdbCollectionInput()
                                        .dense(
                                                new DenseForCreateVikingdbCollectionInput()
                                                        .modelName(
                                                                DenseForCreateVikingdbCollectionInput
                                                                        .ModelNameEnum
                                                                        .DOUBAO_EMBEDDING_VISION
                                                        )
                                                        .modelVersion("251215")
                                                        .textField("f_text")
                                                        .imageField("f_image")
                                                        .dim(1024)
                                                        .instruction(instruction)
                                        )
                                        .sparse(
                                                new SparseForCreateVikingdbCollectionInput()
                                                        .modelName(
                                                                SparseForCreateVikingdbCollectionInput
                                                                        .ModelNameEnum
                                                                        .DOUBAO_EMBEDDING_VISION
                                                        )
                                                        .modelVersion("251215")
                                                        .textField("f_text")
                                        )
                                        .tensor(
                                                new TensorForCreateVikingdbCollectionInput()
                                                        .modelName(
                                                                TensorForCreateVikingdbCollectionInput
                                                                        .ModelNameEnum
                                                                        .DOUBAO_EMBEDDING_VISION
                                                        )
                                                        .modelVersion("251215")
                                                        .textField("f_text")
                                                        .imageField("f_image")
                                                        .ndim(2)
                                                        .shape(Arrays.asList(64, 2048))
                                                        .instruction(instruction)
                                        )
                        );

        try {
            CreateVikingdbCollectionResponse response =
                    api.createVikingdbCollection(request);
            System.out.println("all response content: " + response);
            System.out.println("message: " + response.getMessage());
            System.out.println("resourceId: " + response.getResourceId());
            System.out.println(
                    "responseMetadata: " + response.getResponseMetadata()
            );
            System.out.println(
                    "requestId: "
                            + response.getResponseMetadata().getRequestId()
            );
            System.out.println(
                    "action: " + response.getResponseMetadata().getAction()
            );
            System.out.println(
                    "region: " + response.getResponseMetadata().getRegion()
            );
            System.out.println(
                    "service: " + response.getResponseMetadata().getService()
            );
        } catch (ApiException e) {
            System.err.println("http code: " + e.getCode());
            System.err.println(
                    "requestId: " + e.getResponseMetadata().getRequestId()
            );
            System.err.println(
                    "action: " + e.getResponseMetadata().getAction()
            );
            System.err.println(
                    "region: " + e.getResponseMetadata().getRegion()
            );
            System.err.println(
                    "service: " + e.getResponseMetadata().getService()
            );
            System.err.println(
                    "error code: "
                            + e.getResponseMetadata().getError().getCode()
            );
            System.err.println(
                    "error message: "
                            + e.getResponseMetadata().getError().getMessage()
            );
            System.err.println("response body: " + e.getResponseBody());
        }
    }
}

创建同时开启向量化和全文检索的数据集

以下示例中，f_text 同时用于向量化和全文检索。后续调用 searchByKeywords 且不指定 mode 时，默认优先使用 bm25。

import com.volcengine.ApiClient;
import com.volcengine.ApiException;
import com.volcengine.sign.Credentials;
import com.volcengine.vikingdb.VikingdbApi;
import com.volcengine.vikingdb.model.AnalyzerForCreateVikingdbCollectionInput;
import com.volcengine.vikingdb.model.CreateVikingdbCollectionRequest;
import com.volcengine.vikingdb.model.CreateVikingdbCollectionResponse;
import com.volcengine.vikingdb.model.DenseForCreateVikingdbCollectionInput;
import com.volcengine.vikingdb.model.FieldForCreateVikingdbCollectionInput;
import com.volcengine.vikingdb.model.FullTextForCreateVikingdbCollectionInput;
import com.volcengine.vikingdb.model.VectorizeForCreateVikingdbCollectionInput;

import java.util.Arrays;

public class CreateCollectionWithVectorizeAndFullText {
    public static void main(String[] args) {
        ApiClient apiClient = new ApiClient()
                .setEndpoint("vikingdb.cn-beijing.volcengineapi.com")
                .setCredentials(Credentials.getCredentials(
                        System.getenv("AK"),
                        System.getenv("SK")
                ))
                .setRegion("cn-beijing");

        VikingdbApi api = new VikingdbApi(apiClient);

        CreateVikingdbCollectionRequest request =
                new CreateVikingdbCollectionRequest()
                        .projectName("default")
                        .collectionName("<YOUR_COLLECTION_NAME>")
                        .description("Collection with vectorize and full text")
                        .fields(Arrays.asList(
                                new FieldForCreateVikingdbCollectionInput()
                                        .fieldName("f_id")
                                        .fieldType(
                                                FieldForCreateVikingdbCollectionInput
                                                        .FieldTypeEnum.INT64
                                        )
                                        .isPrimaryKey(true),
                                new FieldForCreateVikingdbCollectionInput()
                                        .fieldName("f_text")
                                        .fieldType(
                                                FieldForCreateVikingdbCollectionInput
                                                        .FieldTypeEnum.TEXT
                                        )
                        ))
                        .vectorize(
                                new VectorizeForCreateVikingdbCollectionInput()
                                        .dense(
                                                new DenseForCreateVikingdbCollectionInput()
                                                        .modelName(
                                                                DenseForCreateVikingdbCollectionInput
                                                                        .ModelNameEnum.BGE_M3
                                                        )
                                                        .modelVersion("default")
                                                        .textField("f_text")
                                        )
                        )
                        .fullText(Arrays.asList(
                                new FullTextForCreateVikingdbCollectionInput()
                                        .field("f_text")
                                        .analyzer(
                                                new AnalyzerForCreateVikingdbCollectionInput()
                                                        .tokenizer("standard")
                                                        .characterConverters(Arrays.asList(
                                                                "en_lower_case",
                                                                "en_num_half_width"
                                                        ))
                                                        .stopWordsFilters(Arrays.asList(
                                                                "symbol",
                                                                "en",
                                                                "zh"
                                                        ))
                                        )
                        ));

        try {
            CreateVikingdbCollectionResponse response =
                    api.createVikingdbCollection(request);
            System.out.println("all response content: " + response);
            System.out.println("message: " + response.getMessage());
            System.out.println("resourceId: " + response.getResourceId());
            System.out.println(
                    "responseMetadata: " + response.getResponseMetadata()
            );
            System.out.println(
                    "requestId: "
                            + response.getResponseMetadata().getRequestId()
            );
            System.out.println(
                    "action: " + response.getResponseMetadata().getAction()
            );
            System.out.println(
                    "region: " + response.getResponseMetadata().getRegion()
            );
            System.out.println(
                    "service: " + response.getResponseMetadata().getService()
            );
        } catch (ApiException e) {
            System.err.println("http code: " + e.getCode());
            System.err.println(
                    "requestId: " + e.getResponseMetadata().getRequestId()
            );
            System.err.println(
                    "action: " + e.getResponseMetadata().getAction()
            );
            System.err.println(
                    "region: " + e.getResponseMetadata().getRegion()
            );
            System.err.println(
                    "service: " + e.getResponseMetadata().getService()
            );
            System.err.println(
                    "error code: "
                            + e.getResponseMetadata().getError().getCode()
            );
            System.err.println(
                    "error message: "
                            + e.getResponseMetadata().getError().getMessage()
            );
            System.err.println("response body: " + e.getResponseBody());
        }
    }
}
最近更新时间：2026.11.05 15:27:19
这个页面对您有帮助吗？
有用
有用
无用
无用