全部產品
Search
文件中心

Alibaba Cloud Model Studio:PDF理解

更新時間:Nov 19, 2026

PDF理解功能使模型能夠解析PDF文件中的文字與圖片,透過 Chat Completions、Responses API、DashScope 或 Anthropic 相容介面進行分析。

支援的模型

qwen4-max、qwen3.8-max、qwen3.8-max-0902、qwen3.8-flash、qwen3.8-27b

qwen3.8-27b 僅支援在北京地區透過 Chat Completions 或 DashScope 呼叫 PDF 理解。

快速開始

運行以下代碼,向模型傳入PDF檔案。

需要已擷取與配置 API Key並配置API Key到環境變數。

OpenAI 相容

Python

範例程式碼

from openai import OpenAI
import os

client = OpenAI(
    # 若沒有配置環境變數,請用百鍊API Key將下行替換為:api_key="sk-xxx"(不建議),
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 以下為新加坡地區的URL,調用時請將 {WorkspaceId} 替換為真實的業務空間ID,各地區的URL不同。
    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": "總結一下這個PDF文檔的內容"
                }
            ]
        }
    ],
    stream=True,
    stream_options={"include_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)

Node.js

範例程式碼

import OpenAI from "openai";
import process from 'process';

const openai = new OpenAI({
    // 若沒有配置環境變數,請用百鍊API Key將下行替換為:apiKey: "sk-xxx",
    apiKey: process.env.DASHSCOPE_API_KEY,
    // 以下為新加坡地區的URL,調用時請將 {WorkspaceId} 替換為真實的業務空間ID,各地區的URL不同。
    baseURL: 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1'
});

async function main() {
    const stream = await openai.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: '總結一下這個PDF文檔的內容'
                    }
                ]
            }
        ],
        stream: true,
        stream_options: { include_usage: true }
    });

    for await (const chunk of stream) {
        if (!chunk.choices?.length) {
            console.log('\nUsage:', chunk.usage);
            continue;
        }
        const delta = chunk.choices[0].delta;
        if (delta.content) {
            process.stdout.write(delta.content);
        }
    }
}

main();

HTTP

範例程式碼

# 以下為新加坡地區的URL,調用時請將 {WorkspaceId} 替換為真實的業務空間ID,各地區的URL不同。
curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "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": "總結一下這個PDF文檔的內容"
                }
            ]
        }
    ],
    "stream": true,
    "stream_options": {
        "include_usage": true
    }
}'

DashScope

Python

範例程式碼

import os
from dashscope import MultiModalConversation
import dashscope

# 以下為新加坡地區的URL,調用時請將 {WorkspaceId} 替換為真實的業務空間ID,各地區的URL不同。
dashscope.base_http_api_url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"

messages = [
    {
        "role": "user",
        "content": [
            {
                "file_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260616/qmycjl/1506.02640v5.pdf"
            },
            {
                "text": "總結一下這個PDF文檔的內容"
            }
        ]
    }
]

completion = MultiModalConversation.call(
    # 若沒有配置環境變數,請用阿里雲百鍊API Key將下行替換為:api_key = "sk-xxx",
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    model="qwen4-max",
    messages=messages,
    stream=True,
    incremental_output=True
)

for chunk in completion:
    message = chunk.output.choices[0].message
    if message.content:
        print(message.content[0]["text"], end="", flush=True)

HTTP

範例程式碼

# 以下為新加坡地區的URL,調用時請將 {WorkspaceId} 替換為真實的業務空間ID,各地區的URL不同。
curl -X POST "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-DashScope-SSE: enable" \
-d '{
    "model": "qwen4-max",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "file_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260616/qmycjl/1506.02640v5.pdf"
                    },
                    {
                        "text": "總結一下這個PDF文檔的內容"
                    }
                ]
            }
        ]
    },
    "parameters": {
        "incremental_output": true,
        "result_format": "message"
    }
}'

Responses API

Responses API 支援透過 input_file.file_url 傳入 PDF。qwen3.8-27b 不支援此方式。

