调用API为LLM智能问答版批量推送文档-智能开放搜索 OpenSearch-阿里云

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

前提条件

获取身份鉴权API Key：调用OpenSearch-LLM智能问答版服务时，需要对调用者身份进行鉴权，具体请参见管理API Key。
获取服务调用地址：调用OpenSearch-LLM智能问答版服务时，需要提供服务的调用地址，具体请参见获取服务调用地址。

接口信息

请求方法	请求协议	请求数据格式
POST	HTTP	JSON

请求URL

{host}/v3/openapi/apps/[app_group_identity]/actions/knowledge-bulk

{host}：调用服务的地址，支持通过公网和VPC两种方式调用API服务，可参见获取服务调用地址。
{app_group_identity}：应用名称，需要登录OpenSearch-LLM智能问答版控制台，在实例管理中查看对应实例的应用名称。

请求参数

Header参数

参数	类型	是否必填	描述	示例值
Content-Type	string	是	请求的数据格式，目前仅支持JSON格式，固定填写"application/json"。	application/json
Authorization	string	是	请求鉴权的API Key，Bearer开头。	Bearer OS-d1**2a

Body参数

参数	类型	是否必填	描述	示例值
cmd	string	是	操作指令。	ADD/DELETE
fields	map	是	字段组合。
fields.id	string	是	主键ID。	13579
fields.title	string	否	文档标题。	Something interesting
fields.url	string	否	文档的链接。	https://www.aliyun.com
fields.content	string	是	文档的内容。	No, is not.

请求体示例

1、上传主表文档

['{
    "cmd": "ADD",
    "fields": {
      "id": "13579",
      "title": "Something interesting",
      "url": "https://www.aliyun.com",
      "content": "No, is not."
      }
}']

上传非结构化文档（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",
    "fields": {					# 数据体，根据表格schema定义
      "key1": "value1",
      "key2": "value2",
      "key3": "value3"
    },
    "table_name": "辅表表名"	# 表名，空默认为主表
  }']

3、删除表

['{
    "cmd" : "DELETE",
    "fields": {
      "id": "13579333"
    }
}']

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 编码，否则会出现推送报错问题。
若接口调用返回错误码 4016，此错误为用户通过RAM用户调用文档推送时权限不足，请为RAM用户授予AliyunOpenSearchFullAccess权限，具体操作请参见为RAM用户授权。