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

PaddleNLP 是基于飞桨（PaddlePaddle）深度学习框架的大语言模型（LLM）开发套件，支持在多种硬件上高效完成大模型预训练、精调（SFT/PEFT）、对齐（DPO/RLHF）、无损压缩与高性能推理，覆盖 LLaMA、Qwen、DeepSeek、Baichuan、ChatGLM、Mistral 等主流模型系列。

目录

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

一、项目概述

1.1 项目定位

PaddleNLP 是百度飞桨团队开源的「产业级大语言模型开发套件」，口号是「简单易用、性能极致」。它脱胎于飞桨 NLP 工具库（曾覆盖分词、句法、预训练模型库、文本分类/序列标注/问答等 NLU 全场景），自 3.0 起全面转向「拥抱大模型」，提供从预训练 → 有监督精调（SFT）→ 参数高效微调（LoRA/PEFT）→ 对齐（DPO/SimPO/ORPO/KTO、RLHF PPO）→ 量化压缩（INT8/INT4/FP8）→ 高性能推理与服务化部署的完整链路。套件接口兼容 Hugging Face Transformers 的使用习惯（AutoTokenizer / AutoModelForCausalLM），开发者迁移成本低，同时底层依托飞桨框架的 4D 并行（数据并行、张量并行、流水线并行、专家/参数分片并行）与国产硬件适配能力。

1.2 核心功能

• 多硬件训推一体：支持英伟达 GPU、昆仑芯 XPU、昇腾 NPU、燧原 GCU、海光 DCU 等多种硬件的大模型与自然语言理解模型训练/推理，套件接口支持硬件快速切换。
• 高效易用的预训练：支持纯数据并行、分组参数切片的数据并行、张量模型并行、流水线模型并行的 4D 高性能训练；Trainer 支持分布式策略配置化；Unified Checkpoint 支持训练断点按机器资源动态扩缩容恢复，异步保存使模型存储加速 95%，Checkpoint 压缩可节省 78.5% 存储空间。
• 高效精调：精调算法结合零填充数据流与自研 FlashMask（列稀疏注意力掩码表示）高性能算子，降低无效填充与计算，大幅提升精调吞吐；自研极致收敛的 RsLoRA+ 算法。
• 无损压缩与高性能推理：推理模块内置动态插入与全环节算子融合；支持 Weight-Only INT8/INT4 推理，支持权重、激活、KV Cache（WAC）INT8、FP8 量化推理；支持 MTP 投机解码。
• 主流模型全覆盖：LLaMA / Llama2 / 3 / 3.1 / 3.2 / 3.3、Baichuan / Baichuan2、Bloom、ChatGLM / 2 / 3、DeepSeek-V2 / V3 / R1、Gemma、Mistral、Mixtral、OPT、Qwen / 1.5 / 2 / 2.5 / 3、QwQ、Yuan2、PP-UIE 等。
• 信息抽取（PP-UIE）：自研下一代通用信息抽取模型，零样本/少样本冷启动，支持 8192 Token 长文档信息抽取。
• 模型融合工具 MergeKit：缓解对齐代价，支持模型合并（以官方文档为准）。
• 在线学习：官方在 AI Studio（免费算力平台）提供交互式教程，可零安装体验。

1.3 技术架构

PaddleNLP 官方 README 提供的项目 logo 如下（本仓库公开文档中未提供独立的架构示意图，其分层架构以官方文档描述为准）：

按官方文档，套件自上而下可分为四层（描述依据 README 与官方文档站）：

1. 应用层：产业级智能助手、内容创作、知识问答（RAG）、关键信息抽取（PP-UIE）等场景；
2. 套件层：Auto API 模型加载、SFTTrainer / TRL 对齐训练、推理部署引擎（llm/server）、Unified Checkpoint、MergeKit；
3. 框架层：飞桨 PaddlePaddle 3.0+，提供 4D 并行、FlashMask、FastFFN/FusedQKV 算子融合等底层能力；
4. 硬件层：NVIDIA GPU、昆仑芯 XPU、昇腾 NPU、燧原 GCU、海光 DCU。

