Java调用通义千问多模态大模型实现PDF表格转Excel完整实践

前阵子接到一个需求，财务那边给了一堆PDF报表，要把里面的表格字段整理到Excel里。试了好几个Java库，PDFBox抽文本能抽出来，但表格结构要靠坐标对齐去恢复，遇到跨行表头、合并单元格、还有几份带水印的扫描件，直接破防。后来换了个思路：让通义千问大模型直接“看”PDF页面，把PDF文件解析为Excel表格，用Java写了一套完整实现，跑通了，效果比传统工具稳定得多。

这篇记录不是官方文档的复述，是我自己从环境搭建到代码落地，再到踩坑排查的完整过程。适合正在做文件解析、报表处理，或者想用大模型能力改造传统流程的Java开发。你会看到为什么传统PDF解析在大模型面前显得有些过时、整条链路的架构设计、核心代码怎么组织、提示词怎么调，以及哪些坑最容易让人怀疑人生。

1. 为什么用大模型来转PDF表格

1.1 传统PDF解析工具卡在哪里

很多人一开始的想法跟我一样，用PDFBox把文本抽出来，再用规则拼成表格。没做过的人可能觉得不难，其实PDF里的表格根本不是一种“结构体”，它是由文本对象、线条图形、坐标位置拼出来的视觉结果。PDFBox确实能拿到每个字符串的坐标，比如某个字符串在页面的x=120、y=450处，但要判断它属于第几列、和哪个表头对齐，完全靠坐标聚类和人工规则。

这种做法遇到标准电子版PDF、线条完整的表格时还能凑合，一旦出现下面几种情况就废了：表头跨列、单元格里有换行、同一列的数据被分割成多个文本块、表格线是扫描出来的虚线、页面有页眉页脚水印。我那时候光是清洗坐标数据就写了将近两百行代码，换一个PDF样式又要重新调，越调越绝望。

tabula、camelot这类的工具我也试过，它们本质上还是基于页面元素坐标来推断表格位置，对有清晰表格线的PDF效果不错。可遇到扫描件，也就是那种整页都是图片、没有任何文本层的PDF，这些工具根本拿不到文本，表格识别也就无从谈起。而我们这个需求里偏偏有相当一部分就是扫描件。

1.2 多模态模型带来的思路转变

通义千问这类多模态大模型给了一个完全不同的解题方向：把“解析PDF”变成“让模型看图说话”。我不再需要去理解PDF内部的绘图指令和坐标关系，只需要把PDF的某一页渲染成一张图片，交给qwen-vl系列模型，它直接用视觉能力识别页面里的表格结构，然后输出结构化的数据。

这个思路的本质区别在于：传统工具是在模拟“坐标对齐”这件底层的事，而大模型是在模拟“人眼看表格”这件事。人眼看表格，不需要知道每条线的坐标，一眼就能分清表头和数据行；跨页的重复表头、合并单元格、甚至有些破损打印件，人也照样能看懂。多模态模型在这一点上更接近人的行为。

我并不是说传统工具完全没用了。如果你的PDF全部是规范电子版、表格结构简单、量又特别大，那传统方案依然省钱省时间。但凡是表格复杂、扫描件多、样式杂的场景，大模型方案是省心很多的那个。

1.3 方案不能覆盖的场景

这里必须泼一盆冷水。别指望大模型能把Excel公式、单元格样式、打印区域这些东西都还原出来，它只负责把表格里的“数据”按行列关系输出，Excel是一个容器，POI负责把我们拿到的行列数据写进去。如果你的需求是连公式、颜色、边框都要保留，那就不要用这个方案。还有那种一张页面里塞了几十行、每行字段又特别多的密集大表，视觉识别可能会漏行，需要分块处理或者加校验逻辑。后面我会专门讲怎么处理这种边界情况。

2. 整体流程与准备工作

2.1 一条清晰的调用链

整个方案的链路并不复杂，关键是一环扣一环：

PDF文件逐页渲染成PNG图片，图片用Base64编码后放进请求体，以多模态消息的方式发给通义千问，模型返回一段JSON文本，用Jackson解析成数据结构，最后用Apache POI写入Excel。每一步单看都不难，拼在一起就是一条完整的PDF转Excel流水线。

