我在做项目时遇到过一个很现实的痛点：业务方丢过来一堆扫描版表格，里面有成绩单、订单明细、财务报表，要求系统自动把里面的数据抽出来，还得能落到 Excel 里给客户下载。光做文字 OCR 远远不够，因为表格的难点在于"结构"，一行一列怎么对、跨行跨列怎么合并，都比单纯识别一串字符麻烦得多。当时我选了 Java + PaddleOCR 这条技术路线，跑通之后效果不错，还能直接导出 HTML 和 Excel。这篇文章就把这套方案完整拆开讲一遍，包括 Python 侧的识别服务怎么封装、Java 侧怎么调用和解析、HTML 和 Excel 导出的细节，以及我在真实项目里踩过的坑。
这篇内容适合有 Java 后端基础、想在自己的系统里集成表格识别能力的开发者。不管你是要做合同识别、票据结构化，还是想把老旧纸质表格电子化，都可以参考这套实现思路。
1. 为什么"Java + 表格识别"这么折腾：先想清楚方案再动手
1.1 表格识别重点不是 OCR，而是恢复结构
先说清楚一个概念：常规 OCR 解决的是"图里有哪几个字"，表格识别解决的是"这些字分别属于哪一行哪一列"。比如下面这张成绩表：
| 学号 | 姓名 | 语文 | 数学 | 总分 |
|---|---|---|---|---|
| 001 | 张三 | 90 | 95 | 185 |
| 002 | 李四 | 88 | 92 | 180 |
如果只做 OCR，拿到的是一堆散落的文字："学号""姓名""001""张三"……你根本不知道"张三"是姓名列还是语文列。表格识别要做两件事：第一，检测出表格区域；第二，根据表格线或者行列分布，把每个单元格的文字映射到对应的行和列上。PaddleOCR 的 PP-Structure 系列模型做的就是这个事，它输出的标准格式是一段 HTML 表格，里面有<table>、<tr>、<td>这些结构化标签，数据天然就是对齐的。
这也是我为什么在标题里强调"支持导出 HTML 和 Excel"。HTML 是 PaddleOCR 表格识别结果的天然载体，拿到 HTML 之后，转 Excel 只是另一层解析工作。整个链路其实是：图片 → 表格结构识别 → HTML → Excel。
1.2 Java 集成 PaddleOCR 的三条路线对比
PaddleOCR 官方主力语言是 Python，Java 生态里没有官方维护的、同样好用的表格识别 SDK。所以"Java 怎么调 PaddleOCR"这个问题，本质上是一个跨语言集成问题。我梳理过三条路线，各有优劣：
| 方案 | 实现方式 | 优点 | 缺点 | 适合场景 |
|---|---|---|---|---|
| REST 服务 | Python 封装识别服务，Java 通过 HTTP 调用 | 语言解耦，模型常驻内存，识别快 | 需要多部署一个 Python 服务 | 生产环境首选 |
| 本地进程调用 | Java 用 ProcessBuilder 启动 Python 脚本 | 不需要额外服务 | 每次启动 Python 解释器代价大，模型重复加载 | 一次性脚本、离线工具 |
| JNI/JavaCPP 直调 | 通过 JNI 绑定 C++ 推理库 | 性能最高 | 编译复杂，依赖不好维护 | 极少见，不推荐 |
我最终选了 REST 服务方案，核心考量有三个。第一，模型首次加载要好几秒，如果每次识别都重新加载一次，体验完全不可接受；REST 方案里 Python 进程常驻，模型只加载一次，后续请求只花推理时间。第二，Java 和 Python 通过 HTTP + JSON 通信，数据结构一目了然，出了问题时也好排查。第三，后续如果要把识别服务拆分出去、水平扩容，REST 天然支持。
2. 搭建识别服务：Python 侧把 PaddleOCR 包装成可用接口
2.1 环境安装与模型下载（含 GPU 版本选择）
先说安装。PaddleOCR 3.x 之后的版本体验好了很多，核心就一个命令：
pip install paddleocr如果你要用 GPU 推理，需要先安装匹配 CUDA 版本的 paddlepaddle-gpu：
# CUDA 11.8 示例 python -m pip install paddlepaddle-gpu==3.0.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu118/这里有个很关键的教训：GPU 版本必须和本机 CUDA 版本匹配，否则安装好后一跑就报错。我之前在一台 CUDA 版本是 12.0 的机器上强行装了 cu118 的包，运行时报了一堆算子不匹配的错误，查了半天才发现是版本不匹配。
装完之后，第一次加载模型时 PaddleOCR 会从官方模型仓库自动下载模型文件。如果下载速度不理想，可以设置环境变量把模型下载源指到国内镜像，或者手动把模型文件放到本地的 paddle 缓存目录。缓存目录一般在用户目录下的.paddlex/official_models里，手动放模型的时候注意按模型名建目录，目录名必须和默认一致，否则识别不到。
建议第一次做的时候先用 CPU 版本把整条链路跑通，确认识别结果没问题之后，再考虑上 GPU。CPU 版在普通服务器上识别一张表格大概 1-3 秒，GPU 能压缩到几百毫秒，但引入的依赖复杂度一下子高很多。链路通了之后再优化性能，是我比较推荐的做法。
2.2 Flask 接口封装与返回结构约定
我用 Flask 做了一个极简的识别接口。核心逻辑不多，最要紧的是模型全局唯一，不能每次请求都PPStructureV3()一次，否则模型重复加载，接口必然超时。
# -*- coding: utf-8 -*- from flask import Flask, request, jsonify from paddleocr import PPStructureV3 import os import uuid app = Flask(__name__) engine = None def get_engine(): global engine if engine is None: engine = PPStructureV3(table=True, ocr=True, lang='ch') return engine @app.route('/table/recognize', methods=['POST']) def recognize(): file = request.files.get('image') if file is None: return jsonify({'code': 400, 'msg': 'image is required'}) suffix = os.path.splitext(file.filename)[-1] tmp_path = f'/tmp/{uuid.uuid4().hex}{suffix}' file.save(tmp_path) try: result = get_engine().predict(tmp_path) tables = extract_tables(result) return jsonify({'code': 0, 'tables': tables}) except Exception as e: return jsonify({'code': 500, 'msg': str(e)}) finally: if os.path.exists(tmp_path): os.remove(tmp_path) if __name__ == '__main__': app.run(host='0.0.0.0', port=8866, debug=False)这里有个细节大家务必注意，debug=False不能省。Flask 的 debug 模式会启动两个进程（一个 reloader 进程 + 一个业务进程），模型会被加载两次，既占资源又容易出奇怪问题。我第一次联调时就是开着 debug，结果发现显存直接翻倍，排查了很久才反应过来。
2.3 解析不同版本 PPStructure 输出的兼容技巧
PPStructureV3的返回结构在不同版本里不太一样。有的版本直接能拿到region['res']['html']，有的版本 res 字段嵌套层级不同，还有的版本字段名从rec变成了别的名字。如果你照着网上旧教程写解析代码，很可能在新版本上拿到空结果。
我写了一个递归遍历函数来兼容这种情况，核心思路是把整个返回结果当成一棵树，深度优先查找type == 'table'的节点，再去它的res下面找html字段：
def extract_tables(result): tables = [] def walk(node): if isinstance(node, dict): if node.get('type') == 'table': res = node.get('res') if isinstance(res, dict): html = res.get('html') if html: tables.append({ 'html': html, 'score': node.get('score', 1.0) }) for v in node.values(): walk(v) elif isinstance(node, list): for item in node: walk(item) walk(result) return tables递归遍历的好处是：不管返回结构怎么变，只要table节点上带着html，就能被找出来。我在真实项目里拿这个函数兼容过 PaddleOCR 2.x 和 3.x 两套输出，基本不用改。
这个 Python 服务跑起来之后，你可以先用 curl 快速验证：
curl -X POST http://localhost:8866/table/recognize \ -F "image=@test_table.png"看到返回 JSON 里有html字段，说明识别服务已经通了，接下来就是 Java 侧的事了。
3. Java 侧调用：上传图片、拿回 HTML
3.1 Spring Boot 项目的 HTTP 调用封装
Java 侧我用 Spring Boot 标准做法：接收前端上传的图片，然后调用 Python 识别服务，把结果里的 HTML 解析出来。调用 Python 服务这一层，我用RestTemplate就够用：
@Service public class TableRecognizeService { private final RestTemplate restTemplate = new RestTemplate(); public List<String> recognizeTable(MultipartFile file) throws IOException { // 构造 multipart 请求体 HttpHeaders headers = new HttpHeaders(); headers.setContentType(MediaType.MULTIPART_FORM_DATA); // 注意：这里用 LinkedMultiValueMap，保证文件字段名和 Python 端 request.files.get('image') 对应 LinkedMultiValueMap<String, Object> body = new LinkedMultiValueMap<>(); body.add("image", new ByteArrayResource(file.getBytes()) { @Override public String getFilename() { return file.getOriginalFilename(); } }); HttpEntity<LinkedMultiValueMap<String, Object>> requestEntity = new HttpEntity<>(body, headers); ResponseEntity<Map> response = restTemplate.postForEntity( "http://localhost:8866/table/recognize", requestEntity, Map.class); Map<String, Object> responseBody = response.getBody(); if (responseBody == null || !Integer.valueOf(0).equals(responseBody.get("code"))) { throw new RuntimeException("识别服务调用失败: " + responseBody); } @SuppressWarnings("unchecked") List<Map<String, Object>> tables = (List<Map<String, Object>>) responseBody.get("tables"); List<String> htmlList = new ArrayList<>(); for (Map<String, Object> table : tables) { htmlList.add((String) table.get("html")); } return htmlList; } }这段代码的核心点是把图片转成ByteArrayResource塞进 multipart 请求体，字段名image要和 Python 端的request.files.get('image')严格对应。很多人第一次联调失败，就是因为字段名对不上，Python 端收到None。
3.2 HTML 落地与文件命名规范
拿到 HTML 之后，可以直接落盘。PaddleOCR 返回的 HTML 是完整的<html><body><table>...</table></body></html>结构，保存的时候务必用 UTF-8 编码，否则中文会出现乱码：
public void saveHtml(String html, String outputDir, String fileName) throws IOException { Files.createDirectories(Paths.get(outputDir)); Path path = Paths.get(outputDir, fileName + ".html"); Files.write(path, html.getBytes(StandardCharsets.UTF_8)); log.info("HTML saved to {}", path); }文件命名我建议带上业务 ID 和时间戳，例如order_20250101_1001.html，不然并发识别时很容易互相覆盖。如果有一次识别多页的需求，建议在后面追加页码后缀_page1、_page2，和 Python 服务返回的多张表对应。
3.3 联调时最容易踩的拦路坑
第一个坑是图片上传大小限制。Spring Boot 默认 multipart 文件大小限制是 1MB，扫描件动辄几 MB，很容易在还没进入业务逻辑之前就被拦截了。需要在application.yml里调大：
spring: servlet: multipart: max-file-size: 20MB max-request-size: 20MB第二个坑是超时设置。RestTemplate默认没有超时时间，如果 Python 服务卡住，Java 线程会一直挂着，久而久之线程池就满了。我建议显式设置连接超时和读取超时：
SimpleClientHttpRequestFactory factory = new SimpleClientHttpRequestFactory(); factory.setConnectTimeout(5000); // 连接超时 5 秒 factory.setReadTimeout(30000); // 读取超时 30 秒 RestTemplate restTemplate = new RestTemplate(factory);识别一张复杂大表可能要跑 5-10 秒，读取超时设 30 秒比较稳妥。
第三个坑是响应体直接反序列化成Map时类型丢失。PaddleOCR 返回的html里包含大量<、>、/这些字符，如果 JSON 序列化时没有处理好特殊字符，Java 端收到之后解析会报错。我在 Python 端的jsonify已经处理过转义，Java 这边的RestTemplate默认用 Jackson 处理，正常情况下没问题。如果你用了其他 HTTP 库，建议响应体先拿原始字符串，再手动转 JSON，一步到位避免坑。
4. 从 HTML 到 Excel：表格数据提取与写入
4.1 用 Jsoup 提取 table 结构（含合并单元格处理）
拿到 HTML 之后，接下来的任务就是把它转成 Excel。这里有两个选择：一是把 HTML 原样塞进 Excel（用 POI 的 HtmlDocumentFacade），二是先用 Jsoup 解析表格，把行列数据抽出来，再写入 Excel。我强烈建议用第二种方式，因为这样你可以控制表头样式、列宽、合并单元格，做出来的 Excel 干净整洁。
Jsoup 解析的核心目标是：把<table>里的每一行每一列变成二维数据。麻烦在于合并单元格，因为<td colspan="2">和<td rowspan="2">会导致同一行的单元格数量不一致，如果只是简单遍历tr > td，后面的列会错位。
我的做法是维护一个"已占位矩阵"，模拟渲染表格的过程：
public static List<List<String>> parseHtmlTable(String html) { Document doc = Jsoup.parse(html); Element table = doc.selectFirst("table"); if (table == null) { throw new IllegalArgumentException("no table found in html"); } Elements rows = table.select("tr"); List<List<String>> data = new ArrayList<>(); boolean[][] occupied = new boolean[rows.size()][32]; // 假设最多32列，可根据图片调整 for (int r = 0; r < rows.size(); r++) { Elements cells = rows.get(r).select("th, td"); List<String> rowData = new ArrayList<>(); int colIndex = 0; for (Element cell : cells) { // 跳过被 rowspan 占用的位置 while (colIndex < occupied[r].length && occupied[r][colIndex]) { colIndex++; } int colspan = parseAttr(cell, "colspan"); int rowspan = parseAttr(cell, "rowspan"); String text = cell.text().trim(); // 占位：标记后续行/列被合并单元格占用 for (int i = 0; i < colspan; i++) { for (int j = 0; j < rowspan; j++) { if (r + j < occupied.length && colIndex + i < occupied[r].length) { occupied[r + j][colIndex + i] = true; } } } rowData.add(text); colIndex += colspan; } data.add(rowData); } return data; } private static int parseAttr(Element cell, String attr) { String val = cell.attr(attr); if (val == null || val.isEmpty()) { return 1; } try { return Math.max(1, Integer.parseInt(val)); } catch (NumberFormatException e) { return 1; } }这段逻辑其实就是"按浏览器渲染表格的规则回放一遍"，先把合并单元格占用的位置标记出来，后面的单元格自然就能排到正确位置。代码不算复杂，但效果很稳，我拿它处理过带大量合并单元格的报销单，列对齐基本不会错。
4.2 用 POI 写入 xlsx 并处理合并区域
数据提取出来之后，写入 Excel。我这里用 Apache POI 的 XSSFWorkbook，因为 EasyExcel 在处理合并单元格和样式时不够灵活：
public static void exportToExcel(List<List<String>> tableData, String outputPath) throws IOException { XSSFWorkbook workbook = new XSSFWorkbook(); XSSFSheet sheet = workbook.createSheet("识别结果"); // 表头样式：加粗、灰色背景 CellStyle headerStyle = workbook.createCellStyle(); Font headerFont = workbook.createFont(); headerFont.setBold(true); headerStyle.setFont(headerFont); headerStyle.setFillForegroundColor(IndexedColors.GREY_25_PERCENT.getIndex()); headerStyle.setFillPattern(FillPatternType.SOLID_FOREGROUND); int rowIndex = 0; for (List<String> rowData : tableData) { XSSFRow row = sheet.createRow(rowIndex); for (int col = 0; col < rowData.size(); col++) { XSSFCell cell = row.createCell(col); cell.setCellValue(rowData.get(col)); if (rowIndex == 0) { cell.setCellStyle(headerStyle); } } rowIndex++; } // 合并单元格：根据第一个单元格内容判断哪些位置应该是跨行跨列的（示例略） // sheet.addMergedRegion(new CellRangeAddress(0, 1, 0, 1)); // 列宽自适应（粗略处理：按第一行数据长度设置） for (int col = 0; col < tableData.get(0).size(); col++) { sheet.autoSizeColumn(col); } try (FileOutputStream fos = new FileOutputStream(outputPath)) { workbook.write(fos); } workbook.close(); }关于autoSizeColumn有个提醒：数据量大的时候，这个方法会遍历每一列的所有行计算宽度，比较耗时；而且它对中文宽度的估算有时候不准，会显得列宽偏窄。建议最后统一做一次列宽度设置，比如按最大值加个 padding。
合并单元格的处理，如果你希望 Excel 里保留 HTML 里colspan/rowspan的样式，可以在解析parseHtmlTable的同时，额外记录每个单元格的合并信息（起始行、起始列、跨行数、跨列数），然后调用sheet.addMergedRegion(new CellRangeAddress(...))对应合并。我一般会把合并信息封装到一个CellSpan对象里，一并返回，这样数据和样式都不丢。
4.3 导出的常见问题：换行、特殊符号、公式注入
这里有几个坑是"你不遇到一次，根本不会想到"的问题。
换行符问题：OCR 识别出来的文本里经常有换行符，尤其是单元格里有多行内容的场景。直接写进 Excel 的话，需要把单元格的换行样式打开，否则文本虽然有换行符号，显示时却是连续的：
CellStyle wrapStyle = workbook.createCellStyle(); wrapStyle.setWrapText(true); cell.setCellStyle(wrapStyle);如果你根本不想要换行，可以在写入前用text.replaceAll("\\s+", " ").trim()把多余的空白压掉。具体场景具体处理，如果是保留原格式的，就开启 wrapText；如果是做数据入库的，就压成单行。
公式注入问题：如果字段值是以=、+、-、@开头的字符串，写入 Excel 时可能被当成公式执行，轻则显示错误，重则有注入风险。比如某个单元格内容恰好是=1+1，POI 会把它按公式处理，导出后在 Excel 里显示2而不是=1+1。处理方式是，凡是读取到的文本以这些字符开头，我都在前面加一个单引号：
String cellValue = text; if (text.startsWith("=") || text.startsWith("+") || text.startsWith("-") || text.startsWith("@")) { cellValue = "'" + text; }这在处理财务报表、订单明细这类数据时尤其重要，因为原表格里完全可能出现-10%或者+0.5这样的值。
空行空列问题：PaddleOCR 识别出的表格，偶尔会在行数据里夹带空行。我在写入 POI 之前会先过滤掉全为空字符串的行，避免导出后出现大量空白行，客户体验很差。
5. 真实项目中的性能调优与部署建议
5.1 模型常驻、连接复用与超时控制
识别性能的第一瓶颈在 Python 侧的模型常驻问题。千万不能在每次请求里创建PPStructureV3实例，模型的权重加载和引擎初始化可能要好几秒，必须全局复用。我上面给的 Flask 代码里用了单例模式，就是为了保证模型只初始化一次。
Java 侧并发调用时要注意控制请求速率。如果同一个 Python 服务实例同时处理 10 个请求，Flasks 自带的多线程模型会在模型推理层产生排队，而且显存占用会成倍增加。我当时用了一个简单的信号量控制并发数：
private final Semaphore semaphore = new Semaphore(4); // 最多同时4个识别请求 public List<String> recognizeTable(MultipartFile file) throws Exception { semaphore.acquire(); try { return doRecognize(file); } finally { semaphore.release(); } }这样既能充分利用 GPU，又不至于把服务打挂。如果压测发现 4 个并发还是不够，优先加 Python 服务实例，而不是无限调大并发数。
5.2 图片压缩与分块识别
PaddleOCR 对输入图片的尺寸有推荐范围，最长边 960-1920 像素是效果比较好的区间。但实际业务里，扫描件的分辨率经常是 300dpi、4000×3000 像素这种级别。直接把原图喂进去，结果就是推理时间暴增、显存吃紧，甚至直接 OOM。
我的处理策略是：在调用 Python 服务之前，Java 侧先对图片做一个预处理：
public static BufferedImage resizeIfTooLarge(BufferedImage src, int maxSide) { int width = src.getWidth(); int height = src.getHeight(); int longestSide = Math.max(width, height); if (longestSide <= maxSide) { return src; } double scale = (double) maxSide / longestSide; int targetWidth = (int) (width * scale); int targetHeight = (int) (height * scale); BufferedImage resized = new BufferedImage(targetWidth, targetHeight, BufferedImage.TYPE_INT_RGB); Graphics2D g = resized.createGraphics(); g.drawImage(src, 0, 0, targetWidth, targetHeight, null); g.dispose(); return resized; }最长边限制在 2000 左右，识别精度几乎不受影响，但速度能快好几倍。如果原图里包含多张表格、需要分块识别的场景，可以先做版面切分，再把每一块单独送入识别服务。这个方案比较复杂，一般需求用不到，我这里只提一个思路。
5.3 生产部署：容器化与 GPU 调度
Python 识别服务和 Java 应用在生产环境通常是两个独立部署单元。Java 应用继续走原来的发布流程，Python 服务用 Docker 单独部署。我用的 Dockerfile 大致长这样：
FROM paddlepaddle/paddle:3.0.0-gpu-cuda11.8-cudnn8.6-trt8.5 RUN pip install paddleocr flask WORKDIR /app COPY app.py . EXPOSE 8866 CMD ["python", "app.py"]如果只用 CPU，基础镜像可以直接选python:3.10-slim，然后pip install paddleocr就行。GPU 服务部署时注意给容器透传 GPU：
docker run -d --gpus all -p 8866:8866 table-ocr-service生产环境建议在 Python 服务前面加一层 gunicorn + gevent 或多 worker，避免 Flask 自带的开发服务器扛不住并发。我实际验证过 gunicorn 配置：
gunicorn -w 2 -b 0.0.0.0:8866 -t 120 app:app这里-w的 worker 数量要结合显存来定，一个 worker 加载一份模型，显存里的占用是叠加的。2GB 显存跑一个 worker 都紧巴巴的，8GB 显存开 2 个 worker 比较稳妥。worker 太多导致显存溢出，是部署阶段最容易踩的坑。
6. 我踩过的坑和现在的稳定用法
最后把这些年用 PaddleOCR 做表格识别实践里踩过的坑做个集中梳理，希望能帮大家省下一些排查时间。
模型版本锁定，不要盲目追新。PaddleOCR 迭代速度很快，小版本升级也可能带来 API 变化。线上服务建议把版本号固定下来：
pip install paddleocr==3.0.0如果你用的是 2.x 的老项目，也不要轻易升级到 3.x，因为底层调用链完全变了。模型文件也一样，建议下载到本地保存一份，不要依赖运行时自动下载。我遇到过服务器重装之后，模型自动下载失败导致服务起不来的情况，后来就改成每次部署时把模型目录整个打包带走。
识别结果一定要人工抽检。PaddleOCR 的表格识别准确率在规整的印刷表格上很高，但遇到复杂表头、竖排文字、手写体、模糊扫描件时，仍然会有结构错位和文字识别错误。我的建议是：在系统里加一个"人工复核"环节，识别完成后把 HTML 渲染成预览图，让业务人员快速过一遍；或者抽样比对几个关键字段。不要盲目相信 OCR 的准确率，尤其是财务报表这种错一个数字影响很大的场景。
HTML 里的样式信息要注意过滤。PaddleOCR 生成的 HTML 里除了<table>结构，还包含大量的内联样式，比如单元格的边框、字体、背景色等。如果你只是需要数据，直接把这些样式丢掉就行，Jsoup 解析时只取text()天然会忽略标签和样式。如果你要还原原表格的视觉样式，那就要把 style 解析出来，这个工作量会大很多。我一般默认只导出数据，样式层面的需求需要单独跟业务方确认。
现在我在项目里的稳定用法是这样的：Java 应用通过 Spring Boot 对外提供上传接口，图片先压缩到最长边 2000 像素以内，再通过 RestTemplate 调用 Python 识别服务；Python 服务用 PPStructureV3 单例模型做表格识别，返回 JSON 里的 HTML 字段；Java 拿到 HTML 后先落一份原始 HTML 存档，再用 Jsoup 解析出表格数据和合并单元格信息，最后用 POI 写入带样式的 xlsx。整条链路里，最容易出问题的地方反而不是 OCR 本身，而是两个服务之间的字段约定和文件传输格式，所以联调时一定要先约定好接口文档，再动手写代码。
这套方案在普通的 2 核 4G 服务器上，CPU 模式单张表格识别时间在 1-3 秒，上了 GPU 之后基本能控制在 500 毫秒以内。对于大多数内部系统来说，已经完全够用了。如果你也在做类似的需求，可以直接照着这套架构搭一遍。
