PaddlePaddle：超详细部署与使用教程

PaddlePaddle（飞桨）是百度开源、国内最早自主研发的深度学习平台，自 2016 年正式开源。它是一套覆盖「核心深度学习框架 → 基础模型库 → 端到端开发套件 → 工具与组件 → 服务化平台」的工业级全栈平台，官方称已服务超过 2330 万开发者、76 万家企业，孵化超过 110 万个模型。当前主线为 3.x 新一代框架（统一动静态图、自动并行、大模型训推一体）。

目录

• 一、项目概述
• 二、环境要求
• 三、部署方式
• 四、使用方法
• 五、常见问题排查（FAQ）
• 六、部署注意事项与最佳实践
• 七、参考资料

一、项目概述

1.1 项目定位

PaddlePaddle（飞桨）脱胎于百度内部大规模工业实践，是「源于产业、服务产业」的深度学习平台。与研究型框架不同，飞桨从设计上就强调工业级落地：训练侧要扛住大规模分布式任务，推理侧要覆盖从服务器到边缘端、从 NVIDIA 到国产芯片的全硬件矩阵。其完整生态由五层构成：

1. 核心深度学习框架（本仓库 Paddle）：动态图/静态图统一的执行引擎、自动微分、分布式调度、异构计算后端；
2. 基础模型库：PaddleNLP（自然语言）、PaddleCV（视觉）、PaddleAudio（语音）、PaddleRec（推荐）等；
3. 端到端开发套件：PaddleOCR（OCR/文档解析）、PaddleX（全场景开发套件）、PaddleSeg、PaddleDetection、PaddleClas 等；
4. 工具与组件：PaddleSlim（模型压缩）、X2Paddle（模型迁移）、动转静工具等；
5. 服务化平台：Paddle Serving（在线服务）、Paddle Lite（端侧推理）、FastDeploy（高性能推理部署）。

本仓库（PaddlePaddle/Paddle）对应的是第 1 层「核心框架」本身——你 pip install paddlepaddle 装的就是它。

1.2 核心功能（3.x 新一代框架）

• 统一动态图/静态图与自动并行：只需基于单卡配置做最少的张量切分标注，框架自动搜索最优分布式并行策略（数据并行 / 张量并行 / 流水线并行的组合），大幅降低工业级分布式训练门槛。
• 大模型训推一体：同一套框架同时支持训练与推理，两个阶段代码复用、无缝衔接，为大模型全流程提供统一开发体验与训练效率。
• 高阶微分与科学计算：提供高阶自动微分、复数运算、傅里叶变换、编译优化与分布式训练支持，可服务数学、力学、材料、气象、生物等领域的微分方程求解。
• 神经网络编译器：一体化框架设计，对生成式模型、科学计算模型都做到「高效训练 + 灵活推理」，在计算灵活性与高性能之间取得平衡，降低性能优化成本。
• 异构多芯片适配：通过标准化接口抽象不同芯片软件栈的差异，实现可插拔架构，成熟支持 NVIDIA、Intel、昆仑芯（XPU）、昇腾（NPU）等多类硬件。
• 动静态图统一 API：新版 API 程序更短，兼顾动态图的调试便利与静态图的部署性能。

1.3 技术架构

PaddlePaddle 采用「前端（Python API）+ 核心引擎（C++）」双层架构：上层是用户熟悉的 Python API（import paddle），下层是 C++ 实现的执行引擎，包括算子库（Operators）、自动微分（Autograd）、图编译与优化、分布式通信（Collective / RPC）、以及多硬件后端（CUDA、CPU、XPU、NPU 等）。安装包里 paddle Python 包通过 C++ 扩展（libpaddle.so）与核心引擎交互。

官方仓库 README 未提供公开可下载的架构图位图（仓库内 doc/imgs/ 仅含 Logo），架构细节以官方文档「框架设计」章节描述为准。

二、环境要求

最重要的一条：不要在任何地方「照抄一条旧版本 pip 命令」。飞桨的安装包是按「操作系统 × Python 版本 × CUDA 版本」三维组合的，正确做法永远是：打开官方快速安装页 https://www.paddlepaddle.org.cn/install/quick ，按你的环境勾选，复制页面现场生成的命令。

