调用API将非结构化文档解析为结构化数据-智能开放搜索 OpenSearch-阿里云-智能开放搜索 OpenSearch(Open Search)-阿里云帮助中心

AI搜索开放平台支持通过API的方式调用文档解析服务，您可以将服务集成到您的业务处理链路中，将非结构化数据解析为结构化数据并应用于业务。

服务名称

服务ID

服务描述

API调用QPS限制（含主账号与RAM子账号）

文档解析服务

ops-document-analyze-001

支持从非结构化文档中提取出标题、分段等逻辑层级结构，以及文本、表格、图片等信息，并以结构化的格式输出。

支持的文档类型：txt、pdf、html、doc、docx、ppt、pptx。

说明

如需扩充QPS，请通过工单联系技术支持协助。

ops-document-analyze-002

提供pdf、图片等多种非结构化文档格式的解析，对复杂元素（表格、公式和图表等）的识别方面出色，且具备较快的推理速度。

使用限制：处理 PDF 文件时，页数不超过 400 页；请求 body 不超过 8 MB。

前提条件

获取身份鉴权信息

通过API调用AI搜索开放平台服务时，需要对调用者身份进行鉴权，如何获取鉴权信息请参见获取API-KEY。
获取服务调用地址

支持通过公网和VPC两种方式调用服务，详情请参见获取服务接入地址。

公共说明

请求body最大不能超过8MB。

概述

文档内容解析提供了同步、异步两类接口。同步接口因存在HTTP超时风险，不建议生产环境中使用，可用于调试接口。生产环境建议使用异步接口，共分为两步，首先通过创建异步提取任务拿到task_id，然后调用获取异步任务接口不断查询状态直至任务完成。

创建异步提取任务

请求方式

POST

URL

{host}/v3/openapi/workspaces/{workspace_name}/document-analyze/{service_id}/async

host：调用服务的地址，支持通过公网和VPC两种方式调用API服务，可参见获取服务接入地址。
workspace_name：工作空间名称，例如default。
service_id：系统内置服务id，例如ops-document-analyze-001。

请求参数

Header参数

API-KEY认证

参数	类型	必填	描述	示例值
Content-Type	String	是	请求类型：application/json	application/json
Authorization	String	是	API-Key	Bearer OS-d1**2a

Body参数

参数	类型	必填	描述	示例值
service_id	String	是	系统内置服务ID。	ops-document-analyze-001
document.url	String	否	文档URL地址，支持HTTP、HTTPS协议（保证可以外网无状态下载）与document.content二选一即可。	http://opensearch-shanghai.oss-cn-shanghai.aliyuncs.com/chatos/***/file-parser/samples/GB10767.pdf
document.content	String	否	文档内容，用Base64Encode编码与document.url二选一即可。	"aGVsbG8gd29ybGQ="
document.file_name	String	否	文档名称，如果为空通过URL推断，如果URL也为空，则需要显式指定。	test.pdf
document.file_type	String	否	文档类型，如果为空从file_name的后缀推断，如果无法推断需要显式指定。支持的文档类型：txt、pdf、html、doc、docx、ppt、pptx。使用 ops-document-analyze-002 处理 PDF 文件时，页数不超过 400 页。	pdf
output.image_storage	String	否	图片存储方式 base64：默认方式 url：url有效期为3天	url
strategy.enable_semantic	Boolean	否	针对txt文档、层级结构不明显的文档，是否在解析过程中启用基于语义理解的层级结构提取功能： true：启用该功能后，模型服务在返回文档解析结果的同时，返回文档的Markdown层级结构信息，有助于提升后续文档切片的准确性。不支持html、ppt及pptx格式的文档。开启该功能后，整体文档解析耗时有所提升。解析时长超过400秒或者超长文档（大于100页）均可能导致系统自动关闭层级结构提取功能。 `usage`计费项参数中增加`semantic_token_count`展示模型使用的Token数，系统根据该Token数计费。默认为false，不开启语义层级结构提取功能。	false

如下图中的文档目录与正文没有明显区分，在开启该功能后，返回结果中层级结构更加准确。

语义结构.jpg

未开启语义结果提取功能：
开启语义结果提取功能后，可以看到开启后返回的结果层级结构更加准确（截图中的“##”表示识别出的二级目录）。

说明
usage.semantic_token_count有返回值表示语义结构提取成功，则收取此计费项产生的Token费用，若无返回值则表示语义提取未成功，则不涉及此计费项。

您可参照以下表格预估开启语义结果提取后的用时及产生的语义Token数。

PDF页数	Token	未开启语义层级结构提取	开启语义层级结构提取
PDF页数	Token	耗时（秒）	耗时（秒）	语义Token
7	11504	2	49	36243
25	10375	1	33	59332
42	41435	5	68	130717

返回参数