说明：官方仓库 README 未内嵌架构图，以上分层为依据官方文档站（paddlenlp.readthedocs.io）描述整理，更细的架构图以官方文档为准。

二、环境要求

安装 PaddlePaddle 前务必先到官方安装页按你的操作系统与 CUDA 版本生成精确安装命令：https://www.paddlepaddle.org.cn/install/quick 。

三、部署方式

3.1 方式一：pip 安装（CPU，最快上手）

# 1) 创建并激活虚拟环境（推荐）
python3 -m venv pnlp_env && source pnlp_env/bin/activate

# 2) 先安装飞桨框架（CPU 版，国内镜像源）
pip install paddlepaddle -i https://mirror.baidu.com/pypi/simple

# 3) 安装 PaddleNLP 3.0 Beta4（README 官方命令）
pip install --upgrade paddlenlp==3.0.0b4

版本说明：截至本文写作时，PyPI 上 paddlenlp 的最新稳定版为 2.8.1；GitHub 最新 Release 标签为 v3.0.0-beta3，而 README（develop 分支）已发布 3.0 Beta4（对应 PyPI 预发布版 3.0.0b4）。生产环境请固定明确版本号，不要省略 == 直接 pip install paddlenlp。

验证安装：

python -c "import paddle; print(paddle.__version__)"
python -c "import paddlenlp; print(paddlenlp.__version__)"

3.2 方式二：GPU 安装（CUDA）

先在官方安装页（https://www.paddlepaddle.org.cn/install/quick ）选择「GPU 版 + 你的 CUDA 版本」，复制生成的命令执行，例如（以官网生成命令为准，勿照抄此示例版本号）：

pip install paddlepaddle-gpu==3.0.0rc1 -i https://www.paddlepaddle.org.cn/packages/stable/cu118/
pip install --upgrade paddlenlp==3.0.0b4

验证 GPU 可用：

python -c "import paddle; paddle.utils.run_check()"   # 出现 PaddlePaddle is installed successfully 即正常

3.3 方式三：源码安装（体验 develop 分支 / 二次开发）

git clone https://github.com/PaddlePaddle/PaddleNLP.git
cd PaddleNLP
# 安装最新 develop 分支预发布版（README 官方命令）
pip install --pre --upgrade paddlenlp -f https://www.paddlepaddle.org.cn/whl/paddlenlp.html

或者以可编辑模式安装仓库源码（修改源码调试用）：

cd PaddleNLP
python -m pip install -e .

源码安装适合需要修改 Trainer/推理引擎源码、复现官方 README 中预训练/精调脚本（llm/run_pretrain.py、llm/run_finetune.py）或体验最新模型（如 Qwen3 系列）的场景。

3.4 方式四：官方推理部署镜像（服务化）

PaddleNLP 3.0 提供「热门模型一键部署」的推理部署镜像，官方文档：llm/server（通用模型部署示例：general_model_inference.html）。典型流程（以官方文档为准）：

# 拉取官方推理镜像（镜像 tag 与模型组合以官方文档为准，勿照抄）
docker pull registry.baidubce.com/paddlenlp/llm-inference:latest

# 启动推理服务并挂载模型权重目录（端口、显存参数以官方文档为准）
nvidia-docker run -it --name pnlp-llm-server \
  -p 8000:8000 \
  -v /your/model/path:/models \
  registry.baidubce.com/paddlenlp/llm-inference:latest bash

具体可用镜像列表、启动脚本与 OpenAI 兼容 API 端口均以官方「推理部署」文档（paddlenlp.readthedocs.io/zh/latest/llm/docs/predict/）为准。

3.5 方式五：快速体验（AI Studio 在线环境，零安装）

不想本地装环境的开发者，可直接在百度 AI Studio（免费算力平台）打开官方交互式教程，按 Notebook 逐格执行：