以下範例使用北京地區的業務空間專屬網域。請替換 {WorkspaceId},並依地區及部署範圍設定 API Key 和網域,詳見接入資訊。

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DASHSCOPE_API_KEY"],
    base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
    timeout=300.0,
)

response = client.responses.create(
    model="qwen3.8-flash",
    input=[{
        "role": "user",
        "content": [
            {"type": "input_file", "file_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260616/qmycjl/1506.02640v5.pdf"},
            {"type": "input_text", "text": "總結這個PDF文件的內容。"},
        ],
    }],
    extra_body={"include_tool_usage": True},
)

print(response.output_text)
curl 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/responses' \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.8-flash",
    "input": [{
      "role": "user",
      "content": [
        {"type": "input_file", "file_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260616/qmycjl/1506.02640v5.pdf"},
        {"type": "input_text", "text": "總結這個PDF文件的內容。"}
      ]
    }],
    "include_tool_usage": true
  }'

Anthropic

qwen3.8-max、qwen3.8-flash 及 qwen4 系列模型支援透過 Anthropic 相容 Messages API 直接傳入 PDF 檔案 URL。在 messages[].content 中使用 type: "document" 內容區塊,將 source.type 設為 url,並在 source.url 中指定 PDF 檔案 URL。

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/apps/anthropic/v1/messages' \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $DASHSCOPE_API_KEY" \
  --data '{
    "model": "qwen3.8-max",
    "max_tokens": 1024,
    "messages": [{
      "role": "user",
      "content": [
        {
          "type": "document",
          "source": {
            "type": "url",
            "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260616/qmycjl/1506.02640v5.pdf"
          }
        },
        {"type": "text", "text": "总结一下这个PDF文档的内容"}
      ]
    }]
  }'

Anthropic相容-Messages

使用Base64輸入

如果無法提供檔案的URL地址,也可以將PDF檔案以Base64編碼字串的形式傳入。使用 file_data 時,filename 欄位為必填項。

說明Base 64 編碼會使資料體積增大約 1/3,例如 150MB 的檔案編碼後約 200MB,會超出請求體大小上限。大檔案請改用 URL 方式傳入。

Chat Completions / DashScope

import base64
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 以下為新加坡地區的URL,調用時請將 {WorkspaceId} 替換為真實的業務空間ID,各地區的URL不同。
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

# 讀取並編碼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": "這份報告的核心結論是什嗎?"
                }
            ]
        }
    ]
)

print(completion.choices[0].message.content)
import base64
import os
from dashscope import MultiModalConversation
import dashscope

# 以下為新加坡地區的URL,調用時請將 {WorkspaceId} 替換為真實的業務空間ID,各地區的URL不同。
dashscope.base_http_api_url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"

# 讀取並編碼PDF檔案
with open("report.pdf", "rb") as f:
    pdf_base64 = base64.b64encode(f.read()).decode("utf-8")

messages = [
    {
        "role": "user",
        "content": [
            {
                "file_data": f"data:application/pdf;base64,{pdf_base64}",
                "filename": "report.pdf"
            },
            {
                "text": "這份報告的核心結論是什嗎?"
            }
        ]
    }
]

response = MultiModalConversation.call(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    model="qwen4-max",
    messages=messages
)

print(response.output.choices[0].message.content[0]["text"])

Anthropic

Anthropic 相容介面也支援 Base64 PDF 輸入。 qwen3.8-max、qwen3.8-flash 及 qwen4 系列模型支援透過 Anthropic 相容 Messages API 直接傳入 PDF 檔案 URL。在 messages[].content 中使用 type: "document" 內容區塊,將 source.type 設為 url,並在 source.url 中指定 PDF 檔案 URL。

Anthropic 相容介面支援透過 document.source 傳入 Base64 PDF。下載範例 PDF並儲存為 report.pdf,或使用自己的 PDF 文件。Python 範例需要安裝 anthropic SDK。

