PaddlePaddle/FastDeploy · 上手攻略

仓库：PaddlePaddle/FastDeploy
链接：https://github.com/PaddlePaddle/FastDeploy
分类：llm-infra / engineering（LLM/VLM 推理部署）
作者：spark
更新：2026-07-21

是什么

FastDeploy 是百度飞桨（PaddlePaddle）团队推出的"LLM + VLM 推理部署工具包"，主打工业级一键部署和国产芯片广覆盖。它的目标不是要替代 vLLM，而是站在 vLLM 接口的肩膀上，把 ERNIE、Qwen3、DeepSeek-V3、PaddleOCR-VL 等模型在 NVIDIA、昆仑芯 XPU、海光 DCU、天数 GPU、燧原 GCU、沐曦 GPU、英特尔 Gaudi 等多种硬件上跑出可生产的吞吐。

核心特性一览（取自官方 README）：

负载均衡式 PD 分离（Prefill/Decode Disaggregation）：工业级方案，支持上下文缓存与动态实例角色切换，优化 SLO 与资源利用率。
统一 KV 缓存传输：自动选择 NVLink/RDMA，跨节点 KV cache 同步。
OpenAI API 兼容 + vLLM 兼容接口：单命令拉起服务，已有的 vLLM/任何 OpenAI SDK 客户端可直接对接。
全量化格式：W8A16/W8A8/W4A16/W4A8/W2A16/FP8，覆盖从精度敏感到大模型压缩。
高级解码：投机解码、Multi-Token Prediction (MTP)、分块预填充（chunked prefill）、前缀缓存、全局 Cache 池化。
多硬件：NVIDIA / 昆仑 XPU / 海光 DCU / 天数 / 燧原 / 沐曦 / 英特尔 Gaudi。

最新稳定版本 v2.5.0（2026-03），新增 Qwen3-VL / Qwen3-VL MoE、W4AFP8 量化方法、强化学习训练链路支持、170+ bug 修复与性能优化。

解决什么问题

国产化卡能不能跑 LLM：信创/政企客户经常被迫在非 NVIDIA 硬件上跑模型，vLLM/SGLang 几乎只覆盖 NVIDIA，FastDeploy 把同一套部署配方搬到 7 类硬件。
PD 分离 + KV 缓存共享：长上下文/多轮对话场景下，prefill 和 decode 资源特征差异大，混部时互相抢资源导致 SLO 不达标；FastDeploy 的 PD 分离方案 + KV cache 传输允许实例角色动态切换与跨节点前缀共享。
ERNIE 一站式：自家 ERNIE-4.5/4.5-VL Thinking 系列模型从权转到服务，FastDeploy 是首选工具链。
HuggingFace 模型兼容：v2.2 之后开始兼容 HF 生态模型（DeepSeek V3、Qwen3-MoE 等），让用户可以在不重训的前提下迁移。

快速安装

环境要求：Linux x86_64、Python 3.10–3.12、GPU 驱动 ≥ 535、CUDA ≥ 12.3、CUDNN ≥ 9.5。预编译镜像仅支持 SM 80/86/89/90（A800/H800/L20/L40/4090）+ Python 3.10。

路线 A：Docker（最快）

# CUDA 12.6
docker pull ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/fastdeploy-cuda-12.6:2.5.0
docker run --gpus all -it --rm -p 8180:8180 \
  ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/fastdeploy-cuda-12.6:2.5.0

路线 B：pip + 飞桨源（推荐）

# 1) 装 paddlepaddle-gpu（CUDA 12.6 示意，CUDA 12.9 换 cu129）
python -m pip install paddlepaddle-gpu==3.3.1 \
  -i https://www.paddlepaddle.org.cn/packages/stable/cu126/

# 2) 装 fastdeploy-gpu（必须从 Paddle 源，不能用 pypi 默认源）
python -m pip install fastdeploy-gpu==2.5.0 \
  -i https://www.paddlepaddle.org.cn/packages/stable/cu126/ \
  --extra-index-url https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple

Nightly 版同理，只是把 stable 换成 nightly。

路线 C：源码编译（含预编译算子）

git clone https://github.com/PaddlePaddle/FastDeploy
cd FastDeploy
# 参数: 打包 wheel / Python 解释器 / 是否编 CPU / GPU 架构 / 是否用预编译算子
bash build.sh 1 python false [90] 1   # SM90 + 预编译算子
# 产物在 FastDeploy/dist/ 与 fastdeploy/model_executor/ops/gpu/

国产芯片（昆仑/海光/天数/燧原/沐曦/英特尔 Gaudi）走各自独立安装文档：

昆仑 XPU：docs/zh/get_started/installation/kunlunxin_xpu.md
海光 DCU：docs/zh/get_started/installation/hygon_dcu.md
天数 CoreX：docs/zh/get_started/installation/iluvatar_gpu.md
燧原 GCU：docs/zh/get_started/installation/Enflame_gcu.md
沐曦 GPU：docs/zh/get_started/installation/metax_gpu.md
英特尔 Gaudi：docs/zh/get_started/installation/intel_gaudi.md

验证安装：

import paddle
from paddle.jit.marker import unified
paddle.utils.run_check()    # 应输出 Running verify PaddlePaddle program ... success

核心用法

1) 拉起 OpenAI 兼容服务（最常用）

export ENABLE_V1_KVCACHE_SCHEDULER=1
python -m fastdeploy.entrypoints.openai.api_server \
  --model baidu/ERNIE-4.5-0.3B-Paddle \
  --port 8180 \
  --metrics-port 8181 \
  --engine-worker-queue-port 8182 \
  --max-model-len 32768 \
  --max-num-seqs 32

