Penguraian konten dokumen - OpenSearch - Alibaba Cloud Documentation Center

AI Search Open Platform menyediakan layanan penguraian dokumen melalui API. Anda dapat mengintegrasikan layanan ini ke dalam alur kerja pemrosesan bisnis untuk mengurai data tidak terstruktur menjadi data terstruktur yang dapat digunakan dalam aplikasi bisnis Anda.

Service name

Service ID

Description

API QPS limit

Document Analysis Service

ops-document-analyze-001

Menyaring struktur hierarkis logis (seperti judul dan paragraf), teks, tabel, serta gambar dari dokumen tidak terstruktur dan mengembalikan output dalam format terstruktur.

Jenis dokumen yang didukung: TXT, PDF, HTML, DOC, DOCX, PPT, dan PPTX.

Catatan

Untuk meminta batas API QPS yang lebih tinggi, kirimkan tiket ke dukungan teknis.

ops-document-analyze-002

Menganalisis berbagai format dokumen tidak terstruktur, seperti PDF dan gambar. Layanan ini unggul dalam mengidentifikasi elemen kompleks, seperti tabel, rumus, dan grafik, serta menawarkan kecepatan inferensi tinggi.

Batas penggunaan: File PDF dibatasi hingga 400 halaman. Badan permintaan tidak boleh melebihi 8 MB.

Prasyarat

Dapatkan kredensial otentikasi

Platform Terbuka AI Search memerlukan Kunci API untuk otentikasi. Untuk petunjuknya, lihat Dapatkan Kunci API.
Dapatkan titik akhir layanan

Anda dapat memanggil layanan melalui jaringan publik atau VPC. Untuk detailnya, lihat Dapatkan titik akhir layanan.

Ikhtisar

Ukuran badan permintaan tidak boleh melebihi 8 MB.

Ikhtisar

Penguraian konten dokumen menyediakan antarmuka sinkron dan asinkron. Antarmuka sinkron tidak disarankan untuk lingkungan produksi karena risiko timeout HTTP, tetapi dapat digunakan untuk debugging. Untuk lingkungan produksi, kami merekomendasikan antarmuka asinkron, yang merupakan proses dua langkah: pertama, buat tugas ekstraksi asinkron untuk mendapatkan task_id, lalu lakukan polling status tugas melalui antarmuka asinkron hingga tugas selesai.

Tugas ekstraksi asinkron

Metode permintaan

POST

URL

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

host: Titik akhir layanan. Anda dapat memanggil layanan API melalui jaringan publik atau melalui VPC. Untuk informasi selengkapnya, lihat Dapatkan titik akhir layanan.

Di panel navigasi sisi kiri Konsol, klik API Keys, pilih ruang kerja target (misalnya, default), lalu lihat Public API Endpoint dan Private API Endpoint di bagian Access Endpoints.
workspace_name: Nama ruang kerja. Contohnya, default.
service_id: ID layanan bawaan. Contohnya, ops-document-analyze-001.

Parameter permintaan

Parameter Header

Otentikasi kunci API

Parameter	Type	Required	Description	Example value
Content-Type	String	Yes	Jenis media dari badan permintaan.	application/json
Authorization	String	Yes	Kunci API untuk otentikasi.	Bearer OS-d1**2a

Parameter Body

Parameter	Type	Required	Description	Example
service_id	String	Yes	ID layanan bawaan.	ops-document-analyze-001
document.url	String	No	URL dokumen. File harus dapat diunduh secara publik melalui HTTP atau HTTPS tanpa otentikasi. Anda harus menentukan salah satu dari `document.url` atau `document.content`.	http://opensearch-shanghai.oss-cn-shanghai.aliyuncs.com/chatos/***/file-parser/samples/GB10767.pdf
document.content	String	No	Konten dokumen yang dikodekan Base64. Anda harus menentukan salah satu dari `document.url` atau `document.content`.	"aGVsbG8gd29ybGQ="
document.file_name	String	No	Nama file. Jika parameter ini tidak ditentukan, sistem akan menyimpulkannya dari URL. Parameter ini wajib jika Anda memberikan konten dokumen langsung menggunakan `document.content`.	test.pdf
document.file_type	String	No	Jenis file. Jika parameter ini tidak ditentukan, sistem akan menyimpulkannya dari ekstensi `file_name`. Parameter ini wajib jika jenis file tidak dapat disimpulkan. Jenis file yang didukung: TXT, PDF, HTML, DOC, DOCX, PPT, dan PPTX. Saat menggunakan layanan `ops-document-analyze-002` untuk memproses file PDF, jumlah halaman tidak boleh melebihi 400.	pdf
output.image_storage	String	No	Menentukan cara menyimpan gambar yang diekstraksi dari dokumen. `base64`: Nilai default. `url`: URL berlaku selama tiga hari.	url
strategy.enable_semantic	Boolean	No	Mengaktifkan ekstraksi struktur hierarkis berbasis semantik dari dokumen TXT dan dokumen tidak terstruktur lainnya. `true`: Layanan model mengembalikan struktur hierarkis dokumen dalam format Markdown bersama hasil penguraian dokumen, yang meningkatkan akurasi pemotongan dokumen berikutnya. Fitur ini tidak didukung untuk dokumen HTML, PPT, dan PPTX. Mengaktifkan fitur ini meningkatkan waktu penguraian dokumen. Sistem mungkin secara otomatis menonaktifkannya jika penguraian melebihi 400 detik atau dokumen melebihi 100 halaman. Pada item yang dapat ditagih `usage`, parameter `semantic_token_count` ditambahkan untuk menunjukkan jumlah token yang digunakan oleh model, yang digunakan untuk penagihan. `false`: Nilai default. Ekstraksi struktur hierarkis semantik dinonaktifkan.	false

