@re-ai/volc-knowledge/docs/参考文档/切片/add.md

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

# 新增知识库切片接口文档
## 一、接口概述
`/api/knowledge/point/add`接口用于在已有的知识库中，为指定文档新增一个切片。通过该接口，用户可以向知识库中添加不同类型的切片，包括非结构化的文本切片、FAQ切片以及结构化数据切片。

## 二、前置条件
完成“签名鉴权方式”页面的注册账号、实名认证、AK/SK密钥获取和签名获取后，才可以调用此API接口实现新增切片的功能。

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

## 四、请求参数
|参数|类型|是否必选|默认值|备注|
|---|---|---|---|---|
|collection_name|string|否|--|知识库名称，由英文字母、数字、下划线组成，以英文字母开头，不能为空，长度在1 - 64之间|
|project|string|否|default|知识库所属项目，在【访问控制】-【资源管理】-【项目】中创建|
|resource_id|string|否|--|知识库唯一id，可直接传该参数，或同时传`name`和`project`作为知识库的唯一标识|
|doc_id|string|是|--|新增切片所属的文档id，若不存在则报错|
|chunk_type|string|是|--|要添加的切片类型，取值为“structured”（结构化知识库）、“text”（非结构化纯文本切片）、“faq”（非结构化faq类型切片），与知识库类型不匹配时会报错|
|content|string|`chunk_type`为“text”或“faq”时必选|--|新增切片文本内容，“chunk_type”为“text”时表示非结构化文档切片内容；“chunk_type”为“faq”时表示答案字段|
|question|string|`chunk_type`为“faq”时必选|--|表示问题字段，长度范围为[1，Embedding模型支持的最大长度]|
|fields|list|`chunk_type`为“structured”时必选|--|结构化数据，字段名称必须已在`collection`里配置，否则报错，拼接后的embedding文本长度不超65535|

## 五、响应消息
|字段|参数说明|
|---|---|
|code|状态码|
|message|返回信息|
|request_id|标识每个请求的唯一标识符|
|data|包含collection_name（知识库名字）、resource_id（知识库唯一标识）、project（项目名）、doc_id（文档id）、chunk_id（切片在文档下的id，在文档内唯一）、point_id（切片id，在知识库下唯一）|

## 六、状态码说明
|状态码|http状态码|返回信息|状态码说明|
|---|---|---|---|
|0|200|success|成功|
|1000001|401|unauthorized|鉴权失败|
|1000002|403|no permission|权限不足|
|1000003|400|invalid request：%s|非法参数|
|1000005|400|collection not exist|collection不存在|
|1001001|400|doc not exist|doc不存在|

## 七、完整示例
### （一）请求消息
```bash
curl -i -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: HMAC-SHA256 ***' \
  https://api-knowledgebase.mlp.cn-beijing.volces.com/api/knowledge/point/add \
  -d '{
    "collection_name": "test_collection_name",
    "project": "default",
    "doc_id": "your_doc_id",
    "chunk_type": "text",
    "content": "test content"
}'
```

### （二）响应消息
1. **执行成功返回**
```json
HTTP/1.1 200 OK
Content-Length: 43
Content-Type: application/json
{
    "code": 0,
    "data": {
        "collection_name": "lzm_test2",
        "project": "default",
        "resource_id": "kb-a638e4045e9708f0",
        "doc_id": "_sys_auto_gen_doc_id-9744689384778553745",
        "chunk_id": 7,
        "point_id": "_sys_auto_gen_doc_id-9744689384778553745-7"
    },
    "message": "success",
    "request_id": "02173431739184000000000000000000000ffff0a0078dc15a2fe"
}
```
2. **执行失败返回**
```json
HTTP/1.1 400 OK
Content-Length: 43
Content-Type: application/json
{"code":1000003, "message":"invalid request：%s", "request_id": "021695029757920fd001de6666600000000000000000002569b8f"}
```