企业官网建设流程全解析

扫描版PDF转文字版PDF，听起来是个很常见的需求，但真做起来坑不少。最近我拿本地的开源编码模型omnicoder-9b辅助写了一个Python小工具，把整条流程跑通了：输入一个扫描版PDF，输出来的PDF既能保持原页面视觉不变，又能复制、搜索、选中文字。整个过程不复杂，核心就是OCR识别加文字层覆盖，难就难在坐标映射和不可见文本层这两个细节上。这篇文章把完整方案、完整代码、踩过的坑都摊开讲一遍，适合有点Python基础、又经常跟扫描件打交道的人。

1. 需求拆解与整体设计思路

1.1 扫描版PDF和文字版PDF的本质区别

先把问题说透。扫描版PDF说白了就是把纸面内容用扫描仪或手机拍下来，每一页其实是一张图片，然后打包成PDF。你打开它看到的"文字"是图像里的像素，不是真正的字符。所以遇到这种PDF，搜索关键词搜不到，选中文字复制也不可行，想在批注里引用一句话只能自己手打。这是最让人抓狂的地方。

文字版PDF就完全不同了，它里面有一个文本层，文字是真实存在的字符对象。像Word导出的PDF、浏览器打印的PDF都属于这类，搜索、复制、朗读都顺畅。我们这次的目标不是把扫描件重排成新文档，而是给原来的扫描图片加一层"看不见但可以被检索"的文字，让两种优点兼得：视觉上还是原汁原味的扫描页面，操作上变成真正的电子文档。

为什么强调"保留原图"？因为很多扫描件包含印章、手写批注、复杂排版，如果直接用OCR结果重排PDF，版面大概率会乱掉，表格错位、图文乱跑都是家常便饭。叠加透明文字层的思路就像给图片加蒙版，原图是底，文字是透明的上层，两者重合后就达到了"看起来没变、实际能选"的效果。

1.2 技术选型：PyMuPDF + PaddleOCR 的组合

我一开始在OCR引擎和PDF处理库上犹豫了一段时间，试过几个组合后，最终锁定了PyMuPDF加PaddleOCR。

先看OCR引擎的对比，这个环节直接决定识别准不准：

再看PDF处理库。pdf2image依赖系统级的poppler工具，而且它只管把PDF渲染成图片，生成PDF还得再搭配reportlab。这样中间环节多，坐标来回转换很容易出错。PyMuPDF（即fitz）一个库就能搞定全部：渲染页面为图像、读取PDF、写入文本层、保存新文件，全程不依赖外部系统命令，处理速度和文件控制也更好。所以选它没悬念。

1.3 借助omnicoder-9b生成代码的策略

这个项目不全是自己手写的，很大一部分代码是让omnicoder-9b生成的。它是个开源编码模型，专注于代码理解和生成，我平时本地跑着当编程助手用。当时给它提的需求大概长这样：

写一个Python脚本，输入扫描版PDF路径，输出文字版PDF。要求：保留原始页面图像作为背景，使用PaddleOCR识别中英文，将识别出的文字以不可见文本层写入原PDF页面，坐标需要从渲染图像映射回PDF页面坐标。依赖使用pymupdf和paddleocr，脚本需要支持命令行参数。

模型很快给出了一版能跑的代码，但它最初没有处理坐标映射细节，直接把OCR返回的像素坐标用在了PDF上，文字位置全偏了。这就是AI辅助编程最典型的场景：大方向它帮你省很多事，但核心的坐标系转换、渲染模式这些关键细节还得人类盯。

实际协作流程我总结成四步：第一步，把完整需求描述清楚，包括输入输出、技术栈、约束条件；第二步，让AI生成初版代码，不要求一步到位；第三步，自己审查关键逻辑，特别是坐标换算、文本可见性参数、内存使用；第四步，把运行报错原样贴回给AI迭代修复。整个过程中，项目本身的思路不能靠模型替你思考，但写代码、查API、修bug这种事，确实快很多。

2. 环境准备与模型初始化

2.1 创建虚拟环境和安装依赖

老规矩，先建独立环境，别把系统Python搞乱了。我用的是Python 3.10，建议3.9以上，太老的版本对PaddleOCR不友好。

python -m venv ocr-env source ocr-env/bin/activate # Windows系统执行 ocr-env\Scripts\activate pip install --upgrade pip pip install paddlepaddle paddleocr pymupdf numpy

这里有两个需要注意的地方。