Untuk dokumen yang daftar isi dan isi utamanya tidak dibedakan secara jelas, seperti pada gambar di bawah, fitur ini menghasilkan struktur hierarkis yang lebih akurat.

语义结构.jpg

Dengan ekstraksi struktur semantik dinonaktifkan:

curl -XGET -H"Content-Type: application/json" "http://xxx.opensearch.aliyuncs.com/v3/openapi/workspaces/default/document-analyze/ops-document-analyze-001/async/task-status?task_id=f6122788-30e2-4/t8-8d18-33217f6a5e7c" -H "Authorization: Bearer OS xxx"
{"request_id":"63877CEA-BB65-43E3-806B-DE4710DEDA98","latency":"3.0","http_code":200,"result":{"status":"SUCCESS","data":"{xxx","事项前置\n10024910010024251717233000000\n\n购买自住住房提取住房公积金 事项前置\n\n购买自住住房提取住房公积金\n金 基金 指南\n\n一、适用范围\n\n及的内容。购买自住住房提取住房公积金\n\n服务对象：\n个人\n二、事项前置类型\n\n即配即办\n\n三、国家/省/市依据\n\n住房公积金相关条例\n\n1999-04-03\n\n第十一条 \n\n住房公积金管理中心履行下列职责：\n\n...（后续为住房公积金管理条例详细内容）\n\n购买1 购买自住住房提取住房公积金流程福利\n\n[IMO]:data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAYABeAAD..."}}

Saat ekstraksi struktur semantik diaktifkan, contoh respons adalah sebagai berikut. Penanda Markdown ## dan ### pada bidang content menunjukkan struktur direktori hierarkis yang dikenali, dan \n merepresentasikan jeda baris.

{"request_id":"9F7B4F1A-4EE0-4430-A537-2C21B01E3676","latency":3.0,"http_code":200,"result":{"status":"SUCCESS","data":{"content":"... 事项编码:1\n## 适用范围\n及的内容：购买自住住房提取住房公积金\n(含购买自住住房提取住房公积金和购服务指南)的制定和发布 事项名称：购买自住住房提取住房公积金 适用范围\n及的内容：购买自住住房提取住房公积金\n\n### 二 事项审查类型\n即时即办\n### 三 国家法律依据\n住房公积金管理条例(国务院 1999-04-03...\n(二)购买自住住房的提取...住房公积金的保值和归集...\n使用等情况...在住房公积金的核算...使用...住房公积金的保值和归集...\n...管理中心应当...提取住房公积金...自3日内作出准予提取或者不准提取的决定,并通知申请人;准予提取的,由受委托银行办理支付手续...\n...建设住房公积金...储存余额的存储方式...建设住房公积金...\n...住房公积金流程...相关申请材料文件\n...\n附录3 帮助购趣群答..."}}}

Catatan

Jika usage.semantic_token_count mengembalikan nilai, ekstraksi struktur semantik berhasil, dan biaya token untuk item penagihan ini dikenakan. Jika tidak ada nilai yang dikembalikan, ekstraksi gagal, dan tidak ada biaya yang dikenakan.

Tabel berikut menunjukkan perkiraan durasi dan jumlah token semantik setelah mengaktifkan ekstraksi hasil semantik.