参数	类型	描述	示例值
result.task_id	String	文档解析异步任务ID。	d5a4019e-853a-****-b5b6-8053d9f5a9fc

Curl请求示例

curl --location 'http://****shanghai.opensearch.aliyuncs.com/v3/openapi/workspaces/default/document-analyze/ops-document-analyze-001/async/' \
--header 'Authorization: Bearer 您的API Key' \
--header 'Content-Type: application/json' \
--data '{  
  "document":{
      "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241018/jahnyn/%E8%A7%A3%E6%9E%90%E6%B5%8B%E8%AF%95.doc"
    },
    "output" :{
      "image_storage":"base64"
    },
    "strategy": {
      "enable_semantic":true
    }
}'

响应示例

正常响应示例

{
    "request_id": "D5A4019E-853A-4E20-****-8053D9F5A9FC",
    "latency": 5.0,
    "http_code": 200,
    "result": {
        "task_id": "d5a4019e-853a-****-b5b6-8053d9f5a9fc"
    }
}

异常响应示例

在访问请求出错的情况下，输出的结果中会通过code和message指明出错原因。

{
    "request_id": "590A7EB8-AA84-****-AF31-8C35DC965972",
    "latency": 0.0,
    "code": "InvalidParameter",
    "http_code": 400,
    "message": "document.file_name required"
}

获取异步提取任务

请求方式

GET

URL

{host}/v3/openapi/workspaces/{workspace_name}/document-analyze/{service_id}/async/task-status?task_id=${task_id}

host：调用服务的地址，支持通过公网和VPC两种方式调用API服务，可参见获取服务接入地址。
workspace_name：工作空间名称，例如default。
service_id：系统内置服务id，例如ops-document-analyze-001。
task_id：创建文档解析响应中返回的异步任务 ID，例如d5a4019e-853a-****-b5b6-8053d9f5a9fc。

请求参数

Header参数

API-KEY认证

参数	类型	必填	描述	示例值
Content-Type	String	是	请求类型：application/json	application/json
Authorization	String	是	API-Key	Bearer OS-d1**2a

返回参数

参数	类型	描述	示例值
result.task_id	String	文档解析异步任务ID。	24c3ad59-****-40cf-974b-b63d63e0571
result.status	String	任务状态： PENDING: 待处理 SUCCESS: 任务处理成功 FAIL: 任务失败终止	PENDING
result.error	String	status=FAIL时的错误信息内容，正常情况为空。	文档解密失败
result.data	Object	文档解析的结果。	markdown
result.data.content	String	文档解析结果-文档内容 pdf文档输出为markdown格式其他文档输出为html格式	"XXX"
result.data.content_type	String	文档解析结果-内容格式 markdown html	markdown
result.data.page_num	Int	文档解析结果-文档页数。	15
request_id	String	系统对一次API调用赋予的唯一标识。	B4AB89C8-B135-****-A6F8-2BAB8018688
latency	Float/Int	请求耗时，单位ms。	10
usage	Object	本次调用产生的计量信息。	"usage": { "token_count": 123, "table_count": 5, "image_count": 6, "semantic_token_count":3068 }
usage.token_count	Int	文档中字符个数。	1234
usage.table_count	Int	文档中表格个数。	5
usage.image_count	Int	文档中图片个数。	6
usage.semantic_token_count	Int	语义提取模型输入字符个数。	3068

Curl请求示例

curl -XGET -H"Content-Type: application/json" \
"http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/document-analyze/ops-document-analyze-001/async/task-status?task_id=110d6349-2e51-****-8bfb-25e5de434686" \
-H "Authorization: Bearer 您的API-KEY"

响应示例

正常响应示例

{
    "request_id": "27F9CEC3-9052-****-83FF-E7957B680492",
    "latency": 13.0,
    "http_code": 200,
    "result": {
        "status": "SUCCESS",
        "data": {
            "content": "Provided proper attribution is provided, Alibaba hereby grants permission to reproduce the tables and figures in this paper solely for use in journalistic or scholarly works....",
            "content_type": "markdown",
            "page_num": 15
        },
        "task_id": "24c3ad59-b196-****-974b-b63d63e05895"
    },
    "usage": {
        "token_count": 31867,
        "table_count": 4,
        "image_count": 8,
        "semantic_token_count":3068
    }
}

异常响应示例

在访问请求出错的情况下，输出的结果中会通过code和message指明出错原因。

{
    "request_id": "0F94BD89-989C-****-963C-6E4F3FF99445",
    "latency": 3.0,
    "code": "BadRequest.TaskNotExist",
    "http_code": 404,
    "message": "task[2fda34f5-40b4-****-a9a2-3e2c1e807361] not exist"
}

创建同步提取任务

重要

同步接口因存在HTTP超时风险，不建议生产环境中使用，可用于调试接口。

请求方式