这里有一条原则我强烈建议遵守：按页处理，不要一次性把整个PDF丢给模型。大模型对图片的输入有尺寸和token限制，几十页的PDF拼成一张长图，模型根本看不清楚，而且输出的内容量大之后很容易中途截断。按页处理还有一个好处：某一页识别失败，只需要重试这一页，不影响其他页面。

2.2 Maven依赖

我用的是Java 11，Spring Boot搭的外层接口，核心依赖如下：

<dependency> <groupId>org.apache.pdfbox</groupId> <artifactId>pdfbox</artifactId> <version>2.0.31</version> </dependency> <dependency> <groupId>org.apache.poi</groupId> <artifactId>poi-ooxml</artifactId> <version>5.4.1</version> </dependency> <dependency> <groupId>com.squareup.okhttp3</groupId> <artifactId>okhttp</artifactId> <version>4.12.0</version> </dependency> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-databind</artifactId> <version>2.17.0</version> </dependency>

PDFBox负责把PDF页面渲染成图片，POI负责生成xlsx文件，OkHttp用来调用通义千问的HTTP接口，Jackson处理模型返回的JSON。没有引入官方SDK，因为DashScope的HTTP接口比较稳定，拼JSON也好控制，避免SDK版本升级搞得代码要跟着改。

2.3 API Key和模型怎么选

调用通义千问需要在阿里云的大模型服务平台上开通，拿到API Key。模型我建议从qwen-vl-plus和qwen-vl-max里选，两个都是多模态模型，直接支持图片输入。它们的关系可以类比为标准版和专业版，plus便宜、速度快，max准确率更高、更擅长复杂版面。

我个人的选择逻辑很简单：先拿一页有代表性的PDF用plus跑，如果表格结构识别得干净，就直接用plus全量跑；发现表格线模糊、合并单元格多、识别出现明显错行，再切到max，只对问题页面重试。这样成本控制得比较好。

有两点必须提醒：API Key千万别硬编码在代码里，放到环境变量或者配置中心，防止代码提交到Git后泄露，别人拿到你的Key能直接消耗你的账户额度；还有模型计费是按输入输出的token数来的，图片本身也会折算成token，高分辨率图片贵不少，这一点会影响后面图片预处理策略。

3. Java核心代码实现

3.1 PDF页面渲染成图片

PDFBox把PDF渲染成图片是整套方案的入口，代码不长，但有讲究：

import org.apache.pdfbox.pdmodel.PDDocument; import org.apache.pdfbox.rendering.PDFRenderer; import org.apache.pdfbox.rendering.ImageType; import javax.imageio.ImageIO; import java.awt.image.BufferedImage; import java.io.File; public class PdfPageRenderer { public static File renderPage(File pdfFile, int pageIndex, int dpi) throws Exception { try (PDDocument document = PDDocument.load(pdfFile)) { if (pageIndex < 0 || pageIndex >= document.getNumberOfPages()) { throw new IllegalArgumentException("pageIndex out of range"); } PDFRenderer renderer = new PDFRenderer(document); BufferedImage image = renderer.renderImageWithDPI(pageIndex, dpi, ImageType.RGB); File imageFile = File.createTempFile("pdf-page-" + pageIndex + "-", ".png"); ImageIO.write(image, "png", imageFile); return imageFile; } } }

DPI的选择直接影响识别效果和成本。普通电子版PDF我一般用150左右，扫描件提到200到300。扫描件本身字迹边缘不清晰，如果DPI太低渲染出来的图片文字发虚，模型识别会受到影响；但DPI拉到300以上，图片体积变大，请求体变大，响应速度也会变慢，还会提高token消耗。别盲目追求高清晰度，够用就好。

渲染出来的PNG如果体积太大，比如超过10MB，建议先压缩一次再转Base64。Java自带的ImageIO可以重新缩放图像尺寸，我把页面长边限制在2048像素以内，实测对视觉模型的识别率影响不大，但请求体小很多。

3.2 调用通义千问模型

