AI 助理
备案控制台
文档
输入文档关键字查找
首页 智能开放搜索 OpenSearch AI搜索开放平台 开发参考 API参考 文档内容解析

文档内容解析

更新时间：
产品详情
相关技术圈
我的收藏

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

服务名称

服务ID

服务描述

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

文档解析服务-001

ops-document-analyze-001

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

1

说明

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

前提条件

  • 获取身份鉴权信息

    通过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服务，可参见获取服务接入地址。

    AI apikey截图.png

  • 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的后缀推断，如果无法推断需要显式指定，如：pdf、doc、docx。

pdf

output.image_storage

String

否

图片存储方式

  • base64：默认方式

  • url：url有效期为3天

url

strategy.enable_semantic

Boolean

否

是否开启语义层级结构提取：

  • true：针对TXT、层级结构不明显的文档，开启后返回文档的Markdown层级结构，有助于提升后续文档切片的准确性。

    • 不支持HTML、PPT及PPTX格式的文档。

    • 开启该功能后，整体文档解析耗时有所提升。解析时长超过400秒或者超长文档（大于100页）均可能导致系统自动关闭层级结构提取功能。

    • usage计费项参数中增加semantic_token_count展示模型使用的Token数，系统根据该Token数计费。

  • 默认为false，不开启语义层级结构提取功能。

false

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

语义结构.jpg

  • 未开启语义结果提取功能：

    未开启语义.jpg

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

    开启层级结构1.jpg

    说明

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

您可参照以下表格预估开启语义结果提取后的用时及产生的语义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"
}

创建同步提取任务

请求方式

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的后缀推断，如果无法推断需要显式指定，如：pdf、doc、docx。

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

内部错误

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

上一篇：API参考下一篇：图片内容提取
文档推荐