PushKnowledgeDocuments-文档推送

OpenSearch-LLM智能问答版支持通过API的方式批量推送文档。

URL

POST /v3/openapi/apps/[app_group_identity]/actions/knowledge-bulk
  • [app_group_identity]:表示应用名(需要指定应用名访问,主要针对服务中的应用版本)。

  • 以上 URL 省略了请求Header参数及编码等因素。

  • 以上 URL 中省略了访问应用的 host 地址。

POST

请求参数

参数

类型

位置

描述

app_group_identity

String

Path

应用名称(AppName)

Object

Body

批量推送结构

Doc 的参数

名称

类型

是否必选

描述

cmd

String

操作指令。

fields

Map

字段组合

fields 的参数

名称

类型

是否必选

描述

id

Int

主键ID

title

String

文档标题

url

String

文档的链接

content

String

文档的内容

请求体示例:

1、上传主表文档

[
  {
    "cmd": "ADD",
    "fields": {
    	"id": "13579",
      "title": "Something interesting", //可选字段
      "url": "https://www.aliyun.com",	//可选字段
      "content": "No, it's not."
  	}
  },
  {
    "cmd": "DELETE",
    "fields": {
    	"id": "2468"
  	}
  }
]

上传非结构化文档(pdf/doc/txt/html)

[
  {
    "cmd" : "URL/BASE64",
    "fields": {
      "id": "文档id(可选)",
      "type": "文件类型,pdf/doc/txt/html...",
      "title": "文件名(可选)",
      "content": "URL/Base64编码数据",
      "url": "链接(可选)"
    }
  }
]

注:URL仅支持OSS的通过ossClient.generatePresignedUrl生成的数据访问URL

2、上传辅表

[
  {
    "cmd" : "ADD/DELETE",
    "fields": {					# 数据体,根据表格schema定义
      "key1": "valse1",
      "key2": "valse2",
      "key3": "valse3"
    },
    "table_name": "辅表表名"	# 表名,空默认为主表
  }
]
  • cmd : 必选字段。定义该文档的操作行为,可以为“add”、“delete”。建议一个请求中进行批量更新操作,提高网络交互及处理效率。“add”表示新增文档,如果该主键对应文档已经存在,则会覆盖原来文档;“delete”表示删除文档,如果该主键对应文档已经不存在,则认为删除成功。

  • fields : 必选字段。要操作的文档内容,主键字段必选,系统所有操作都是通过主键来进行的。对于“delete”只需要提供文档主键即可。

  • 注意:最外层是JsonArray类型,支持多个文档批量操作。

返回参数

参数

类型

描述

errors

List

错误内容

status

String

status:执行结果,OK为成功,FAIL为失败,请根据返回错误码进行排查

request_id

String

当前请求的 request_id

result

Boolean

执行成功返回该参数,值为true,报错不返回该参数

total

Int

上传文档的总数

success

Int

上传成功文档数

failure

Int

上传失败的文档数

failed_ids

Array

上传失败的文档id

响应体示例:

{
  "request_id" : "abc123-ABC",
  "result" : {
    "total": 100,
    "success": 50,
    "failure": 50,
    "failed_ids": [
      "id1",
      "id2",
      "id3",
      "..."
    ]
  }
  "errors" : [
    {
      "code" : "如果有错误,这里填错误码",
      "message" : "如果有错误,这里填错误信息"
    }
  ]
}

注意事项

  • 使用API/SDK推送数据时,应用的字段名称大小写不敏感;

  • 使用API/SDK推送数据有次数及大小限制,不同应用限制不同,具体请参考使用限制描述;

  • 数据上传后请务必检查返回值,并对相关错误码进行重试(尤其是3007错误),否则会出现数据丢失情况。同时,数据处理是异步的,系统返回“OK”后只表示系统接收数据成功,数据处理过程的错误会在控制台错误信息中展示,请注意及时检查;

  • POST的数据大小有限制,如果您上传的文档总量过大(编码前2M),服务器将拒绝接收任何参数,同时返回异常;

  • POST推送操作 body 部分的数据若包含中文必须要做 utf-8 编码,Header中的Content-MD5 参数也一样,在计算数据 MD5 值前,必须要先进行 utf-8 编码,否则会出现推送报错问题;