服务启动后会暴露：

http://0.0.0.0:8180/v1/chat/completions
http://0.0.0.0:8180/v1/completions
http://0.0.0.0:8181/metrics（Prometheus）
http://0.0.0.0:8180/health

直接用 OpenAI SDK：

import openai
client = openai.Client(base_url="http://0.0.0.0:8180/v1", api_key="null")
resp = client.chat.completions.create(
    model="null",
    messages=[{"role": "user", "content": "把李白的静夜思改写为现代诗"}],
    stream=True,
)
for chunk in resp:
    if chunk.choices[0].delta:
        print(chunk.choices[0].delta.content, end="")

2) 模型自动下载

如果 --model baidu/ERNIE-4.5-0.3B-Paddle 当前目录不存在，会自动去 AIStudio 拉预设模型（默认下载到 ~/xx），无需手动 git lfs pull。

3) 跑 VLM / 多模态

v2.5 起新增 Qwen3-VL、ERNIE-4.5-VL-28B-A3B-Thinking、PaddleOCR-VL-0.9B 等。ERNIE-4.5-VL-Thinking 部署详见 docs/zh/get_started/ernie-4.5-vl-thinking.md。

4) PD 分离部署 + KV 缓存传输

参考 docs/zh/features/disaggregated.md 与 docs/zh/online_serving/router.md。典型拓扑：Router 节点 + Prefill 节点池 + Decode 节点池 + 共享 KV 缓存传输层。

5) 量化

python -m fastdeploy.tools.quantize \
  --model baidu/ERNIE-4.5-0.3B-Paddle \
  --output_dir ./ernie-w4a16 \
  --quant_type w4a16

支持 W8A16/W8A8/W4A16/W4A8/W2A16/FP8（W4AFP8 是 v2.5 新增）。

6) 投机解码 / MTP

--enable-speculative-decoding 与 --enable-mtp，结合 EAGLE/MTP draft 模型可拿到 2×–3× 吞吐增益，详见 docs/zh/features/speculative_decoding.md。

典型适用场景

国产化栈 LLM 服务：信创/政企项目必须跑在昆仑、海光、天数、燧原等非 NVIDIA 卡上。
高并发在线推理：PD 分离 + KV cache 池化让单集群能扛住数十万 QPS 的长上下文请求。
ERNIE / 文心系列商业部署：自家模型原生支持，避免下游再换框架。
跨硬件一致性：同一份部署脚本能在 A100/H100 与国产卡之间切换，便于多供应商交付。
OCR-VL/文档智能：PaddleOCR-VL-0.9B 在 FastDeploy 上是文档解析场景的最佳实践路径之一。

坑与注意

必须用飞桨源：fastdeploy-gpu 不能从默认 PyPI 装；忽视 -i https://www.paddlepaddle.org.cn/... 会装到一个空壳 wheel。
预编译 wheel 限制多：仅 SM 80/90、CUDA 12.6、Python 3.10；其他架构需自编译（SM86/89 也支持，但要现编）。
驱动/CUDA 苛刻：驱动 ≥ 535、CUDA ≥ 12.3、CUDNN ≥ 9.5 都要对齐，老机器（Tesla P40/V100）跑不动。
PaddlePaddle vs PyTorch 模型权重：很多 HF 模型需要先转换到 Paddle 格式（paddlepaddle 系列模型），或确认 v2.2+ 已支持的 HF 直跑模型清单。
Stars/周增：仓库卡片 Stars 3701 / 周增 +0，仓库活跃但近期 star 增量一般；问题响应主要靠 GitHub Issue 与飞桨官方论坛。
PD 分离部署复杂：单 GPU 测试无意义，至少需要 4-8 张卡 + 共享存储 / RDMA 网络才能体现收益；中小规模直接 vLLM 即可。
License：Apache-2.0，但部分 ERNIE 模型权重有附加许可，商用前确认 model card。

与同类对比

维度	FastDeploy	vLLM	SGLang	TensorRT-LLM
国产硬件覆盖	★★★（7 类）	★	★	×
NVIDIA 单卡性能	★★	★★★	★★★	★★★
PD 分离 / KV 池化	★★★	★★（v1 拆分实验）	★★	★★
OpenAI API 兼容	★★★	★★★	★★★	★★
HuggingFace 模型兼容	★★（v2.2+）	★★★	★★★	★★
量化丰富度	★★★（W8A8/W4A16/W2A16/FP8）	★★	★★	★★★（TRT 原生）
易用门槛	★★（pip 源/驱动要求）	★★★	★★★	★

定位差异：FastDeploy 的真正护城河是国产硬件覆盖 + ERNIE 原生。如果只跑 NVIDIA，vLLM/SGLang 通常更顺手；如果客户要昆仑/海光卡 + ERNIE，FastDeploy 几乎无可替代。

一句话推荐

国产化硬件 / ERNIE 商业部署首选 FastDeploy；纯 NVIDIA 场景下它仍是合格的"vLLM 兼容替代品"，但不会比 vLLM 更强，请按客户卡型决策。

不确定处：v2.5 ReleaseNote 中提到的"强化学习训练支持"具体是 RLHF/RLAIF/GRPO 哪种未在 README 展开，需要点进 ReleaseNote 链接核对；W4AFP8 在不同模型上的精度损失官方未给出统一指标，留待实测。