CUDA 版本怎么选？ 先在终端执行 nvcc --version（或 nvidia-smi 右上角的 CUDA Version）看本机 CUDA Toolkit 版本，然后在安装页选择不高于该版本的 wheel（例如本机 CUDA 12.6 可以选 cu126 索引）。不要选高于本机 CUDA 的 wheel——向后不兼容。

CPU 版还是 GPU 版怎么选？ - 只是学习 API、跑教程、跑小模型推理 → 装 CPU 版 paddlepaddle； - 训练模型、跑大模型（哪怕是 0.3B 小模型微调）→ 装 GPU 版 paddlepaddle-gpu； - 同一台机器两个都想试？装在两个虚拟环境里，不要共存在一个环境。

三、部署方式

3.1 方式一：CPU 版 pip 安装（最快上手 / 验证学习）

# 1) 建议新建虚拟环境
python3 -m venv paddle_env && source paddle_env/bin/activate
python -m pip install --upgrade pip

# 2) 安装 CPU 版（使用百度镜像源加速）
python -m pip install paddlepaddle -i https://mirror.baidu.com/pypi/simple

上面的 paddlepaddle 不带版本号，默认拉取当前稳定版；若安装页针对你的 Python 版本建议了具体版本号（例如 paddlepaddle==3.0.0），以安装页生成的命令为准。

3.2 方式二：GPU 版安装（训练主力，必须走官方安装页）

步骤 1：打开 https://www.paddlepaddle.org.cn/install/quick 。

步骤 2：按页面表单逐项选择：

• 版本：推荐版本（稳定版）/ 预编译版（Nightly）；
• 系统：Linux / Windows / macOS；
• 安装方式：pip / conda / 源码编译；
• 计算设备：CPU / GPU（选 GPU 后继续选 CUDA 版本，如 11.8 / 12.3 / 12.6）；
• Python 版本：与你本机 python --version 完全一致。

步骤 3：复制页面生成的命令执行。命令形如（仅为格式示例，版本号与索引源必须以页面现场生成结果为准，切勿照抄）：

# 示例格式：GPU 版通过官方专用索引源安装（CUDA 版本不同，索引 URL 不同）
python -m pip install paddlepaddle-gpu==3.0.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu126/

步骤 4：验证 GPU 可用（见 3.5）。

3.3 方式三：conda 安装

在官方安装页选择「conda」安装方式后复制生成命令，格式类似：

# 示例格式（以安装页为准）
conda install paddlepaddle==3.0.0 -c https://mirror.tuna.tsinghua.edu.cn/anaconda/cloud/paddle/

conda 渠道与 pip 渠道的包是两套体系，二选一即可，不要混装。

3.4 方式四：源码编译安装（仅二次开发/需要自定义算子）

# 拉取源码（默认开发分支为 develop）
git clone https://github.com/PaddlePaddle/Paddle.git
cd Paddle
git checkout release/3.0   # 如需稳定版，切到对应 release 分支（以实际分支列表为准）

# 编译需要满足官方编译依赖（cmake、gcc、CUDA 等），
# 详细编译步骤严格按官方文档「从源码编译」章节执行：
# https://www.paddlepaddle.org.cn/documentation/docs/zh/guides/08_contribution/index_cn.html

源码编译耗时长（首次编译通常数小时）且依赖严格，普通使用者直接 pip 安装即可；仅当你需要改框架源码、自定义算子、或官方预编译包不支持你的组合时才走这条路径。

3.4.1 Windows 环境特别说明

Windows 下的安装流程与 Linux 一致（同样先去官方安装页选择系统=Windows 生成命令），但注意：

• 仅提供 64 位 Windows（Win10/Win11）的预编译包；
• GPU 版 Windows 同样需要先装好 NVIDIA 驱动与对应 CUDA；
• 建议在「开始菜单」找到对应版本的「x64 Native Tools Command Prompt」或使用 Anaconda Prompt 执行 pip 命令，避免普通 CMD 下的编码与路径问题；
• 如安装页未提供你本机 Python 版本的 Windows 包，官方建议改用 WSL2 里的 Linux 环境安装。

