PaddlePaddle（飞桨）源码构建指南：基于 Docker 的 whl 编译、镜像发布与开发工作流全解析

PaddlePaddle飞桨源码构建指南基于 Docker 的 whl 编译、镜像发布与开发工作流全解析【免费下载链接】PaddlePArallel Distributed Deep LEarning: Machine Learning Framework from Industrial Practice 『飞桨』核心框架深度学习机器学习高性能单机、分布式训练和跨平台部署项目地址: https://gitcode.com/GitHub_Trending/pa/PaddlePaddlePaddle 作为面向工业实践的深度学习框架其构建流程覆盖从源码编译 Pythonwhl安装包、按 CUDA/CUDNN/Python ABI 产出差异化二进制到发布预装框架的 Docker 镜像并在集群如 Kubernetes上运行的完整链路。本文以 paddle/scripts/README.md 为骨架结合 paddle_docker_build.sh 与 paddle_build.sh 的源码实现系统讲解 PaddlePaddle 的构建目标、官方推荐的 Docker 构建方式、构建选项、镜像制作与使用以及无 Docker 环境下的替代路径。读完本文你将掌握从克隆源码到产出可分发的whl包、再到构建并运行 PaddlePaddle 应用镜像的完整实战技能。构建目标为什么 PaddlePaddle 要围绕 Docker 设计构建流程PaddlePaddle 的构建体系设计目标见 paddle/scripts/README.md 开篇非常明确构建过程可静态复现同样的输入应能稳定产出同样的结果避免在我机器上能编译的尴尬产出可跨发行版使用的 Pythonwhl包让一个编译产物能被尽量多的 Linux 发行版直接pip install按发布场景产出不同二进制针对不同 CUDA / CUDNN 版本历史上如 CUDA 7.5、8.0、9.0分别编译产出仅含 C API 的二进制供推理等轻量场景使用对应WITH_PYTHONOFF针对 Python 宽字符wide unicode支持与否编译不同 ABI构建预装 PaddlePaddle 的 Docker 镜像用户可直接在 Docker 或 Kubernetes 集群中运行 PaddlePaddle 应用。为了实现上述目标社区维护了预置构建环境的 Docker 镜像仓库镜像名为paddlepaddle/paddle并在文档中强烈建议在官方预置的 Docker 环境中构建。其核心理由是Docker 容器把编译所需的编译器、CUDA 工具链、依赖库等全部固化进镜像从源头上消除环境不一致导致编译失败的问题这与源码中 cmake/external 目录下统一管理第三方依赖protobuf、glog、gflags、onednn、cub 等的设计一脉相承。开发工作流源码留在宿主机编译放进容器一个贯穿 PaddlePaddle 构建哲学的原则是源代码存放在开发机宿主机上这样 Eclipse、VSCode 等编辑器可以直接解析源码提供自动补全而编译动作则在 Docker 容器内完成容器通过卷挂载方式访问宿主机源码。对于普通的笔记本/台式机开发场景流程如下而对于依赖 GPU 的复杂场景则往往拆分为开发机 带 GPU 的 Linux 主机两段式环境从两张示意图可以看出两种典型拓扑单机模式开发机如 MacBook Pro克隆 GitHub 源码后通过docker run -v将源码挂载进容器终端经ssh进入容器执行cmake、make、paddle version、paddle train等命令编辑器通过本地 I/O 直接读写宿主机源码GPU 模式源码仍放在开发机但编译与运行转移到带 GPU 的 Linux 主机上的容器中开发机通过ssh执行命令、通过sshfs等工具访问容器内文件系统以满足 CUDA 编译与训练对硬件的要求。这一宿主机存源码、容器做编译的模型正是 paddle_docker_build.sh 中-v $PADDLE_ROOT:/paddle卷挂载的直观体现。使用 Docker 构建 PaddlePaddle构建环境镜像官方预置的构建环境镜像为镜像Tagpaddlepaddle/paddlelatest-dev其中latest-dev是持续更新的开发镜像内置了完整编译工具链源码中 paddle_docker_build.sh 通过DOCKER_REPOpaddlepaddle/paddle与VERSIONlatest-dev拼出实际拉取的镜像paddlepaddle/paddle:latest-dev。开始构建git clone Paddle 仓库地址 cd Paddle ./paddle/scripts/paddle_docker_build.sh build构建完成后whl安装包会输出在宿主机build/python/dist目录下。该命令的执行过程对照 paddle_docker_build.sh 源码执行docker pull paddlepaddle/paddle:latest-dev拉取最新开发镜像在后台启动一个容器脚本默认使用nvidia-docker若系统未安装则回退到docker在容器内运行构建脚本/paddle/paddle/scripts/paddle_build.sh build注意容器内路径为/paddle/paddle/...宿主机路径为$PWD/paddle/...容器把宿主机源码目录挂载为/paddle因此容器内写/paddle/build实际上写的是宿主机$PWD/build——这也是whl产物能在宿主机build/python/dist找到的原因。构建选项Docker 构建参数用户可以通过环境变量传入以下构建参数取值一般为ON或OFF选项默认值说明WITH_GPUOFF生成 NVIDIA CUDA GPU 代码并依赖 CUDA 库WITH_AVXOFF设为 ON 以启用 AVX 指令集支持WITH_TESTINGOFF编译单元测试二进制注以当前仓库 paddle_build.sh 源码为准-DWITH_TESTING的缺省值为 ONWITH_MKLON启用 Intel oneMKL 与 Intel oneDNN 支持WITH_PYTHONON构建 Python 支持若只为 C API 构建可关闭WITH_STYLE_CHECKON构建时执行代码风格检查PYTHON_ABI为不同 Python ABI 构建如cp310-cp310、cp311-cp311等RUN_TESTOFF构建完成后立即运行单元测试在容器启动时paddle_docker_build.sh 还会注入一批与 CI 对齐的默认环境变量例如WITH_GPUON、CUDA_ARCH_NAMEAuto默认按 GPU 构建并自动探测计算架构WITH_AVXON、WITH_TESTINGON、WITH_COVERAGEONCMAKE_BUILD_TYPERelWithDebInfoWITH_DISTRIBUTEON开启分布式训练相关组件RUN_TESTON构建后跑测试CUDA_VISIBLE_DEVICES0,1、FLAGS_fraction_of_gpu_memory_to_use0.15等运行时控制项同时挂载${HOME}/.ccache到/root/.ccache以复用编译缓存加速增量构建。这些环境变量最终都会被 paddle_build.sh 中的cmake配置阶段消费见下文源码级实现。PaddlePaddle Docker 镜像获取、自建与使用官方发布镜像官方发布的 Docker 镜像可通过docker pull paddlepaddle/paddle:version获取也可自行构建。镜像 tag 分为latest最新 CPU 版与带版本号的发布 tag如历史版本0.10.0并针对 CPU / GPU 提供不同 tagTag说明latest最新 CPU 版镜像latest-gpu最新 GPU 版镜像0.10.00.10.0 版本 CPU 版镜像0.10.0-gpu0.10.0 版本 GPU 版镜像注上表为构建文档成文时记录的 tag 约定具体可用 tag 以镜像仓库实际列表为准。自建运行镜像由于 PaddlePaddle 只需pip install即可完成安装自建运行镜像非常简单。文档给出了一份示例DockerfileFROM nvidia/cuda:7.5-cudnn5-runtime-centos6 RUN yum install -y centos-release-SCL RUN yum install -y python27 # 该 whl 包由前述构建步骤产出 ADD python/dist/paddlepaddle-0.10.0-cp27-cp27mu-linux_x86_64.whl / RUN pip install /paddlepaddle-0.10.0-cp27-cp27mu-linux_x86_64.whl rm -f /*.whl随后在存放该Dockerfile的目录下执行docker build -t [REPO]/paddle:[TAG] .此外社区还提供了跨 CUDA 版本批量生成 Dockerfile 的脚本。执行bash ./build_docker_images.sh生成各 CUDA 版本的 Dockerfile再逐个构建bash ./build_docker_images.sh docker build -t [REPO]/paddle:tag -f [generated_docker_file] .注意可以根据自身环境选择不同的基础镜像如不同 CUDA 版本的nvidia/cuda系列镜像。实际上当前仓库在构建时会自动生成发布用 Dockerfilepaddle_build.sh的dockerfile任务以及build、avx_build等任务收尾阶段会调用gen_dockerfile根据WITH_GPU、CUDA_VERSION、CUDNN_VERSION等环境变量生成${PADDLE_ROOT}/build/Dockerfile供后续docker build使用详见 paddle_build.sh。生成逻辑包括GPU 构建时以nvidia/cuda:${CUDA_MAJOR}-cudnn${CUDNN_MAJOR}-devel-ubuntu16.04为基础镜像CPU 构建则用ubuntu:16.04GPU 镜像额外设置LD_LIBRARY_PATH并为libcudnn.so、libcublas.so、libcublasLt.so建立软链接保证运行时能找到动态库GPU 场景安装对应版本的 NCCLlibnccl2/libnccl-devCPU 场景跳过镜像内还会编译安装对应版本的 Python源码生成逻辑覆盖 cp38 至 cp312用于安装 whl。使用镜像运行应用假设你编写了一个使用 PaddlePaddle 的应用程序train.py可用以下命令在容器中直接运行docker run --rm -it -v $PWD:/work paddlepaddle/paddle /work/a.py但该命令成立的前提是train.py的所有依赖都已包含在生产镜像中。若应用有额外依赖需要以生产镜像为基础再构建一个新镜像并安装更多依赖。在 Docker 中运行 PaddlePaddle BookBook 教程仓库同样提供了镜像可在容器内启动 Jupyter Notebook 进行交互学习docker run -d -p 8888:8888 paddlepaddle/book运行分布式应用在分布式训练 API 的设计中将 PaddlePaddle 应用打成 Docker 镜像后再调用kubectl在集群上启动作业。手动流程为先用docker build构建应用镜像再打 tag、推送最后用kubectl部署docker build -f some/Dockerfile -t myapp . docker tag myapp me/myapp docker push kubectl ...更多选项无 Docker 构建与附加任务不使用 Docker 构建如果本机环境与官方 Dockerfile 一致可以跳过 Docker 直接执行构建脚本./paddle/scripts/paddle_build.sh build脚本默认在仓库根目录通过${BASH_SOURCE[0]}/../../计算得到PADDLE_ROOT创建build目录执行cmake配置与make install并统计产物大小、构建耗时输出到build/build_summary.txt。注意无 Docker 环境下需要自行准备编译工具链与依赖这是官方文档明确建议避免的路径。构建脚本的附加任务不带任何参数运行构建脚本即可查看帮助菜单脚本会列出全部可选任务./paddle/scripts/paddle_build.sh # 或 ./paddle/scripts/paddle_docker_build.sh从 paddle_build.sh 的帮助信息与任务分发逻辑main中的 case 分支可以看出脚本支持的子命令包括子命令用途buildx86 平台常规构建cmake 配置 编译 生成发布 Dockerfiletest运行全部单元测试基于ctestsingle_test运行单个单元测试bind_test将并行测试绑定到不同 GPU 上执行doc生成 PaddlePaddle 文档gen_doc_lib生成文档库html将 C 源码转换为 HTMLdockerfile生成 PaddlePaddle 发布用 Dockerfilefluid_inference_lib部署 Fluid 推理库生成并打包推理动态库check_style运行代码风格检查基于 pre-commit clang-formatcicheck在 Linux 上运行 CI 任务构建 测试maccheck在 Mac 上运行 CI 任务此外还有avx_build/noavx_build/mac_m1_arm分别为 AVX、非 AVX 与 Mac M1 ARM 构建、build_inference_lib纯推理库构建等分支。测试任务内部会通过ctest --output-on-failure执行并对失败用例进行多轮自动重跑相关实现可继续阅读 paddle_build.sh。源码级实现paddle_build.sh 内部的构建链路为了让读者知其然更知其所以然这里结合源码梳理paddle_build.sh的关键实现初始化init()导出PADDLE_ROOT与SCRIPT_NAME并默认开启FLAGS_call_stack_level2便于 CI 调试时打印 C 错误堆栈Python 环境准备cmake_base()会根据传入的PYTHON_ABI当前脚本支持cp310至cp314Linux 下路径形如/opt/_internal/cpython-3.x设置LD_LIBRARY_PATH、PATH与PYTHON_FLAGS并安装 python/requirements.txt 与 compile_requirements.txt 中的编译期依赖Linux 下包含 jinja2、pybind11_stubgen 等CMake 配置cmake_base()在build目录中执行cmake ..透传约 40 个选项除上文的WITH_GPU、WITH_MKL、WITH_AVX外还包括WITH_TENSORRT、WITH_ROCM、WITH_CINN、WITH_DISTRIBUTE、WITH_XPU、WITH_IPU、WITH_ARM、WITH_UNITY_BUILD、CUDA_ARCH_NAME、PY_VERSION等覆盖 CPU / GPU / 昆仑 XPU / 华为昇腾 / IPU 等不同硬件后端完整清单见 paddle_build.sh 的配置打印段编译build_base()在 Linux 上按nproc自动决定并行度nproc大于 16 时使用nproc - 8否则用nproc默认先make clean再make install -j ${parallel_number}并通过ccache -z统计缓存命中率ARM 场景WITH_ARMON则使用make TARGETARMV8产物统计build_size()计算build目录、build/python/dist下whl及libpaddle.so的大小并写入build/build_summary.txt收尾build任务在编译完成后自动调用gen_dockerfile生成发布镜像的 Dockerfile为镜像发布环节铺路。值得一提的是脚本中make clean与产物清理逻辑删除旧的python/dist、python/paddle缓存保证了静态、可复现的构建目标而clean_build_files()会在构建后清理libpaddle.so与 flash attention 动态库等 CI 敏感产物。总结PaddlePaddle 围绕 Docker 构建了一套源码在宿主机、编译进容器、产物可分发的工程体系开发镜像paddlepaddle/paddle:latest-dev提供可复现的编译环境paddle_docker_build.sh负责拉镜像、挂载源码、注入构建选项并驱动paddle_build.sh后者通过 CMake 的多维度开关GPU / CPU / 硬件后端 / Python ABI / 测试开关产出定制化whl并自动生成发布 Dockerfile。无论你是想定制自己的 PaddlePaddle 二进制、搭建 GPU 训练环境还是准备把应用容器化后部署到 Kubernetes都可以以 paddle/scripts/README.md 为入口结合本文梳理的脚本源码调用链快速落地一条可复现、可扩展的构建与发布流水线。【免费下载链接】PaddlePArallel Distributed Deep LEarning: Machine Learning Framework from Industrial Practice 『飞桨』核心框架深度学习机器学习高性能单机、分布式训练和跨平台部署项目地址: https://gitcode.com/GitHub_Trending/pa/Paddle创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考