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

向量数据库VikingDB

请输入
  • 文档首页
    • 向量数据库VikingDBVikingDB 向量库向量库新版本（V2）API V2参考控制面API数据集(Collection)创建数据集-CreateVikingdbCollection
复制全文
下载 pdf
我的收藏
数据集(Collection)
创建数据集-CreateVikingdbCollection
复制全文
下载 pdf
我的收藏
创建数据集-CreateVikingdbCollection

概述

接口用于创建向量数据库的数据集（Collection）。

接口升级说明
  • 对应的V1接口为：https://www.volcengine.com/docs/84313/1254542
  • 使用区别：
V2接口V1接口
参数命名风格驼峰（CollectionName）下划线（collection_name）
参数类型Vectorize 类型为mapvectorize的数据类型是[]map。
主键参数位置Fields的子参数IsPrimaryKeyprimary_key

请求接口

请求向量数据库 VikingDB 的 OpenAPI 接口时，可以使用 ak、sk 构造签名进行鉴权。请参见控制面API调用流程，复制调用示例并填入必要信息。

调试

请求参数

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

参数概览

参数一级参数二级参数类型是否必填示例值描述
ProjectNameString否default项目名称

CollectionName

String

是

数据集名称
说明：

  • 必须以英文字母开头，可包含英文字母、数字、下划线和点号，且不能以点号结尾。
  • UTF-8 编码长度（字节）要求：[1, 128]。
  • 同账号下，所有 Collection 名称不能重复。
  • 同账号下，Collection 数量不超过 200 个。
DescriptionString否数据集描述
说明：小于 65535 字节
FieldsList是详见下文 字段定义 小节
VectorizeMap否详见下文 向量化设置 小节
FullTextList否详见下文 全文检索设置 小节

字段定义

通过 Fields 定义数据集包含的字段及其类型，并设置主键、向量维度和默认值等字段属性。

参数一级参数二级参数类型是否必填示例值描述
FieldsList是字段列表

FieldName

String

是

字段名称
说明：

  • 只能使用英文字母、数字、下划线 _，并以英文字母开头，不能为空。
  • 长度（字节）要求：[1, 128]。
  • 同一个 Collection 下，Field 名称不能重复。
  • 单个 Collection 下，field 数量不超过 200 个。
FieldTypeString是字段类型，详见下文 FieldType。
DimIntegerFieldType 为 vector 时必填稠密向量维度，取值范围 [4, 4096]。仅 vector 字段可设置该参数，其他字段类型传入 Dim 会返回参数错误。字段维度本身不要求为 4 的倍数；使用 Int8 量化索引时才要求维度为 4 的倍数。
IsPrimaryKeyBoolean否是否为主键字段。可以为数据集指定 1 个主键字段（string 或 int64 类型）。若没有指定，则使用自动生成的主键，字段名为 AUTO_ID。

DefaultValue

任意类型

否

按字段类型确定

字段默认值。
省略时：

  • int64 默认为 0。
  • float32 默认为 0.0。
  • string 默认为 "default"。
  • bool 默认为 false。
  • list<int64> 默认为 [0]。
  • list<string> 默认为 ["default"]。
  • date_time 默认为 1970-01-01T00:00:00Z。
  • geo_point 默认为 "0, 0"。
  • list<geo_point> 默认为空列表。
  • 主键及 vector、sparse_vector、tensor、text、image、video 不允许显式设置 DefaultValue。
  • text 的隐式默认值为空字符串。

FieldType