第一，paddlepaddle和paddleocr的版本要匹配。有一次我装了新版PaddleOCR后没升级PaddlePaddle，运行时报了一堆"找不到算子"的异常，后来把两个库一起升级到最新版才好。建议直接pip安装时不要手欠加版本号，让pip自己解析。

第二，如果你的电脑有NVIDIA显卡，想用GPU加速，那就把paddlepaddle换成paddlepaddle-gpu。但CPU版本也不是不能用，只是识别速度慢一些。我实测下来，一个普通A4页面在CPU上大概跑2到4秒，批量处理几百页也能忍。

安装完可以用一行命令验证库是否可用：

python -c "import fitz; print(fitz.__doc__)" python -c "from paddleocr import PaddleOCR; print('OK')"

2.2 首次运行：模型下载与验证

PaddleOCR第一次运行时会在用户目录下自动下载三个模型文件：检测模型、方向分类模型、识别模型，体积加起来大概一百多兆。下载速度取决于网络，完成后存放在~/.paddleocr/目录下。

我建议第一次先拿一张带文字的图片直接验证识别是否正常，别一上来就处理整个PDF。快速验证代码：

from paddleocr import PaddleOCR ocr = PaddleOCR(use_angle_cls=True, lang="ch", show_log=False) result = ocr.ocr("test.png", cls=True) for line in result[0]: box, (text, score) = line print(text, round(score, 4))

如果能打印出文字和置信度，说明环境通了。这里lang="ch"表示简体中文加英文混排识别，如果你的扫描件是纯英文，也可以改成lang="en"，但一般ch也能兼容英文。

注意：如果模型下载失败，检查一下网络，或者到PaddleOCR官方仓库手动下载模型文件放到~/.paddleocr/对应目录下，不用反复重新拉。

3. 核心代码实现：三步完成PDF改造

整个转换过程拆成三步：渲染PDF页面为图像、OCR识别、把识别结果写入原页面。下面一节一节说清楚。

3.1 第一步：渲染PDF页面为图像

扫描版PDF每一页本身就是一张图片，但我们要通过PDF渲染接口把它转成OCR能处理的图像格式是因为有些扫描页还会带一些矢量元素、水印、注释，直接渲染能保证OCR看到的就是用户最终看到的完整页面。

渲染分辨率是关键。PDF的标准分辨率是72DPI，也就是zoom系数为1.0时，页面上的图形和文字会按原始尺寸输出。但对OCR来说72DPI太低了，笔画都糊在一起。实测下来zoom取3.0（即216DPI）效果比较理想，识别率能上去，渲染时间也可接受。如果是特别小或者特别花的字，可以再往上调到4.0。

import fitz def render_page_to_image(page, zoom=3.0): """将PDF页渲染为numpy数组图像""" mat = fitz.Matrix(zoom, zoom) pix = page.get_pixmap(matrix=mat) import numpy as np img = np.frombuffer(pix.samples, dtype=np.uint8).reshape(pix.height, pix.width, pix.n) if pix.n == 4: # RGBA转RGB img = img[:, :, :3] return img, zoom

这里有个细节：pix.n是像素通道数，可能为1（灰度）、3（RGB）、4（RGBA）。PaddleOCR要求输入是三通道RGB，所以遇到4通道必须舍掉alpha通道，否则后面会报形状错误。

3.2 第二步：OCR识别与坐标映射

渲染出图像后，调用PaddleOCR识别：

result = ocr.ocr(img, cls=True)

返回结果的结构是外层列表对应图像，内层每个元素是[box, (text, score)]。其中box是一个4x2的数组，表示文本框四个角点的坐标，顺序是左上、右上、右下、左下。text是识别出的字符串，score是置信度。

到这里最关键的坑就来了：box坐标是相对于渲染图像的像素坐标，而PDF页面坐标是另外一套体系。虽然PyMuPDF的页面坐标也是以左上角为原点、Y轴向下，但单位不是像素，而是PDF点（1点=1/72英寸）。渲染图像时我们用了zoom倍的缩放，所以像素坐标转PDF坐标只需要简单除以zoom：

# box的四个点分别对应左上、右上、右下、左下 xs = [p[0] for p in box] ys = [p[1] for p in box] x_min, x_max = min(xs), max(xs) y_min, y_max = min(ys), max(ys) # 转成PDF页面坐标 pdf_x = x_min / zoom pdf_y = y_min / zoom pdf_w = (x_max - x_min) / zoom pdf_h = (y_max - y_min) / zoom

注意y方向不需要翻转。因为PyMuPDF渲染图像时，图像第一行对应页面顶部，而页面操作的坐标原点同样在左上角，两者方向一致，直接除以缩放系数即可。这个映射关系如果搞错，生成的文字层就会整页跑偏。

