文档中心

向量数据库VikingDB

数据集(Collection)

CreateVikingdbCollection

概述

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

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

创建数据集时：

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

方法定义

output, err := client.CreateVikingdbCollection(input)

方法签名：

func (c *VIKINGDB) CreateVikingdbCollection(
    input *CreateVikingdbCollectionInput,
) (*CreateVikingdbCollectionOutput, error)

请求参数

参数概览

请求参数类型为 CreateVikingdbCollectionInput。

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

字段定义

Fields 的元素类型为 FieldForCreateVikingdbCollectionInput。

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

FieldType

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

字段默认值

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

参数	类型	备注
`int64`	`int64`	默认值为 `0`。
`float32`	`float32`	默认值为 `0.0`。
`string`	`string`	默认值为 `"default"`。
`bool`	`bool`	默认值为 `false`。
`list<int64>`	`[]int64`	默认值为 `[]int64{0}`。
`list<string>`	`[]string`	默认值为 `[]string{"default"}`。
`date_time`	`string`	默认值为 `1970-01-01T00:00:00Z`。
`geo_point`	`string`	默认值为 `"0, 0"`。
`list<geo_point>`	`[]string`	默认值为空切片。

向量化设置

Vectorize 的类型为 VectorizeForCreateVikingdbCollectionInput。

参数	必须	类型	备注
Dense	是	`*DenseForCreateVikingdbCollectionInput`	稠密向量化模型配置。
Sparse	否	`*SparseForCreateVikingdbCollectionInput`	稀疏向量化模型配置。
Tensor	否	`*TensorForCreateVikingdbCollectionInput`	张量化模型配置。

Dense

Dense 的类型为 DenseForCreateVikingdbCollectionInput。

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

Sparse

Sparse 的类型为 SparseForCreateVikingdbCollectionInput。

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

Tensor

Tensor 的类型为 TensorForCreateVikingdbCollectionInput。

参数	必须	类型	备注
ModelName	是	`*string`	当前固定为 `doubao-embedding-vision`，并需与 `Dense.ModelName` 保持一致。
ModelVersion	否	`*string`	当前固定为 `251215`，并需与 `Dense.ModelVersion` 保持一致。
TextField	否	`*string`	文本张量化字段名称，需与 Dense 配置的对应字段一致。
ImageField	否	`*string`	图片张量化字段名称，需与 Dense 配置的对应字段一致。
VideoField	否	`*string`	视频张量化字段名称，需与 Dense 配置的对应字段一致。
NDim	是	`*int32`	张量阶数，当前固定为 `2`。Go 结构体字段名为 `NDim`。
Shape	是	`[]*int32`	张量维度，格式为 `[M, N]`。M 为 2-64；N 为 4-2048，且 N 大于 4 时必须是 8 的倍数。
Instruction	否	`*InstructionForCreateVikingdbCollectionInput`	Instruction 配置。

Instruction

Instruction 的类型为 InstructionForCreateVikingdbCollectionInput。

参数	必须	类型	备注
AutoFill	是	`*bool`	是否在写入数据时根据模态信息自动填充 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	二选一	`[]*string`	多分词器配置。切片不能为空、不能包含重复项，且不能与 `Tokenizer` 同时设置。每一项的可选值与 `Tokenizer` 相同。
CharacterConverters	否	`[]*string`	字符转换器。可选值为 `en_lower_case`、`en_num_half_width`。不传时默认使用两者；显式传空切片表示不启用字符转换。
StopWordsFilters	否	`[]*string`	停用词过滤器。可选值为 `symbol`、`symbol_simple`、`en`、`en_simple`、`zh`、`zh_simple`。不传时默认使用 `symbol`、`en`、`zh`；显式传空切片表示不启用停用词过滤。

返回参数

返回类型为 CreateVikingdbCollectionOutput。

