ドキュメントコンテンツの解析 - OpenSearch - Alibaba Cloud ドキュメントセンター

AI Search Open Platform は、API を介してドキュメントをパースするサービスを提供します。このサービスをビジネスワークフローに統合することで、非構造化データを構造化データにパースし、ビジネスアプリケーションで利用できます。

サービス名

サービス ID

説明

API QPS 制限

ドキュメント分析サービス

ops-document-analyze-001

非構造化ドキュメントから、論理的な階層構造 (タイトルや段落など)、テキスト、表、画像を抽出し、構造化フォーマットで出力を返します。

対応ドキュメント形式：TXT、PDF、HTML、DOC、DOCX、PPT、PPTX。

説明

より高い API QPS 制限をリクエストするには、テクニカルサポートにチケットを送信してください。

ops-document-analyze-002

PDF や画像など、複数の非構造化ドキュメント形式を分析します。表、数式、グラフなどの複雑な要素の識別に優れており、推論速度が高速です。

使用制限：PDF ファイルは 400 ページまでです。リクエストボディは 8 MB を超えることはできません。

前提条件

認証情報の取得

AI Search オープンプラットフォームでは、認証に API キーが必要です。手順については、「API キーの取得」をご参照ください。
サービスエンドポイントの取得

パブリックネットワークまたは VPC 経由でサービスを呼び出せます。詳細については、「サービスエンドポイントの取得」をご参照ください。

概要

リクエストボディは 8 MB を超えることはできません。

概要

ドキュメントコンテンツの解析では、同期インターフェイスと非同期インターフェイスの両方を使用できます。同期インターフェイスは HTTP タイムアウトのリスクがあるため、本番環境での使用は推奨しませんが、デバッグには使用できます。本番環境では、非同期インターフェイスの使用を推奨します。これは 2 段階のプロセスです。まず、非同期抽出タスクを作成して 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。

リクエストパラメータ

ヘッダーパラメーター

API キー認証

パラメータ	タイプ	必須	説明	サンプル値
Content-Type	文字列	はい	リクエストボディのメディアタイプ。	application/json
Authorization	文字列	はい	認証用の API キー。	Bearer OS-d1**2a

ボディパラメーター