字段类型格式可为主键说明
int64整型数值是整数
注：当作为主键时，需满足该字段取值不为 0
float32浮点数值否浮点数
string字符串是字符串
推荐使用方式：当用于枚举值过滤时，推荐长度不超过 128 字节
硬性限制：要求不超过 65535 字节；当作为主键时，需满足长度不超过 256 字节
booltrue/false否布尔类型
list<string>字符串数组否字符串数组
推荐使用方式：当用于枚举值过滤时，列表长度不超过 32 个，单元素不超过 1024 字节
硬性限制：列表长度不超过 20000，单元素不超过 1024 字节，总大小不超过 1 MB
list<int64>整型数组否整数数组
硬性限制：列表长度不超过 1024
vector向量（浮点数数组）
float32/float64 压缩为 bytes 后的 base64 编码		否稠密向量
硬性限制：长度范围为 [4, 4096]。向量字段本身不要求维度为 4 的倍数；使用 Int8 量化索引时才有该要求。
sparse_vector输入格式为 <token_id, token_weight> 的字典列表，用于表征稀疏向量的非零位下标及其对应的值，其中 token_id 为 string 类型，token_weight 为 float 类型否稀疏向量

tensor

张量：输入格式为 MN 的二维数组（向量矩阵），以 shape 为 48 的二维数组为例

tensor_tuple = [
    [0.12, 0.34, -0.21, 0.56, 0.78, -0.45, 0.89, -0.10],
    [0.09, 0.41, -0.18, 0.62, 0.71, -0.39, 0.82, -0.15],
    [0.15, 0.37, -0.24, 0.59, 0.75, -0.42, 0.86, -0.08],
    [0.11, 0.39, -0.20, 0.57, 0.77, -0.44, 0.88, -0.12]
]

否

张量 tensor

text字符串否文本
若为向量化字段，则值不能为空。
若为全文检索字段，可以为空；空文本按空文本语义处理。
单个 text 字段值长度不超过 1 MB。
一个数据集内所有 text 字段值的总大小不超过 4 MB。
当 text 字段配置了全文检索时，推荐单字段写入大小不超过 64 KB。若有超大文档，建议先进行文档分片等预处理操作；过长文本可能导致检索效果下降，并降低分词处理速度。
image字符串否图片
若为向量化字段，则值不能为空。（若否，可以为空）
图片 TOS 链接：tos://{bucket}/{object}
http/https 格式 URL 链接
对应图片需满足宽高长度大于 14 px，像素小于 3600 万
可参考：多模态向量化

video

map

否

视频
若为向量化字段，则值不能为空。（若否，可以为空）
视频 TOS 链接：tos://{bucket}/{object}
http/https 格式 URL 链接
对应视频需满足大小不超过 50 MB
可参考：多模态向量化

{
  "value": "tos://{bucket}/{object}", // 或 http/https 格式 URL 链接，该字段必填
  "fps": 0.2 // 取值范围 0.2-5，选填
}
date_timestring否分钟级别：
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
注：取值需满足在 1970-01-01T00:00:00Z 至 3000-01-01T00:00:00Z 之间
geo_pointstring否地理坐标 longitude,latitude，其中 longitude 取值为 (-180, 180)，latitude 取值为 (-90, 90)
例如：116.408108,39.915023

向量化设置

创建数据集时有两种向量使用方式：如果已有向量数据，可在 Fields 中定义 vector、sparse_vector 或 tensor 字段，写入数据时直接传入向量；如果只有待向量化的文本、图片或视频等多模态数据，可通过 Vectorize 配置向量化模型，由向量库在写入数据时自动生成向量：