3.5 验证部署成功（必做）

# 1) 导入并查看版本
python -c "import paddle; print(paddle.__version__)"

# 2) 官方一键自检：CPU 版应输出 /proc 信息，GPU 版应识别到 CUDA 设备
python -c "import paddle; paddle.utils.run_check()"

预期：CPU 版输出 PaddlePaddle is installed successfully!；GPU 版输出中能看到检测到的 GPU 型号、CUDA 版本，并提示 GPU 运行正常。看到 PaddlePaddle is installed successfully 字样即部署成功。

再补一个最小张量运算冒烟测试：

import paddle
x = paddle.to_tensor([[1.0, 2.0], [3.0, 4.0]])
y = x * 2 + 1
print(y)
# 预期输出 Tensor([[3., 5.], [7., 9.]])

四、使用方法

4.1 基础用法：十分钟上手

import paddle
from paddle.vision.transforms import Compose, ToTensor

# 1) 加载 MNIST 示例数据集（首次运行自动下载）
transform = Compose([ToTensor()])
train_dataset = paddle.vision.datasets.MNIST(mode='train', transform=transform)
val_dataset = paddle.vision.datasets.MNIST(mode='test', transform=transform)

# 2) 定义一个简单的卷积网络
lenet = paddle.nn.Sequential(
    paddle.nn.Conv2D(1, 32, 3, 1),
    paddle.nn.ReLU(),
    paddle.nn.MaxPool2D(2),
    paddle.nn.Flatten(),
    paddle.nn.Linear(5408, 128),
    paddle.nn.ReLU(),
    paddle.nn.Linear(128, 10),
)

# 3) 配置训练
model = paddle.Model(lenet)
model.prepare(
    optimizer=paddle.optimizer.Adam(learning_rate=0.001, parameters=model.parameters()),
    loss=paddle.nn.CrossEntropyLoss(),
    metrics=[paddle.metric.Accuracy()],
)

# 4) 训练与评估
model.fit(train_dataset, epochs=2, batch_size=64, verbose=1)
model.evaluate(val_dataset, verbose=1)

model.fit 是高层 API；喜欢底层控制的用户也可以手写训练循环（paddle.DataLoader + 前向 + loss.backward() + optimizer.step()），两种方式在官方文档「快速开始」里都有完整示例。

Windows 用户提示：上面的 Linux/Mac 示例代码可直接在 Windows 运行，唯一区别是数据路径用反斜杠（或统一写成正斜杠 /）；控制台中文打印建议先 set PYTHONIOENCODING=utf-8。

4.2 常用 API 速查

import paddle

# 张量创建
a = paddle.zeros([2, 3])
b = paddle.randn([2, 3])            # 正态分布随机
c = paddle.to_tensor([1, 2, 3])

# 设备：CPU / GPU
paddle.set_device('cpu')            # 或 'gpu'
x = paddle.to_tensor([1.0]).cuda()  # 移到 GPU

# 神经网络层
layer = paddle.nn.Linear(10, 5)

# 优化器
opt = paddle.optimizer.SGD(learning_rate=0.01, parameters=layer.parameters())

# 自动微分
x = paddle.to_tensor([3.0], stop_gradient=False)
y = x ** 2
y.backward()
print(x.grad)                       # 期望 6.0

4.2.1 模型保存、加载与导出

import paddle

# 训练过程中保存 checkpoint（优化器状态也一并保存，便于断点续训）
layer = paddle.nn.Linear(10, 5)
paddle.save(layer.state_dict(), "linear.pdparams")
paddle.save(optimizer.state_dict(), "optimizer.pdopt")

# 加载
layer.set_state_dict(paddle.load("linear.pdparams"))

# 导出可部署的静态图推理模型（交给 FastDeploy / Serving / Lite）
@paddle.jit.to_static
def forward(x):
    return layer(x)

paddle.jit.save(forward, path="infer_model/inference")
# 生成 infer_model/inference.pdmodel 与 inference.pdiparams 两个文件