• 入口：https://aistudio.baidu.com/aistudio/personalcenter/thirdview/574995
• 特点：预装 PaddlePaddle 与 PaddleNLP 依赖，提供免费 GPU 算力，适合跑通推理与微调流程后再迁移到本地。

3.6 验证部署成功（通用）

执行官方 README 的最小验证——加载 Qwen2-0.5B 并生成一句文本（首次运行会自动下载模型，需要网络）：

from paddlenlp.transformers import AutoTokenizer, AutoModelForCausalLM

tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen2-0.5B")
# CPU 环境请将 dtype="float16" 改为 "float32"
model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen2-0.5B", dtype="float16")
inputs = tokenizer("你好！请自我介绍一下。", return_tensors="pd")
outputs = model.generate(**inputs, max_new_tokens=128)
print(tokenizer.batch_decode(outputs[0], skip_special_tokens=True))

终端输出包含一段通顺的中文回复（如「我是一个 AI 语言模型，我可以回答各种问题……」）即部署成功。

四、使用方法

4.1 基础用法：Auto API 文本生成

from paddlenlp.transformers import AutoTokenizer, AutoModelForCausalLM

# 加载分词器与因果语言模型（模型名与 Hugging Face 仓库同名，如 Qwen/Qwen2.5-7B-Instruct）
tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen2-0.5B")
# dtype 可选 float16 / bfloat16 / float32；CPU 用 float32
model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen2-0.5B", dtype="float16")

# 对话式推理（chat 模板）
messages = [
    {"role": "user", "content": "用一句话解释什么是自动驾驶。"}
]
inputs = tokenizer.apply_chat_template(messages, tokenize=True, return_tensors="pd")
outputs = model.generate(**inputs, max_new_tokens=128, temperature=0.7)
print(tokenizer.batch_decode(outputs[0], skip_special_tokens=True))

4.2 常用命令与脚本

一行代码快速微调（无需 clone 源码）

from paddlenlp.trl import SFTConfig, SFTTrainer
from datasets import load_dataset

dataset = load_dataset("ZHUI/alpaca_demo", split="train")

training_args = SFTConfig(output_dir="Qwen/Qwen2.5-0.5B-SFT", device="gpu")
trainer = SFTTrainer(
    args=training_args,
    model="Qwen/Qwen2.5-0.5B-Instruct",
    train_dataset=dataset,
)
trainer.train()

源码方式：预训练

git clone https://github.com/PaddlePaddle/PaddleNLP.git && cd PaddleNLP
mkdir -p llm/data && cd llm/data
wget https://bj.bcebos.com/paddlenlp/models/transformers/llama/data/llama_openwebtext_100k.bin
wget https://bj.bcebos.com/paddlenlp/models/transformers/llama/data/llama_openwebtext_100k.idx
cd ..   # 回到 PaddleNLP/llm
python -u run_pretrain.py ./config/qwen/pretrain_argument_0p5b.json

源码方式：SFT 精调

git clone https://github.com/PaddlePaddle/PaddleNLP.git && cd PaddleNLP
mkdir -p llm/data && cd llm/data
wget https://bj.bcebos.com/paddlenlp/datasets/examples/AdvertiseGen.tar.gz && tar -zxvf AdvertiseGen.tar.gz
cd ..   # 回到 PaddleNLP/llm
python -u run_finetune.py ./config/qwen/sft_argument_0p5b.json

常用配置项（JSON 配置文件节选，以仓库实际为准）

Python 加载量化模型推理

from paddlenlp.transformers import AutoTokenizer, AutoModelForCausalLM

# 以 INT8 量化方式加载（低显存场景；量化类型以官方对应模型文档为准）
tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen2.5-1.5B-Instruct")
model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen2.5-1.5B-Instruct",
    dtype="float16",
    quantization="weight_only_int8",
)
inputs = tokenizer("介绍一下甘肃陇南的特色美食。", return_tensors="pd")
outs = model.generate(**inputs, max_new_tokens=128)
print(tokenizer.batch_decode(outs[0], skip_special_tokens=True))

