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

ERNIE（文心）是百度开源的大模型家族仓库，当前主线为 ERNIE 4.5：一套包含 10 个变体的大规模多模态模型家族，涵盖 MoE 大语言模型（最大 424B 总参 / 47B 激活）、视觉-语言模型（VLM）与 0.3B 稠密小模型，全部权重以 Apache-2.0 协议公开。仓库同时提供工业级训练工具包 ERNIEKit（SFT / LoRA / DPO / QAT）与高性能推理部署方案 FastDeploy，形成「下载模型 → 训练微调 → 推理上线」的完整闭环。

目录

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

一、项目概述

1.1 项目定位

ERNIE 仓库是百度文心大模型的官方开源入口。与「只放权重」的仓库不同，它把三样东西打包在一起：

1. 模型权重：ERNIE 4.5 全系 10 个模型的预训练权重与推理代码，全部托管在 HuggingFace（huggingface.co/baidu）与百度 AI Studio；
2. ERNIEKit：基于 PaddlePaddle 的工业级训练与压缩工具包，支持全参数 SFT、LoRA 微调、DPO 对齐、QAT 量化感知训练；
3. FastDeploy：高性能推理部署工具（独立仓库 PaddlePaddle/FastDeploy），提供离线推理与 OpenAI 兼容 API 服务。

官方定位很明确：用 PaddlePaddle 框架训练和推理 ERNIE 4.5 全系模型，在 NVIDIA 及多类国产硬件上获得生产级性能。

1.2 核心功能（ERNIE 4.5 模型族，以官方 README 为准）

ERNIE 4.5 共 10 个模型变体，统一支持 128K 上下文窗口：

其他要点：

• 异构多模态 MoE 架构：MoE 中 47B 总参、3B 激活的配置，同时支持模态间参数共享与模态专属参数；视觉-语言模型支持 Thinking / 非 Thinking 双模式。
• 高性能训练：异构混合并行 + 分层负载均衡，FP8 混合精度，官方公布最大模型预训练 MFU 达 47%。
• 推理优化：多专家并行协作、卷积码量化（支持 4-bit / 2-bit 无损量化）、PD 分离（Prefill/Decode 分离）动态角色切换。
• 训练工具链 ERNIEKit：SFT、SFT-LoRA、DPO、DPO-LoRA、QAT、PTQ（开发中），覆盖 ERNIE-4.5 全系及 VL 系列（28B/424B VL 支持 WebUI 训练与对话）。
• 推理部署 FastDeploy：BF16 / W4A16C16 / W8A16C16 / W4A8C8 / FP8 / 2Bits 多档量化精度，OpenAI 兼容 API 服务，vLLM 兼容。
• 官方 Cookbook：对话应用、联网搜索对话、知识库问答、SFT/DPO 教程、文本识别/文档翻译/合同信息抽取（与 PaddleOCR 组合）等 10 个 Notebook 示例。

1.3 技术架构

下图是官方发布的 ERNIE 4.5 语言模型 benchmark 对比表（0.3B / 21B-A3B 与 Qwen3-30B-A3B 在 General、Knowledge、Instruction Following、Math、Reasoning、Coding 等维度的对照）：

下图是官方发布的 ERNIE 4.5-VL 多模态模型在非 Thinking 模式下的 benchmark 对比（视觉知识、文档与图表、多模态推理、视觉感知、视频理解五个维度，对比 Qwen2.5-VL 7B/32B/72B）：

二、环境要求

重要：不同模型的「最低硬件要求」官方写在 docs/erniekit.md 中，不要按 0.3B 的经验直接上 300B。先读对应模型在 HuggingFace 模型卡上的硬件说明，再准备机器。

模型选型速查（按你的资源对号入座）：

三、部署方式

下面给出三种用途对应的路径：① 下载模型权重（推理起步）→ ② 安装 ERNIEKit（训练/微调）→ ③ 安装 FastDeploy（高性能推理服务）。

3.1 方式一：下载模型权重（所有用法的第一步）

以最小的 ERNIE-4.5-0.3B-Paddle 为例：

# 1) 安装 HuggingFace 命令行
pip install -U huggingface_hub