3.3 第三步：写入不可见文字层

文字层最优雅的实现方式是使用fitz.TextWriter，它能把文本逐个插入到页面上，并且支持render_mode参数。PDF规范里render_mode=3代表"不可见文本"，也就是文字只存在于内容流中，不实际渲染到视觉效果上，但可以被搜索和复制。

def add_invisible_text_layer(page, ocr_result, zoom): writer = fitz.TextWriter(page.rect) font = fitz.Font("china-s") # PyMuPDF内置简体中文字体 for item in ocr_result: box, (text, score) = item if score < 0.5: # 太低置信度的直接跳过 continue xs = [p[0] for p in box] ys = [p[1] for p in box] x = min(xs) / zoom y = min(ys) / zoom w = (max(xs) - min(xs)) / zoom h = (max(ys) - min(ys)) / zoom # 字号约等于行高的0.85倍，这是一个经验值 fontsize = h * 0.85 writer.append((x, y), text, font=font, fontsize=fontsize) writer.write_page(page, render_mode=3)

这里"字号取行高的0.85"是我调了几次得出的经验值。如果直接拿行高当字号，文字层会偏大，虽然搜索不受影响，但有些PDF阅读器在显示文本层时会对不上位置。不同字体、不同字符集会有差异，0.85到0.9这个范围内基本都能对齐。

字体选择上用fitz.Font("china-s")，这是PyMuPDF内置的简体中文字体，不需要额外引入字体文件，也省去了嵌入字体的麻烦。如果扫描件里有大量生僻字或繁体字，建议换成系统里安装的完整中文字体，比如通过fitz.Font(fontname="Noto Sans CJK SC")指定，确保字符覆盖全面。

3.4 完整脚本与命令行入口

把上面三个环节整合成一个完整可运行的脚本：

import sys import fitz import numpy as np from paddleocr import PaddleOCR ocr = PaddleOCR(use_angle_cls=True, lang="ch", show_log=False) def convert_pdf(input_pdf, output_pdf, zoom=3.0): doc = fitz.open(input_pdf) for page in doc: # 渲染页面为图像 mat = fitz.Matrix(zoom, zoom) pix = page.get_pixmap(matrix=mat) img = np.frombuffer(pix.samples, dtype=np.uint8).reshape( pix.height, pix.width, pix.n )[:, :, :3] # OCR识别 result = ocr.ocr(img, cls=True) if result and result[0]: add_invisible_text_layer(page, result[0], zoom) print(f"第 {page.number + 1} 页处理完成，识别到 {len(result[0])} 条文本") else: print(f"第 {page.number + 1} 页未识别到文字，跳过") # 保存时做优化，去掉冗余对象并压缩 doc.save(output_pdf, garbage=3, deflate=True) doc.close() print(f"转换完成，输出文件：{output_pdf}") def add_invisible_text_layer(page, ocr_result, zoom): writer = fitz.TextWriter(page.rect) font = fitz.Font("china-s") for box, (text, score) in ocr_result: if score < 0.5: continue xs = [p[0] for p in box] ys = [p[1] for p in box] x = min(xs) / zoom y = min(ys) / zoom w = (max(xs) - min(xs)) / zoom h = (max(ys) - min(ys)) / zoom fontsize = h * 0.85 writer.append((x, y), text, font=font, fontsize=fontsize) writer.write_page(page, render_mode=3) if __name__ == "__main__": if len(sys.argv) != 3: print("用法: python scan_pdf_to_text.py 输入.pdf 输出.pdf") sys.exit(1) convert_pdf(sys.argv[1], sys.argv[2])

运行方式很简单：

python scan_pdf_to_text.py 扫描件.pdf 文字版.pdf

提示：程序会逐页处理并实时打印进度，建议先用三五页的小文件试跑一次，确认输出效果后再处理几百页的大文件。

4. 常见问题与实战排查

这个工具我前后跑了不下几十次，踩了无数坑，把最典型的几个问题整理成速查表，你遇到类似情况可以直接照方抓药。

4.1 识别精度上不去怎么办

这是大家问得最多的。如果生成的文字层能搜到但错字率很高，先检查渲染的zoom系数。我见过有人用zoom=1.5识别，那精度惨不忍睹。建议至少zoom=2.0，追求效果直接上3.0以上。

其次，PaddleOCR对图片质量很敏感。老扫描件经常发黄、有噪点、对比度低，这种可以先做预处理：转灰度、再二值化或做自适应对比度增强。网上常见的做法是配合OpenCV：