支持的量化类型（WINT8 / WINT4 / INT8-A8W8 / FP8-A8W8 等）随模型系列不同，详见 README「模型推理支持列表」与官方各模型文档页。

4.3 进阶功能

• LoRA / PEFT 参数高效微调：官方支持 LoRA、Prefix Tuning（README 模型矩阵标注 ✅），适合单卡低显存场景。
• 对齐训练：DPO / SimPO / ORPO / KTO 与 RLHF PPO（3.0 Beta 起 PPO 引入高性能生成加速），详见 paddlenlp.trl。
• 量化推理：DeepSeek V3/R1 完整版支持 FP8、INT8、4-bit 量化与 MTP 投机解码；官方宣称单机 FP8 推理输出超 1000 tokens/s、4-bit 超 2100 tokens/s。
• Unified Checkpoint：训练断点支持机器资源动态扩缩容恢复，Checkpoint 压缩节省 78.5% 空间。
• PP-UIE 信息抽取：8192 Token 长文档零样本信息抽取，模型见 paddlenlp/PP-UIE-0.5B/1.5B/7B/14B。
• MergeKit 模型融合：缓解对齐代价，用法见官方文档 llm/docs/mergekit.html。
• RAG 支持：FlashRAG-Paddle 基于 PaddleNLP 构建检索增强应用，推理性能较 Transformers 动态图提升 70% 以上。
• AI Studio 在线教程：无需本地 GPU，在免费算力平台上手。

4.4 适用场景

• 企业级大模型精调与对齐：基于开源基座（Qwen、Llama、DeepSeek）训练行业专属模型；
• 大模型高性能推理服务化：单机/多卡部署热门模型，对外提供 OpenAI 兼容接口；
• 低成本硬件适配：昆仑芯、昇腾等国产芯片上的训推一体；
• 长文档信息抽取（PP-UIE）：合同、财报、卷宗的关键信息抽取；
• 知识问答/RAG 应用：结合向量检索构建企业知识库；
• 教学与科研：AI Studio 免费算力上复现 4D 并行、量化、对齐全流程。

本教程版本基准：README 基于 develop 分支（v3.0 Beta4）；GitHub 最新 Release 标签为 v3.0.0-beta3，PyPI 稳定版为 2.8.1。不同版本 API 差异较大，操作前请核对文档站版本。

五、常见问题排查（FAQ）

Q1：安装时报错 Could not find a version that satisfies the requirement paddlenlp==3.0.0b4 - 原因：pip 未启用预发布版索引，或网络无法访问 PyPI 预发布包。 - 解决：确认 pip 版本较新；或改用官方预发布索引：pip install --pre --upgrade paddlenlp -f https://www.paddlepaddle.org.cn/whl/paddlenlp.html；网络受限时加 -i https://mirror.baidu.com/pypi/simple。

Q2：import paddle 失败或提示 paddlepaddle is not installed - 原因：PaddleNLP 依赖飞桨框架，只装 paddlenlp 不够。 - 解决：先按官方安装页安装 paddlepaddle（CPU）或 paddlepaddle-gpu（GPU），再装 paddlenlp。

Q3：GPU 推理报显存不足（OOM） - 原因：BF16/FP16 全精度加载大模型超出显存。 - 解决：① 换用量化加载（int8/int4/fp8，以官方推理文档为准）；② 减小 max_length / batch；③ 开启张量并行（多卡）；④ 小显存先用 0.5B/1.5B/7B 模型验证流程。

Q4：CPU 上运行报半精度（float16）算子错误或极慢 - 原因：CPU 不支持 float16 推理。 - 解决：from_pretrained(..., dtype="float32")；并降低 max_new_tokens 测试。

Q5：首次运行模型下载失败/超时 - 原因：默认模型源（Hugging Face）网络不通或大文件下载中断。 - 解决：使用国内镜像源环境变量（如 HF_ENDPOINT=https://hf-mirror.com），或从 AI Studio 手动下载模型权重后指定本地路径加载。