# 2) 下载模型到本地目录（首次运行会下载全部权重，耐心等待）
huggingface-cli download baidu/ERNIE-4.5-0.3B-Paddle --local-dir baidu/ERNIE-4.5-0.3B-Paddle

国内网络访问 HuggingFace 慢时，两个替代方案：

# 方案 A：使用 HF 镜像端点
export HF_ENDPOINT=https://hf-mirror.com
huggingface-cli download baidu/ERNIE-4.5-0.3B-Paddle --local-dir baidu/ERNIE-4.5-0.3B-Paddle

# 方案 B：改用百度 AI Studio 下载（在 AI Studio 模型页找到对应模型，按页面指引）

模型名规则：仓库 README 给出的官方列表是 ERNIE-4.5-300B-A47B(-Base)、ERNIE-4.5-21B-A3B(-Base)、ERNIE-4.5-VL-424B-A47B(-Base)、ERNIE-4.5-VL-28B-A3B(-Base)、ERNIE-4.5-0.3B(-Base)；HuggingFace 上对应仓库名一般带 -Paddle 后缀（如 ERNIE-4.5-0.3B-Paddle）。下载前在 huggingface.co/baidu 核对完整仓库名，不要臆造。

3.2 方式二：安装 ERNIEKit（训练/微调）

# 1) 拉取本仓库（默认分支即 ERNIEKit 主线）
git clone https://github.com/PaddlePaddle/ERNIE.git
cd ERNIE

# 2) 安装 ERNIEKit 及其依赖（按仓库 docs/erniekit.md 的最新说明执行）
pip install -e .
# 或按官方文档指定的安装方式（以 docs/erniekit.md 为准）

安装成功后验证：

erniekit --help

能看到 train、WebUI 等子命令输出即安装成功。

3.3 方式三：安装 FastDeploy（推理部署）

FastDeploy 是独立仓库：

# 按 FastDeploy 官方仓库 README 安装（独立仓库，以其最新说明为准）
# https://github.com/PaddlePaddle/FastDeploy
pip install -U fastdeploy

3.4 验证部署成功

# 1) 权重已就位
ls baidu/ERNIE-4.5-0.3B-Paddle/
# 预期看到配置文件、权重分片（model-*.safetensors 或 .pdparams）等

# 2) ERNIEKit 可用
erniekit --help

# 3) FastDeploy 可导入
python -c "import fastdeploy; print(fastdeploy.__version__)"

再跑一次最小推理（见 4.1），能出文本即整条链路通。

四、使用方法

4.1 基础用法：离线推理（FastDeploy）

from fastdeploy import LLM, SamplingParams

prompt = "Write me a poem about large language model."
sampling_params = SamplingParams(temperature=0.8, top_p=0.95)

llm = LLM(model="baidu/ERNIE-4.5-0.3B-Paddle", max_model_len=32768)

outputs = llm.generate(prompt, sampling_params)
print(outputs)

说明：

• model= 既可以填 HuggingFace 仓库名（自动下载），也可以填方式一下载好的本地路径；
• max_model_len 控制最大上下文长度，按显存调整；
• 换成更大模型时，把 model 换成 baidu/ERNIE-4.5-21B-A3B-Paddle 等对应仓库名即可。

4.2 在线服务：OpenAI 兼容 API

python -m fastdeploy.entrypoints.openai.api_server \
    --model "baidu/ERNIE-4.5-0.3B-Paddle" \
    --max-model-len 32768 \
    --port 9904

启动后，服务暴露 OpenAI 兼容接口（/v1/chat/completions 等），可直接用 OpenAI SDK 改 base_url 调用：

from openai import OpenAI

client = OpenAI(base_url="http://localhost:9904/v1", api_key="not-needed")
resp = client.chat.completions.create(
    model="ERNIE-4.5-0.3B-Paddle",
    messages=[{"role": "user", "content": "你好，介绍一下你自己"}],
)
print(resp.choices[0].message.content)

4.3 进阶：用 ERNIEKit 做 SFT 微调

官方一键流程：

# 1) 下载模型
huggingface-cli download baidu/ERNIE-4.5-0.3B-Paddle --local-dir baidu/ERNIE-4.5-0.3B-Paddle

