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

向量数据库VikingDB

请输入
  • 文档首页
    • 向量数据库VikingDBViking 知识库API参考知识库create
复制全文
下载 pdf
我的收藏
知识库
create
复制全文
下载 pdf
我的收藏
create
概述

/api/knowledge/collection/create 接口用于创建一个新的知识库。创建成功后，可以导入数据。

前提条件

完成"签名鉴权方式"页面的注册账号、实名认证、AK/SK 密钥获取和签名获取后，可调用 API 接口实现知识库的创建功能。

请求接口
URI/api/knowledge/collection/create统一资源标识符
请求方法POST客户端对向量数据库服务器请求的操作类型
请求头Content-Type: application/json请求消息类型
Authorization: HMAC-SHA256 ***鉴权
请求参数（旗舰版）
参数子参数类型是否必选默认值参数说明

name

--

string

是

--

知识库名称

  • 只能使用英文字母、数字、下划线_，并以英文字母开头，不能为空
  • 长度要求：[1-64]
  • 知识库名称不能重复

project

--

string

否

default

知识库所属项目，获取方式参见文档API 接入与技术支持
若不指定该字段，则在default项目下创建。
若需要在指定项目下创建知识库，则需正确配置该字段。

description

--

string

否

""

知识库描述信息

  • 长度要求：[1, 65535]

version

--

int

否

4

2: 标准版
4: 旗舰版
当前版本下该值为 4 （仅旗舰版支持结构化知识库和音视频模态）

data_type

string

否

unstructured_data

知识库内的数据类型

  • unstructured_data：全模态数据（同时支持上传结构化文件，如 pdf、 doc、csv、xlsx、png、mp4 等）
  • structured_data：结构化数据（仅支持上传结构化文件，如 csv、xlsx、jsonl）

preprocessing

object

否

非结构化文档处理策略
当 data_type 为 “unstructured_data” 时生效，为 “structured_data” 时无效。

chunking_strategy

string

否

--

