调用CreateIndex API创建文档搜索类知识库-大模型服务平台百炼-阿里云

创建一个文档搜索类知识库。

接口说明

关键限制：本接口仅支持创建文档搜索类知识库，不支持创建数据查询和图片问答类知识库，请通过阿里云百炼控制台创建。
权限要求：
- RAM 用户（子账号）：需先获取阿里云百炼的 API 权限（可使用AliyunBailianDataFullAccess策略，该策略已包含本接口所需的 sfm:CreateIndex 权限点），并加入一个业务空间后，才能调用本接口。
- 阿里云账号（主账号）：默认拥有权限，可直接调用。
调用方式：推荐使用最新版阿里云百炼 SDK调用，SDK 已封装复杂的签名计算逻辑，可简化您的调用过程。
后续操作：本接口仅初始化知识库创建作业。完成调用后，必须调用 SubmitIndexJob 接口以完成创建（否则，您将得到一个空的知识库）。相应代码示例请参见知识库 API 指南。
幂等性：本接口不具有幂等性，重复调用可能会创建多个同名知识库。建议通过“先查询、后创建”的逻辑实现幂等调用。

限流说明： 本接口频繁调用会被限流，频率请勿超过 10 次/秒。如遇限流，请稍后重试。

调试

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

调试

授权信息

下表是API对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：

操作：是指具体的权限点。
访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。
资源类型：是指操作中支持授权的资源类型。具体说明如下：
- 对于必选的资源类型，用前面加 * 表示。
- 对于不支持资源级授权的操作，用全部资源表示。
条件关键字：是指云产品自身定义的条件关键字。
关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。

操作	访问级别	资源类型	条件关键字	关联操作
sfm:CreateIndex	create	全部资源 ``	无	无

请求语法

POST /{WorkspaceId}/index/create HTTP/1.1

请求参数

名称	类型	必填	描述	示例值
WorkspaceId	string	是	业务空间 ID，即在该业务空间中创建知识库。获取方式请参见如何使用业务空间。	llm-3z7uw7fwz0vexxxx
Name	string	是	知识库名称。长度为 1~20 个字符，支持中文、英文、数字、下划线（_）、短划线（-）、半角句号（.）和半角冒号（:）。	企业帮助文档库
StructureType	string	是	知识库类型。取值范围： unstructured：文档搜索类知识库。说明请注意，知识库创建后将无法更改其类型。本接口不支持数据查询和图片问答类知识库，请使用阿里云百炼控制台创建。	unstructured
EmbeddingModelName	string	否	知识库使用的向量模型。向量模型用于将原始输入 prompt 和知识文本转换为数值化向量，以便对二者进行相似度比较。text-embedding-v4 模型在语种支持、代码片段向量化效果和向量维度选择等方面，相比 text-embedding-v3 模型进行了全面升级，适用于大部分场景。更多信息，请参见向量化。取值范围： text-embedding-v4 text-embedding-v3 默认值为空，此时使用 text-embedding-v3 模型。
RerankModelName	string	否	知识库使用的排序模型。排序模型是位于知识库外部的评分系统，它会计算用户问题与知识库中每个文本切片的相似度分数并按此降序排列，并返回分数最高的前 K 个文本切片。取值范围： gte-rerank-hybrid：官方排序。 gte-rerank：gte-rerank 排序。默认值为空，此时使用 gte-rerank-hybrid，即官方排序。说明如仅需语义排序，可使用 gte-rerank；若同时需要语义排序和文本匹配特征以确保相关性，建议使用官方排序。	gte-rerank-hybrid
RerankMinScore	double	否	相似度阈值，仅相似度分数超过此数值的文本切片才会被召回，用于筛选排序模型返回的文本切片。取值范围[0.01-1.00]。若未指定，默认采用 0.01。	0.20
ChunkSize	integer	否	分段长度，即每个文本切片的字符数上限。超过该长度时：智能切分（未指定`chunkMode`）：文本很可能会被截断。自定义切分（指定了`chunkMode`）：文本将被强制截断。取值范围[1-6000]。若未指定，默认采用 500。说明若设置了`ChunkSize`且小于 100，则必须同时设置`OverlapSize`。您也可以不指定这 2 个参数，系统将使用默认值。	128
OverlapSize	integer	否	分段重叠长度，表示当前文本切片与前一个文本切片的重叠字符数。取值范围[0-1024]。若未指定，默认采用 100。说明 `OverlapSize`必须小于`ChunkSize`，否则将导致切分异常。	16
Separator	string	否	分句标识符，仅在`chunkMode`=regex 时生效（其他模式下即使传入也不生效）。可传入一个正则表达式（不支持多个），用于将文件分割为小段的文本切片。使用智能切分（未指定`chunkMode`）时，保持默认空值即可。	(?<=。)
SourceType	string	否	注意此参数在最新版 SDK 中已改为必传，否则调用 SubmitIndexJob 接口将报错：Required parameter(data_sources) missing or invalid。导入数据来源。取值范围： DATA_CENTER_CATEGORY：类目类型，即导入应用数据中指定类目下的所有文件，可同时导入多个类目。 DATA_CENTER_FILE：文件类型，即导入应用数据下的指定文件，可同时导入多个文件。说明如果本参数传入 DATA_CENTER_CATEGORY，则必须指定`CategoryIds`参数；如果本参数传入 DATA_CENTER_FILE，则必须指定`DocumentIds`参数。说明要创建空知识库，可使用不含文件的空类目：本参数传入 DATA_CENTER_CATEGORY，`CategoryIds`传入空类目 ID。	DATA_CENTER_FILE
DocumentIds	array	否	创建知识库时可同步导入文件。此处可指定需要导入的文件列表（传入文件 ID，建议导入不超过 10000 个。如有剩余文件，后续可调用 SubmitIndexAddDocumentsJob 接口继续导入）。
	string	否	文件 ID，即 AddFile 接口返回的`FileId`，或者在应用数据-文件页签，单击文件名称旁的 ID 图标获取。	file_9a65732555b54d5ea10796ca5742ba22_xxxxxxxx