我直接用HTTP方式调DashScope，接受的返回格式是message形式。下面这段代码构造多模态请求体：

import okhttp3.*; public class QwenVisionClient { private static final String ENDPOINT = "https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation"; private final String apiKey; private final OkHttpClient client = new OkHttpClient(); public QwenVisionClient(String apiKey) { this.apiKey = apiKey; } public String call(String imageBase64, String promptText) throws Exception { String contentBody = "{" + "\"model\":\"qwen-vl-plus\"," + "\"input\":{\"messages\":[" + "{\"role\":\"system\",\"content\":[{\"text\":\"" + PromptConstants.SYSTEM_PROMPT + "\"}]}," + "{\"role\":\"user\",\"content\":[" + "{\"image\":\"data:image/png;base64," + imageBase64 + "\"}," + "{\"text\":\"" + promptText + "\"}" + "]}" + "]}," + "\"parameters\":{\"result_format\":\"message\",\"temperature\":0.1}" + "}"; Request request = new Request.Builder() .url(ENDPOINT) .addHeader("Authorization", "Bearer " + apiKey) .addHeader("Content-Type", "application/json") .post(RequestBody.create(contentBody, MediaType.parse("application/json"))) .build(); try (Response response = client.newCall(request).execute()) { String respBody = response.body().string(); if (!response.isSuccessful()) { throw new RuntimeException("dashscope api error: " + response.code() + " " + respBody); } return extractAssistantText(respBody); } } private String extractAssistantText(String respBody) throws Exception { com.fasterxml.jackson.databind.JsonNode root = new com.fasterxml.jackson.databind.ObjectMapper().readTree(respBody); // 典型的返回结构是 output.choices[0].message.content[0].text return root.path("output").path("choices").get(0) .path("message").path("content").get(0).path("text").asText(); } }

这段代码里省掉了字符串转义的复杂处理，实际操作时建议用Jackson构造JSON对象，而不是直接拼接字符串，否则提示词里的引号、换行很容易把请求体搞坏。我在初版代码里就是直接拼接，结果提示词里稍微多写了一个引号，整个请求就400，排查了很长时间。

3.3 解析模型返回的JSON

模型说好只返回JSON，但它偶尔会给JSON外面裹一层markdown代码块标记。解析前必须先清洗。我写了一个稳妥的提取方法：

public class JsonExtractor { public static String cleanup(String text) { if (text == null) return null; String cleaned = text.trim(); // 去掉 ```json ... ``` 这类包裹 if (cleaned.startsWith("```")) { int firstNewLine = cleaned.indexOf('\n'); if (firstNewLine > 0) { cleaned = cleaned.substring(firstNewLine + 1); } if (cleaned.endsWith("```")) { cleaned = cleaned.substring(0, cleaned.length() - 3); } } return cleaned.trim(); } }

清洗完之后再用Jackson反序列化，注意要定义一个和数据格式对应的数据结构，不要直接返回Map，否则后面写Excel时字段名容易搞混。下面是我用的内部类写法，很直白：

import com.fasterxml.jackson.databind.ObjectMapper; public class TableData { public String name; public java.util.List<String> headers = new java.util.ArrayList<>(); public java.util.List<java.util.List<String>> rows = new java.util.ArrayList<>(); public boolean hasHeader = true; public static TableData fromText(String text) throws Exception { String cleaned = JsonExtractor.cleanup(text); return new ObjectMapper().readValue(cleaned, TableData.class); } }

3.4 用POI把数据写进Excel

拿到TableData后，写Excel就非常机械了，重点在于表头的处理逻辑。第一页通常有表头，如果继续页没表头，就不重复创建表头行：

import org.apache.poi.xssf.usermodel.XSSFWorkbook; import org.apache.poi.ss.usermodel.*; import java.io.FileOutputStream; public class ExcelWriter { public static void writePages(java.util.List<TableData> pages, File output) throws Exception { try (XSSFWorkbook workbook = new XSSFWorkbook()) { Sheet sheet = workbook.createSheet("merged"); Row headerRow = null; int rowIndex = 0; for (TableData page : pages) { if (page.hasHeader && page.headers != null && !page.headers.isEmpty()) { headerRow = sheet.createRow(rowIndex++); for (int i = 0; i < page.headers.size(); i++) { headerRow.createCell(i).setCellValue(page.headers.get(i)); } } if (page.rows != null) { for (java.util.List<String> row : page.rows) { Row excelRow = sheet.createRow(rowIndex++); for (int i = 0; i < row.size(); i++) { if (row.get(i) != null) { excelRow.createCell(i).setCellValue(row.get(i)); } } } } } if (headerRow != null) { for (int i = 0; i < headerRow.getLastCellNum(); i++) { sheet.autoSizeColumn(i); } } try (FileOutputStream fos = new FileOutputStream(output)) { workbook.write(fos); } } } }

注意一个细节：autoSizeColumn在中文字体环境下偶尔会估算错宽度，如果发现导出后列宽不合适，可以手动setColumnWidth，或者是在内存里统计每列最长内容的字节数，再换算成列宽单位。这是个小问题，但影响Excel观感。

4. 提示词设计，决定识别质量的关键变量

4.1 为什么提示词比模型参数更重要

同样的模型、同样的图片，提示词写得清楚和写得模糊，识别出来的表格能差一个档次。原因是视觉模型虽然在“看图”，但它的输出仍然受指令约束。如果你的提示词只说“请提取表格”，它可能会返回一段自然语言描述，或者把解释文字和数据混在一起。要让后续环节稳定处理，必须让它只输出一种格式，并且把这个格式写死在提示词里。

提示词的本质是给模型划清边界：哪些需要提取、按什么顺序、用什么结构、哪些东西必须忽略。边界划得越清楚，识别结果越稳定。我甚至把提示词当作代码的一部分来维护，每次调整都会保留版本记录。

4.2 一份可直接使用的提示词

下面是我实际在用的提示词，直接用System消息发给模型：

你是一个PDF表格提取助手。 请你认真观察用户提供的PDF页面图片，提取图片中的所有表格数据。 必须遵循以下规则： 1. 只输出一个JSON对象，禁止输出任何解释性文字，禁止使用markdown代码块。 2. JSON结构固定如下： { "name": "表格名称，如果有多个表格就写\"sheet1\"", "headers": ["列1表头", "列2表头", "列3表头"], "rows": [["第1行第1列", "第1行第2列"], ["第2行第1列", "第2行第2列"]], "hasHeader": true } 3. 如果当前页面没有表头，headers返回空数组，并把hasHeader设为false。 4. 合并单元格时，合并区域内的数据只保留左上角位置对应的值，其余单元格填充空字符串。 5. 忽略页眉、页脚、水印、页码，这些内容不要放进rows。 6. 仔细核对行数，不要漏掉任何数据行，保证rows的顺序和图片中从上到下的顺序一致。

这套提示词的核心是六个字：定结构、清噪点。特别是第5条“忽略页眉页脚水印”，很多表格识别工具最大的噪音来源就是这些非表格元素。

4.3 继续页处理和输出约束

多页PDF经常遇到同一个表格被拆到两页的情况，第二页开始没有表头，只有数据。有了hasHeader字段，拼接Excel的时候就可以判断：第一页写入表头，后续页不再写表头，直接把数据行追加进同一个sheet。这个逻辑在ExcelWriter那段代码里已经体现了。

还可以进一步让模型在跨页时做标记，比如要求它判断“当前页是否为上一页的延续，如果是，headers返回空数组”。我用下来，qwen-vl系列对这个指令的理解能力是可以的，但偶尔会有误差。比较稳妥的做法是在解析后增加一个规则：如果连续两页的headers完全一样，就认为第二页是复制了表头，自动把第二页的hasHeader改成false，再去合并。

temperature参数我也习惯设为0.1。这类结构化提取任务不需要模型发挥创造力，温度越低，输出越收敛，越不容易编造出表格里不存在的内容。

5. 实测效果：哪些PDF适合、哪些模型更稳

5.1 不同PDF类型的表现

我拿一批测试样本跑了一圈，包括清晰电子版、低质量扫描件、带水印的表格、表格线不完整的打印件。清晰电子版自不必说，表格线完整、文字清晰，qwen-vl-plus几乎都能正确恢复行列。带水印的表格也稳，只要提示词里写了忽略水印，模型基本不会把水印内容混进表格。最考验的是低质量扫描件，画面带噪点、字迹偏淡，qwen-vl-plus偶尔会出现漏行的情况，qwen-vl-max好一些，但仍不是百分百准确。

表格线不完整的PDF是很有意思的案例。传统工具靠坐标对齐，表格线缺了就会判断错列边界。大模型反而表现不错，因为它不只是依赖线条，还能根据文字的纵向对齐关系推断出列结构，这个能力有点接近人眼的判断。

下面是我用下来对两类模型的直观感受：

5.2 输出截断和漏行怎么处理

大模型在生成长文本时偶尔会中途截断，尤其是大表格输出几百行JSON的时候，这会导致JSON不完整。遇到这种情况不要慌，先检查返回文本长度，如果明显比正常短，并且JSON解析报错，基本上就是截断了。处理办法有几种：把DPI从300降到200，让模型看到的内容规模简单一点；把页面从整页切分成上下两半分别识别；或者对截断页面简单重试一次。

漏行问题更隐蔽，因为JSON语法是对的，解析不报错，但行数比原表少。我建议识别完之后做一个基础校验：如果表头列数能确认，就检查每行数组长度是否一致；如果有数据文件可以对比总数，那就让模型输出的行数和文件总数对一下。这样能抓出一部分漏行。

5.3 成本控制经验

成本这个问题一开始容易被忽略。图片输入会折算成token，图片越清晰、分辨率越高，token消耗越大。qwen-vl-plus便宜，量大的时候优势明显。我的经验是先小批量验证，确认那一类PDF的识别率能接受，再用plus大规模跑。只有个别页面识别效果不行，才切到max重试，这样整体成本能压下来很多。

还有一点，同一份PDF反复解析是很浪费的。我会在临时目录里缓存每个页面的识别结果，缓存key直接取图片内容的MD5值。下次遇到相同页面，先查缓存，有就直接读结果，没有再调模型。手工调接口调试的时候，这个缓存能省下不少白花的钱。

6. 踩过的坑与排查链路

6.1 请求体图片格式不对

某天突然连续报400错误，我第一反应是API Key过期，检查了一下Key没问题。后来打印出请求体，发现Base64字符串里带着换行符。Java的Base64编码器默认输出会带换行分段，这在传输到DashScope时可能造成解析异常。解决方法是编码时故意去掉换行：

String base64 = Base64.getEncoder().encodeToString(bytes) .replaceAll("\n", "") .replaceAll("\r", "");

另外图片的data URL前缀也要正确，data:image/png;base64,这一长串不能少，少了这一拍模型接口不认识这个图片输入。

6.2 模型返回JSON被markdown包裹

解析异常的排查过程是这个问题最值得记录的地方。第一次报JSON解析异常，我先怀疑是JSON语法不合法，打印出原始字符串一看，它的开头是json结尾是```，标准markdown代码块包裹。虽然提示词里反复强调不要用markdown，但模型偶尔还是会犯。加一个清洗函数把所有代码块标记剥掉，问题就没了。

6.3 并发一高就被限流

批量处理几十页PDF，我一开始用线程池一口气并发几十个请求，结果每隔几秒就报限流错误。这时候才意识到，模型接口不是无限并发，账号有QPS限制。排查链路是这样的：先看错误码，如果包含限流相关标识，就去控制台看账号的并发配额，再回头改造代码。

我的做法很简单，用一个Semaphore把并发数限制到3，同时给每次调用加一个简单的重试机制：

import java.util.concurrent.Semaphore; public class LimitedCaller { private final Semaphore semaphore = new Semaphore(3); public String safeCall(String base64, String prompt) throws Exception { semaphore.acquire(); try { return new QwenVisionClient(apiKey).call(base64, prompt); } finally { semaphore.release(); } } }

指数退避重试也顺手加上了，第一次失败等2秒，第二次等4秒，最多重试三次。这样批量跑下来基本不会再触发限流。

6.4 重复表头和跨页拼接

第一版导出Excel时发现，每个页面都有表头，导出结果里表头重复了好几遍。原因是提示词只说了“提取表格”，没说清楚下一页如果没有表头该怎么处理。改造方法是加上hasHeader字段，加上明确指令“如果当前页面没有表头，headers返回空数组”。这样ExcelWriter就只需要在hasHeader为true时才创建表头行，重复表头问题一下就解决了。

6.5 性能瓶颈不在模型在图片渲染

跑全量的时候发现速度比预期慢，排查了一圈才发现瓶颈不在调用模型，而在PDFBox渲染那一层。每页渲染300DPI、再把PNG写到磁盘，这一套在低配机器上要花不少时间。优化方式很简单：不需要落盘就直接把BufferedImage转成字节数组做Base64，省掉临时文件IO。另外用parallelStream按页并发渲染也能明显提速，但注意控制线程数，太狠了同样会把内存吃爆。

7. 工程化落地与扩展方向

7.1 封装成可复用的处理器

不要把核心逻辑散落在Main方法里。我建议拆成几个类各管一段：PdfPageRenderer负责渲染、QwenVisionClient负责模型调用、TableData负责数据结构、ExcelWriter负责输出、最外层的PdfToExcelService负责编排。这样将来换模型、改提示词、加缓存，都不需要动其他代码。

服务层的编排逻辑也很简单：

public interface PdfToExcelService { File convert(File pdfFile) throws Exception; }

实现类里做四件事：遍历页码、逐页渲染、调用模型识别、把每页的TableData收集起来传给ExcelWriter。如果某页识别失败，记录日志并继续下一页，不要因为一页失败就把整个文件挂掉。

7.2 做成Spring Boot接口

如果要做成Web服务，建议提供一个异步接口。原因是模型调用是耗时的，同步接口会让HTTP连接长时间挂着，用户体验很差，也容易触发网关超时。提交任务后返回一个taskId，后台线程池跑解析，前端轮询任务状态，解析完成后通过文件下载接口拿结果。这个模式对大批量文件处理非常重要。

任务状态可以用一个简单的Map维护，生产环境换成数据库表或者Redis都行。注意线程池要单独配置，不要直接用Tomcat的请求线程去跑模型调用，不然请求一多线程池直接被打满。

7.3 后续可以继续优化的点

这套方案其实还有不少扩展空间。比如加一个页面级缓存，用图片MD5做key，重复文件直接命中缓存，成本能进一步压缩。再比如引入一个校验步骤，让模型同时输出每个表格的近似行数，和实际解析出的行数对比，超过阈值就自动重试。还有就是把模型输出直接转成Excel之前，先做一次字符串清洗，把单元格里不必要的换行、空白字符去掉，让Excel数据更干净。

我之前还试过一种混合方案：先用PDFBox尝试抽取文本层，如果有文本层就优先用传统坐标方式解析，只有解析结果看起来不可靠时，再调用模型重新识别。这样做的好处是传统方案处理简单PDF非常快且便宜，模型只处理疑难页。如果你们的PDF样本量特别大，这个方法值得研究。

一些实际操作上的体会

这套流程调通之后，我最大的感受是：这类需求的技术难点早就不是“解析PDF”本身了，而是怎么把大模型的输出变成稳定可靠的数据流。PDFBox和POI都是很成熟的东西，真正的变数在模型返回质量、边界情况和异常处理上。所以我给所有想抄作业的人一个建议：先把提示词和异常处理当成一等公民，它们比渲染代码更值得花时间。

另外分享两个小技巧。一个是渲染图片时如果发现页面方向不对，表格是横着排的，而模型没能正确识别，可以在渲染后对BufferedImage旋转90度再发送，很多识别失败其实是方向问题，不是模型能力问题。另一个是批量处理时记录每个PDF的成功页数，方便在最终Excel里插入一列来源页码，这样数据出问题后回溯也容易。

如果你也正在处理一堆PDF表格，这个思路值得一试。控制好成本，别硬刚一套解析规则吃到老，换条路往往更快。