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檔案。
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文档的内容"}
]
}]
}'
使用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(數組)形式。
參數 | 類型 | 是否必填 | 說明 |
|---|---|---|---|
file_url | string | 二選一必填 | 指定PDF檔案的下載地址,和 |
file_data | string | Base64格式的PDF檔案輸入,格式為 | |
filename | string | 條件必填 | 檔案名稱,使用 |
file_format | string | 否 | 檔案格式,選擇性參數,當前僅支援 |
限制說明
專案 | 限制 |
|---|---|
單檔案大小限制 | 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"
}
}
}