文档中心

向量数据库VikingDB

数据集(Collection)

createVikingdbCollection

概述

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

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

创建数据集时：

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

方法定义

response = client.create_vikingdb_collection(request)

其中：

client 类型为 VIKINGDBApi。
request 类型为 CreateVikingdbCollectionRequest。
返回类型为 CreateVikingdbCollectionResponse。

请求参数

参数概览

请求参数类型为 CreateVikingdbCollectionRequest。

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

字段定义

fields 的元素类型为 FieldForCreateVikingdbCollectionInput。

参数	必须	类型	备注
field_name	是	`str`	字段名称。必须以英文字母开头，只能包含英文字母、数字和下划线；UTF-8 编码长度为 1-128 字节。同一 Collection 下字段名不能重复。
field_type	是	`str`	字段类型，支持的字符串取值见下表。
dim	`field_type` 为 `vector` 时必填	`int`	稠密向量维度，范围为 [4, 4096]。仅 `vector` 字段可设置。使用 Int8 量化索引时，维度必须是 4 的倍数。
is_primary_key	否	`bool`	是否为主键字段。仅 `string` 或 `int64` 字段可作为主键，一个数据集最多指定一个主键。
default_value	否	`object`	字段默认值。主键及 `vector`、`sparse_vector`、`tensor`、`text`、`image`、`video` 字段不允许显式设置。`text` 的隐式默认值为空字符串。

FieldType

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

字段默认值

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

参数	类型	备注
`int64`	`int`	默认值为 `0`。
`float32`	`float`	默认值为 `0.0`。
`string`	`str`	默认值为 `"default"`。
`bool`	`bool`	默认值为 `False`。
`list<int64>`	`list[int]`	默认值为 `[0]`。
`list<string>`	`list[str]`	默认值为 `["default"]`。
`date_time`	`str`	默认值为 `1970-01-01T00:00:00Z`。
`geo_point`	`str`	默认值为 `"0, 0"`。

向量化设置

vectorize 的类型为 VectorizeForCreateVikingdbCollectionInput。

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

Dense

dense 的类型为 DenseForCreateVikingdbCollectionInput。

参数	必须	类型	备注
model_name	是	`str`	模型名称。当前 API 模型列表包括 `bge-large-zh`、`bge-m3`、`bge-visualized-m3` 和 `doubao-embedding-vision`。
model_version	否	`str`	模型版本。BGE 系模型默认使用 `default`；豆包模型应指定对应版本。
text_field	否	`str`	文本向量化字段名称。
image_field	否	`str`	图片向量化字段名称。
video_field	否	`str`	视频向量化字段名称。
dim	否	`int`	稠密向量维度。必须是所选模型支持的可选维度；省略时使用模型默认维度。
instruction	否	`InstructionForCreateVikingdbCollectionInput`	Instruction 配置。

Sparse

sparse 的类型为 SparseForCreateVikingdbCollectionInput。

参数	必须	类型	备注
model_name	是	`str`	模型名称。应选择当前 API 模型列表中支持稀疏向量的模型。
model_version	否	`str`	模型版本。
text_field	否	`str`	文本向量化字段名称。
instruction	否	`InstructionForCreateVikingdbCollectionInput`	Instruction 配置。

Tensor

tensor 的类型为 TensorForCreateVikingdbCollectionInput。

参数	必须	类型	备注
model_name	是	`str`	当前固定为 `doubao-embedding-vision`，并需与 `dense.model_name` 保持一致。
model_version	否	`str`	当前固定为 `251215`，并需与 `dense.model_version` 保持一致。
text_field	否	`str`	文本张量化字段名称，需与 Dense 配置的对应字段一致。
image_field	否	`str`	图片张量化字段名称，需与 Dense 配置的对应字段一致。
video_field	否	`str`	视频张量化字段名称，需与 Dense 配置的对应字段一致。
n_dim	是	`int`	张量阶数，当前固定为 `2`。Python 构造参数名为 `n_dim`。
shape	是	`list[int]`	张量维度，格式为 `[M, N]`。M 为 2-64；N 为 4-2048，且 N 大于 4 时必须是 8 的倍数。
instruction	否	`InstructionForCreateVikingdbCollectionInput`	Instruction 配置。