参数	必须	类型	备注
Message	成功时返回	`*string`	操作结果信息。成功时为 `success`。
ResourceId	成功时返回	`*string`	新创建数据集的资源 ID。
Metadata	是	`*response.ResponseMetadata`	请求元数据，包括 Request ID、Action、Region、Service 和 HTTP 状态码等信息。

请求示例

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

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

创建带 vector 字段的数据集

package main

import (
	"errors"
	"fmt"
	"os"

	"github.com/volcengine/volcengine-go-sdk/service/vikingdb"
	"github.com/volcengine/volcengine-go-sdk/volcengine"
	"github.com/volcengine/volcengine-go-sdk/volcengine/credentials"
	"github.com/volcengine/volcengine-go-sdk/volcengine/session"
	"github.com/volcengine/volcengine-go-sdk/volcengine/volcengineerr"
)

func main() {
	config := volcengine.NewConfig().
		WithRegion(os.Getenv("VIKINGDB_REGION")).
		WithCredentials(credentials.NewStaticCredentials(
			os.Getenv("VIKINGDB_AK"),
			os.Getenv("VIKINGDB_SK"),
			"",
		))

	sess, err := session.NewSession(config)
	if err != nil {
		fmt.Println("client initialization failed:", err)
		return
	}
	client := vikingdb.New(sess)

	input := &vikingdb.CreateVikingdbCollectionInput{
		ProjectName:    volcengine.String("default"),
		CollectionName: volcengine.String("<YOUR_COLLECTION_NAME>"),
		Description:    volcengine.String("Collection with vector fields"),
		Fields: []*vikingdb.FieldForCreateVikingdbCollectionInput{
			{
				FieldName:    volcengine.String("f_id"),
				FieldType:    volcengine.String("string"),
				IsPrimaryKey: volcengine.Bool(true),
			},
			{
				FieldName:    volcengine.String("f_int64"),
				FieldType:    volcengine.String("int64"),
				DefaultValue: int64(-1),
			},
			{
				FieldName: volcengine.String("f_vector"),
				FieldType: volcengine.String("vector"),
				Dim:       volcengine.Int32(1024),
			},
			{
				FieldName: volcengine.String("f_sparse_vector"),
				FieldType: volcengine.String("sparse_vector"),
			},
		},
	}

	output, err := client.CreateVikingdbCollection(input)
	if err != nil {
		printSDKError(err)
		return
	}

	fmt.Println("all response content:", output)
	fmt.Println("message:", volcengine.StringValue(output.Message))
	fmt.Println("resource ID:", volcengine.StringValue(output.ResourceId))
	if output.Metadata != nil {
		fmt.Println("request ID:", output.Metadata.RequestId)
		fmt.Println("action:", output.Metadata.Action)
		fmt.Println("region:", output.Metadata.Region)
		fmt.Println("service:", output.Metadata.Service)
		fmt.Println("HTTP code:", output.Metadata.HTTPCode)
	}
}

func printSDKError(err error) {
	fmt.Println("request error:", err)

	var requestFailure volcengineerr.RequestFailure
	if errors.As(err, &requestFailure) {
		fmt.Println("status code:", requestFailure.StatusCode())
		fmt.Println("request ID:", requestFailure.RequestID())
	}

	var sdkError volcengineerr.Error
	if errors.As(err, &sdkError) {
		fmt.Println("error code:", sdkError.Code())
		fmt.Println("error message:", sdkError.Message())
		if sdkError.OrigErr() != nil {
			fmt.Println("original error:", sdkError.OrigErr())
		}
	}
}

创建带 vectorize 的数据集

package main

import (
	"errors"
	"fmt"
	"os"

	"github.com/volcengine/volcengine-go-sdk/service/vikingdb"
	"github.com/volcengine/volcengine-go-sdk/volcengine"
	"github.com/volcengine/volcengine-go-sdk/volcengine/credentials"
	"github.com/volcengine/volcengine-go-sdk/volcengine/session"
	"github.com/volcengine/volcengine-go-sdk/volcengine/volcengineerr"
)