import cv2 def preprocess_image(img): gray = cv2.cvtColor(img, cv2.COLOR_RGB2GRAY) # 提升对比度 thresh = cv2.adaptiveThreshold(gray, 255, cv2.ADAPTIVE_THRESH_GAUSSIAN_C, cv2.THRESH_BINARY, 11, 2) return cv2.cvtColor(thresh, cv2.COLOR_GRAY2RGB)

不过要注意，预处理不是万能的。有些手写批注很多的页面，二值化反而是灾难，手写笔迹会干扰识别。这种情况建议只做轻度的亮度对比度增强，不要暴力二值化。

4.2 竖排文字、表格、多栏版面的处理

扫描书里经常有三栏排版或竖排文字，PaddleOCR的use_angle_cls=True能解决一部分倾斜和横竖方向问题，但遇到复杂的多栏布局，它按自然阅读顺序输出的文字列表可能和你阅读顺序不一致，导致搜索结果虽然能匹配，但整段复制出来的文字顺序不对。

这种情况短期没有一劳永逸的方案。我的做法是：先识别，再用score排序，最后手动检查低置信度的部分。如果只是给自己用，顺序问题一般不影响搜索定位。表格扫描件的话，PaddleOCR有专门的PP-Structure工具做表格识别，这个后续可以单独讲，不在这个基础工具范围内。

4.3 大文件处理的性能优化

一个300页的扫描PDF，在CPU机器上跑下来可能要十到二十分钟。除了等，可以做两件事优化。

第一，用多进程。因为每页识别是独立的，可以把页面列表交给concurrent.futures.ProcessPoolExecutor并行跑。但这里有个坑：OCR模型对象不能用进程池直接共享，每个子进程需要独立加载。好在加载模型大概几秒，一次性开销能接受。

第二，合理控制zoom。同一份文件，zoom=3的识别时间可能是zoom=2的两倍多。如果扫描件本身很清晰，用zoom=2.5就够了；只有字体很小的书页才有必要上到3.0以上。实际效果跑一页对比一下再决定全局参数会更稳妥。

5. 进阶：批量处理与更多功能扩展

基础版本已经能解决单文件转换，实际使用中几个需求很常见，这里分享我的扩展思路。

5.1 批量转换整个文件夹

我处理资料的时候经常是一个目录几十个扫描PDF，一个个手敲命令不现实。可以用pathlib遍历文件夹，批量调用convert_pdf：

from pathlib import Path input_dir = Path("扫描件") output_dir = Path("文字版") output_dir.mkdir(exist_ok=True) for pdf_file in input_dir.glob("*.pdf"): output_file = output_dir / f"{pdf_file.stem}_text.pdf" convert_pdf(str(pdf_file), str(output_file))

如果想让AI帮手补充"处理进度条""日志记录""失败重试"这些功能，直接把这段话作为新需求丢给编码模型，它一般能改出可用的版本。

5.2 整段文字层之外，还可以做哪些增强

目前方案是OCR结果全覆盖式的文字层，还可以按需调整文字层的显示模式。比如有些场景希望文字层在复制时保留段落换行，那append时判断同一行的高度差来加入换行逻辑即可。另外，如果希望文字层可以被"看到"以校对，可以把render_mode=3改成render_mode=0（实心文字），输出一份带红字的校对稿，视觉上字压在扫描图上，方便逐字比对。这是临时校对很实用的小技巧。

5.3 低质量扫描件的补救方案

遇到特别模糊的扫描件，OCR之前先用超分辨率模型增强图片是当前最有效的手段。开源方案可以用Real-ESRGAN，但它在CPU上的推理速度很慢，在GPU上还能接受。实际操作时，只对关键页面做超分，比全文档做超分效率高得多。我这里提一句就行了，真要对多页大文件做全面超分，时间和算力成本需要自己权衡。

话说回来，我做了这个工具后的最大体会是：扫描件数字化这个事，真正麻烦的不是OCR本身，而是把"识别结果"正确放回"原文档"的过程。你理解了坐标映射、文本渲染模式、PDF保存优化这几个底层原理，哪怕不用AI辅助，自己写也不难；而AI编码模型在其中扮演的角色就是帮你把脑子里想到的流程快速落成代码，再把报错信息丢给它当调试器使。这套思路也不限于PDF处理，任何"老格式转新格式"的工具开发都能复用。最后再分享一个小技巧：处理重要文档前，务必先备份原文件，哪怕脚本写得再熟练，也别拿不可恢复的资料试水。