@re-ai/volc-knowledge/docs/参考文档/知识库/create.md

火山引擎知识库接口接入SDK

# 创建知识库接口文档
## 一、接口概述
`/api/knowledge/collection/create`接口用于创建新的知识库，创建成功后可进行数据导入。

## 二、前提条件
完成“签名鉴权方式”页面的注册账号、实名认证、AK/SK密钥获取和签名获取后，方可调用该API接口创建知识库。

## 三、请求接口
|参数|详情|描述|
|---|---|---|
|URI|`/api/knowledge/collection/create`|统一资源标识符|
|请求方法|POST|客户端对向量数据库服务器请求的操作类型|
|请求头|`Content-Type: application/json`<br>`Authorization: HMAC-SHA256 ***`|请求消息类型<br>鉴权|

## 四、请求参数
|参数|子参数|类型|是否必选|默认值|参数说明|
|---|---|---|---|---|---|
|name|--|string|是|--|知识库名字，只能用英文字母、数字、下划线_，需以英文字母开头，不能为空，长度[1-64]，且名称不能重复|
|project|--|string|否|default|知识库所属项目，在【访问控制】-【资源管理】-【项目】中创建|
|description|--|string|否|""|知识库描述信息，长度[1, 65535]|
|data_type|--|string|否|unstructured_data|知识库内的数据类型，可选“unstructured_data”（非结构化数据）、“structured_data”（结构化数据）|
|preprocessing|chunking_strategy|string|否|--|切片策略，枚举值["custom_balance", "custom"]。“custom_balance”为新默认策略，提升多种文档解析能力和检索性能；“custom”为自定义分隔符策略。原“default”仅兼容存量知识库|
|preprocessing|chunking_identifier|list|否|--|自定义分隔符号，仅“custom”策略时生效|
|preprocessing|chunk_length|int|否|500|切片最大长度，取值参考向量化模型及索引算法对照表|
|preprocessing|merge_small_chunks|bool|否|true|是否合并短文本片，合并后长度不超切片最大长度|
|preprocessing|multi_modal|--|否|--|图片召回策略，枚举值"image_ocr"，传参开启，不传不开启，新创建知识库不推荐用旧参数名“multi_mode”|
|table_config|table_type|string|否|--|当data_type为“structured_data”时生效，“row”表示从行开始解析，“col”表示从列开始解析|
|table_config|table_pos|int|否|--|字段位于第几行或列|
|table_config|start_pos|int|否|--|起始数据所在行|
|table_config|table_fields|object|否|--|包含字段名称、类型、是否参与索引、默认值、是否为过滤字段等信息的列表|
|index|index_config|object|否|--|索引配置|
|index|index_config.fields|object|否|--|标签，数量限制180个且名称不可重复，不能以“_sys_auto”开头，不传或值为空则不加入筛选字段|
|index|index_config.cpu_quota|int|否|1|cpu配额，大于0|
|index|index_config.embedding_model|string|否|doubao-embedding-and-m3|指定向量化模型，可选范围参考对照表|
|index|index_config.embedding_dimension|int|否|2048|向量维度，可选范围参考对照表|
|index|index_config.quant|string|否|int8|向量量化方式，可选范围参考对照表|
|index|index_type|string|否|hnsw_hybrid|指定索引算法，支持hnsw_hybrid、hnsw和flat，推荐“hnsw_hybrid”|

## 五、响应消息
|参数|参数说明|
|---|---|
|code|状态码|
|message|返回信息|
|data|返回的详细信息，包含“resource_id”（知识库的唯一id）|
|request_id|标识每个请求的唯一标识符|

## 六、状态码说明
|状态码|http状态码|返回信息|状态码说明|
|---|---|---|---|
|0|200|success|成功|
|1000001|403|unauthorized|鉴权失败|
|1000002|403|no permission|权限不足|
|1000003|400|invalid request：%s|非法参数，包括缺失必选参数、collection命名不规范、字段类型与属性不满足约束条件等|
|1000004|400|collection exist|collection已存在|

## 七、完整示例
### （一）请求消息
```bash
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"
}'
```

### （二）响应消息
1. **执行成功返回**
```json
HTTP/1.1 200 OK
Content-Length: 43
Content-Type: application/json
{
    "code":0,
    "message":"success",
    "data": {
        "resource_id": "kb-8349ef57441ab57"
    },
    "request_id":"021695029537650fd001de666660000000000000000000230da93"
}
```
2. **执行失败返回**
```json
HTTP/1.1 400 OK
Content-Length: 43
Content-Type: application/json
{"code":1000003, "message":"invalid request：%s", "request_id": "021695029757920fd001de6666600000000000000000002569b8f"}
```