参数一级参数二级参数类型是否必填示例值描述
VectorizeMap否向量化模型设置。仅当数据集需要向量化时填写。参考：【向量库】表征方式配置参考
DenseMap是稠密向量化模型配置
ModelNameString是模型名称
ModelVersionString否模型版本
TextFieldString否文本向量化字段名称
ImageFieldString否图片向量化字段名称
VideoFieldString否视频向量化字段名称
DimInteger否模型默认维度如果需要生成稠密向量，可显式指定向量维度；取值必须属于所选模型在下方模型列表中声明的可选稠密向量维度。省略时使用模型默认维度。
InstructionMap否Instruction 配置
通过设置 instructions 引导模型更准确地聚焦输入内容的关键信息，以提升向量表示精度，详细参考：Instruction参数设置
SparseMap否稀疏向量化配置
ModelNameString是模型名称
ModelVersionString否模型版本
TextFieldString否文本向量化字段名称
InstructionMap否Instruction 配置
通过设置 instructions 引导模型更准确地聚焦输入内容的关键信息，以提升向量表示精度，详细参考：Instruction参数设置
TensorMap否张量化配置
注：当前若需要配置张量字段，需将张量化字段名、张量化模型名、张量化模型版本的配置与稠密向量化模型名、稠密向量化模型版本的配置保持一致，且模型固定为"doubao-embedding-vision"，模型版本固定为"251215"
ModelNameString是模型名称
注：当前配置张量化字段需将张量化模型和稠密向量化模型均配置为**"doubao-embedding-vision"。**
ModelVersionString否模型版本
注：当前配置张量化字段需将张量化模型版本和稠密向量化模型版本均配置为**"251215"**
TextFieldString否文本张量化字段名称
注：张量化字段名称需与稠密向量化字段名称一致
ImageFieldString否图片张量化字段名称
注：张量化字段名称需与稠密向量化字段名称一致
VideoFieldString否视频张量化字段名称
注：张量化字段名称需与稠密向量化字段名称一致
NDimint是张量阶数
目前固定张量维度阶数为2，可视作向量矩阵
Shapelist是张量维度
格式为[M,N]：
M：向量矩阵的行数，取值[2,64]间的整数
N：向量矩阵的列数，取值[4,2048]间的整数，且当N>4时，N必须是8的倍数
InstructionMap否Instruction 配置
通过设置 instructions 引导模型更准确地聚焦输入内容的关键信息，以提升向量表示精度，详细参考：Instruction参数设置

Instruction

参数一级参数类型是否必填默认值描述
InstructionMap否Instruction 配置
通过设置 instructions 引导模型更准确地聚焦输入内容的关键信息，以提升向量表示精度
若不填该字段则等价于 AutoFill=true
AutoFillBoolean是true自动填充 Instruction 内容
写入数据时，会自动根据模态信息填充 Instruction 内容。如果模型不支持Instruction，填写后不报错但不生效。各模型的填充规则见下表模型列表。

模型列表

模型名称模型版本支持向量化类型默认稠密向量维度可选稠密向量维度文本截断长度支持稀疏向量支持张量可支持 Instruction支持入库 Instruction
auto fill 内容		支持检索 Instruction
auto fill 内容
bge-large-zhdefaulttext10241024512否否是null为这个句子生成表示以用于检索相关文章：
拼接到 text 最前面
bge-m3defaulttext102410248192是否否nullnull
bge-visualized-m3defaulttext、image 及其组合102410248192否否否nullnull
doubao-embedding-vision250615兼容 241215 的用法。另外，支持 full_modal_seq（文/图/视频序列）20482048、1024128k否否是null根据这个问题，找到能回答这个问题的相应文本或图片：
拼接到 text 最前面

doubao-embedding-vision

251215

兼容 241215 的用法，支持 full_modal_seq（文/图/视频序列）。另外支持张量

2048

2048、1024

128k

是

是

是

 
Instruction:Compress the {} into one word.
Query:

占位符里根据数据集模态信息（如 text、text and image、text and image and video ...）自动填充

 
Target_modality: {}.
Instruction:根据这个问题，找到能回答这个问题的相应文本或图片
Query:

占位符里根据数据集模态信息（如 text、text and image、text and image and video ...）自动填充

全文检索设置

通过 FullText 为 text 字段配置全文检索。配置后，写入原始文本即可由向量库自动完成文本解析，并可在 SearchByKeywords 接口中使用 bm25 模式检索。

参数一级参数二级参数类型是否必填示例值描述

FullText

List

否