CategoryIds	array	否	创建知识库时可同步导入文件。此处通过指定类目 ID，可导入对应类目下的所有文件（建议导入不超过 10000 个。如有剩余文件，后续可调用 SubmitIndexAddDocumentsJob 接口继续导入）。
	string	否	类目 ID，即 AddCategory 接口返回的`CategoryId`。或者在应用数据-文件页签，单击类目旁的 ID 图标获取。	ca_hiu2383nfxxxx
TableIds	array	否	说明该参数暂不开放，请勿传入。
	string	否	说明该参数暂不开放，请勿传入。
DataSource	object	否	说明该参数暂不开放，请勿传入。
CredentialId	string	否	说明该参数暂不开放，请勿传入。
CredentialKey	string	否	说明该参数暂不开放，请勿传入。
Database	string	否	说明该参数暂不开放，请勿传入。
Endpoint	string	否	说明该参数暂不开放，请勿传入。
IsPrivateLink	boolean	否	说明该参数暂不开放，请勿传入。
Region	string	否	说明该参数暂不开放，请勿传入。
SubPath	string	否	说明该参数暂不开放，请勿传入。
SubType	string	否	说明该参数暂不开放，请勿传入。
Table	string	否	说明该参数暂不开放，请勿传入。
Type	string	否	说明该参数暂不开放，请勿传入。
SinkType	string	是	知识库的向量存储类型。更多信息，请参见知识库。取值范围： BUILT_IN：将向量数据托管在阿里云百炼平台中。 ADB：AnalyticDB for PostgreSQL 数据库。如需高级功能，如管理、审计和监控数据库，推荐选择 ADB。说明若您尚未在阿里云百炼上使用过 ADB 存储，可前往创建知识库页面选择向量存储类型为 ADB-PG，并按界面提示完成授权。如果您传入了 ADB，则必须指定`SinkInstanceId`和`SinkRegion`参数。	BUILT_IN
SinkInstanceId	string	否	AnalyticDB for PostgreSQL 实例 ID（仅在`SinkType`指定 ADB 时才需要传入）。请前往AnalyticDB for PostgreSQL 数据实例列表页面获取此 ID。	gp-bp32109xxxx
SinkRegion	string	否	AnalyticDB for PostgreSQL 实例所在地域（仅在`SinkType`指定 ADB 时才需要传入）。您可调用 DescribeRegions 获取地域列表。	cn-hangzhou
Columns	array<object>	否	说明该参数暂不开放，请勿传入。
	object	否	说明该参数暂不开放，请勿传入。
