@re-ai/volc-knowledge
Version:
火山引擎知识库接口接入SDK
98 lines (91 loc) • 6.03 kB
Markdown
# 向知识库导入文档接口文档
## 一、接口概述
`/api/knowledge/doc/add`接口用于向已创建的知识库导入文档，文档类型需符合支持文档格式说明。
## 二、前提条件
完成“签名鉴权方式”页面的注册账号、实名认证、AK/SK密钥获取和签名获取后，可调用该API接口实现文档导入功能。
## 三、请求接口
|参数|详情|描述|
|---|---|---|
|URI|`/api/knowledge/doc/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作为唯一标识|
|add_type|--|string|是|--|文档添加方式，枚举值为“url”（提供可下载链接）、“tos”（tos已授权目录，仅支持华北区域）、“lark”（上传飞书文档）|
|doc_id|--|string|否|--|知识库下的文档唯一标识，由英文字母、数字、下划线组成，以英文字母开头，不能为空，长度在1 - 128之间。“add_type”为“url”时必传，“add_type”为“tos”时无效，“add_type”为“lark”时可选，未传则自动生成|
|doc_name|--|string|否|--|文档名称，长度在1 - 256之间。“add_type”为“url”时必传，“add_type”为“tos”和“lark”时无效，系统自动获取|
|doc_type|--|string|否|--|上传文档的类型，非结构化文档支持txt、doc等，结构化文档支持xlsx等。“add_type”为“url”时必传，“add_type”为“tos”时无效，“add_type”为“lark”时可选|
|lark_file|url<br>obj_type<br>obj_token<br>include_childe|json|否|--|飞书文档地址信息，“url”和“obj_type + obj_token”二选一，“include_childe”默认为false|
|tos_path|--|string|否|--|已授权的tos目录或指定文件路径，“add_type”为“tos”时必传，其他情况无效|
|url|--|string|否|--|上传文档的url链接，对应文档不超20MB。“add_type”为“url”时必传，长度在1 - 1024之间，其他情况无效|
|meta|field_name<br>field_type<br>field_value|array/json字符串|否|--|meta信息，“add_type”为“url”或“lark”时有效，“add_type”为“tos”时无效|
|dedup|--|bool|否|--|是否去重，任一子参数为true时生效，检查content和doc name，其他信息变更不检查|
|content_dedup|--|bool|否|false|内容去重，查找库中相同doc hash的文档，根据文档数量和auto_skip参数处理|
|doc_name_dedup|--|bool|否|false|文档名称去重，查找库中相同doc name的文档，根据文档数量和auto_skip参数处理|
|auto_skip|--|bool|否|false|重复文档处理策略，true时自动跳过重复文档并返回原始ID，false时覆盖并返回新ID|
## 五、响应消息
|参数|参数说明|备注|
|---|---|---|
|code|状态码| - |
|message|返回信息| - |
|request_id|标识每个请求的唯一标识符| - |
|data|包含collection_name（知识库名字）、resource_id（知识库唯一标识）、project（项目名）、doc_id（文档唯一标识）|通过tos目录/飞书导入时，不会返回|
## 六、状态码说明
|状态码|http状态码|返回信息|状态码说明|
|---|---|---|---|
|0|200|success|成功|
|1000001|401|unauthorized|鉴权失败|
|1000002|403|no permission|权限不足|
|1000003|400|invalid request：%s|非法参数|
|1000005|400|collection not exist|collection不存在|
|1001010|400|doc num is exceed 10000|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/doc/add \
-d '{
"collection_name": "test_collection_name",
"project": "",
"add_type": "url",
"doc_id": "test0123",
"doc_name": "张某某盗窃案",
"doc_type": "pdf",
"url": "https://fwh-my-test-bucket.tos-cn-beijing.volces.com/%E6%96%B0%E6%A9%99%E7%A7%91%E6%8A%80/%E5%91%A8%E6%9D%A8%E7%9B%97%E7%AA%83%E6%A1%88.pdf?X-Tos-Algorithm=TOS4-HMAC-SHA256&X-Tos-Content-Sha256=UNSIGNED-PAYLOAD&X-Tos-Credential=AKTP0UZNtgnE7Lfth5eB2z0Z9qy2gyewikK9nbStjHp0OY%2F20240325%2Fcn-beijing%2Ftos%2Frequest&X-Tos-Date=20240325T114024Z&X-Tos-Expires=3600&X-Tos-SignedHeaders=host&X-Tos-Security-Token=nCgdqdEROend3.ChsKBzNzX056d3cSEGBgA9av-UtVs7ClfMkXS4oQk8WFsAYYo-GFsAYgle7V6QcoAjCSkLEJOhx6aGFpeXVqaWEuMDMyMkBieXRlZGFuY2UuY29tQgN0b3NSHHpoYWl5dWppYS4wMzIyQGJ5dGVkYW5jZS5jb21YBGAB.Nur_XCwZ_1LHmSsfeWGjDUn8SEOo3c6op5hx3lUgLZuxtHN_sqs-Kd0KbKw-51CT6wXKQo3AbmidScqVTu6gLQ&X-Tos-Signature=5c3dff2f8cd67daae99476d54188033cc32932d87f1ff85f4f1afd5862fa35cd",
"meta":[
{"field_name":"行业","field_type":"string", "field_value":"企业服务"},
{"field_name":"是否公开","field_type":"bool", "field_value":true}
]
}'
```
### （二）响应消息
1. **执行成功返回**
```json
HTTP/1.1 200 OK
Content-Length: 43
Content-Type: application/json
{
"code":0,
"message":"success",
"request_id":"021695029537650fd001de666660000000000000000000230da93",
"data":{
"collection_name": "张某某盗窃案",
"resource_id": "kb-8349ef57441ab57",
"project": "default",
"doc_id": "_sys_auto_gen_doc_id-17691607628519396693"
}
}
```
2. **执行失败返回**
```json
HTTP/1.1 400 OK
Content-Length: 43
Content-Type: application/json
{"code":1000003, "message":"invalid request：%s", "request_id": "021695029757920fd001de6666600000000000000000002569b8f"}
```