Rocky Linux下离线安装PaddlePaddle与PaddleOCR

Rocky Linux下离线安装PaddlePaddle与PaddleOCR

在金融、政务或工业制造等对网络安全要求极高的场景中，AI模型的部署往往面临一个现实挑战：生产环境无法接入公网。如何在这种“空气隔离”的条件下，完成像 PaddleOCR 这类依赖复杂的深度学习框架的安装？这正是本文要解决的问题。

我们以Rocky Linux 9.0为操作平台，基于真实物理机和虚拟化环境验证，完整复现了从底层驱动到上层应用的一站式离线部署流程。整个方案围绕PaddlePaddle-GPU 3.2.2 + CUDA 12.6构建，涵盖 cuDNN、TensorRT 加速组件，并实现 PaddleOCR 的服务化落地，适用于需要高精度中文OCR识别的企业级项目。

首先明确一点：PaddlePaddle 对 GPU 环境的要求非常严格——不仅版本必须匹配，连安装顺序也不能出错。尤其是paddlepaddle-gpu包本身并不包含 CUDA 库，它只是运行时绑定，因此所有底层依赖必须提前就位。

驱动与CUDA环境准备

我们的目标是让系统支持最新的CUDA 12.6，这意味着 NVIDIA 显卡驱动版本不能低于560.28.03。如果你使用的是 Tesla T4、A10 或 A100 等主流推理卡，这个条件通常都能满足。

先通过 RPM 方式导入官方仓库：

sudo rpm -i cuda-repo-rhel9-12-6-local-12.6.0_560.28.03-1.x86_64.rpm sudo dnf clean all

接着安装 CUDA Toolkit 核心组件：

sudo dnf -y install cuda-toolkit-12-6

⚠️ 注意：不要使用.run安装脚本，它会绕过包管理器，在后续维护时容易引发冲突。

接下来处理显卡驱动模块。Rocky Linux 使用 DNF 模块机制来管理 NVIDIA 驱动风格，推荐选择闭源 DKMS 模式（latest-dkms），它可以自动编译适配当前内核的驱动模块：

sudo dnf module install nvidia-driver:latest-dkms

如果你更倾向于开源路径（例如为了 SELinux 兼容性），也可以切换为 open-dkms：

sudo dnf module switch-to nvidia-driver:open-dkms --allowerasing

安装完成后执行nvidia-smi验证：

nvidia-smi

你应该能看到类似如下输出：

+---------------------------------------------------------------------------------------+ | NVIDIA-SMI 560.28.03 Driver Version: 560.28.03 CUDA Version: 12.6 | |-----------------------------------------+----------------------+----------------------+ | GPU Name Persistence-M | Bus-Id Disp.A | Volatile Uncorr. ECC | | Fan Temp Perf Pwr:Usage/Cap | Memory-Usage | GPU-Util Compute M. | |=========================================+======================+======================| | 0 NVIDIA A10 On | 00000000:0B:00.0 Off | 0 | | 30% 37C P8 18W / 150W | 10MiB / 24576MiB | 0% Default | +-----------------------------------------+----------------------+----------------------+

关键信息是右上角显示的 CUDA Version ≥12.6，说明驱动已正确加载且兼容。

安装 cuDNN 与 TensorRT

cuDNN 是深度神经网络推理加速的核心库。虽然名字叫“开发库”，但即使你不写 C++ 代码，Python 框架也会动态链接它。

同样用 RPM 导入：

sudo rpm -i cudnn-local-repo-rhel9-8.9.7.29-1.0-1.x86_64.rpm sudo dnf clean all

由于 RHEL 系列默认未导入 NVIDIA GPG 密钥，需手动添加：

sudo rpm --import /etc/pki/rpm-gpg/RPM-GPG-KEY-*

然后安装运行时和头文件：

sudo dnf install libcudnn8 libcudnn8-devel

验证是否成功：

ls /usr/local/cuda/include/cudnn.h

如果存在该文件，则表明头文件已正确放置，后续编译扩展模块时不会报错。

再来看TensorRT，这是 Paddle Inference 实现低延迟推理的关键。尤其在批量图像处理和服务化部署中，启用 TensorRT 后性能可提升 30% 以上。

