add

请求方法

POST

客户端对向量数据库服务器请求的操作类型

请求头

Content-Type: application/json

请求消息类型

Authorization: HMAC-SHA256 ***

鉴权

collection_name

string

是

知识库的名字。

add_type

string

是

表示文档添加的方式，可为以下枚举值：

• url：提供了可以直接下载的url链接
• tos：tos的已授权目录，目前只支持华北区域

doc_id

string

否

一个知识库下的文档唯一标识。

• 只能使用英文字母、数字、下划线_，并以英文字母开头，不能为空。
• 长度要求：[1, 128]。

注：

• 多次上传，重复的doc_id会进行覆盖（新上传的覆盖旧的）。
• add_type为url时，该字段必传。
• add_type为tos时，该字段无效。系统会自动从tos文件的meta中获取。

doc_name

string

否

文档名称：

• 长度要求：[1, 256]。
• add_type为url时，该字段必传。
• add_type为tos时，该字段无效，系统会自动从tos中获取。

doc_type

string

否

上传文档的类型，当前支持以下类型：txt, doc, docx, pdf, markdown/md, faq.xlsx, pptx
注：

• add_type为url时，该字段必传。
• add_type为tos时，该字段无效，系统会自动从tos文件的扩展名中获取。
• 关于文档大小的限制：
  • 对于doc，docx，pdf类型的文档，大小限制为20M。
  • 对于txt类型的文档，大小限制为5M
• 关于文档生成chunk数的限制：
  • 单个文档的生成的chunk数限制为10K个。

【对于faq格式的说明】

1. 上传文档时，需要通过特殊的后缀.faq进行标识，格式为：文档名.faq.xlsx；文档固定格式为一列问题、一列答案，示例：Q&A问答对示例
2. 解析限制说明：支持解析多个sheet，不超过50个；多个sheet总行数上限为1w，超过文档处理失败；对于问题或答案为空的行会跳过不做处理。

tos_path

string

否

• add_type为url时，该字段无效。
• add_type为tos时，该字段必传。
• 已授权的tos目录（如下图），已支持格式的文件会被自动导入到知识库。

• 文档需有doc_id信息，该信息保存在tos上文件的元数据信息上。如果doc_id的值不符合格式规范，文档将不会被添加进知识库。如果没有doc_id字段，系统会自动使用文档的完整路径生成hash后生成doc_id。
• 元数据信息上除doc_id外的其他信息会被当做文件的doc_meta信息保存。

注：

• 导入目录下的文档是一次性的，后续目录下的文档变更不会被自动同步到知识库。
• 目录下文档的doc_id不能重复，如果有重复，最终只会保留其中的一个文档。
• 如果目录中有库中已有的文档（doc_id相同），会使用tos中的文档替换已有的文档。
• 如果目录下文件内容的变更需求，有以下两种方式：
  • 通过url方式导入，并指定要替换文档的doc_id（相对比较快）。
  • 通过tos方式导入，这种方式会对目录下所有的文档做变更检查，并将新文档替换旧文档。由于需要做文件校验，这种方式耗时较长。
• 当前tos目录的导入文件数量限制为10K个，超过的将不会被导入。
• 导入目录时只会扫描目录下的文件，而不会递归查看子目录。

url

string

否

• 上传文档的url链接，对应url链接的文档不超过20M。
• add_type为url时，该字段必传，字段长度需要范围是 1-1024。
• add_type为其他值时，该字段无效。

meta

array 或array对应的json字符串

否

• add_type为url时，该字段有效；
• add_type为其他值时，该字段无效。
• array中是需要添加的meta信息，meta信息为如下格式：

{
"field_name": 字段名
"field_type": 字段类型
"field_value": 字段的值
}
注：

• 这3个字段均为必传，其中field_name不能为doc_id。
• 其中field_name为string类型，使用英文字母，数字，下划线，并以英文字母开头，长度不得超过128；field_type支持int64，float32，string，bool，list, list类型，限制参考VikingDB的field_type规则和说明。
• 存在于collection的fields中的field_name可以用于在检索时的字段筛选，不存在的只能用于信息展示(注意类型需要保持一致）。

code

状态码

message

返回信息

request_id

标识每个请求的唯一标识符

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数量已满