Instruction

instruction 的类型为 InstructionForCreateVikingdbCollectionInput。

参数	必须	类型	备注
auto_fill	是	`bool`	是否在写入数据时根据模态信息自动填充 Instruction。省略整个 `instruction` 配置时，等价于 `auto_fill=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。

全文检索设置

full_text 的元素类型为 FullTextForCreateVikingdbCollectionInput。

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

配置 full_text 后：

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

Analyzer

analyzer 的类型为 AnalyzerForCreateVikingdbCollectionInput。

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

返回参数

返回类型为 CreateVikingdbCollectionResponse。

参数	必须	类型	备注
message	成功时返回	`str`	操作结果信息。成功时为 `success`。
resource_id	成功时返回	`str`	新创建数据集的资源 ID。

请求示例

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

按“安装与 client 初始化”文档在 Python 项目中引入 VikingDB 控制面 SDK。
在火山引擎控制台“密钥管理”中创建 AK/SK，并配置 VIKINGDB_AK、VIKINGDB_SK 环境变量。
根据地域和访问域名配置 VIKINGDB_HOST 和 VIKINGDB_REGION。

创建带 vector 字段的数据集

import os

import volcenginesdkcore
import volcenginesdkvikingdb as vdb
from volcenginesdkcore.rest import ApiException
from volcenginesdkvikingdb.api.vikingdb_api import VIKINGDBApi

configuration = volcenginesdkcore.Configuration()
configuration.ak = os.environ["VIKINGDB_AK"]
configuration.sk = os.environ["VIKINGDB_SK"]
configuration.region = os.environ["VIKINGDB_REGION"]
configuration.host = os.environ["VIKINGDB_HOST"]
configuration.scheme = "https"
volcenginesdkcore.Configuration.set_default(configuration)

client = VIKINGDBApi()

request = vdb.CreateVikingdbCollectionRequest(
    project_name="default",
    collection_name="<YOUR_COLLECTION_NAME>",
    description="Collection with vector fields",
    fields=[
        vdb.FieldForCreateVikingdbCollectionInput(
            field_name="f_id",
            field_type="string",
            is_primary_key=True,
        ),
        vdb.FieldForCreateVikingdbCollectionInput(
            field_name="f_int64",
            field_type="int64",
            default_value=-1,
        ),
        vdb.FieldForCreateVikingdbCollectionInput(
            field_name="f_vector",
            field_type="vector",
            dim=1024,
        ),
        vdb.FieldForCreateVikingdbCollectionInput(
            field_name="f_sparse_vector",
            field_type="sparse_vector",
        ),
    ],
)

try:
    response = client.create_vikingdb_collection(request)
    print("all response content:", response)
    print("message:", response.message)
    print("resource_id:", response.resource_id)
except ApiException as error:
    print("status:", error.status)
    print("reason:", error.reason)
    print("headers:", error.headers)
    print("body:", error.body)
except Exception as error:
    print("request exception:", error)
    raise

创建带 vectorize 的数据集

import os

import volcenginesdkcore
import volcenginesdkvikingdb as vdb
from volcenginesdkcore.rest import ApiException
from volcenginesdkvikingdb.api.vikingdb_api import VIKINGDBApi

configuration = volcenginesdkcore.Configuration()
configuration.ak = os.environ["VIKINGDB_AK"]
configuration.sk = os.environ["VIKINGDB_SK"]
configuration.region = os.environ["VIKINGDB_REGION"]
configuration.host = os.environ["VIKINGDB_HOST"]
configuration.scheme = "https"
volcenginesdkcore.Configuration.set_default(configuration)

client = VIKINGDBApi()

instruction = vdb.InstructionForCreateVikingdbCollectionInput(
    auto_fill=True,
)

request = vdb.CreateVikingdbCollectionRequest(
    project_name="default",
    collection_name="<YOUR_COLLECTION_NAME>",
    description="Collection with automatic vectorization",
    fields=[
        vdb.FieldForCreateVikingdbCollectionInput(
            field_name="f_id",
            field_type="int64",
            is_primary_key=True,
        ),
        vdb.FieldForCreateVikingdbCollectionInput(
            field_name="f_text",
            field_type="text",
        ),
        vdb.FieldForCreateVikingdbCollectionInput(
            field_name="f_image",
            field_type="image",
        ),
    ],
    vectorize=vdb.VectorizeForCreateVikingdbCollectionInput(
        dense=vdb.DenseForCreateVikingdbCollectionInput(
            model_name="doubao-embedding-vision",
            model_version="251215",
            text_field="f_text",
            image_field="f_image",
            dim=1024,
            instruction=instruction,
        ),
        sparse=vdb.SparseForCreateVikingdbCollectionInput(
            model_name="doubao-embedding-vision",
            model_version="251215",
            text_field="f_text",
        ),
        tensor=vdb.TensorForCreateVikingdbCollectionInput(
            model_name="doubao-embedding-vision",
            model_version="251215",
            text_field="f_text",
            image_field="f_image",
            n_dim=2,
            shape=[64, 2048],
            instruction=instruction,
        ),
    ),
)

try:
    response = client.create_vikingdb_collection(request)
    print("all response content:", response)
    print("message:", response.message)
    print("resource_id:", response.resource_id)
except ApiException as error:
    print("status:", error.status)
    print("reason:", error.reason)
    print("headers:", error.headers)
    print("body:", error.body)
except Exception as error:
    print("request exception:", error)
    raise

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

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

import os

import volcenginesdkcore
import volcenginesdkvikingdb as vdb
from volcenginesdkcore.rest import ApiException
from volcenginesdkvikingdb.api.vikingdb_api import VIKINGDBApi

configuration = volcenginesdkcore.Configuration()
configuration.ak = os.environ["VIKINGDB_AK"]
configuration.sk = os.environ["VIKINGDB_SK"]
configuration.region = os.environ["VIKINGDB_REGION"]
configuration.host = os.environ["VIKINGDB_HOST"]
configuration.scheme = "https"
volcenginesdkcore.Configuration.set_default(configuration)

client = VIKINGDBApi()

request = vdb.CreateVikingdbCollectionRequest(
    project_name="default",
    collection_name="<YOUR_COLLECTION_NAME>",
    description="Collection with vectorize and full text",
    fields=[
        vdb.FieldForCreateVikingdbCollectionInput(
            field_name="f_id",
            field_type="int64",
            is_primary_key=True,
        ),
        vdb.FieldForCreateVikingdbCollectionInput(
            field_name="f_text",
            field_type="text",
        ),
    ],
    vectorize=vdb.VectorizeForCreateVikingdbCollectionInput(
        dense=vdb.DenseForCreateVikingdbCollectionInput(
            model_name="bge-m3",
            model_version="default",
            text_field="f_text",
        ),
    ),
    full_text=[
        vdb.FullTextForCreateVikingdbCollectionInput(
            field="f_text",
            analyzer=vdb.AnalyzerForCreateVikingdbCollectionInput(
                tokenizer="standard",
                character_converters=[
                    "en_lower_case",
                    "en_num_half_width",
                ],
                stop_words_filters=[
                    "symbol",
                    "en",
                    "zh",
                ],
            ),
        ),
    ],
)

try:
    response = client.create_vikingdb_collection(request)
    print("all response content:", response)
    print("message:", response.message)
    print("resource_id:", response.resource_id)
except ApiException as error:
    print("status:", error.status)
    print("reason:", error.reason)
    print("headers:", error.headers)
    print("body:", error.body)
except Exception as error:
    print("request exception:", error)
    raise

最近更新时间：2026.11.05 15:27:19

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

参数概览 #

字段定义 #

FieldType #

字段默认值 #

向量化设置 #

Dense #

Sparse #

Tensor #

Instruction #

模型列表 #

全文检索设置 #

Analyzer #

创建带 vector 字段的数据集 #

创建带 vectorize 的数据集 #

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