CreateKnowledgeBase - 创建知识库-事件总线(EventBridge)-阿里云帮助中心

创建知识库

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

授权信息

当前API暂无授权信息透出。

请求参数

名称	类型	必填	描述	示例值
KnowledgeBaseName	string	是	知识库名称，同一命名空间内唯一	product-docs
Description	string	否	知识库描述	产品文档知识库
MetadataSchema	array<object>	是	声明知识库的 Metadata 字段，上传文档时 Metadata 只能包含此处声明的字段。创建后不可修改	[{"Name":"department","Type":"STRING"}]
	object	否	元数据字段
Name	string	是	字段名称	department
Type	string	是	取值范围：STRING、LONG、DOUBLE、BOOLEAN、DATETIME	STRING
Value	string	否	ValueMode=CONSTANT 时为固定值（空表示上传时可赋值）；ValueMode=SYSTEM_VARIABLE 时为系统变量名（如 DOCUMENT_NAME、FILE_TYPE、FILE_SIZE、DOCUMENT_UPLOAD_TIME、SOURCE_TYPE、SOURCE_URI、SOURCE_MODIFIED_TIME）	EventHouse
ValueMode	string	是	CONSTANT 表示常量（Value 非空时所有文档使用固定值，Value 空时上传可赋值）；SYSTEM_VARIABLE 表示系统变量（Value 为变量名，系统自动生成，上传时不能覆盖）	CONSTANT
Catalog	string	是	知识库所属的 EventHouse Catalog，与 Namespace、KnowledgeBaseName 共同定位知识库。创建后不可修改，不允许绑定系统 Catalog	my_catalog
Namespace	string	是	知识库所属的 EventHouse Namespace，必须属于指定的 Catalog，与 Catalog、KnowledgeBaseName 共同定位知识库。创建后不可修改	my_namespace
EmbeddingModel	string	否	可选。向量化模型，创建后不可修改。取值范围：text-embedding-v3、text-embedding-v4、qwen3.7-text-embedding、qwen3.7-text-embedding-flash（仅支持百炼通义系模型，不支持第三方厂商模型）。不传时默认 text-embedding-v4	text-embedding-v4
EmbeddingDimension	integer	否	可选。向量维度，与 Embedding 模型绑定校验：text-embedding-v3 支持 64、128、256、512、768、1024；text-embedding-v4 支持 64、128、256、512、768、1024、1536、2048；qwen3.7-text-embedding 支持 256、512、768、1024、1536、2048、2560；qwen3.7-text-embedding-flash 支持 256、512、768、1024。不传时使用模型默认维度 1024。创建后不可修改，即使维度相同，更换模型也必须重建知识库	1024
ChunkConfiguration	object	否	可选。知识库默认分块策略，仅对之后新上传的文档生效。不传时使用系统默认分块策略
HeadingLevel	integer	否	BY_HEADING 策略下必填，取值 [1, 6]，其他策略下传入将被忽略。小于等于 HeadingLevel 级的标题都作为切分边界（如指定 2 时 H1、H2 都切分），更深级标题不切分、保留在切片正文中；节内容超过 MaxChunkSize 时按段落/句子回退切分；无标题文档退化为智能切分	2
MaxChunkSize	integer	否	单个分块的最大字符长度，取值 [1, 6000]（字符），超限报错	512
OverlapSize	integer	否	仅 BY_LENGTH 策略下生效，其他策略下传入将被忽略。相邻分块的重叠长度（单位为字符）：大于 0 时，后一个切片头部会重复前一个切片尾部该窗口内的内容，重叠不会使切片超过 MaxChunkSize。缺省 0 表示不重叠	40
PreprocessRules	object	否	预处理规则
RemoveUrlsAndEmails	boolean	否	是否在解析时删除 URL 与邮箱地址	false
ReplaceConsecutiveWhitespace	boolean	否	是否将连续的空白字符（空格、换行、制表符）替换为单个空格	true
Separator	string	否	BY_SEPARATOR 策略下必填，其他策略下传入将被忽略。按字面字符串整体匹配切分（非正则），最长 32 个字符，如段落分隔符 \n\n	\\n\\n
Strategy	string	是	AUTO 表示智能切分（标题感知+段落打包）；BY_LENGTH 表示按长度滑动窗口切分，可指定 OverlapSize；BY_SEPARATOR 表示按分隔符切分，必须指定 Separator；BY_HEADING 表示按标题级数切分，必须指定 HeadingLevel	BY_SEPARATOR
SearchConfiguration	object	否	可选。知识库级默认检索配置，检索请求未传对应参数时生效，创建后可通过 UpdateKnowledgeBase 修改
Mode	string	否	KEYWORD 表示关键词检索，VECTOR 表示向量检索，HYBRID 表示混合检索	HYBRID
RankAlgorithm	string	否	仅混合检索模式生效。RRF 表示倒数排名融合，WEIGHTED 表示加权归一融合（配合 VectorWeight 使用）。不传时默认 RRF	RRF
RerankEnabled	boolean	否	仅混合检索模式生效。检索请求未指定 Rerank 时使用此默认值	false
RerankModel	string	否	检索请求未指定 RerankModel 时使用此默认值。取值范围：qwen3-rerank。不传时默认 qwen3-rerank	qwen3-rerank
RrfK	integer	否	RRF 融合算法参数，默认 60，必须大于 0	60
TopK	integer	否	默认返回结果数量	20
VectorWeight	number	否	WEIGHTED 融合算法的向量路权重，取值 [0, 1]，关键词路权重为 1 减去该值。不传时默认 0.7	0.7

