Penguraian konten dokumen - OpenSearch

AI Search Open Platform memungkinkan Anda memanggil layanan penguraian konten dokumen menggunakan API. Anda dapat mengintegrasikan layanan ini ke dalam rantai pemrosesan bisnis untuk mengurai data tidak terstruktur menjadi data terstruktur dan menerapkannya dalam bisnis Anda.

Nama Layanan

ID Layanan

Deskripsi Layanan

Batas QPS untuk panggilan API (Untuk Akun Alibaba Cloud dan Pengguna RAM)

Document Parsing Service

ops-document-analyze-001

Mendukung ekstraksi struktur hierarki logis seperti judul dan segmen dari dokumen tidak terstruktur, serta teks, tabel, gambar, dan informasi lainnya, dan menampilkannya dalam format terstruktur.

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

Catatan

Untuk mengajukan QPS lebih tinggi, kirim tiket.

ops-document-analyze-002

Mengurai berbagai format dokumen tidak terstruktur, seperti PDF dan gambar, unggul dalam mendeteksi elemen kompleks termasuk tabel, rumus, dan grafik, serta memberikan kecepatan inferensi yang cepat.

Prasyarat

Informasi otentikasi telah diperoleh.
Saat memanggil layanan AI Search Open Platform menggunakan API, Anda perlu mengotentikasi identitas pemanggil.
Alamat akses layanan telah diperoleh.
Anda dapat memanggil layanan melalui Internet atau virtual private cloud (VPC). Untuk informasi lebih lanjut, lihat Dapatkan Alamat Pendaftaran Layanan.

Informasi umum

Ukuran maksimum badan permintaan tidak boleh melebihi 8 MB.

Ikhtisar

Penguraian konten dokumen menyediakan antarmuka sinkron dan asinkron. Karena risiko timeout HTTP, antarmuka sinkron tidak disarankan untuk lingkungan produksi dan hanya digunakan untuk debugging. Antarmuka asinkron direkomendasikan untuk lingkungan produksi dan melibatkan dua langkah: pertama, buat tugas ekstraksi asinkron untuk mendapatkan task_id, lalu panggil antarmuka pengambilan tugas asinkron untuk memeriksa status hingga tugas selesai.

Buat tugas ekstraksi asinkron

Metode permintaan

POST

URL

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

host: alamat untuk memanggil layanan. Anda dapat memanggil layanan API melalui Internet atau VPC. Untuk informasi lebih lanjut, lihat Dapatkan Alamat Pendaftaran Layanan.
workspace_name: nama ruang kerja, seperti default.
service_id: ID layanan bawaan, seperti ops-document-analyze-001.

Parameter permintaan

Parameter header

Otentikasi Kunci API

Parameter	Tipe	Diperlukan	Deskripsi	Contoh
Content-Type	String	Ya	Tipe permintaan. Nilai valid: application dan json.	application/json
Authorization	String	Ya	Kunci API.	Bearer OS-d1**2a

Parameter Badan