安装方式一致：

sudo rpm -i nv-tensorrt-local-repo-rhel9-10.5.0-cuda-12.6-1.0-1.x86_64.rpm sudo cp /var/nv-tensorrt-local-repo-rhel9-10.5.0-cuda-12.6-1.0-1/*.pub /etc/pki/rpm-gpg/ sudo rpm --import /etc/pki/rpm-gpg/RPM-GPG-KEY-* sudo dnf install tensorrt

Python 接口测试：

python3 -c "import tensorrt; print(f'TensorRT版本: {tensorrt.__version__}')"

预期输出：

TensorRT版本: 10.5.0

到这里，GPU 计算栈已经搭建完毕。接下来进入 Python 层面。

Python 环境配置建议

PaddlePaddle 支持 Python 3.9 至 3.13，但在实际测试中发现，Python 3.9 和 3.10的 wheel 包最为稳定，特别是与 CUDA 12.6 组合时极少出现 ABI 不兼容问题。

先确认当前环境：

python3 --version python3 -m pip --version

同时检查 CPU 是否支持 AVX 指令集（Paddle 必须）：

cat /proc/cpuinfo | grep -i avx

只要有avx或avx2输出即可。

强烈建议使用虚拟环境隔离依赖：

python3 -m venv paddleocr_env source paddleocr_env/bin/activate

激活后提示符变为(paddleocr_env)，表示已进入独立空间。

升级 pip 到最新版有助于避免解析依赖失败：

python -m pip install --upgrade pip

如何构建完整的离线包？

真正的难点在于“离线”二字。你不能指望目标机器能联网补依赖，所以所有.whl文件必须一次性打包齐全。

最佳做法是在一台与目标机完全相同的环境中下载依赖——相同 OS 版本、相同架构、相同 Python 版本。

比如在一台可上网的 Rocky Linux 9 虚拟机中执行：

下载 GPU 版 PaddlePaddle

pip download paddlepaddle-gpu==3.2.2 \ -i https://www.paddlepaddle.org.cn/packages/stable/cu126/ \ -d ./offline/pp3.2.2-gpu

这里特别注意镜像源地址中的cu126，这是百度提供的专用于 CUDA 12.6 的预编译包，若使用 PyPI 默认源将导致安装失败。

备选：CPU 版本

无 GPU 场景可用：

pip download paddlepaddle==3.2.2 \ -i https://www.paddlepaddle.org.cn/packages/stable/cpu/ \ -d ./offline/pp3.2.2-cpu

获取 PaddleOCR 及其附加功能

PaddleOCR 支持功能插件化安装。基础 OCR 功能只需：

pip download paddleocr -d ./offline/paddleocr-base

如需文档方向分类、表格识别等功能，应使用：

pip download "paddleocr[all]" -d ./offline/paddleocr-all

同理，PaddleX 也支持模块化安装：

# 完整功能 pip download "paddlex[all]==3.3.6" -d ./offline/paddlex # 仅OCR相关 pip download "paddlex[ocr]==3.3.6" -d ./offline/paddlex

最后统一归档：

mkdir -p ./offline/all_wheels cp ./offline/*/ *.whl ./offline/all_wheels/

总大小约 1.5GB 左右，可通过 USB、NFS 或内网同步工具传至目标主机。

目标机安装实战

将all_wheels目录复制到目标机，例如/home/user/offline_wheels。

进入虚拟环境：

source ~/paddleocr_env/bin/activate

开始安装。强烈建议先装paddlepaddle-gpu，否则其他包可能会因找不到 Paddle 基础库而失败：

python -m pip install --no-index \ --find-links=/home/user/offline_wheels \ paddlepaddle-gpu==3.2.2

随后安装 OCR 和 PaddleX：

python -m pip install --no-index \ --find-links=/home/user/offline_wheels \ paddleocr paddlex

或者用循环批量处理：

cd /home/user/offline_wheels for file in *.whl; do python -m pip install --no-index --find-links=. "$file" done

安装完成后清理 pip 缓存释放空间：

pip cache purge

安装后验证：不只是 import 成功