func main() {
	config := volcengine.NewConfig().
		WithRegion(os.Getenv("VIKINGDB_REGION")).
		WithCredentials(credentials.NewStaticCredentials(
			os.Getenv("VIKINGDB_AK"),
			os.Getenv("VIKINGDB_SK"),
			"",
		))

	sess, err := session.NewSession(config)
	if err != nil {
		fmt.Println("client initialization failed:", err)
		return
	}
	client := vikingdb.New(sess)

	instruction := &vikingdb.InstructionForCreateVikingdbCollectionInput{
		AutoFill: volcengine.Bool(true),
	}

	input := &vikingdb.CreateVikingdbCollectionInput{
		ProjectName:    volcengine.String("default"),
		CollectionName: volcengine.String("<YOUR_COLLECTION_NAME>"),
		Description:    volcengine.String("Collection with automatic vectorization"),
		Fields: []*vikingdb.FieldForCreateVikingdbCollectionInput{
			{
				FieldName:    volcengine.String("f_id"),
				FieldType:    volcengine.String("int64"),
				IsPrimaryKey: volcengine.Bool(true),
			},
			{
				FieldName: volcengine.String("f_text"),
				FieldType: volcengine.String("text"),
			},
			{
				FieldName: volcengine.String("f_image"),
				FieldType: volcengine.String("image"),
			},
		},
		Vectorize: &vikingdb.VectorizeForCreateVikingdbCollectionInput{
			Dense: &vikingdb.DenseForCreateVikingdbCollectionInput{
				ModelName:    volcengine.String("doubao-embedding-vision"),
				ModelVersion: volcengine.String("251215"),
				TextField:    volcengine.String("f_text"),
				ImageField:   volcengine.String("f_image"),
				Dim:          volcengine.Int32(1024),
				Instruction:  instruction,
			},
			Sparse: &vikingdb.SparseForCreateVikingdbCollectionInput{
				ModelName:    volcengine.String("doubao-embedding-vision"),
				ModelVersion: volcengine.String("251215"),
				TextField:    volcengine.String("f_text"),
			},
			Tensor: &vikingdb.TensorForCreateVikingdbCollectionInput{
				ModelName:    volcengine.String("doubao-embedding-vision"),
				ModelVersion: volcengine.String("251215"),
				TextField:    volcengine.String("f_text"),
				ImageField:   volcengine.String("f_image"),
				NDim:         volcengine.Int32(2),
				Shape:        volcengine.Int32Slice([]int32{64, 2048}),
				Instruction:  instruction,
			},
		},
	}

	output, err := client.CreateVikingdbCollection(input)
	if err != nil {
		printSDKError(err)
		return
	}

	fmt.Println("all response content:", output)
	fmt.Println("message:", volcengine.StringValue(output.Message))
	fmt.Println("resource ID:", volcengine.StringValue(output.ResourceId))
	if output.Metadata != nil {
		fmt.Println("request ID:", output.Metadata.RequestId)
		fmt.Println("action:", output.Metadata.Action)
		fmt.Println("region:", output.Metadata.Region)
		fmt.Println("service:", output.Metadata.Service)
		fmt.Println("HTTP code:", output.Metadata.HTTPCode)
	}
}

func printSDKError(err error) {
	fmt.Println("request error:", err)

	var requestFailure volcengineerr.RequestFailure
	if errors.As(err, &requestFailure) {
		fmt.Println("status code:", requestFailure.StatusCode())
		fmt.Println("request ID:", requestFailure.RequestID())
	}

	var sdkError volcengineerr.Error
	if errors.As(err, &sdkError) {
		fmt.Println("error code:", sdkError.Code())
		fmt.Println("error message:", sdkError.Message())
		if sdkError.OrigErr() != nil {
			fmt.Println("original error:", sdkError.OrigErr())
		}
	}
}

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

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

package main