Parameter	Tipe	Diperlukan	Deskripsi	Contoh
service_id	String	Ya	ID layanan bawaan.	ops-document-analyze-001
document.url	String	Tidak	URL dokumen. Nilai valid: protokol HTTP dan HTTPS. Pastikan URL dapat diunduh secara tanpa status dari jaringan publik. Salah satu document.content atau document.url diperlukan.	http://opensearch-shanghai.oss-cn-shanghai.aliyuncs.com/chatos/***/file-parser/samples/GB10767.pdf
document.content	String	Tidak	Konten dokumen yang dikodekan dalam Base64. Salah satu document.content atau document.url diperlukan.	"aGVsbG8gd29ybGQ="
document.file_name	String	Tidak	Nama dokumen. Jika Anda meninggalkan parameter ini kosong, nama dapat disimpulkan dari URL. Jika Anda meninggalkan parameter ini dan parameter document.url kosong, nama dokumen perlu ditentukan secara eksplisit.	test.pdf
document.file_type	String	Tidak	Tipe dokumen. Jika Anda meninggalkan parameter ini kosong, tipe dokumen dapat disimpulkan dari akhiran nama dokumen. Jika tidak dapat disimpulkan, tipe dokumen perlu ditentukan secara eksplisit. Jenis dokumen yang didukung meliputi TXT, PDF, HTML, DOC, DOCX, PPT, dan PPTX.	pdf
output.image_storage	String	Tidak	Metode penyimpanan gambar. base64: metode default. url: URL berlaku selama 3 hari.	url
strategy.enable_semantic	Boolean	Tidak	Menentukan apakah akan mengaktifkan ekstraksi hierarki semantik saat penguraian dokumen TXT atau dokumen dengan struktur hierarki yang tidak jelas. Nilai valid: true: Setelah Anda mengaktifkan fitur ini, layanan model akan mengembalikan dokumen dalam format hierarki Markdown, yang membantu meningkatkan akurasi pemotongan dokumen selanjutnya. Fitur ini tidak mendukung dokumen tipe HTML, PPT, dan PPTX. Setelah Anda mengaktifkan fitur ini, waktu penguraian dokumen keseluruhan akan meningkat. Waktu penguraian lebih dari 400 detik atau dokumen super panjang (lebih dari 100 halaman) dapat menyebabkan sistem secara otomatis menonaktifkan fitur ini. Parameter `penggunaan` billing akan mencakup `semantic_token_count` untuk menampilkan jumlah token yang digunakan oleh model, dengan biaya berdasarkan jumlah token ini. false: nilai default.	false

Untuk dokumen tanpa pembedaan yang jelas antara daftar isi dan teks utama, ekstraksi hierarki semantik membuat struktur hierarki dalam hasil lebih akurat.

Catatan

Jika parameter usage.semantic_token_count mengembalikan nilai, ekstraksi hierarki semantik diaktifkan dan Anda akan ditagih berdasarkan konsumsi token semantik. Tidak adanya nilai yang dikembalikan menunjukkan bahwa fitur tersebut gagal, sehingga Anda tidak akan ditagih.

Anda dapat memperkirakan waktu dan konsumsi token setelah mengaktifkan ekstraksi hierarki semantik berdasarkan tabel berikut.

Halaman PDF	Jumlah Token	Tanpa ekstraksi hierarki semantik	Dengan ekstraksi hierarki semantik
Halaman PDF	Jumlah Token	Waktu (detik)	Waktu (s)	Token semantik
7	11.504	2	49	36.243
25	10.375	1	33	59.332
42	41.435	5	68	130.717

Parameter respons

Parameter	Tipe	Deskripsi	Contoh
result.task_id	String	ID tugas penguraian dokumen asinkron.	d5a4019e-853a-****-b5b6-8053d9f5a9fc

Contoh permintaan 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

Contoh respons normal

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

Contoh respons abnormal

Dalam kasus kesalahan permintaan akses, hasil keluaran akan menunjukkan alasan kesalahan melalui kode dan pesan.

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

Dapatkan tugas ekstraksi asinkron

Metode permintaan

GET

URL

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

host: alamat untuk memanggil layanan. Anda dapat memanggil layanan API melalui Internet atau VPC. Untuk informasi lebih lanjut, lihat Dapatkan Alamat Pendaftaran Layanan.
workspace_name: nama ruang kerja, seperti default.
service_id: ID layanan bawaan, seperti ops-document-analyze-001.
task_id: ID tugas asinkron yang dikembalikan dalam respons penguraian dokumen, seperti d5a4019e-853a-****-b5b6-8053d9f5a9fc.

Parameter permintaan

Parameter Header

Otentikasi Kunci API

Parameter	Tipe	Diperlukan	Deskripsi	Contoh
Content-Type	String	Ya	Tipe permintaan. Nilai valid: application dan json.	application/json
Authorization	String	Ya	Kunci API.	Bearer OS-d1**2a