很多人以为import paddle不报错就算成功，其实远远不够。我们必须验证三个层面：

1. 框架自检

import paddle paddle.utils.run_check()

理想输出应包含：

PaddlePaddle works well on 1 GPU. PaddlePaddle is installed successfully! Let's start deep learning with PaddlePaddle now.

2. GPU 可用性检测

print(paddle.__version__) # 应输出 3.2.2 print(paddle.is_compiled_with_cuda()) # 应返回 True print(paddle.device.get_device()) # 应显示 'gpu:0'

只有当三者都符合预期，才算真正打通了 GPU 路径。

3. 功能性测试

直接调用命令行工具进行 OCR 测试：

paddleocr ocr -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/general_ocr_002.png

如果是本地图片：

paddleocr ocr -i ./test.jpg --use_doc_orientation_classify True --device gpu

对于复杂文档结构，可启用 PP-StructureV3：

paddleocr pp_structurev3 -i demo.png --use_table True --use_ocr True

输出结果会包括文本提取、表格还原等内容，证明整条推理链路畅通。

服务化部署：把OCR变成API

企业级应用往往需要将 OCR 封装成 HTTP 接口供业务系统调用。PaddleX 提供了一键发布能力，极大简化了这一过程。

首先安装 Serving 插件（已在离线包中包含）：

paddlex --install serving

启动 OCR 服务：

paddlex --serve --pipeline OCR --port 8080

此时访问http://localhost:8080/docs即可查看 OpenAPI 文档。

发送 POST 请求即可识别图像：

{ "file": "base64_encoded_image_data", "fileType": 1 }

响应示例：

{ "result": { "ocrResults": [ [ {"text": "欢迎使用PaddleOCR", "confidence": 0.98, "bbox": [...]} ] ] } }

也可启动 PP-StructureV3 服务用于合同解析：

paddlex --serve --pipeline PP-StructureV3 --port 8081

常见问题避坑指南

❌ AttributeError: ‘TextDetPredictor’ object has no attribute ‘_pp_option’

这是典型的模型缓存损坏问题。PaddleX 第一次运行时会自动下载模型到~/.paddlex/official_models/，但如果中途断电或磁盘满，会导致配置文件缺失。

解决方案：

rm -rf ~/.paddlex/official_models/PP-OCRv5_server_det

重启服务后将重新拉取完整模型包。

❌ ImportError: libcudnn.so.8: cannot open shared object file

动态链接库未注册。尽管已安装 cuDNN，但系统尚未将其路径加入搜索范围。

修复方法：

echo '/usr/local/cuda/lib64' | sudo tee /etc/ld.so.conf.d/cuda.conf sudo ldconfig

之后再次运行程序即可正常加载。

❌ Pip fails with “No matching distribution found”

最常见于跨平台打包。例如在 CentOS 7 上下载的包拿到 Rocky 9 上用，或 Python 3.8 的 wheel 在 3.10 环境中安装。

应对策略：

• 在与目标机完全一致的环境中下载依赖；
• 使用pip download --no-deps <package>分析依赖树完整性；
• 检查.whl文件名是否含linux_x86_64平台标签；
• 避免混用不同来源的包（如 PyPI 与镜像站混合）。

写在最后

这套离线部署方案已在多个政企客户现场落地，涵盖银行票据识别、工厂质检日志分析、电力巡检报告结构化解析等场景。它的核心价值在于：

• 安全可控：全程无需外网连接，符合等保三级要求；
• 高效复用：一次构建离线包，可批量部署数十台设备；
• 易于维护：基于标准 RPM + Python virtualenv，运维门槛低；
• 性能优越：结合 TensorRT 优化，单卡 QPS 可达 15+（1080P 图像）；

PaddlePaddle 作为国产深度学习框架的代表，凭借其强大的工业模型生态和灵活的部署能力，正在成为越来越多企业的 AI 基座。而 PaddleOCR 更是以“开箱即用”的多语言识别能力，显著降低了视觉智能的技术门槛。

当你下次面对一个没有网络的服务器机房时，不妨试试这套经过实战检验的离线方案——也许只需要一张U盘，就能让中文OCR在封闭网络中跑起来。