import (
	"errors"
	"fmt"
	"os"

	"github.com/volcengine/volcengine-go-sdk/service/vikingdb"
	"github.com/volcengine/volcengine-go-sdk/volcengine"
	"github.com/volcengine/volcengine-go-sdk/volcengine/credentials"
	"github.com/volcengine/volcengine-go-sdk/volcengine/session"
	"github.com/volcengine/volcengine-go-sdk/volcengine/volcengineerr"
)

func main() {
	config := volcengine.NewConfig().
		WithRegion(os.Getenv("VIKINGDB_REGION")).
		WithCredentials(credentials.NewStaticCredentials(
			os.Getenv("VIKINGDB_AK"),
			os.Getenv("VIKINGDB_SK"),
			"",
		))

	sess, err := session.NewSession(config)
	if err != nil {
		fmt.Println("client initialization failed:", err)
		return
	}
	client := vikingdb.New(sess)

	input := &vikingdb.CreateVikingdbCollectionInput{
		ProjectName:    volcengine.String("default"),
		CollectionName: volcengine.String("<YOUR_COLLECTION_NAME>"),
		Description:    volcengine.String("Collection with vectorize and full text"),
		Fields: []*vikingdb.FieldForCreateVikingdbCollectionInput{
			{
				FieldName:    volcengine.String("f_id"),
				FieldType:    volcengine.String("int64"),
				IsPrimaryKey: volcengine.Bool(true),
			},
			{
				FieldName: volcengine.String("f_text"),
				FieldType: volcengine.String("text"),
			},
		},
		Vectorize: &vikingdb.VectorizeForCreateVikingdbCollectionInput{
			Dense: &vikingdb.DenseForCreateVikingdbCollectionInput{
				ModelName:    volcengine.String("bge-m3"),
				ModelVersion: volcengine.String("default"),
				TextField:    volcengine.String("f_text"),
			},
		},
		FullText: []*vikingdb.FullTextForCreateVikingdbCollectionInput{
			{
				Field: volcengine.String("f_text"),
				Analyzer: &vikingdb.AnalyzerForCreateVikingdbCollectionInput{
					Tokenizer: volcengine.String("standard"),
					CharacterConverters: volcengine.StringSlice([]string{
						"en_lower_case",
						"en_num_half_width",
					}),
					StopWordsFilters: volcengine.StringSlice([]string{
						"symbol",
						"en",
						"zh",
					}),
				},
			},
		},
	}

	output, err := client.CreateVikingdbCollection(input)
	if err != nil {
		printSDKError(err)
		return
	}

	fmt.Println("all response content:", output)
	fmt.Println("message:", volcengine.StringValue(output.Message))
	fmt.Println("resource ID:", volcengine.StringValue(output.ResourceId))
	if output.Metadata != nil {
		fmt.Println("request ID:", output.Metadata.RequestId)
		fmt.Println("action:", output.Metadata.Action)
		fmt.Println("region:", output.Metadata.Region)
		fmt.Println("service:", output.Metadata.Service)
		fmt.Println("HTTP code:", output.Metadata.HTTPCode)
	}
}

func printSDKError(err error) {
	fmt.Println("request error:", err)

	var requestFailure volcengineerr.RequestFailure
	if errors.As(err, &requestFailure) {
		fmt.Println("status code:", requestFailure.StatusCode())
		fmt.Println("request ID:", requestFailure.RequestID())
	}

	var sdkError volcengineerr.Error
	if errors.As(err, &sdkError) {
		fmt.Println("error code:", sdkError.Code())
		fmt.Println("error message:", sdkError.Message())
		if sdkError.OrigErr() != nil {
			fmt.Println("original error:", sdkError.OrigErr())
		}
	}
}

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

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

参数概览 #

字段定义 #

FieldType #

字段默认值 #

向量化设置 #

Dense #

Sparse #

Tensor #

Instruction #

模型列表 #

全文检索设置 #

Analyzer #

创建带 vector 字段的数据集 #

创建带 vectorize 的数据集 #

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