以下範例使用北京地區的業務空間專屬網域。請替換 {WorkspaceId},並依地區及部署範圍設定 API Key 和網域,詳見接入資訊。

import os
import base64
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["DASHSCOPE_API_KEY"],
    base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/apps/anthropic",
    timeout=300.0,
)

with open("report.pdf", "rb") as file:
    pdf_base64 = base64.b64encode(file.read()).decode("utf-8")

response = client.messages.create(
    model="qwen3.8-flash",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "document",
                "source": {
                    "type": "base64",
                    "media_type": "application/pdf",
                    "data": pdf_base64,
                },
            },
            {"type": "text", "text": "總結這個PDF文件的內容。"},
        ],
    }],
    extra_body={"include_tool_usage": True},
)

for block in response.content:
    if block.type == "text":
        print(block.text)
PDF_BASE64=$(base64 < report.pdf | tr -d '\n')
curl 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/apps/anthropic/v1/messages' \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
{
  "model": "qwen3.8-flash",
  "max_tokens": 1024,
  "messages": [{
    "role": "user",
    "content": [
      {
        "type": "document",
        "source": {
          "type": "base64",
          "media_type": "application/pdf",
          "data": "$PDF_BASE64"
        }
      },
      {"type": "text", "text": "總結這個PDF文件的內容。"}
    ]
  }],
  "include_tool_usage": true
}
EOF

請求參數

以下參數表適用於 Chat Completions。Responses API 使用 type: "input_file" 和 file_url;Anthropic 相容介面使用 type: "document",並在 source 中設定 type: "base64"、media_type: "application/pdf" 和 data(不含 Data URI 前綴的 Base64 字串)。 DashScope 使用 content 陣列中包含 file_url 或 file_data 的元素傳入文件。 URL 輸入時,type 必填,固定為 document;source 為必填物件,其中 type 為必填字串,設為 url,url 為必填字串,指定 PDF 檔案 URL。

說明協議中 URL 部分僅支援字串輸入,不支援 list(數組)形式。

OpenAI相容協議格式:

參數

類型

是否必填

說明

file_url

string

二選一必填

指定PDF檔案的下載地址,和 file_data 二選一必填。

file_data

string

Base64格式的PDF檔案輸入,格式為 data:application/pdf;base64,xxx,和 file_url 二選一必填。

filename

string

條件必填

檔案名稱,使用 file_data 作為入參時必填。

file_format

string

否

檔案格式,選擇性參數,當前僅支援 pdf,預設 pdf。

限制說明

專案

限制

單檔案大小限制

150MB

單文檔頁數限制

256頁

說明PDF解析可能比普通文本請求耗時更長,首包逾時時間最長為300秒,建議使用流式輸出方式即時擷取結果,避免長時間等待。

計費說明

計費涉及以下方面:

  • 模型調用費用:PDF檔案解析出的文字與圖片會計入模型的輸入Token,按照模型的標準輸入價格計費。
  • 文檔解析費用:按PDF文檔解析的頁數計費,各地域單價不同:華北2(北京)$0.003/頁,新加坡$0.0033/頁。全球部署模式:$0.003/頁。

各模型的輸入輸出單價請參見模型調用計費。

查看PDF解析頁數

qwen4-max 的 Responses API 使用回應頂層 tool_usage,各工具的 num_requests 為計費次數,pdf_page_parser.num_requests 為解析頁數。Qwen3.8 的 Responses 範例仍使用 usage.x_tools。

Chat Completions 與 Responses API (Qwen3.8) 可在請求主體頂層傳入 include_tool_usage: true,從 usage.x_tools.pdf_page_parser.count 查看解析頁數;DashScope 從 usage.plugins.pdf_page_parser.count 查看。Anthropic 相容介面在回應頂層 x_tools.pdf_page_parser.count 返回解析頁數。未返回計數不代表沒有產生解析費用。

{
    "x_tools": {
        "pdf_page_parser": {
            "count": 10,
            "strategy": "normal"
        }
    }
}