⚙️ 先决条件：硬件与软件基线
💻 硬件：仅支持特定加速卡
DeepInfer 官方支持的硬件非常集中：
-
NVIDIA SM100 GPU（即 Blackwell 架构，如 B200）
-
华为昇腾 950 NPU
这意味着常见的 A100、H100、RTX 4090/5090 等均不在官方支持范围内。社区有实测使用 4×B200 的案例，但那是在改写了 RDMA 依赖之后才跑通的。
🐧 操作系统与工具链
官方 Prerequisites 只写了"Linux"，但结合构建要求与社区实践，实际基线如下：
| 项目 | 要求 | 说明 |
|---|---|---|
| 操作系统 | Ubuntu 22.04 或任何 glibc ≥ 2.31 的 Linux | Ubuntu 22.04 是社区验证最充分的起点 |
| GCC | ≥ 13.0 | 这是硬性门槛，低于 13 会直接导致 C++ 扩展编译失败 |
| Python | 恰好 3.12（fresh empty environment） | 版本不匹配会立即失败，建议从干净 venv 开始 |
| NVIDIA 侧 | CUDA 13 | 需搭配 SM100 GPU |
| 昇腾侧 | CANN 9.2 | 需搭配昇腾 950 NPU |
注意 ：网上存在一个同名的
sepine/DeepInfer旧项目（基于 PyTorch 1.11 + CUDA 11.3），与 DeepSeek 的 DeepInfer 完全无关，切勿混用。
🚀 从源码构建（以 Ubuntu 22.04 + NVIDIA 为例）
📦 安装系统级构建依赖
在 Ubuntu 22.04 上，以下命令已被社区实践验证可行：
bash
sudo apt-get update
sudo apt-get install -y build-essential cmake libprotobuf-dev protobuf-compiler如果系统默认的 GCC 版本低于 13，需要通过 apt 安装 gcc-13/g++-13，或使用 update-alternatives 切换默认编译器。
🐍 创建并激活 Python 3.12 环境
官方明确要求使用空的 Python 3.12 环境，以避免已有包干扰构建：
bash
python3.12 -m venv ~/deepinfer-venv
source ~/deepinfer-venv/bin/activate📥 克隆仓库并导出加速器变量
bash
git clone https://github.com/deepseek-ai/DeepInfer.git
cd DeepInfer
export DEEPINFER_ACCELERATOR=nvidia # 昇腾平台则使用 ascend这是部署中最容易踩的坑之一 ：
DEEPINFER_ACCELERATOR必须在执行构建的 shell 以及后续运行推理的每一个 shell 中都保持导出状态。如果中间切换终端忘记重新导出，框架会静默加载错误的后端。
🔨 执行构建脚本
bash
./build.shbuild.sh 会处理 CMake 配置和原生库编译。如果构建失败，首要排查项就是 GCC 是否 ≥ 13 以及 Python 是否精确为 3.12------这两项不满足时，C++ 扩展会在编译初期直接报错退出。
🧠 模型权重的获取与指定
DeepInfer 目前只支持 DeepSeek-V4.1-Flash ，默认检查点为 deepseek-ai/DeepSeek-V4.1-Flash-1017。
🔄 方式一：首次运行自动从 Hugging Face 拉取
如果机器可以访问 Hugging Face，无需手动下载。直接运行离线推理示例时，权重会自动下载到 Hugging Face 缓存目录：
bash
python examples/offline_inference.py📂 方式二：指定本地权重目录（推荐用于离线/内网环境）
如果已经将权重下载到本地，通过环境变量指向该目录即可跳过自动下载：
bash
export DEEPINFER_HF_MODEL_DIR=/path/to/DeepSeek-V4.1-Flash-1017
python examples/offline_inference.py✅ 启动验证：运行离线推理示例
在完成构建和权重指定后，用官方示例做冒烟测试是最直接的验证方式：
bash
export DEEPINFER_ACCELERATOR=nvidia
export DEEPINFER_HF_MODEL_DIR=/path/to/DeepSeek-V4.1-Flash-1017 # 如使用本地权重
python examples/offline_inference.py如果终端开始正常输出推理结果，说明构建、后端加载和权重读取的整条链路已经打通。示例目录中还有 _structured_output.py 等脚本，可用于验证结构化输出等附加能力。
🔧 关键环境变量速查
除了构建时必需的 DEEPINFER_ACCELERATOR，以下变量在调优和功能启用时常用：
| 环境变量 | 作用 |
|---|---|
DEEPINFER_ACCELERATOR |
必填 ，nvidia 或 ascend，决定加载哪个后端 |
DEEPINFER_HF_MODEL_DIR |
指定本地权重路径，替代从 Hugging Face 下载 |
DEEPINFER_ENABLE_MTP_VARLEN=1 |
启用 DSpark 投机解码 |
DEEPINFER_USE_NEXTN_DECODE |
控制最大草稿长度（默认 5） |
DEEPINFER_YOCO_PREFILL_TRUNCATION_MODE=compact |
V4.1 的 SWA Bounded Replay 默认配置 |
DEEPINFER_YOCO_PREFILL_KEEP_TOKENS=140 |
SWA 保留后缀 token 数（V4.1 默认） |
DEEPINFER_BATCH_INVARIANT=1 |
启用批不变推理（仅 NVIDIA） |
🚨 常见陷阱与故障排查
| 现象 | 最可能的原因 | 处理方式 |
|---|---|---|
| 构建脚本立即失败 | GCC < 13 或 Python 不是 3.12 | 确认 gcc --version ≥ 13，Python 精确为 3.12，并使用干净的 venv |
| 运行时行为异常，但无明确报错 | DEEPINFER_ACCELERATOR 在当前 shell 中未导出 |
在每一个 执行 DeepInfer 的终端中重新 export |
| 无法启动，提示网络/RDMA 相关错误 | 官方默认实现依赖 GPUDirect RDMA 读取 Engram 表 | 单机或非 RDMA 环境需参考社区的去 RDMA 化改造方案，用共享内存替代 RDMA 取数 |
| 怀疑装错了项目 | 混入了 sepine/DeepInfer |
确认克隆的是 github.com/deepseek-ai/DeepInfer，而不是同名旧仓库 |
🔗 多卡并行配置要点
DeepInfer 的并行策略按阶段分化，开源离线版本的最小有效多卡单元与生产环境不同：
-
Prefill 阶段 ：EP 取 2～8，显存够用就尽量取小并行度。
-
Decode 阶段 ：采用 Wide-EP ，即 64～128 路专家并行，卡有余量就往大了开。
官方生产环境的最小部署单元是 64 卡 Prefill + 64 卡 Decode ，但这不代表开源离线版本必须在这个规模下才能跑通。社区已验证 4×B200 在 EP4 配置下可以在改写 RDMA 依赖后完成离线推理和基准测试，代价是单卡吞吐比官方 EP8/EP64 配置低约 25%。对于验证性部署或小规模离线推理，可以从单机多卡、较小的 EP 度起步。
⚠️ 部署前必须知道的范围限制
本次开源的 DeepInfer 是离线推理核心 ，以下生产级组件不包含在发布中：
-
KV 缓存系统（完整的多级缓存管理）
-
VE / Prefill / Decode 分离部署的完整编排（引擎侧大部分功能已实现，但服务化编排不在内）
-
跨数据并行副本的负载均衡（Prefill 与 Decode 两侧的负载均衡器均未开源）