文档切片策略，枚举值：["custom_balance", "custom"]

  • “custom_balance” 是知识库系统提供的最新默认文档处理策略，该策略：
    1. 升级了对 pdf、docx 等复杂文档的解析和理解能力，对复杂文档版面结构、语义结构的解析能力获得大幅提升；特别优化了图片内容及其上下文的理解和加工能力，支持将图片和文本 chunk 混合编排，增强上下文一致性；特别优化了表格内容的理解加工能力，对长表格解析和切片更具优势；结合 VikingDB 语义和关键词融合检索算法，提高了多模态内容的检索能力，大幅提升相关信息的召回能力；提高了切片算法信噪比，无关信息更少，语义损失更小。
    2. 选用此策略后，可生效的文档处理策略子参数包括：
    • "chunk_length" (仅当 "chunking_identifier" 为空时生效）
    • "merge_small_chunks" (仅当 "chunking_identifier" 为空时生效）
    • "multi_modal" (仅当 "chunking_identifier" 为空时生效）
  • “custom” 是使用自定义分隔符的文档处理策略，选用此策略后，可生效的文档处理策略子参数包括：
    • "chunking_identifier"
    • "chunk_length" (仅当 "chunking_identifier" 为空时生效）
    • "merge_small_chunks" (仅当 "chunking_identifier" 为空时生效）
    • "multi_modal" (仅当 "chunking_identifier" 为空时生效）
  • 请注意原“default”策略目前仅用于兼容存量知识库，不再维护，新建知识库建议采用“custom_balance”

chunking_identifier

list<string>

否

--

自定义分隔符号
仅在 chunking_strategy == “custom” 时生效。列表长度为 [1, 20]，每个分隔符长度为 [1, 10] 个字符，且不能包含 \|；分隔符按普通字符串匹配，不是正则表达式。

chunk_length

int

否

500

文档类型切片最大长度，单位为字节
取值范围随 embedding_model 变化，见 向量化模型及索引算法对照表。

merge_small_chunks

bool

否

true

是否合并短切片（文档、音视频通用）
配置是否对短切片进行合并，且合并后的文本/音视频片会限制不超过设置的切片最大长度限制

multi_modal

list

否

--

图片理解策略
枚举值：

  • "image_ocr"：图片 ocr
    传参示例：
  • 当 "multi_modal": ["image_ocr"] 时，开启图片 ocr，不传值即代表不开启图片 ocr
    使用旧参数命名“multi_mode”创建的库仍保留原命名，但新创建知识库不推荐继续使用

video_chunking_strategy

string

否

smart_slice

视频切片策略
当选择创建音视频知识库时生效（即 embedding_model 参数为 doubao-embedding-vision-and-m3或 doubao-embedding-vision，embedding_model_version 参数为 250615 时），参数值如下：

  • smart_slice: 智能内容切片
  • voice_slice: 语音语义切片

vlm_prompt

string

否

连续剪裁分段模板的 prompt

视频切片规则
仅当 video_chunking_strategy == “smart_slice” 时生效，字数不超过5000，必须包含 start_time 和 end_time 以及格式说明，否则直接造成视频分段失败

"preprocessing": {
"chunk_length": 2000,
"chunking_strategy": "custom_balance",
"enable_smart_summary": true,
"keep_raw_text": true,
"merge_small_chunks": true,
"multi_modal": [
"image_ocr"
],
"video_chunking_strategy": "smart_slice",
// 视频切片规则（自定义prompt）
"vlm_prompt": "### 任务：视频智能切片\n\t\t你需要仅基于提供的视频分镜抽帧将视频拆分若干个小切片。要求每个切片满足：\n\t\t1. 时长：每个小片段时长控制在60秒左右,但不要超过300秒\n\t\t2. 第一个片段的start_time从0开始，最后一个片段的end_time为视频结尾时间\n\t\t3. 所有小片段连贯无间隔（end_time = 下一段start_time）,每个片段必须满足 start_time < end_time（起始早于结束\n\t\t4. 拆分断点选择在分镜切换处\n\t\t5. content_summary 直接显示\"自定义caption\"\n\t\t\t### 输出要求（JSON格式）,紧凑排列、无多余空格：\n\t\t\t请输出一个JSON数组，每个元素代表一个切片，包含：\n\t\t\t- `start_time`：切片开始时间(格式：HH:MM:SS.sss)。\n\t\t\t- `end_time`：切片结束时间(格式：HH:MM:SS.sss)。\n\t\t\t- `content_summary`\n\t\t\t例如：\n\t\t\t[{{\"start_time\":\"00:00:00.000\",\"end_time\":\"00:00:10.000\",\"content_summary\":\"自定义caption\"}},{{\"start_time\":\"00:00:10.000\",\"end_time\":\"00:00:20.000\",\"content_summary\":\"自定义caption\"}}]\n\t\t\t即使音频ASR文本或分镜抽帧有缺失，也尽量根据视频内容进行切片。"
}

enable_smart_summary

bool

否

true

视频是否开启大纲智能总结
配置是否开启大纲，开启后支持使用大模型对视频内容进行智能大纲总结

video_max_length

int

否

30

视频最大切片长度
仅当 video_chunking_strategy == “voice_slice” 时生效，取值范围 [1, 60] ，单位 s

audio_chunk_length

int

否

2000

音频 ASR 文本切片最大长度，单位为字节
取值范围与所选 embedding_model 的 chunk_length 范围一致。

enable_slice_analysis

bool

否

false

是否开启切片内容分析
true 时生成切片分析结果并在检索结果的 description 字段返回；false 或不传时不执行切片分析。

enable_audio_smart_summary

bool

否

false

音频是否开启大纲智能总结
配置是否开启大纲，开启后支持使用大模型对音频内容进行智能大纲总结

table_config--objectdata_type 为 structured_data 时必填--结构化知识库表字段配置
table_typestring否--表结构方向：row 表示按行解析，col 表示按列解析。
table_posint否--字段定义所在的行号或列号，含义由 table_type 决定。
start_posint否--数据起始行号或列号，含义由 table_type 决定。
table_fieldslist<object>是--结构化表字段定义列表。
table_fields[].field_namestring是--字段名称，长度 [1, 128]。
table_fields[].field_typestring是--支持 string、int64、float32、bool、list<string>。
table_fields[].if_embeddingbool是false是否参与向量索引。
table_fields[].default_value与 field_type 一致否--字段默认值。
table_fields[].if_filterbool是false是否作为标签过滤字段。
indexobject否--索引配置
index_configobject否--知识库索引配置；所有子字段均为选填，不传时使用系统默认索引配置。
index_config.fieldslist<object>否[]文档标签字段定义，最多 180 个；子字段包含 field_name（string，最长 128）、field_type（string）和 default_val（与 field_type 一致）。
index_config.cpu_quotaint否1CPU 配额，单位为核，取值范围 [1, 100]。
index_config.embedding_modelstring否doubao-embedding-and-m3向量化模型，支持值见下方对照表。
index_config.embedding_model_versionstring否模型默认版本向量化模型版本；视频知识库使用 250615。
index_config.embedding_dimensionint否模型默认维度必须是所选模型支持的维度。
index_config.quantstring否int8量化方式，具体可选值取决于 index_type。
index_config.field_enumerated_liststring否--标签枚举配置的 JSON 字符串。
index_config.chunk_title_entity_extractionbool否false是否对切片标题执行实体抽取。

index_type

string

否

hnsw_hybrid

指定索引算法，支持 hnsw_hybrid、hnsw 和 flat
推荐选择 “hnsw_hybrid”，能够兼具对关键词和语义的理解，综合提高检索精度
向量化模型和索引算法的对照关系参考 向量化模型及索引算法对照表

doc_summary_configobject否--知识库摘要配置

enabled

bool

否

false

是否开启文档 AI 摘要功能
配置知识库是否开启文档 AI 生成摘要功能，开启后，该知识库将自动为每篇文档生成摘要并保存结果到文档元信息中
注：此功能仅对当知识库类型为非结构化知识库时生效，即 data_type 为 “unstructured_data” 时生效

请求参数（标准版）
参数子参数类型是否必选默认值参数说明

name

--

string

是

--

知识库名称

  • 只能使用英文字母、数字、下划线_，并以英文字母开头，不能为空
  • 长度要求：[1-64]
  • 知识库名称不能重复

project

--

string

否

default

知识库所属项目，获取方式参见文档API 接入与技术支持
若不指定该字段，则在default项目下创建。
若需要在指定项目下创建知识库，则需正确配置该字段。

description

--

string

否

""

知识库描述信息

  • 长度要求：[1, 65535]

version

--

int

否

4

2: 标准版
4: 旗舰版
当前版本下该值为 2

preprocessing

object

否

非结构化文档处理策略
当 data_type 为 “unstructured_data” 时生效，为 “structured_data” 时无效。

chunking_strategy

string

否

--

文档切片策略，枚举值：["custom_balance", "custom"]

  • “custom_balance” 是知识库系统提供的最新默认文档处理策略，该策略：
    1. 升级了对 pdf、docx 等复杂文档的解析和理解能力，对复杂文档版面结构、语义结构的解析能力获得大幅提升；特别优化了图片内容及其上下文的理解和加工能力，支持将图片和文本 chunk 混合编排，增强上下文一致性；特别优化了表格内容的理解加工能力，对长表格解析和切片更具优势；结合 VikingDB 语义和关键词融合检索算法，提高了多模态内容的检索能力，大幅提升相关信息的召回能力；提高了切片算法信噪比，无关信息更少，语义损失更小。
    2. 选用此策略后，可生效的文档处理策略子参数包括：
    • "chunk_length" (仅当 "chunking_identifier" 为空时生效）
    • "merge_small_chunks" (仅当 "chunking_identifier" 为空时生效）
    • "multi_modal" (仅当 "chunking_identifier" 为空时生效）
  • “custom” 是使用自定义分隔符的文档处理策略，选用此策略后，可生效的文档处理策略子参数包括：
    • "chunking_identifier"
    • "chunk_length" (仅当 "chunking_identifier" 为空时生效）
    • "merge_small_chunks" (仅当 "chunking_identifier" 为空时生效）
    • "multi_modal" (仅当 "chunking_identifier" 为空时生效）
  • 请注意原“default”策略目前仅用于兼容存量知识库，不再维护，新建知识库建议采用“custom_balance”

chunking_identifier

list<string>

否

--

自定义分隔符号
仅在 chunking_strategy == “custom” 时生效。列表长度为 [1, 20]，每项长度为 [1, 10] 个字符，且不能包含 \|。

chunk_length

int

否

500

文档类型切片最大长度，单位为字节
取值范围见 向量化模型及索引算法对照表

merge_small_chunks

bool

否

true

是否合并短文本片
配置是否对短文本片进行合并，且合并后的文本片会限制不超过切片最大长度

multi_modal

list

否

--

图片理解策略
枚举值：

  • "image_ocr"：图片 ocr
    传参示例：
  • 当 "multi_modal": ["image_ocr"] 时，开启图片 ocr，不传值即代表不开启图片 ocr
    使用旧参数命名“multi_mode”创建的库仍保留原命名，但新创建知识库不推荐继续使用。
doc_summary_configobject否--知识库摘要配置

enabled

bool

否

false

是否开启文档 AI 摘要功能
配置知识库是否开启文档 AI 生成摘要功能，开启后，该知识库将自动为每篇文档生成摘要并保存结果到文档元信息中

向量化模型及索引算法对照表
创建知识库类型向量化模型模型版本产出类型索引类型向量维度量化方式chunk_length 取值检索类型

音视频知识库、
图像/富文本知识库

doubao-embedding-vision

251215（图像/富文本知识库）、250615（音视频知识库）、250328（图像/富文本知识库）

稠密向量

hnsw（默认）、flat

1024、2048
默认2048

int8（默认）、float、fix16

[100, 8000]
默认 2000

语义检索（字节自研模型）

doubao-embedding-vision-and-m3

251215（图像/富文本知识库）、250615（音视频知识库）、250328（图像/富文本知识库）

稠密向量和稀疏向量

hnsw_hybrid（默认）

1024、2048
默认2048

int8（默认）、float、fix16

[100, 8000]
默认 2000

混合检索（兼顾语义检索和关键词匹配）

结构化知识库、
纯文本知识库

bge-large-zh

--

稠密向量

hnsw（默认）、flat

1024

int8（默认）、float、fix16

[100, 500]
默认 500

语义检索

bge-m3

--

稠密向量和稀疏向量

hnsw_hybrid（默认）

1024

int8（默认）、float、fix16

[100, 8000]
默认 2000

混合检索（兼顾语义检索和关键词匹配）

--

hnsw（默认）、flat

1024

int8（默认）、float、fix16

[100, 8000]
默认 2000

语义检索（此时稀疏向量被忽略，适用于只需要长文本窗口、多语言检索的纯语义检索场景）

bge-large-zh-and-m3

--

稠密向量和稀疏向量

hnsw_hybrid（默认）

1024

int8（默认）、float、fix16

[100, 500]
默认 500

混合检索（兼顾语义检索和关键词匹配）

纯文本知识库

doubao-embedding-and-m3

240715

稠密向量和稀疏向量

hnsw_hybrid（默认）

1024、2048
默认 2048

int8（默认）、float、fix16

[100, 4000]
默认 2000

混合检索（兼顾语义检索和关键词匹配）

响应消息
参数参数说明
code状态码
message返回信息

data

返回的详细信息
{
"resource_id": 知识库 id
}

request_id标识每个请求的唯一标识符

状态码说明

状态码http状态码返回信息状态码说明
0200success成功
1000001403unauthorized鉴权失败
1000002403no permission权限不足

1000003

400

invalid request: %s

非法参数

  • 缺失必选参数
  • collection 命名不符合规范
  • 字段类型与相关字段属性不满足约束条件
1000004400collection existcollection 已存在
完整示例

请求消息

创建结构化知识库

curl -i -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: HMAC-SHA256 ***' \
  https://api-knowledgebase.mlp.cn-beijing.volces.com/api/knowledge/collection/create \
  -d '{
    "name": "apiexample",
    "description": "test",
    "index": {
        "index_type": "hnsw_hybrid",
        "index_config": {
            "fields": [],
            "quant": "int8",
            "cpu_quota": 1,
            "embedding_model": "doubao-embedding-and-m3",
            "embedding_dimension": 2048
        }
    },
    "table_config": {
        "table_type": "row",
        "table_pos": 1,
        "start_pos": 2,
        "table_fields": [
            {
                "field_type": "string",
                "field_name": "讲解模块",
                "if_embedding": true,
                "if_filter": false
            },
            {
                "field_type": "string",
                "field_name": "子模块",
                "if_embedding": true,
                "if_filter": false
            },
            {
                "field_type": "string",
                "field_name": "问题示例",
                "if_embedding": true,
                "if_filter": false
            },
            {
                "field_type": "string",
                "field_name": "记忆化 ————讲解要点",
                "if_embedding": true,
                "if_filter": false
            }
            

        ]
    },
    "data_type": "structured_data",
    "project": "default"
  }'

创建视频知识库

curl -i -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: HMAC-SHA256 ***' \
  https://api-knowledgebase.mlp.cn-beijing.volces.com/api/knowledge/collection/create \
  -d '{
      "data_type": "unstructured_data",
      "description": "Video_XXX",
      "index": {
        "index_config": {
          "chunk_title_entity_extraction": false,
          "cpu_quota": 1,
          "embedding_dimension": 2048,
          "embedding_model": "doubao-embedding-vision-and-m3",
          "embedding_model_version": "250615",
          "field_enumerated_list": "{}",
          "fields": [
            {
              "field_name": "doc_id",
              "field_type": "string"
            }
          ],
          "quant": "int8"
        },
        "index_type": "hnsw_hybrid"
      },
      "name": "Video_XXX",
      "preprocessing": {
        "chunk_length": 2000,
        "chunking_strategy": "custom_balance",
	          "enable_slice_analysis": true,
        "enable_smart_summary": true,
        "merge_small_chunks": true,
	          "video_chunking_strategy": "smart_slice"
      }
    }'

响应消息

执行成功返回：

HTTP/1.1 200 OK
Content-Length: 43
Content-Type: application/json
 
{
    "code":0,
    "message":"success",
    "data": {
        "resource_id": "kb-8349ef57441ab57"
    },
    "request_id":"021695029537650fd001de666660000000000000000000230da93"
}

执行失败返回：

HTTP/1.1 400 Bad Request
Content-Length: 43
Content-Type: application/json
 
{"code":1000003, "message":"invalid request: %s", "request_id": "021695029757920fd001de6666600000000000000000002569b8f"}
最近更新时间：2026.09.08 20:33:08
这个页面对您有帮助吗？
有用
有用
无用
无用