4.3 进阶功能

• 自动并行（大模型训练）：3.x 核心能力，基于单卡模型定义 + 少量切分标注，框架自动完成分布式策略搜索，文档见官方「分布式训练」章节。
• 模型库生态：NLP 用 PaddleNLP、视觉用 PaddleCV 套件（PaddleDetection / PaddleSeg / PaddleClas）、OCR 用 PaddleOCR、全场景开发用 PaddleX——它们都构建在本框架之上。
• 推理部署：训练好的模型用 paddle.jit.save 导出静态图模型，再交给 FastDeploy（高性能推理）、Paddle Serving（在线服务）或 Paddle Lite（端侧）部署。
• 模型压缩：通过 PaddleSlim 做量化/剪枝/蒸馏，配合 4.2/4.4/2.2 比特量化推理（如 ERNIE 4.5 的实践）。
• 国产硬件：通过 paddle.device 统一接口，XPU（昆仑芯）、NPU（昇腾）等后端的安装包在官方安装页按硬件类型单独选择。
• 科学计算：高阶微分、复数与傅里叶变换接口面向 PDE 求解场景。

4.4 适用场景

• 工业视觉质检、OCR、文档智能（配合 PaddleOCR / PaddleX）；
• 大模型预训练与微调（3.x 自动并行 + ERNIEKit 训练工具链）；
• 推荐系统、广告排序（PaddleRec）；
• 端侧/边缘设备部署（Paddle Lite，覆盖国产芯片）；
• 科研教学：国内高校 AI 课程常用教学框架，中文文档最完善；
• 数据合规要求高、需要国产化硬件适配的企业生产环境。

五、常见问题排查（FAQ）

Q1：pip install paddlepaddle-gpu 安装成功但 paddle.utils.run_check() 报 no CUDAPlugin / not compiled with CUDA - 原因：装错包了——装的是 CPU 版（paddlepaddle），或 GPU wheel 的 CUDA 版本与本机 CUDA 不一致。 - 解决：卸载后回到官方安装页，严格按本机 CUDA 版本重新生成并执行 GPU 版安装命令；pip uninstall paddlepaddle paddlepaddle-gpu 后再重装。

Q2：安装时报 Could not find a version that satisfies the requirement paddlepaddle-gpu - 原因：你的「Python 版本 × CUDA 版本 × 操作系统」组合没有预编译包，或 pip 源里没有。 - 解决：去官方安装页勾选后看它给的索引 URL，用 -i 指定；注意 Python 大版本必须严格匹配（如 3.10 不能用 3.11 的包）。

Q3：导入时报 ImportError: DLL load failed（Windows）或 libcudart.so.xx: cannot open shared object file（Linux） - 原因：Windows 缺少 VC++ 运行库或 CUDA 环境变量；Linux 未装 cuDNN 或 CUDA bin/lib 未进 PATH。 - 解决：Windows 装 Visual C++ Redistributable；Linux 确认 nvcc --version、ldconfig -p | grep cudnn 正常，并把 CUDA 的 bin/、lib64/ 加入 PATH / LD_LIBRARY_PATH。

Q4：pip 下载极慢 / 超时 - 解决：换百度镜像 -i https://mirror.baidu.com/pypi/simple；GPU 版官方索引源本身就在 paddlepaddle.org.cn，国内速度尚可。

Q5：paddle.utils.run_check() 卡在 CUDA 初始化或报显存不足 - 原因：GPU 显存被其他进程占满，或驱动版本过低。 - 解决：nvidia-smi 查看占用；升级 NVIDIA 驱动；小显存机器先跑 CPU 版验证。

Q6：和 PyTorch / TensorFlow 装在同一环境冲突 - 原因：两者都依赖 numpy、mkl 等底层库，版本容易互相顶掉。 - 解决：一个深度学习框架一个虚拟环境（conda create 或 venv），这是最省心的做法。

Q7：Windows 下 import 报 ZipImportError 或安装后文件缺失 - 原因：解压/杀毒软件拦截了 wheel 内文件，或路径含中文/空格。 - 解决：换无中文路径的目录重建虚拟环境；临时关闭杀毒软件后重装。