# 2) 8K 序列长度 SFT（使用仓库内置示例配置）
erniekit train examples/configs/ERNIE-4.5-0.3B/sft/run_sft_8k.yaml

其他能力入口：

• LoRA 微调 / DPO 对齐：示例配置同样在 examples/configs/ 对应模型目录下，把 erniekit train 的配置文件换成对应 yaml（SFT-LoRA / DPO / DPO-LoRA）；
• VL 模型训练：ERNIE-4.5-VL 系列（含 Thinking 变体）的 SFT 与 function call 训练，见仓库 News 中对应版本说明与 docs/ 文档；
• WebUI：官方提供训练与对话 WebUI（支持 28B/424B VL 模型），启动方式见 docs/erniekit.md；
• 多机训练与高级功能：多节点训练、AutoParallel、padding-free 等特性，均在 docs/erniekit.md 中。

4.3.1 量化部署速查

官方 README 给出的推理精度档位（符号 WxAxCx：权重/激活/KV Cache 精度）：

具体在 FastDeploy 中如何选择量化参数，以 FastDeploy 仓库对应模型（如 ERNIE-4.5-21B-A3B）模型卡的说明为准。

4.4 官方 Cookbook 应用示例

仓库 cookbook/ 目录提供 Notebook 与可运行脚本：

4.5 适用场景

• 私有化部署的国产大模型底座（Apache-2.0 可商用，中文能力强）；
• 基于 ERNIE 4.5 的二次微调（行业 SFT、DPO 对齐）；
• 多模态文档理解（VL 系列支持图片/视频输入，配合 PaddleOCR）；
• 高吞吐在线推理服务（FastDeploy 的 OpenAI 兼容接口 + 量化部署）；
• 国产硬件适配的大模型落地（PaddlePaddle 全栈）。

五、常见问题排查（FAQ）

Q1：huggingface-cli download 卡住或超时 - 原因：国内访问 HuggingFace 官方 CDN 不稳定。 - 解决：export HF_ENDPOINT=https://hf-mirror.com 走镜像；或直接在百度 AI Studio 模型页下载权重；大模型建议配合 hf_transfer（pip install hf_transfer 并 export HF_HUB_ENABLE_HF_TRANSFER=1）加速。

Q2：加载 21B/300B 模型报 CUDA out of memory - 原因：单卡显存放不下 BF16 全量权重。 - 解决：① 换量化精度（W4A16C16 / W8A16C16 等，FastDeploy 支持）；② 多卡张量并行；③ 先用 0.3B 小模型验证流程。

Q3：import fastdeploy 失败或版本与 PaddlePaddle 不匹配 - 原因：FastDeploy 与 PaddlePaddle 版本有配套要求。 - 解决：先按官方安装页装好 GPU 版 PaddlePaddle，再按 FastDeploy README 指定的版本安装；不要混用 CPU 版框架。

Q4：erniekit train 报配置文件找不到 - 原因：不在 ERNIE 仓库根目录执行，或分支不对。 - 解决：cd 到刚 clone 的 ERNIE 仓库根目录执行；确认在正确分支（默认主线）；配置文件路径以仓库 examples/configs/ 实际内容为准。

Q5：模型下载下来是 HuggingFace 格式（safetensors），PaddlePaddle 能直接用吗？ - 说明：官方提供的就是 -Paddle 后缀仓库（如 ERNIE-4.5-0.3B-Paddle），权重与推理代码都是 PaddlePaddle 原生格式，FastDeploy 可直接加载；不要把非 -Paddle 仓库的权重硬塞进来。

Q6：多卡训练时 NCCL / 通信报错 - 解决：确认多卡/多机网络互通、CUDA 与 NCCL 版本配套；先在单卡跑通 0.3B 示例配置，再放大到多卡。

Q7：在线服务端口 9904 被占用或外部访问不了 - 解决：换 --port ；服务器上需安全组放行端口；生产环境前置 Nginx + HTTPS。

Q8：VL 模型（图片/视频输入）推理报错 - 原因：多模态输入预处理依赖与纯文本不同。 - 解决：使用 FastDeploy 的 VLM 加载接口（参数与示例见 FastDeploy 官方 VL 文档），不要直接套纯文本 LLM 的调用方式。