POST

URL

{host}/v3/openapi/workspaces/{workspace_name}/document-analyze/{service_id}/sync

参数说明

host：调用服务的地址，支持通过公网和VPC两种方式调用API服务，可参见获取服务接入地址。
workspace_name：工作空间名称，例如default。
service_id：系统内置服务id，例如ops-document-analyze-001。

请求参数

Header参数

API-KEY认证

参数	类型	必填	描述	示例值
Content-Type	String	是	请求类型：application/json	application/json
Authorization	String	是	API-Key	Bearer OS-d1**2a

Body参数

参数	类型	必填	描述	示例值
document.url	String	否	文档URL地址，支持HTTP、HTTPS协议（保证可以外网无状态下载）与document.content二选一即可。	http://opensearch-shanghai.oss-cn-shanghai.aliyuncs.com/chatos/***/file-parser/samples/GB10767.pdf
document.content	String	否	文档内容，用Base64Encode编码与document.url二选一即可。	"aGVsbG8gd29ybGQ="
document.file_name	String	否	文档名称，如果为空从URL推断，如果URL为空需要显式指定。	test.pdf
document.file_type	String	否	文档类型，如果为空从file_name的后缀推断，如果无法推断需要显式指定。支持的文档类型：txt、pdf、html、doc、docx、ppt、pptx。	pdf
output.image_storage	String	否	图片存储方式 base64，默认方式 url，有效期为3天	url
strategy.enable_semantic	Boolean	否	是否开启语义结构提取，默认为false；开启后返回的markdown层次结构更准确，但是耗时会大幅提升，usage计费项会多出semantic_token_count项。默认超时400s，超长文档（>100页）可能会超时并降级为关闭结构提取。不支持html、ppt及pptx格式输入。	false

返回参数

参数	类型	描述	示例值
result.status	String	任务状态： PENDING: 待处理 SUCCESS: 任务处理成功 FAIL: 任务失败终止	PENDING
result.error	String	status=FAIL时的错误信息内容，正常情况为空。	文档解密失败
result.data	Object	文档解析的结果。	markdown
result.data.content	String	文档解析结果-文档内容 pdf文档输出为markdown格式其他文档输出为html格式	"XXX"
result.data.content_type	String	文档解析结果-内容格式 markdown html	markdown
result.data.page_num	Int	文档解析结果-文档页数。	15
request_id	String	系统对一次API调用赋予的唯一标识。	B4AB89C8-B135-****-A6F8-2BAB801A2CE4
latency	Float/Int	请求耗时，单位ms。	10
usage	Object	本次调用产生的计量信息。	"usage": { "token_count": 123, "table_count": 5, "image_count": 6, "semantic_token_count":3068 }
usage.token_count	Int	文档中字符个数。	1234
usage.table_count	Int	文档中表格个数。	5
usage.image_count	Int	文档中图片个数。	6
usage.semantic_token_count	Int	语义提取模型输入字符个数。	3068

Curl请求示例

curl --location 'http://****shanghai.opensearch.aliyuncs.com/v3/openapi/workspaces/default/document-analyze/ops-document-analyze-001/sync/' \
--header 'Authorization: Bearer 您的API Key' \
--header 'Content-Type: application/json' \
--data '{  
  "document":{
      "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241018/jahnyn/%E8%A7%A3%E6%9E%90%E6%B5%8B%E8%AF%95.doc"
    },
    "output" :{
      "image_storage":"base64"
    },
    "strategy": {
      "enable_semantic":true
    }
}'

响应示例

正常响应示例

{
    "request_id": "27F9CEC3-9052-****-83FF-E7957B689D04",
    "latency": 13.0,
    "http_code": 200,
    "result": {
        "status": "SUCCESS",
        "data": {
            "content": "Provided proper attribution is provided, Alibaba hereby grants permission to reproduce the tables and figures in this paper solely for use in journalistic or scholarly works....",
            "content_type": "markdown",
            "page_num": 15
        }
    },
    "usage": {
        "token_count": 31867,
        "table_count": 4,
        "image_count": 8,
        "semantic_token_count":3068
    }
}

异常响应示例

在访问请求出错的情况下，输出的结果中会通过code和message指明出错原因。

{
    "request_id": "6F33AFB6-A35C-****-AFD2-9EA16CCF4383",
    "latency": 2.0,
    "code": "InvalidParameter",
    "http_code": 400,
    "message": "JSON parse error: Cannot deserialize value of type `ImageStorage` from String \\"xxx\\"
}

状态码说明

HTTP 状态码	错误码	描述
200	-	请求成功，包括任务失败场景，实际任务状态需从result.status中判断
404	BadRequest.TaskNotExist	任务不存在
400	InvalidParameter	不合法请求
500	InternalServerError	内部错误

更多状态码说明，请参见状态码说明。