Q6：paddle.utils.run_check() 失败 / 提示 CUDA 不可用 - 原因：GPU 版 paddlepaddle 与系统 CUDA、驱动版本不匹配。 - 解决：按 nvidia-smi 确认驱动与 CUDA 版本，回到官方安装页重新生成对应 cu 版本的安装命令；确认安装的是 paddlepaddle-gpu 而非 paddlepaddle。

Q7：源码训练脚本报错缺少 fused_ln 等外部算子 - 原因：README 注释说明，使用 use_fused_rms_norm=true 前需安装外部算子。 - 解决：按 README 提示前往 slm/model_zoo/gpt-3/external_ops 安装 fused_ln；或先关闭该配置跑通流程。

Q8：Windows 下控制台中文输出乱码 - 解决：设置 set PYTHONIOENCODING=utf-8；代码文件保存为 UTF-8；必要时输出重定向到文件查看。

Q9：加载模型时报 connect timed out / SSLError - 原因：默认从 Hugging Face Hub 拉取权重，国内网络不稳定。 - 解决：① 设置镜像：export HF_ENDPOINT=https://hf-mirror.com；② 或在 AI Studio / ModelScope 手动下载模型文件夹后，将 from_pretrained("Qwen/Qwen2-0.5B") 的参数换成本地目录路径。

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

1. 框架与套件版本严格匹配：PaddleNLP 3.0 Beta 要求 PaddlePaddle >= 3.0.0rc1；2.x 时代的 paddlenlp（2.8.1）与 3.0 Beta API 不兼容（如 paddlenlp.trl、SFTTrainer 为 3.0 新接口），升级前读官方迁移文档。
2. 先验证 GPU 环境：装好 paddlepaddle-gpu 后立即 paddle.utils.run_check()，不要等到训练几小时后才发现用了 CPU。
3. 模型权重走受控下载：大模型权重（7B BF16 约 14GB+）下载慢，建议用 AI Studio/ModelScope 国内源或预先下载到共享目录，避免每台机器重复下载。
4. 生产服务化用官方镜像：不要直接把 Python 脚本当服务长期跑；用 llm/server 官方推理镜像，开启模型常驻、并发与量化。
5. 显存预算：全参微调 7B 模型建议单卡 >= 24GB（BF16）；LoRA 可在 16GB 完成；千亿模型必须多卡 4D 并行，具体配置以官方对应模型文档为准。
6. Checkpoint 管理：使用 Unified Checkpoint 保存断点，定期备份；磁盘空间不足时开启 Checkpoint 压缩（官方称省 78.5%）。
7. 数据合规：训练涉及身份证、对话等敏感数据时注意数据安全与合规要求。
8. 关注版本节奏：PaddleNLP 3.0 仍在 Beta 阶段，模型支持列表与 API 迭代快，使用前确认所用版本对应文档（readthedocs 可切换版本）。

七、参考资料

• GitHub 仓库：https://github.com/PaddlePaddle/PaddleNLP
• 官方文档站：https://paddlenlp.readthedocs.io/zh/latest/
• 大模型套件（llm）说明：https://github.com/PaddlePaddle/PaddleNLP/tree/develop/llm
• 安装教程：https://github.com/PaddlePaddle/PaddleNLP/blob/develop/docs/zh/get_started/installation.rst
• PaddlePaddle 官方安装页：https://www.paddlepaddle.org.cn/install/quick
• 推理部署文档：https://paddlenlp.readthedocs.io/zh/latest/llm/docs/predict/index.html
• 服务化部署（llm/server）：https://paddlenlp.readthedocs.io/zh/latest/llm/server/README.md
• Unified Checkpoint：https://github.com/PaddlePaddle/PaddleNLP/blob/develop/llm/docs/unified_checkpoint.md
• AI Studio 交互式教程：https://aistudio.baidu.com/aistudio/personalcenter/thirdview/574995
• Release 下载：https://github.com/PaddlePaddle/PaddleNLP/releases
• PyPI 页面：https://pypi.org/project/paddlenlp/