全文检索配置。配置后，可在 SearchByKeywords 接口中使用 bm25 模式进行全文检索。
说明：

  • 最多可配置 5 个 text 字段为全文检索字段。
  • 同一个字段不能重复配置。
  • 全文检索字段与向量化字段相互独立：字段可以只配置全文检索、只配置向量化，也可以同时配置全文检索和向量化。
  • 配置 FullText 后，用户写入数据时只需要写入原始 text 字段，不需要写入分词结果。
  • 对已开启全文检索的字段，后续 UpsertData / UpdateData 会自动完成文本解析。

FullTextConfig 结构：

参数名必选类型备注
Field是String全文检索字段名。该字段必须已在 Fields 中定义，且 FieldType 必须为 text。
Analyzer是AnalyzerConfig全文检索解析器配置。AnalyzerConfig 结构见下。

AnalyzerConfig 结构：

参数名必选类型备注

Tokenizer

与 Tokenizers 二选一

String

单分词器配置，用于兼容原有配置方式。不能与 Tokenizers 同时设置。
可选值：

  • standard：通用分词，支持中文、英文及中英文混合文本。
  • zh：中文分词，适用于以中文为主的文本。
  • whitespace：按空白字符分割（空格、\t、\n、\r、\v、\f），适用于客户端已自行完成分词，并使用空白字符分隔词项的场景。
  • cjk_char_ngram_2：对连续的 CJK（中文、日文、韩文）字符按相邻两个字符切分；非 CJK 字符会中断连续切分。
  • cjk_rare_char：提取 CJK 文本中的生僻字，并按单字切分。
  • pinyin：写入时将汉字转换为不带声调的全拼，支持多音字。例如，写入“北京”时生成 bei、jing；检索时将连续的英文字母解析为拼音音节，例如，查询 beijing 时解析为 bei、jing。

Tokenizers

与 Tokenizer 二选一

List

多分词器配置。

  • 数组不能为空。
  • 不能包含重复项。
  • 不能与 Tokenizer 同时设置。
  • 每一项的可选值及含义与 Tokenizer 相同。
  • 系统会分别执行各分词器，再合并分词结果。

CharacterConverters

否

List

字符转换器。高级参数，主要用于控制分词前的字符归一化，不是常规效果调优参数；一般场景无需专门设置。
可选值：

  • en_lower_case：将大写英文字母转换为小写。
  • en_num_half_width：将全角英文字母和数字转换为半角。
  • 不传时，默认使用 ["en_lower_case", "en_num_half_width"]。
  • 显式传空数组 [] 时，表示不启用字符转换器。

StopWordsFilters

否

List

停用词过滤器。高级参数，主要用于控制分词后的停用词过滤，不是常规效果调优参数；一般场景无需专门设置。
可选值：

  • symbol：过滤常用标点符号。
  • symbol_simple：过滤常用标点符号精简版。
  • en：过滤常用英文停用词。
  • en_simple：过滤常用英文停用词精简版。
  • zh：过滤常用中文停用词。
  • zh_simple：过滤常用中文停用词精简版。
  • 不传时，默认使用 ["symbol", "en", "zh"]。
  • 显式传空数组 [] 时，表示不启用停用词过滤器。
  • 说明：pinyin 和 cjk_rare_char 的分词结果不会使用停用词过滤。

全文检索限制说明：

  • 单个 text 值参与 Analyzer 的输入推荐不超过64KB，最大长度不超过 1 MB。

  • 单个词项最大长度为 1 KB，超过 1 KB 的词项会被忽略。

    示例：

{
    "CollectionName": "coll_ft_1",
    "Fields": [
        {"FieldName": "f_int64_id", "FieldType": "int64", "IsPrimaryKey": true},
        {"FieldName": "f_text_1", "FieldType": "text"},
        {"FieldName": "f_vector", "FieldType": "vector", "Dim": 4}
    ],
    "FullText": [
        {
            "Field": "f_text_1",
            "Analyzer": {
                "Tokenizer": "standard"
            }
        }
    ]
}