Q8：paddle 与 paddleocr / paddlenlp 版本不匹配（如 AttributeError: module 'paddle' has no attribute 'xxx'） - 原因：上层套件要求更高版本的框架，本地框架版本过旧。 - 解决：pip install -U paddlepaddle（或 GPU 版）升级到套件要求的版本；套件 README 中一般会写明框架版本要求。

Q9：多卡训练时 nccl 报错或卡在通信初始化 - 原因：NCCL 版本与驱动/CUDA 不匹配，或多机网络互通有问题。 - 解决：确认 NCCL 与 CUDA 版本配套；单机多卡先跑通官方分布式训练示例；多机场景确认节点间通信端口放行。

Q10：想换国内镜像加速但又要装 GPU 专用索引源，怎么组合？ - 说明：CPU 版可用 mirror.baidu.com/pypi/simple；GPU 版必须使用官方安装页给出的 paddlepaddle.org.cn/packages/stable/cuXXX/ 专用索引——GPU wheel 不在普通 PyPI 镜像里，两者不要混用。

Q11：macOS 上只能用 CPU 版吗？想跑 GPU 怎么办？ - 说明：macOS（含 Apple Silicon）官方以 CPU 版为主；需要 GPU 训练请改用 Linux 机器或云服务器（NVIDIA 卡），Apple Silicon 的加速支持以官方文档最新说明为准。

六、部署注意事项与最佳实践

1. 永远以官方安装页为准：安装命令是「环境组合」动态生成的，网上博客的旧命令（尤其带具体版本号的）大概率已过时，照抄必踩 CUDA 不匹配的坑。
2. GPU 环境先核对三件套：显卡驱动、CUDA Toolkit、cuDNN 版本三者匹配后，再去选对应 CUDA 版本的 wheel。
3. 一个环境只装一个框架：飞桨与 PyTorch 各占一个 venv/conda env，避免底层库冲突。
4. 训练与部署分离：训练用 GPU 版；推理服务用 FastDeploy/PaddleServing 镜像，不要把训练依赖带进生产容器。
5. 模型导出规范：上线前用 paddle.jit.save 导出静态图模型并在目标环境实测，不要直接拿动态图 checkpoint 上生产。
6. 关注 3.x 版本节奏：框架 3.x 仍在快速演进（自动并行、编译器能力持续增强），生产项目锁定大版本，升级前看 Release Notes。
7. 国产芯片适配：昆仑芯/昇腾等后端安装包与驱动配套，安装页选择对应硬件通道，文档按硬件专项指南执行。
8. 善用中文社区：官方论坛、GitHub Issues、PFCC 社区博客（pfcc.blog）是排错第一资源。
9. 内存与显存预估：训练时显存大致与「模型参数量 × 精度字节数 × 训练系数（约 16–20）」成正比；估不准时先用小 batch 试跑，再逐步加大。
10. 日志与监控：训练脚本里用 paddle.summary 打印模型结构参数量；多卡/长任务接入官方日志或 WandB 类工具，避免黑盒跑训。

七、参考资料

• GitHub 仓库：https://github.com/PaddlePaddle/Paddle
• 官方官网：https://www.paddlepaddle.org.cn
• 快速安装页（生成安装命令）：https://www.paddlepaddle.org.cn/install/quick
• 中文文档：https://www.paddlepaddle.org.cn/documentation/docs/zh/guides/index_cn.html
• English Docs：https://www.paddlepaddle.org.cn/documentation/docs/en/guides/index_en.html
• Release 列表：https://github.com/PaddlePaddle/Paddle/releases
• 社区博客：https://pfcc.blog/
• 源码编译指南：https://www.paddlepaddle.org.cn/documentation/docs/zh/guides/08_contribution/index_cn.html
• 关联生态：PaddleNLP https://github.com/PaddlePaddle/PaddleNLP 、PaddleOCR https://github.com/PaddlePaddle/PaddleOCR 、FastDeploy https://github.com/PaddlePaddle/FastDeploy