パラメーター	タイプ	必須	説明	例
service_id	String	はい	組み込みサービスの ID です。	ops-document-analyze-001
document.url	String	いいえ	ドキュメントの URL です。ファイルは、認証なしで HTTP または HTTPS 経由でパブリックにダウンロード可能である必要があります。 `document.url` または `document.content` のいずれかを指定する必要があります。	http://opensearch-shanghai.oss-cn-shanghai.aliyuncs.com/chatos/***/file-parser/samples/GB10767.pdf
document.content	String	いいえ	Base64 エンコードされたドキュメントのコンテンツです。 `document.url` または `document.content` のいずれかを指定する必要があります。	"aGVsbG8gd29ybGQ="
document.file_name	String	いいえ	ファイル名です。このパラメーターが指定されていない場合、システムは URL からファイル名を推測します。`document.content` を使用してドキュメントのコンテンツを直接指定する場合、このパラメーターは必須です。	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` パラメーターが追加され、モデルで使用されたトークン数が表示されます。このトークン数が課金に使用されます。 `false` ：デフォルト値です。セマンティックな階層構造の抽出は無効になります。	false

下の図のように目次と本文が明確に区別されていないドキュメントでは、この機能によって、より正確な階層構造が生成されます。

语义结构.jpg

意味構造抽出が無効の場合：
意味構造抽出を有効にすると、結果の階層構造がより正確になります (スクリーンショット内の「##」はレベル 2 の見出しを示します)。

説明
usage.semantic_token_count が値を返す場合、意味構造抽出が成功し、この課金項目のトークン料金が課金されます。値が返されない場合、抽出は失敗し、料金は発生しません。

以下の表に、セマンティック結果抽出を有効にした後の推定所要時間とセマンティックトークン数を示します。

PDF ページ	トークン	セマンティック階層なし	セマンティック階層あり
PDF ページ	トークン	時間 (秒)	時間 (秒)	セマンティックトークン
7	11504	2	49	36243
25	10375	1	33	59332
42	41435	5	68	130717

応答パラメーター

パラメーター	タイプ	説明	例
result.task_id	文字列	ドキュメント解析用の非同期タスクの 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 ' \
--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。

リクエストパラメーター

ヘッダーパラメーター

API キー認証

パラメーター	タイプ	必須	説明	例
Content-Type	文字列	はい	リクエストのメディアタイプ。値は application/json である必要があります。	application/json
Authorization	文字列	はい	認可用の API キー。先頭に「Bearer 」を付けます。	Bearer OS-d1**2a

レスポンスパラメーター

パラメーター	タイプ	説明	値
result.task_id	文字列	非同期ドキュメント解析タスクの ID。	24c3ad59-****-40cf-974b-b63d63e0571
result.status	文字列	タスクステータス。指定可能な値は次のとおりです： PENDING ：タスクは処理キューに入っています。 SUCCESS ：タスクは正常に完了しました。 FAIL ：タスクは失敗しました。	PENDING
result.error	文字列	失敗したタスクのエラーメッセージ。それ以外の場合、このパラメーターは空です。	Failed to decrypt the document.
result.data	Object	ドキュメント解析の結果。	markdown
result.data.content	文字列	解析されたドキュメントのコンテンツ。 PDF ファイルの場合、コンテンツは Markdown 形式です。その他のファイルタイプの場合、コンテンツは HTML 形式です。	"XXX"
result.data.content_type	文字列	解析後のコンテンツの形式。 markdown html	markdown
result.data.page_num	整数	ドキュメントのページ数。	15
request_id	文字列	この API 呼び出しの一意の識別子。	B4AB89C8-B135-****-A6F8-2BAB8018688
latency	浮動小数点数 / 整数	リクエストレイテンシー (ミリ秒)。	10
usage	Object	この API 呼び出しのメータリング情報。	"usage": { "token_count": 123, "table_count": 5, "image_count": 6, "semantic_token_count": 3068 }
usage.token_count	整数	ドキュメント内のトークン数。	1234
usage.table_count	整数	ドキュメント内のテーブル数。	5
usage.image_count	整数	ドキュメント内の画像数。	6
usage.semantic_token_count	整数	セマンティック抽出モデルへの入力のトークン数。	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 キー>"

レスポンスの例

成功レスポンス

{
    "request_id": "27F9CEC3-9052-****-83FF-E7957B680492",
    "latency": 13.0,
    "http_code": 200,
    "result": {
        "status": "SUCCESS",
        "data": {
            "content": "適切な出典が明記されることを条件に、アリババは、本論文中の表および図を、ジャーナリズムまたは学術的な著作物においてのみ使用するために複製することを許可します...",
            "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 フィールドにはエラー情報が含まれます。

同期解析タスクの作成

重要

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。

リクエストパラメーター

ヘッダーパラメーター

API キー認証

パラメータ	タイプ	必須	説明	値
Content-Type	文字列	はい	リクエストタイプ。	application/json
Authorization	文字列	はい	API キー。	Bearer OS-d1**2a

ボディパラメーター

パラメーター	タイプ	必須	説明	値の例
document.url	文字列	いいえ	ドキュメントのパブリック URL です。認証なしで HTTP または HTTPS 経由でアクセスできる必要があります。 `document.url` または `document.content` のいずれかを指定する必要があります。	http://opensearch-shanghai.oss-cn-shanghai.aliyuncs.com/chatos/***/file-parser/samples/GB10767.pdf
document.content	文字列	いいえ	Base64 エンコードされたドキュメントのコンテンツです。 `document.url` または `document.content` のいずれかを指定する必要があります。	"aGVsbG8gd29ybGQ="
document.file_name	文字列	条件付き	ファイル名です。このパラメーターを省略すると、システムは `document.url` から名前を推測します。`document.content` を指定する場合、このパラメーターは必須です。	test.pdf
document.file_type	文字列	条件付き	ファイルタイプです。このパラメーターを省略すると、システムは `file_name` の拡張子からファイルタイプを推測します。タイプを自動的に推測できない場合、このパラメーターは必須です。サポートされているファイルタイプ：TXT、PDF、HTML、DOC、DOCX、PPT、PPTX。	pdf
output.image_storage	文字列	いいえ	画像の保存方法です。 `base64`：デフォルトの方法です。 `url`：URL は 3 日間有効です。	url
strategy.enable_semantic	ブール値	いいえ	セマンティック構造抽出を有効にするかどうかを指定します。デフォルトは `false` です。有効にすると、この機能は返される `Markdown` でより正確な階層構造を提供しますが、処理時間が大幅に増加し、使用量の詳細に `semantic_token_count` 課金項目が追加されます。デフォルトのタイムアウトは 400 秒です。大きすぎるドキュメント (100 ページ超) のリクエストがタイムアウトした場合、サービスは構造抽出を無効にしてデグレードします。この機能は HTML、PPT、PPTX ドキュメントには対応していません。	false

レスポンスパラメータ

パラメーター	タイプ	説明	例
result.status	文字列	タスクステータス。有効な値は次のとおりです： `PENDING`：タスクは処理待ちです。 `SUCCESS`：タスクは正常に完了しました。 `FAIL`：タスクは失敗しました。	PENDING
result.error	文字列	ステータスが `FAIL` の場合に返されるエラーメッセージ。タスクが成功した場合、このフィールドは存在しません。	Document decryption failed
result.data	Object	ドキュメント解析の結果。	{
result.data.content	文字列	解析されたドキュメントのコンテンツ。 PDF ファイルの場合、コンテンツは Markdown フォーマットです。その他のファイルタイプの場合、コンテンツは HTML フォーマットです。	"XXX"
result.data.content_type	文字列	解析されたドキュメントのコンテンツタイプ。有効な値は次のとおりです： `markdown` `html`	markdown
result.data.page_num	整数	ドキュメントのページ数。	15
request_id	文字列	リクエストの一意の識別子。	B4AB89C8-B135-****-A6F8-2BAB801A2CE4
latency	浮動小数点数/整数	リクエストレイテンシー (ミリ秒)。	10
usage	Object	リクエストの使用量の詳細。	"usage": { "token_count": 123, "table_count": 5, "image_count": 6, "semantic_token_count": 3068 }
usage.token_count	整数	ドキュメント内の合計トークン数。	123
usage.table_count	整数	ドキュメント内の合計テーブル数。	5
usage.image_count	整数	ドキュメント内の合計画像数。	6
usage.semantic_token_count	整数	セマンティック抽出モデルへの入力として使用される、セマンティックトークンの合計数。	3068

cURL

curl --location 'http://****shanghai.opensearch.aliyuncs.com/v3/openapi/workspaces/default/document-analyze/ops-document-analyze-001/sync/' \
--header 'Authorization: Bearer お使いの API キー' \
--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": "適切な帰属表示がなされることを条件に、Alibaba は、報道または学術研究での利用に限り、本書の表および図を複製することを許可します....",
            "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 解析エラー：String \\"xxx\\" から `ImageStorage` 型の値をデシリアライズできません。"
}

ステータスコード

HTTP ステータスコード	エラーコード	説明
200	-	リクエストは成功しました。このステータスは、タスクが失敗した場合でも返されます。タスクのステータスを確認するには、`result.status` フィールドを確認してください。
400	BadRequest.TaskNotExist	タスクは存在しません。
400	InvalidParameter	リクエストが無効です。
500	InternalServerError	内部エラーが発生しました。

詳細については、「ステータスコード」をご参照ください。

前提条件

概要

概要

非同期抽出タスク

リクエストメソッド

URL

リクエストパラメータ

ヘッダーパラメーター

ボディパラメーター

応答パラメーター

cURL の例

レスポンスの例

成功レスポンス

エラーレスポンス

非同期タスクの取得

リクエストメソッド

URL

リクエストパラメーター

ヘッダー パラメーター

レスポンスパラメーター

cURL リクエスト

レスポンスの例

成功レスポンス

エラー応答

同期解析タスクの作成

リクエストメソッド

URL

パラメーター

リクエストパラメーター

ヘッダーパラメーター

ボディパラメーター

レスポンスパラメータ

cURL

レスポンスの例

成功応答の例

エラーレスポンスの例

ステータスコード

ヘッダーパラメーター