返回参数

名称	类型	描述	示例值
	object
Code	string	接口返回码，Success 表示成功，失败时为具体错误码	Success
Data	KnowledgeBase	本次创建的知识库详情，包含名称、状态与配置信息
Message	string	接口返回的提示信息，成功时为 Operation success，失败时为具体错误描述	Operation success
RequestId	string	请求 ID	34AD682D-5B91-5773-8132-AA38C130****
Success	boolean	本次调用是否成功，true 表示成功	true

示例

正常返回示例

JSON格式

{
  "Code": "Success",
  "Data": {
    "Catalog": "my_catalog",
    "ChunkConfiguration": {
      "HeadingLevel": 2,
      "MaxChunkSize": 600,
      "OverlapSize": 40,
      "PreprocessRules": {
        "RemoveUrlsAndEmails": false,
        "ReplaceConsecutiveWhitespace": true
      },
      "Separator": "\\\\n\\\\n",
      "Strategy": "BY_SEPARATOR"
    },
    "CreatedAt": "2026-08-24T10:00:00Z",
    "Description": "产品文档知识库",
    "EmbeddingDimension": 1024,
    "EmbeddingModel": "text-embedding-v4",
    "FailureReason": "OssException: BucketAlreadyExists ...",
    "KnowledgeBaseName": "product-docs",
    "MetadataSchema": [
      {
        "Name": "department",
        "Type": "STRING",
        "Value": "EventHouse",
        "ValueMode": "CONSTANT"
      }
    ],
    "Namespace": "my_namespace",
    "SearchConfiguration": {
      "Mode": "HYBRID",
      "RankAlgorithm": "RRF",
      "RerankEnabled": false,
      "RerankModel": "qwen3-rerank",
      "RrfK": 60,
      "TopK": 20,
      "VectorWeight": 0.7
    },
    "Status": "ACTIVE",
    "UpdatedAt": "2026-08-24T10:00:00Z"
  },
  "Message": "Operation success",
  "RequestId": "34AD682D-5B91-5773-8132-AA38C130****",
  "Success": true
}

错误码

HTTP status code	错误码	错误信息
400	InvalidParameter	The specified parameter is invalid
400	InvalidMetadata	The specified metadata is invalid or contains fields not declared in the knowledge base schema
400	InvalidMetadataSchema	The specified metadata schema is invalid
400	QuotaExceeded	The quota is exceeded
400	InvalidCatalog	The specified catalog is a system catalog and cannot be bound
403	ServiceNotEnable	Service not enable
404	CatalogNotFound	The specified catalog does not exist
404	NamespaceNotFound	The specified namespace does not exist

访问错误中心查看更多错误码。

变更历史

更多信息，参考变更详情。