Skip to main content

Create a Knowledge Base and Import Documents

Create a knowledge base and import documents in one step.

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.
knowledgeTypeConsole labelstructureTypeAvailable knowledgeScene
documentDocument Searchunstructuredbasic_document_qa (basic document Q&A)
visual_perception_qa (visual understanding, rich text documents)
lite_document_qa (express Q&A)
tableData Querystructuredbasic_table_qa (fixed)
imageImage Q&Aunstructuredimage_qa (fixed)
multimediaAudio and Video Searchunstructuredbasic_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

数据源配置列表。

​
enum<string>

知识库类型，取值与 structureType/knowledgeScene 的匹配见知识库类型与使用场景

Available options:document,table,image,multimedia
​
enum<string>

使用场景，取值取决于 knowledgeType，见知识库类型与使用场景

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