PDF pages	Tokens	Without semantic hierarchy	With semantic hierarchy
PDF pages	Tokens	Time (s)	Time (s)	Semantic tokens
7	11504	2	49	36243
25	10375	1	33	59332
42	41435	5	68	130717

Parameter respons

Parameter	Type	Description	Example
result.task_id	String	ID tugas asinkron untuk penguraian dokumen.	d5a4019e-853a-****-b5b6-8053d9f5a9fc

Contoh cURL

curl --location 'http://****shanghai.opensearch.aliyuncs.com/v3/openapi/workspaces/default/document-analyze/ops-document-analyze-001/async/' \
--header 'Authorization: Bearer your 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
    }
}'

Contoh respons

Respons sukses

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

Respons error

Jika permintaan gagal, respons menjelaskan error pada bidang code dan message.

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

Pengambilan tugas asinkron

Metode permintaan

GET

URL

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

host: Titik akhir layanan. Anda dapat memanggil layanan API melalui jaringan publik atau melalui VPC. Untuk informasi selengkapnya, lihat Dapatkan titik akhir layanan.
workspace_name: Nama ruang kerja. Contohnya, default.
service_id: ID layanan bawaan. Contohnya, ops-document-analyze-001.
task_id: ID tugas asinkron yang dikembalikan oleh permintaan pembuatan tugas. Contohnya, d5a4019e-853a-****-b5b6-8053d9f5a9fc.

Parameter permintaan

Parameter Header

Otentikasi kunci API

Parameter	Type	Required	Description	Example
Content-Type	String	Yes	Jenis media permintaan. Nilainya harus application/json.	application/json
Authorization	String	Yes	Kunci API untuk otentikasi, diawali dengan Bearer .	Bearer OS-d1**2a

Parameter respons

Parameter	Type	Description	Value
result.task_id	String	ID tugas penguraian dokumen asinkron.	24c3ad59-****-40cf-974b-b63d63e0571
result.status	String	Status tugas. Nilai yang mungkin adalah: PENDING: Tugas sedang dalam antrian untuk diproses. SUCCESS: Tugas berhasil diselesaikan. FAIL: Tugas gagal.	PENDING
result.error	String	Pesan error untuk tugas yang gagal. Parameter ini kosong jika tidak ada error.	Failed to decrypt the document.
result.data	Object	Hasil penguraian dokumen.	markdown
result.data.content	String	Konten dokumen yang telah diurai. Untuk file PDF, konten dalam format Markdown. Untuk jenis file lain, konten dalam format HTML.	"XXX"
result.data.content_type	String	Format konten yang telah diurai. markdown html	markdown
result.data.page_num	Int	Jumlah halaman dalam dokumen.	15
request_id	String	Pengidentifikasi unik untuk pemanggilan API ini.	B4AB89C8-B135-****-A6F8-2BAB8018688
latency	Float/Int	Latensi permintaan dalam milidetik (ms).	10
usage	Object	Informasi metering untuk pemanggilan API ini.	"usage": { "token_count": 123, "table_count": 5, "image_count": 6, "semantic_token_count":3068 }
usage.token_count	Int	Jumlah karakter dalam dokumen.	1234
usage.table_count	Int	Jumlah tabel dalam dokumen.	5
usage.image_count	Int	Jumlah gambar dalam dokumen.	6
usage.semantic_token_count	Int	Jumlah karakter dalam input ke model ekstraksi semantik.	3068

Permintaan 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 Your API key"

Contoh respons

Respons sukses

{
    "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
    }
}

Respons error

Jika permintaan akses gagal, bidang code dan message dalam respons menjelaskan error tersebut.

Buat tugas penguraian sinkron

Penting

Hindari menggunakan antarmuka sinkron di lingkungan produksi karena risiko timeout HTTP. Anda dapat menggunakannya hanya untuk debugging.

Metode permintaan

POST

URL

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

Parameter

host: Titik akhir layanan. Anda dapat memanggil layanan API melalui jaringan publik atau VPC. Untuk informasi selengkapnya, lihat Dapatkan titik akhir layanan.
workspace_name: Nama ruang kerja. Contohnya, default.
service_id: ID layanan bawaan. Contohnya, ops-document-analyze-001.

Parameter permintaan

Parameter header

Otentikasi kunci API

Parameter	Type	Required	Description	Value
Content-Type	String	Yes	Jenis permintaan.	application/json
Authorization	String	Yes	Kunci API Anda.	Bearer OS-d1**2a

Parameter body

