跳转到主要内容
工具调用

PDF理解

PDF文件通过VL模型解析

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文件。 获取千问AI平台 API Key并配置环境变量。
  • OpenAI 兼容
  • DashScope
  • Responses API
from openai import OpenAI
import os

client = OpenAI(
    # 若没有配置环境变量,请用千问AI平台 API Key 将下行替换为:api_key="sk-xxx"(不建议),
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://maas.qianwenaiapi.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},
    # 需要开启该参数才会在 usage 中返回 x_tools.pdf_page_parser.count(PDF解析页数)
    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)

使用Base64输入

如果无法提供文件的URL地址,也可以将PDF文件以Base64编码字符串的形式传入。使用 file_data 时,filename 字段为必填项。
Base64 编码会使数据体积增大约 1/3,例如 150MB 的文件编码后约 200MB,会超出请求体大小上限。大文件请改用 URL 方式传入。
  • OpenAI 兼容
  • DashScope
  • Anthropic
Python
import base64
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://maas.qianwenaiapi.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)

请求参数

以下参数表适用于 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 部分仅支持字符串输入,不支持 list(数组)形式。
OpenAI兼容协议格式:
参数类型是否必填说明
file_urlstring二选一必填指定PDF文件的下载地址,和 file_data 二选一必填。
file_datastring二选一必填Base64格式的PDF文件输入,格式为 data:application/pdf;base64,xxx,和 file_url 二选一必填。
filenamestring条件必填文件名,使用 file_data 作为入参时必填。
file_formatstring否文件格式,可选参数,当前仅支持 pdf,默认 pdf。

限制说明

项目限制
单文件大小限制150MB
单文档页数限制256页
PDF解析可能比普通文本请求耗时更长,首包超时时间最长为300秒,建议使用流式输出方式实时获取结果,避免长时间等待。

计费说明

计费涉及以下方面:
  • 模型调用费用:PDF文件解析出的文字与图片会计入模型的输入Token,按照模型的标准输入价格计费。
  • 文档解析费用:按PDF文档解析的页数计费,0.02元/页。
各模型的输入输出单价请参见模型调用计费。

查看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。解析计数未返回时,不表示本次未产生解析费用。
// 需在请求体顶层传入 "include_tool_usage": true 后才会返回。
// OpenAI Python SDK 请通过 extra_body={"include_tool_usage": True} 传入,
// 直接使用 HTTP/curl 时放在请求体顶层,不要嵌套到 extra_body 或 stream_options。
{
    "usage": {
        "x_tools": {
            "pdf_page_parser": {
                "count": 10,
                "strategy": "normal"
            }
        }
    }
}

错误码

如果调用失败,请参阅错误码。
qwen4-max 的 Responses API 从响应顶层 tool_usage 读取工具计数:web_search.num_requests 为计费搜索次数,web_extractor.num_requests 为计费抓取次数,pdf_page_parser.num_requests 为 PDF 解析页数。流式请求从 response.completed.response.tool_usage 读取。计数不按 output 项数计算。 旧版工具计数字段仅适用于仍返回该结构的模型。