Column	string	否	说明该参数暂不开放，请勿传入。	school
IsRecall	boolean	否	说明该参数暂不开放，请勿传入。	true
IsSearch	boolean	否	说明该参数暂不开放，请勿传入。	true
Name	string	否	说明该参数暂不开放，请勿传入。	学校
Type	string	否	说明该参数暂不开放，请勿传入。	string
Description	string	否	知识库描述。长度为 0~1000 个英文或中文字符。默认值为空。	企业帮助文档库包括了公司制度、产品清单等重要资料。
metaExtractColumns	array<object>	否	元数据提取配置。元数据是与非结构化数据内容相关的一系列附加属性，这些属性以 key-value 键值对的形式集成到文本切片中。更多信息，请参见知识库。
	object	否
Key	string	否	元数据字段，长度为 1~50 个字符，必须为英文或下划线。如果指定本参数，则必须指定`Value`和`Type`参数。	author
Value	string	否	元数据字段的值。	Tim
Type	string	否	元数据字段的取值方法。取值范围： constant：常量。 variable：变量。 custom_prompt：大模型。 regular：正则。 keywords：关键词搜索。枚举值： constant：常量抽取。 keywords：关键词抽取。 custom_prompt：大模型。 variable：变量抽取。 regular：正则。	constant
Desc	string	否	元数据字段的中文描述。长度为 0~1000 个字符，支持中文、英文、数字、下划线（_）、短划线（-）、半角句号（.）和半角冒号（:）。默认值为空。	作者名
EnableLlm	boolean	否	开启后表示该元数据字段和值将和文本切片的内容一同参与大模型的回答生成过程。取值范围： true：开启。 false：不开启。默认值为 false。	false
EnableSearch	boolean	否	开启后表示该元数据字段和值将和文本切片的内容一同参与知识库检索。取值范围： true：开启。 false：不开启。默认值为 false。	false
enableHeaders	boolean	否	是否将所有 xlsx、xls 格式文件的第一行数据作为表头，并拼接到每个文本切片中，避免大模型误将表头当作普通数据行来处理。说明建议仅在导入文件均为 .xlsx、.xls 格式且包含表头时启用该功能，否则无需开启。取值范围： true：开启。 false：不开启。若未指定，默认不开启。	false
chunkMode	string	否	启用自定义切分，并指定切分策略。更多说明，请参见知识库。可能取值（不支持同时传入多个值）： length：按长度切分。严格按照您指定的`ChunkSize`和`OverlapSize`切分。若您未传入这两个参数，系统将采用默认值（`ChunkSize`为 500，`OverlapSize`为 100）。按长度切分不支持`Separator`（即使传入也不生效）。 page：按页切分。如果指定了`ChunkSize`，切分时将一并考虑（未传入时，将使用默认值 500）。按页切分不支持`OverlapSize`和`Separator`（即使传入也不生效）。 h1：按照一级标题切分。如果指定了`ChunkSize`，切分时将一并考虑（未传入时，将使用默认值 500）。按照一级标题切分不支持`OverlapSize`和`Separator`（即使传入也不生效）。 h2：按照二级标题切分。如果指定了`ChunkSize`，切分时将一并考虑（未传入时，将使用默认值 500）。按照二级标题切分不支持`OverlapSize`和`Separator`（即使传入也不生效）。 regex：按照正则切分，此时必须指定`Separator`参数。如果指定了`ChunkSize`，切分时将一并考虑（未传入时，将使用默认值 500）。按正则切分不支持`OverlapSize`（即使传入也不生效）。若未指定，默认采用智能切分。	regex
EnableRewrite	boolean	否	是否开启多轮对话改写。取值范围： true：开启。 false：不开启。若未指定，默认为开启。	true
CreateIndexType	string	否	说明该参数暂不开放，请勿传入。

返回参数

名称	类型	描述	示例值
	object	Schema of Response
Code	string	错误状态码。
Data	object	请求成功时返回的业务数据。
Id	string	知识库 ID，又称`IndexId`，创建的知识库唯一标识。说明请妥善保管该值，它将用于后续所有与此知识库相关的 API 操作。	jkurxhxxxx
Message	string	错误信息。
RequestId	string	请求 ID。	17204B98-xxxx-4F9A--2446A84821CA
Status	string	接口返回的状态码。	200
Success	boolean	请求是否成功，可能值为： true：成功。 false：失败。	true

示例

正常返回示例

JSON格式

{
  "Code": "",
  "Data": {
    "Id": "jkurxhxxxx"
  },
  "Message": "",
  "RequestId": "17204B98-xxxx-4F9A--2446A84821CA",
  "Status": 200,
  "Success": true
}

错误码

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

变更历史

变更时间	变更内容概要	操作

暂无变更历史