Q9：模型权重下载到一半磁盘满了 - 原因：大模型权重是几十个分片（动辄几十到几百 GB）。 - 解决：先 df -h 确认目标盘剩余；下载支持断点续传，补磁盘后重新执行同一命令即可；缓存默认在 ~/.cache/huggingface，空间不够时用 --local-dir 直接下到大盘。

Q10：想把 ERNIE 接到自己的 OpenAI 生态应用（如 Dify、NextChat） - 做法：按 4.2 启动 FastDeploy OpenAI 兼容服务，把应用的 API Base URL 指向 http://<服务器IP>:9904/v1，模型名填 baidu/ERNIE-4.5-0.3B-Paddle 即可，无需改业务代码。

Q11：SFT 训练 Loss 不下降 / 输出乱码 - 原因：数据格式与训练配置不匹配，或学习率设置过大。 - 解决：先确认训练数据格式符合 ERNIEKit 要求（conversation 格式）；从官方示例 yaml 出发逐项改参数；先用小数据集跑通再放大。

Q12：Windows 下能否跑 ERNIE 训练？ - 说明：官方训练（ERNIEKit）与多卡推理以 Linux 为主；Windows 用户建议用 WSL2 或远程 Linux 服务器，不要在原生 Windows 硬跑多卡任务。

Q13：部署后想监控 Token 用量与延迟，怎么做？ - 做法：FastDeploy 的 OpenAI 兼容接口在响应中携带 usage 信息；接入网关时记录每次请求的 prompt/completion Token 数与首包延迟，按天聚合即可。

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

1. 模型选择要务实：个人开发者/小团队从 ERNIE-4.5-0.3B 起步，21B-A3B 是单卡/多卡的平衡点，300B/424B 属于集群级资源，先算清硬件账。
2. 权重磁盘预留：300B 级别模型权重本身数百 GB，下载缓存与工作副本要预留 2 倍以上空间，建议挂大盘。
3. 训练先读 erniekit.md：不同模型的最低硬件、并行策略、配置项都在 docs/erniekit.md，不要凭经验改 yaml。
4. 量化降本：推理上线优先 W4A16/W8A16 量化档，官方宣称 4-bit/2-bit 近无损，显存与吞吐收益巨大。
5. 版本配套：PaddlePaddle、ERNIEKit、FastDeploy 三者版本要对齐，升级前看各仓库 Release Notes。
6. 数据合规：微调语料与业务数据注意版权与合规要求；对外提供服务时保留模型使用记录。
7. Apache-2.0 可商用：ERNIE 4.5 全系权重 Apache-2.0 许可，允许商用，但需遵守许可证条款（保留版权声明等）。
8. 生产服务：FastDeploy 的 OpenAI 接口适合直接内网暴露，对外服务前加鉴权、限流、监控。
9. PD 分离：高并发在线场景建议开启官方推荐的 PD 分离（Prefill/Decode 分离部署），动态角色切换可显著提升大 MoE 模型的推理吞吐，配置见 FastDeploy 文档。
10. 关注版本节奏：ERNIEKit 迭代很快（v1.0→v1.5 不到半年），升级前看仓库 News 栏目确认新增模型支持与破坏性变更。

七、参考资料

• GitHub 仓库：https://github.com/PaddlePaddle/ERNIE
• HuggingFace 模型页（baidu 组织）：https://huggingface.co/baidu
• 百度 AI Studio 模型广场：https://aistudio.baidu.com/modelsoverview
• ERNIE 4.5 技术博客：https://yiyan.baidu.com/blog/posts/ernie4.5
• ERNIEKit 训练文档：https://github.com/PaddlePaddle/ERNIE/blob/release/v1.5/docs/erniekit.md
• FastDeploy 推理部署：https://github.com/PaddlePaddle/FastDeploy
• 官方 Cookbook 目录：https://github.com/PaddlePaddle/ERNIE/tree/release/v1.5/cookbook
• 预训练文档：https://github.com/PaddlePaddle/ERNIE/tree/release/v1.5/examples/pre-training
• Release 列表：https://github.com/PaddlePaddle/ERNIE/releases