返回参数

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

参数类型示例值描述
ResourceIdString资源ID
MessageStringsuccess操作结果信息

请求示例

创建带vector字段的数据集 

{
  "ProjectName": "default",
  "CollectionName": "my_test_coll_1",
  "Description": "this is my test collection",
  "Fields": [
    {
      "FieldName": "f_id",
      "FieldType": "string",
      "IsPrimaryKey": true
    },
    {
      "FieldName": "f_int64",
      "FieldType": "int64",
      "DefaultValue": -1
    },
    {
      "FieldName": "f_vector",
      "FieldType": "vector",
      "Dim": 1024
    },
    {
        "FieldName": "tensor_text_vector",
        "FieldType": "tensor",
        "NDim": 2,
        "Shape": [32, 2048]
    }
]
}

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

{
    "ProjectName": "default",
    "CollectionName": "my_test_coll_2",
    "Description": "",
    "Fields": [
        {"FieldName": "f_id", "FieldType": "int64", "IsPrimaryKey": true},
        {"FieldName": "f_text", "FieldType": "text" },
        {"FieldName": "f_image", "FieldType": "image" },
        {"FieldName": "f_video", "FieldType": "video" }
    ],
    "Vectorize": {
        "Dense": {
            "ModelName": "doubao-embedding-vision",
            "ModelVersion": "251215",
            "TextField": "f_text",
            "ImageField": "f_image",
            "Dim": 1024,
            "Instruction": {
                "AutoFill": true
            }
        },
        "Sparse": {
            "ModelName": "doubao-embedding-vision",
            "ModelVersion": "251215",
            "TextField": "f_text"
        },
        "Tensor": {
            "ModelName": "doubao-embedding-vision",
            "ModelVersion": "251215",
            "NDim": 2,
            "Shape": [64, 2048],
            "TextField": "f_text",
            "ImageField": "f_image"
        }
    }
}

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

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

{
    "ProjectName": "default",
    "CollectionName": "my_test_coll_vectorize_fulltext",
    "Description": "",
    "Fields": [
        {"FieldName": "f_id", "FieldType": "int64", "IsPrimaryKey": true},
        {"FieldName": "f_text", "FieldType": "text"}
    ],
    "Vectorize": {
        "Dense": {
            "ModelName": "bge-m3",
            "TextField": "f_text"
        }
    },
    "FullText": [
        {
            "Field": "f_text",
            "Analyzer": {
                "Tokenizer": "standard"
            }
        }
    ]
}

返回示例 

{
  "ResponseMetadata": {
    "RequestId": "20250331173619111231152071D44F42",
    "Action": "CreateVikingdbCollection",
    "Version": "2025-06-09",
    "Service": "vikingdb",
    "Region": "cn-beijing"
  },
  "Result": {
    "Message": "success"
  }
}

错误码

公共错误码请参见公共错误码文档。

参数说明补充

DefaultValue 的省略行为由 FieldType 决定：int64、float32、string、bool、list<int64>、list<string>、date_time、geo_point、list<geo_point> 使用参数表列出的类型默认值；主键及 vector、sparse_vector、tensor、text、image、video 不支持设置默认值。

请求接口补充

请求接口

  • HTTP 方法：POST
  • 请求路径：/
  • Host：vikingdb.<region>.volcengineapi.com
  • Query：Action=CreateVikingdbCollection&Version=2025-06-09

请求体使用本页参数表所列 JSON 结构；<region> 替换为实例所在地域。

参数说明补充

AutoFill=true 时服务按输入模态自动填充 Instruction；AutoFill=false 时服务完全不自动填充，调用方必须提供符合业务场景的自定义 Instruction。若同时省略自定义内容，服务不会回退到自动模板。

最近更新时间：2026.09.28 14:22:30
这个页面对您有帮助吗？
有用
有用
无用
无用