Parameter respons

Parameter	Tipe	Deskripsi	Contoh
result.task_id	String	ID tugas penguraian dokumen asinkron.	24c3ad59-****-40cf-974b-b63d63e0571
result.status	String	Status tugas. Nilai valid: PENDING SUCCESS FAIL	PENDING
result.error	String	Pesan kesalahan saat Anda menyetel result.status ke FAIL. Nilai parameter ini kosong jika tugas berhasil.	Gagal dekripsi dokumen
result.data	Object	Hasil penguraian dokumen.	markdown
result.data.content	String	Hasil penguraian dokumen - konten. Dokumen PDF dikeluarkan dalam format markdown Dokumen lainnya dikeluarkan dalam format HTML	"XXX"
result.data.content_type	String	Hasil penguraian dokumen - format konten. markdown html	markdown
result.data.page_num	Int	Hasil penguraian dokumen - jumlah halaman.	15
request_id	String	Pengenal unik yang ditetapkan oleh sistem untuk panggilan API.	B4AB89C8-B135-****-A6F8-2BAB8018688
latency	Float/Int	Durasi permintaan. Unit: milidetik.	10
usage	Object	Informasi penagihan yang dihasilkan oleh panggilan 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	Token input model ekstraksi semantik.	3068

Contoh 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

Contoh respons normal

