使用文檔內容解析API將非結構化資料結構化-智能OpenSearch OpenSearch-阿里雲 - OpenSearch

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	內部錯誤

更多狀態代碼說明，請參見狀態代碼說明。