Parameter	Type	Required	Description	Example value
document.url	String	No	URL publik dokumen. Dokumen harus dapat diakses melalui HTTP atau HTTPS tanpa otentikasi. Anda harus menentukan salah satu dari `document.url` atau `document.content`.	http://opensearch-shanghai.oss-cn-shanghai.aliyuncs.com/chatos/***/file-parser/samples/GB10767.pdf
document.content	String	No	Konten dokumen, dikodekan Base64. Anda harus menentukan salah satu dari `document.url` atau `document.content`.	"aGVsbG8gd29ybGQ="
document.file_name	String	No	Nama file. Jika parameter ini dihilangkan, sistem akan menyimpulkan nama dari document.url. Parameter ini wajib saat document.content ditentukan.	test.pdf
document.file_type	String	No	Jenis file. Jika parameter ini dihilangkan, sistem akan menyimpulkan jenis file dari ekstensi `file_name`. Parameter ini wajib jika jenis file tidak dapat disimpulkan secara otomatis. Jenis file yang didukung: TXT, PDF, HTML, DOC, DOCX, PPT, dan PPTX.	pdf
output.image_storage	String	No	Metode penyimpanan gambar. `base64`: Metode default. `url`: URL berlaku selama tiga hari.	url
strategy.enable_semantic	Boolean	No	Menentukan apakah akan mengaktifkan ekstraksi struktur semantik. Nilai default adalah `false`. Saat diaktifkan, fitur ini memberikan struktur hierarkis yang lebih akurat dalam Markdown yang dikembalikan, tetapi secara signifikan meningkatkan waktu pemrosesan dan menambahkan item penagihan `semantic_token_count` ke detail penggunaan. Timeout default adalah 400 detik. Jika permintaan untuk dokumen berukuran besar (lebih dari 100 halaman) mengalami timeout, layanan akan menurunkan kualitas dengan menonaktifkan ekstraksi struktur. Fitur ini tidak mendukung dokumen HTML, PPT, atau PPTX.	false

Parameter respons

Parameter	Type	Description	Example
result.status	String	Status tugas. Nilai yang valid meliputi: `PENDING`: Tugas sedang menunggu pemrosesan. `SUCCESS`: Tugas berhasil diselesaikan. `FAIL`: Tugas gagal.	PENDING
result.error	String	Pesan error yang dikembalikan saat status `FAIL`. Bidang ini tidak ada untuk tugas yang berhasil.	Document decryption failed
result.data	Object	Hasil penguraian dokumen.	markdown
result.data.content	String	Konten dokumen yang telah diurai. Untuk file PDF, konten dalam format Markdown. Untuk jenis file lain, konten dalam format HTML.	"XXX"
result.data.content_type	String	Jenis konten dokumen yang telah diurai. Nilai yang valid meliputi: `markdown` `html`	markdown
result.data.page_num	Int	Jumlah halaman dokumen.	15
request_id	String	Pengidentifikasi unik untuk permintaan.	B4AB89C8-B135-****-A6F8-2BAB801A2CE4
latency	Float/Int	Latensi permintaan dalam milidetik (ms).	10
usage	Object	Detail penggunaan untuk permintaan.	"usage": { "token_count": 123, "table_count": 5, "image_count": 6, "semantic_token_count":3068 }
usage.token_count	Int	Jumlah total token dalam dokumen.	1234
usage.table_count	Int	Jumlah total tabel dalam dokumen.	5
usage.image_count	Int	Jumlah total gambar dalam dokumen.	6
usage.semantic_token_count	Int	Jumlah total token semantik yang digunakan sebagai input untuk model ekstraksi semantik.	3068

cURL

curl --location 'http://****shanghai.opensearch.aliyuncs.com/v3/openapi/workspaces/default/document-analyze/ops-document-analyze-001/sync/' \
--header 'Authorization: Bearer your 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
    }
}'

Contoh respons

Contoh respons sukses

{
    "request_id": "27F9CEC3-9052-****-83FF-E7957B689D04",
    "latency": 13.0,
    "http_code": 200,
    "result": {
        "status": "SUCCESS",
        "data": {
            "content": "Provided proper attribution is given, 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
    }
}

Contoh respons error

Jika permintaan akses gagal, respons menunjukkan error pada bidang code dan 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\\""
}

Kode status

Http status code	Error code	Description
200	-	Permintaan berhasil. Status ini dikembalikan bahkan jika tugas gagal. Periksa bidang `result.status` untuk menentukan status tugas.
404	BadRequest.TaskNotExist	Tugas tidak ada.
400	InvalidParameter	Permintaan tidak valid.
500	InternalServerError	Terjadi error internal.

Untuk informasi selengkapnya tentang kode status, lihat kode status.