PaddleFormers

环境要求

• Python ≥ 3.12（安装章节实际支持 python 3.10～3.13）
• CUDA ≥ 13.0（官方镜像同时提供 cuda12.6 / cuda12.9 / cuda13.0 版本）
• PaddleFleet ≥ 0.3（仅 GPU 训练功能需要）
• 操作系统：Linux 或 Windows
• 使用容器方式时需要 Docker 与 NVIDIA 显卡驱动（--gpus all）

安装与启动步骤

1. 1Docker 方式（推荐）

   用官方预置镜像起容器，镜像内已克隆 PaddleFormers 仓库并完成安装，避免本地环境冲突。按显卡选择 cuda12.6/12.9/13.0 镜像标签。

   docker run --gpus all --name paddleformers-work -v $(pwd):/work  
       -w=/work --shm-size=512G --network=host -it 
       ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddle:3.3.0-gpu-cuda12.6-cudnn9.5 /bin/bash

   复制

2. 2创建虚拟环境

   不使用 Docker 时，推荐先用 conda / venv / uv 隔离 Python 环境，再安装依赖。以下以 conda 为例。

   conda create -n paddleformers-work python=3.10
   conda activate paddleformers-work

   复制

3. 3源码安装

   克隆仓库后以可编辑模式安装，并附带 paddlefleet 依赖；按实际 CUDA 版本替换命令中的 cu126 索引地址。

   git clone https://github.com/PaddlePaddle/PaddleFormers.git
   cd PaddleFormers
   python -m pip install -e '.[paddlefleet]' --extra-index-url https://www.paddlepaddle.org.cn/packages/nightly/cu126/ --extra-index-url https://www.paddlepaddle.org.cn/packages/stable/cu126/

   复制

4. 4pip 直接安装

   不想拉取源码时，可直接从 pip 安装 PaddleFormers 与 PaddleFleet，同样需按 CUDA 版本选择索引地址。

   python -m pip install "paddleformers[paddlefleet]" --extra-index-url https://www.paddlepaddle.org.cn/packages/stable/cu126/

   复制

5. 5轻量安装 tokenizer

   如果只使用 tokenizer 或 processor，可只装基础包，不安装训练相关依赖，安装速度更快。

   python -m pip install paddleformers

   复制

如何确认成功

安装或 docker run 命令无报错，进入容器/虚拟环境后执行 python -c "import paddleformers" 能正常导入即成功。

常见问题

注意事项

• Docker 方式被 README 标注为推荐，容器已拉取仓库并完成安装，可直接进入 /work 目录开始工作。
• docker run 使用 --shm-size=512G 与 --network=host，训练大模型时不要随意改小共享内存。
• 官方镜像标签为 paddle:3.3.0-gpu-cuda12.6-cudnn9.5，另有 cuda12.9-cudnn9.9 与 cuda13.0-cudnn9.13 可选。
• 命令示例中统一以 cuda12.6（cu126）为例，其他版本请按注释替换为 cu129 或 cu130。