Skip to main content

Pemahaman PDF

Fitur pemahaman PDF memungkinkan model mengurai teks dan gambar dalam dokumen PDF, serta menganalisisnya melalui Chat Completions, Responses API, DashScope, atau API kompatibel Anthropic.

Model yang Didukung

qwen4-max, qwen3.8-max, qwen3.8-max-0902, qwen3.8-flash, qwen3.8-27b qwen3.8-27b hanya mendukung pemahaman PDF di wilayah Beijing melalui Chat Completions atau DashScope.

Mulai Cepat

Jalankan kode berikut untuk mengirimkan file PDF ke model.
Anda harus telah mendapatkan dan mengonfigurasi Kunci API serta mengonfigurasi Kunci API sebagai variabel lingkungan.
  • Kompatibel OpenAI
  • DashScope
  • Responses API
  • Anthropic
  • Python
  • Node.js
  • HTTP

Kode Contoh

from openai import OpenAI
import os

client = OpenAI(
    # Jika variabel lingkungan belum dikonfigurasi, ganti baris berikut dengan Kunci API Model Studio Anda: api_key="sk-xxx" (tidak disarankan),
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # Berikut adalah URL untuk wilayah Singapura. Saat memanggil, ganti {WorkspaceId} dengan ID ruang kerja aktual Anda. URL berbeda-beda tergantung wilayah.
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

completion = client.chat.completions.create(
    model="qwen4-max",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "file",
                    "file": {
                        "file_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260616/qmycjl/1506.02640v5.pdf"
                    }
                },
                {
                    "type": "text",
                    "text": "Ringkas isi dokumen PDF ini"
                }
            ]
        }
    ],
    stream=True,
    stream_options={"include_usage": True},
    # Parameter ini perlu diaktifkan agar x_tools.pdf_page_parser.count (jumlah halaman PDF yang diurai) dikembalikan dalam usage
    extra_body={"include_tool_usage": True}
)

for chunk in completion:
    if not chunk.choices:
        print(f"\nUsage: {chunk.usage}")
        continue
    delta = chunk.choices[0].delta
    if hasattr(delta, "content") and delta.content:
        print(delta.content, end="", flush=True)

Menggunakan Input Base64

Jika Anda tidak dapat menyediakan URL file, Anda juga dapat mengirimkan file PDF sebagai string yang diencode Base64. Saat menggunakan file_data, bidang filename wajib diisi.
Encoding Base64 meningkatkan ukuran data sekitar 1/3. Misalnya, file 150MB menjadi sekitar 200MB setelah diencode, yang melebihi batas ukuran body permintaan. Untuk file besar, gunakan metode URL sebagai gantinya.
  • Chat Completions / DashScope
  • Anthropic
import base64
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # Berikut adalah URL untuk wilayah Singapura. Saat memanggil, ganti {WorkspaceId} dengan ID ruang kerja aktual Anda. URL berbeda-beda tergantung wilayah.
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

# Baca dan encode file PDF
with open("report.pdf", "rb") as f:
    pdf_base64 = base64.b64encode(f.read()).decode("utf-8")

completion = client.chat.completions.create(
    model="qwen4-max",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "file",
                    "file": {
                        "file_data": f"data:application/pdf;base64,{pdf_base64}",
                        "filename": "report.pdf"
                    }
                },
                {
                    "type": "text",
                    "text": "Apa kesimpulan utama dari laporan ini?"
                }
            ]
        }
    ]
)

print(completion.choices[0].message.content)

Parameter Permintaan

Tabel parameter berikut berlaku untuk Chat Completions. Responses API menggunakan type: "input_file" dan file_url; API kompatibel Anthropic menggunakan type: "document" dan menetapkan type: "base64", media_type: "application/pdf", serta data (string Base64 tanpa prefiks Data URI) dalam source. DashScope mengirimkan file melalui elemen dalam array content yang berisi file_url atau file_data. Untuk input URL, type wajib diisi dan bernilai tetap document; source adalah objek wajib, dengan type berupa string wajib bernilai url, dan url berupa string wajib yang menentukan URL file PDF.
Dalam protokol, bagian URL hanya mendukung input string, bukan bentuk list (array).
Format protokol kompatibel OpenAI:

Parameter

Tipe

Wajib atau Tidak

Deskripsi

file_urlstringWajib (pilih salah satu dari keduanya)Alamat unduhan file PDF. Parameter ini atau file_data wajib diisi salah satu.
file_datastringInput file PDF dalam format Base64, dengan format data:application/pdf;base64,xxx. Parameter ini atau file_url wajib diisi salah satu.
filenamestringWajib bersyaratNama file. Wajib diisi saat file_data digunakan sebagai parameter input.
file_formatstringTidakFormat file. Opsional. Saat ini hanya pdf yang didukung, dan nilai default-nya adalah pdf.

Batasan

Item

Batas

Batas ukuran file tunggal150MB
Batas jumlah halaman per dokumen256 halaman
Parsing PDF dapat memerlukan waktu lebih lama daripada permintaan teks biasa. Timeout token pertama dapat mencapai 300 detik. Kami merekomendasikan menggunakan keluaran streaming untuk mendapatkan hasil secara real-time dan menghindari penantian yang lama.

Rincian Penagihan

Penagihan mencakup aspek-aspek berikut:
  • Biaya pemanggilan model: Teks dan gambar yang diurai dari file PDF dihitung sebagai token input model dan ditagih dengan harga input standar model.
  • Biaya parsing dokumen: Ditagih berdasarkan jumlah halaman PDF yang diurai, dengan harga satuan yang bervariasi menurut wilayah: Tiongkok (Beijing) $0.003/halaman, Singapura $0.0033/halaman. Mode deployment global: $0.003/halaman.
Untuk harga satuan input dan output setiap model, lihat Penagihan pemanggilan model.

Melihat jumlah halaman PDF yang diurai

Responses API dari qwen4-max menggunakan tool_usage tingkat teratas respons, dengan num_requests setiap alat sebagai jumlah panggilan yang ditagih, dan pdf_page_parser.num_requests sebagai jumlah halaman yang diurai. Contoh Responses untuk Qwen3.8 masih menggunakan usage.x_tools. Chat Completions dan Responses API (Qwen3.8) dapat mengirimkan include_tool_usage: true pada tingkat teratas body permintaan dan melihat jumlah halaman yang diurai dari usage.x_tools.pdf_page_parser.count; untuk DashScope, lihat dari usage.plugins.pdf_page_parser.count. Jumlah halaman yang diurai yang dikembalikan oleh API kompatibel Anthropic berada pada tingkat teratas respons di x_tools.pdf_page_parser.count. Jika jumlah parsing tidak dikembalikan, itu tidak berarti tidak ada biaya parsing yang dikenakan untuk permintaan ini.
// Hanya dikembalikan setelah "include_tool_usage": true dikirimkan pada tingkat teratas body permintaan.
// Untuk OpenAI Python SDK, kirimkan melalui extra_body={"include_tool_usage": True},
// saat menggunakan HTTP/curl secara langsung, letakkan di tingkat teratas body permintaan, jangan disarangkan ke extra_body atau stream_options.
{
    "usage": {
        "x_tools": {
            "pdf_page_parser": {
                "count": 10,
                "strategy": "normal"
            }
        }
    }
}