{
    "request_id": "27F9CEC3-9052-****-83FF-E7957B680492",
    "latency": 13.0,
    "http_code": 200,
    "result": {
        "status": "SUCCESS",
        "data": {
            "content": "Dengan menyediakan atribusi yang tepat, Alibaba dengan ini memberikan izin untuk mereproduksi tabel dan gambar dalam makalah ini hanya untuk digunakan dalam karya jurnalistik atau ilmiah....",
            "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
    }
}

Contoh respons abnormal

Dalam kasus kesalahan permintaan akses, hasil keluaran akan menunjukkan alasan kesalahan melalui kode dan pesan.

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

Buat tugas ekstraksi sinkron

Penting

Antarmuka sinkron tidak disarankan untuk lingkungan produksi karena risiko timeout HTTP. Gunakan antarmuka ini hanya untuk debugging.

Metode permintaan

POST

URL

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

Deskripsi parameter

host: alamat untuk memanggil layanan. Anda dapat memanggil layanan API melalui Internet atau VPC. Untuk informasi lebih lanjut, lihat Dapatkan Alamat Pendaftaran Layanan.
workspace_name: nama ruang kerja, seperti default.
service_id: ID layanan bawaan, seperti ops-document-analyze-001.

Parameter permintaan

Parameter Header

Otentikasi Kunci API

Parameter	Tipe	Diperlukan	Deskripsi	Contoh
Content-Type	String	Ya	Tipe permintaan. Nilai valid: application dan json.	application/json
Authorization	String	Ya	Kunci API.	Bearer OS-d1**2a

Parameter Body

Parameter	Type	Diperlukan	Deskripsi	Contoh
document.url	String	Tidak	URL dokumen. Nilai valid: protokol HTTP dan HTTPS. Pastikan dapat diunduh secara tanpa status dari jaringan publik. Salah satu document.content atau document.url diperlukan.	http://opensearch-shanghai.oss-cn-shanghai.aliyuncs.com/chatos/***/file-parser/samples/GB10767.pdf
document.content	String	Tidak	Konten dokumen yang dikodekan dalam Base64. Salah satu document.content atau document.url diperlukan.	"aGVsbG8gd29ybGQ="
document.file_name	String	Tidak	Nama dokumen. Jika Anda meninggalkan parameter ini kosong, nama dapat disimpulkan dari URL. Jika Anda meninggalkan parameter ini dan parameter document.url kosong, nama dokumen perlu ditentukan secara eksplisit.	test.pdf
document.file_type	String	Tidak	Tipe dokumen. Jika Anda meninggalkan parameter ini kosong, tipe dokumen dapat disimpulkan dari akhiran nama dokumen. Jika tidak dapat disimpulkan, tipe dokumen perlu ditentukan secara eksplisit. Jenis dokumen yang didukung meliputi TXT, PDF, HTML, DOC, DOCX, PPT, dan PPTX.	pdf
output.image_storage	String	Tidak	Metode penyimpanan gambar. base64: metode default. url: URL berlaku selama 3 hari.	url
strategy.enable_semantic	Boolean	Tidak	Menentukan apakah akan mengaktifkan ekstraksi hierarki semantik. Mengaktifkan fitur ini akan mengembalikan dokumen dalam format hierarki Markdown dengan akurasi yang lebih baik. Saat Anda mengaktifkan fitur ini, waktu penguraian dokumen keseluruhan akan meningkat. Waktu penguraian lebih dari 400 detik atau dokumen super panjang (lebih dari 100 halaman) dapat menyebabkan sistem secara otomatis menonaktifkan fitur ini. Fitur ini tidak mendukung dokumen tipe HTML, PPT, atau PPTX.	false

Parameter respons

Parameter	Tipe	Deskripsi	Contoh
result.status	String	Status tugas. Nilai valid: PENDING SUCCES FAIL	PENDING
result.error	String	Pesan kesalahan saat Anda menyetel result.status ke FAIL. Nilai parameter ini kosong jika tugas berhasil.	Gagal dekripsi dokumen
result.data	Object	Hasil penguraian dokumen.	markdown
result.data.content	String	Hasil penguraian dokumen - konten. Dokumen PDF dikeluarkan dalam format markdown Dokumen lainnya dikeluarkan dalam format HTML	"XXX"
result.data.content_type	String	Hasil penguraian dokumen - format konten. markdown html	markdown
result.data.page_num	Int	Hasil penguraian dokumen - jumlah halaman.	15
request_id	String	Pengenal unik yang ditetapkan oleh sistem untuk panggilan API.	B4AB89C8-B135-****-A6F8-2BAB801A2CE4
latency	Float/Int	Durasi permintaan. Unit: milidetik.	10
usage	Object	Informasi penagihan yang dihasilkan oleh panggilan 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	Token input model ekstraksi semantik.	3068

Contoh permintaan 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 normal

{
    "request_id": "27F9CEC3-9052-****-83FF-E7957B689D04",
    "latency": 13.0,
    "http_code": 200,
    "result": {
        "status": "SUCCESS",
        "data": {
            "content": "Dengan menyediakan atribusi yang tepat, Alibaba dengan ini memberikan izin untuk mereproduksi tabel dan gambar dalam makalah ini hanya untuk digunakan dalam karya jurnalistik atau ilmiah....",
            "content_type": "markdown",
            "page_num": 15
        }
    },
    "usage": {
        "token_count": 31867,
        "table_count": 4,
        "image_count": 8,
        "semantic_token_count":3068
    }
}

Contoh respons abnormal

Dalam kasus kesalahan permintaan akses, hasil keluaran akan menunjukkan alasan kesalahan melalui kode dan pesan.

{
    "request_id": "6F33AFB6-A35C-****-AFD2-9EA16CCF4383",
    "latency": 2.0,
    "code": "InvalidParameter",
    "http_code": 400,
    "message": "Kesalahan parse JSON: Tidak dapat mendeserialisasi nilai tipe `ImageStorage` dari String \\"xxx\\""
}

Deskripsi kode status

Kode status HTTP	Pesan kesalahan	Deskripsi
200	-	Permintaan berhasil, termasuk skenario kegagalan tugas. Status tugas aktual perlu ditentukan dari result.status
404	BadRequest.TaskNotExist	Tugas tidak ada
400	InvalidParameter	Permintaan tidak valid
500	InternalServerError	Kesalahan internal