Create a Knowledge Base and Import Documents - 阿里云百炼 Agent Studio

POST

/api/v1/indices/rag/index/create_v2

cURL

curl -X POST "https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/indices/rag/index/create_v2" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-knowledge-base",
    "description": "知识库描述信息",
    "structureType": "unstructured",
    "sinkType": "DEFAULT",
    "sourceType": "DATA_CENTER_FILE",
    "embeddingModelName": "text-embedding-v4",
    "chunkSize": 600,
    "docIds": ["file_abc123", "file_def456"],
    "dataSources": [{"sourceType": "DATA_CENTER_FILE"}]
  }'

{
  "code": "Success",
  "status_code": 200,
  "success": true,
  "message": "success",
  "data": {
    "pipelineId": "your_pipeline_id",
    "ingestionId": "ing_abc123",
    "status": "PENDING",
    "created_at": 1783657930436,
    "updated_at": 1783657930436
  },
  "request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "SUCCESS"
}

The file ID parameter is docIds — not file_ids or fileIds. However, the validation error message uses the internal name file_ids.

Knowledge Base type and usage scenario

knowledgeType and knowledgeScene correspond to Knowledge Base Type and Usage Scenario in step 1 of the console creation wizard. They must be supplied together or omitted together — sending only one returns knowledgeType and knowledgeScene cannot be empty. When both are omitted, the system applies defaults based on structureType. The console only offers a Usage Scenario choice for Document Search. The other three types have a fixed scenario that the console fills in automatically, but you must still send the pair explicitly when creating a Knowledge Base through the API.

knowledgeType	Console label	structureType	Available knowledgeScene
`document`	Document Search	`unstructured`	`basic_document_qa` (basic document Q&A) `visual_perception_qa` (visual understanding, rich text documents) `lite_document_qa` (express Q&A)
`table`	Data Query	`structured`	`basic_table_qa` (fixed)
`image`	Image Q&A	`unstructured`	`image_qa` (fixed)
`multimedia`	Audio and Video Search	`unstructured`	`basic_multimedia_qa` (fixed)

An incompatible knowledgeType and structureType pair returns knowledgeType and structureType do not match. A knowledgeScene that does not belong to the selected type returns knowledgeType and knowledgeScene do not match.
lite_document_qa (express Q&A) requires sinkType to be BUILT_IN. Using the default DEFAULT returns Lite Rag only supports BUILT_IN sink type.
visual_perception_qa and image_qa must specify a multimodal embedding model through multimodalEmbeddingModelName (for example qwen3-vl-embedding), otherwise the request returns invalid multi embedding model.
The document type also has a visual_document_qa (rich media answers) scenario. The API still accepts this value, but the console no longer exposes it, so avoid it for new Knowledge Bases.

Example request body for image Q&A:

{
  "name": "image-kb",
  "description": "Image Q&A Knowledge Base",
  "structureType": "unstructured",
  "knowledgeType": "image",
  "knowledgeScene": "image_qa",
  "sinkType": "BUILT_IN",
  "sourceType": "DATA_CENTER_FILE",
  "multimodalEmbeddingModelName": "qwen3-vl-embedding",
  "docIds": ["file_abc123"],
  "dataSources": [{ "sourceType": "DATA_CENTER_FILE" }]
}

Authorizations

string

header

required

DashScope API Key，在控制台 API Key 页面获取。

Body

application/json

string

required

知识库名称，1-20 字符。

Required range:length: 1–20

string

required

知识库描述，1-200 字符。

Required range:length: 1–200

enum<string>

required

结构类型：unstructured（非结构化）或 structured（结构化）。

Available options:unstructured,structured

string

default"DEFAULT"

required

存储类型，默认 DEFAULT。BUILT_IN 表示使用平台内置向量存储，knowledgeScene 为 lite_document_qa（极速问答）时必须为 BUILT_IN。

string

required

数据源类型，如 DATA_CENTER_FILE。

string[]

required

必填。创建知识库时同步导入的文件 ID 列表，值来自 addFile 注册文件后返回的 fileId，或通过 listFile 查询已有文件获取。建议导入不超过 10000 个。注意参数名为 docIds，不是 file_ids 或 fileIds；但校验失败时错误信息中的参数名为 file_ids。

Required range:items >= 1

object[]

required

数据源配置列表。

Show child attributes

string

数据源类型，如 DATA_CENTER_FILE。

enum<string>

知识库类型，对应控制台的知识库类型：document（文档搜索）、table（数据查询）、image（图片问答）、multimedia（音视频搜索）。取值需与 structureType 匹配：document、image 和 multimedia 搭配 unstructured，table 搭配 structured。必须与 knowledgeScene 同时提供或同时省略；同时省略时，系统按 structureType 采用默认配置。

Available options:document,table,image,multimedia

enum<string>

使用场景，对应控制台的使用场景，取值取决于 knowledgeType：document 支持 basic_document_qa（基础文档问答）、visual_perception_qa（视觉理解，富文本文档）、lite_document_qa（极速问答）；table 固定为 basic_table_qa；image 固定为 image_qa；multimedia 固定为 basic_multimedia_qa。控制台仅在文档搜索类型下提供场景选项，其余类型自动填入固定值，但通过 API 创建时仍需显式传入。必须与 knowledgeType 同时提供或同时省略。注意：lite_document_qa 要求 sinkType 为 BUILT_IN；visual_perception_qa 和 image_qa 要求通过 multimodalEmbeddingModelName 指定多模态向量模型。此外 document 还接受 visual_document_qa（图文并茂回复），但控制台已不再提供该入口。

Available options:basic_document_qa,visual_document_qa,lite_document_qa,visual_perception_qa,basic_table_qa,image_qa,basic_multimedia_qa

string

向量嵌入模型名称，如 text-embedding-v4。

string

多模态向量模型名称，如 qwen3-vl-embedding。knowledgeScene 为 image_qa（图片问答）或 visual_perception_qa（视觉理解）时必填，缺失或取值非法会返回 invalid multi embedding model。

integer

文档切片大小（字符数）。建议值 300-800。

Required range:x >= 1

string[]

创建知识库时可同步导入文件。通过指定类目 ID，可导入对应类目下的所有文件，建议导入不超过 10000 个。

Response

200-application/json

string

响应码，成功时为 Success。

integer

HTTP 状态码。

boolean

请求是否成功，成功时为 true。

string

响应消息，成功时为 success。

string

请求唯一标识，排查问题时请提供此 ID。

string

请求状态，成功时为 SUCCESS。

object

Show child attributes

string

知识库 ID。

string

导入任务 ID。

string

任务状态，创建后为 PENDING。

integer

知识库创建时间（Unix 毫秒时间戳）。

integer

知识库最近更新时间（Unix 毫秒时间戳）。

​Knowledge Base type and usage scenario

Authorizations

Body

Response

Knowledge Base type and usage scenario