docs: add README and Dockerfile for Biren BR166M vLLM
This commit is contained in:
Chranos
31
Dockerfile
Normal file
31
Dockerfile
Normal file
@@ -0,0 +1,31 @@
|
||||
# 基于壁仞官方 vLLM 推理镜像
|
||||
FROM git.modelhub.org.cn:9443/enginex/xc-llm-biren166m:26.01
|
||||
|
||||
# 镜像元信息
|
||||
LABEL maintainer="enginex"
|
||||
LABEL description="vLLM inference engine for Biren BR166M (SUPA) GPU"
|
||||
LABEL version="26.01"
|
||||
|
||||
# 设置工作目录
|
||||
WORKDIR /workspace
|
||||
|
||||
# 复制壁仞适配代码
|
||||
COPY vllm_br/ /workspace/vllm_br/
|
||||
|
||||
# 如果需要覆盖基础镜像中的 vllm（按需启用）
|
||||
# COPY vllm/ /workspace/vllm/
|
||||
|
||||
# 确保 vllm_br 可被 Python 发现
|
||||
ENV PYTHONPATH="/workspace:${PYTHONPATH}"
|
||||
|
||||
# 默认使用 V1 引擎
|
||||
ENV VLLM_USE_V1=1
|
||||
|
||||
# SUPA 设备相关默认配置
|
||||
ENV VLLM_BR_WEIGHT_TYPE=NUMA
|
||||
ENV VLLM_BR_QUANT_METHOD=INT8
|
||||
|
||||
# 暴露 vLLM API 服务端口
|
||||
EXPOSE 8000
|
||||
|
||||
ENTRYPOINT ["python", "-m", "vllm.entrypoints.openai.api_server"]
|
||||
193
README.md
193
README.md
@@ -1,2 +1,195 @@
|
||||
# enginex-biren-vllm
|
||||
|
||||
基于 vLLM 推理框架的壁仞 BR166M 算力卡适配项目。通过 vLLM 的 OOT（Out-of-Tree）平台插件机制，将壁仞 SUPA 设备无缝接入 vLLM 生态，实现大语言模型在壁仞硬件上的高性能推理服务。
|
||||
|
||||
## 项目结构
|
||||
|
||||
```
|
||||
enginex-biren-vllm/
|
||||
├── vllm/ # 标准 vLLM 代码（含编译后的二进制）
|
||||
└── vllm_br/ # 壁仞适配层（核心代码）
|
||||
├── __init__.py # 插件入口，注册 SUPAPlatform
|
||||
├── platform.py # SUPA 平台抽象实现
|
||||
├── envs.py # 壁仞专用环境变量定义
|
||||
├── utils.py # 工具函数与 monkey-patch
|
||||
├── forward_context.py # 前向推理上下文扩展
|
||||
├── attention/ # Attention 层 patch
|
||||
├── compilation/ # SUPA Graph 图优化与编译
|
||||
│ ├── supa_graph.py # SUPAGraphWrapper（类似 CUDA Graph）
|
||||
│ └── supa_piecewise_backend.py # 分段编译后端
|
||||
├── config/ # 编译配置扩展
|
||||
├── distributed/ # 分布式通信（SCCL）
|
||||
│ └── communicator.py # SUPACommunicator
|
||||
├── executor/ # Ray 执行器 patch
|
||||
├── model_executor/
|
||||
│ ├── layers/ # 自定义算子层
|
||||
│ │ ├── linear.py # NUMA 权重线性层
|
||||
│ │ ├── activation.py # 激活函数
|
||||
│ │ ├── layernorm.py # 层归一化
|
||||
│ │ ├── rotary_embedding.py # 旋转位置编码
|
||||
│ │ ├── logits_processor.py # Logits 处理
|
||||
│ │ └── vocab_parallel_embedding.py # 词<><E8AF8D><EFBFBD>并行嵌入
|
||||
│ └── models/ # 壁仞优化模型实现
|
||||
│ ├── deepseek_v2.py # DeepSeek V2/V3
|
||||
│ ├── deepseek_mtp.py # DeepSeek MTP（多 Token 预测）
|
||||
│ ├── qwen2.py / qwen3.py / qwen3_moe.py # Qwen 系列
|
||||
│ ├── qwen2_vl.py / qwen2_5_vl.py / qwen3_vl.py # Qwen 视觉语言模型
|
||||
│ ├── chatglm.py / glm4.py / glm4_moe.py # GLM 系列
|
||||
│ ├── llama.py # LLaMA
|
||||
│ ├── internlm2.py # InternLM2
|
||||
│ ├── intern_vit.py # InternViT
|
||||
│ ├── roberta.py / bert.py # BERT 系列
|
||||
│ └── registry.py # 模型注册
|
||||
├── sample/ # 采样操作
|
||||
├── v0/ # vLLM V0 引擎适配
|
||||
│ ├── attention/backends/ # V0 Flash Attention 后端
|
||||
│ └── worker/ # V0 SUPAWorker
|
||||
└── v1/ # vLLM V1 引擎适配
|
||||
├── attention/backends/ # V1 Attention 后端
|
||||
│ ├── attention_v1.py # SUPAFlashAttentionBackend
|
||||
│ └── mla/ # MLA 注意力（DeepSeek 专用）
|
||||
│ ├── flashmla.py # SupaFlashMLABackend
|
||||
│ └── flashmla_sparse.py # SupaFlashMLASparseBackend
|
||||
├── core/ # V1 调度器扩展
|
||||
├── engine/ # V1 引擎 patch
|
||||
├── executor/ # V1 执行器 patch
|
||||
├── sample/ # V1 采样
|
||||
├── spec_decode/ # 投机解码（EAGLE）
|
||||
└── worker/ # V1 SUPAWorker & ModelRunner
|
||||
```
|
||||
|
||||
## 核心架构
|
||||
|
||||
### 插件注册机制
|
||||
|
||||
项目通过 vLLM 的 OOT 平台插件系统集成：
|
||||
|
||||
```
|
||||
vllm_br/__init__.py::register()
|
||||
→ 返回 "vllm_br.platform.SUPAPlatform"
|
||||
→ vLLM 加载 SUPAPlatform 作为当前平台
|
||||
→ 自动选择 SUPAWorker、Attention 后端、通信器等组件
|
||||
```
|
||||
|
||||
`SUPAPlatform` 继承自 `vllm.platforms.interface.Platform`，核心配置：
|
||||
- 设备名称：`supa`（映射到 PyTorch 的 `PrivateUse1` dispatch key）
|
||||
- 分布式后端：`sccl`（SUPA Collective Communications Library）
|
||||
- KV Cache Block Size：固定 128
|
||||
- 支持数据类型：`bfloat16`、`float32`
|
||||
|
||||
### 双引擎支持
|
||||
|
||||
同时适配 vLLM V0（旧版）和 V1（新版）两套引擎架构：
|
||||
|
||||
| 组件 | V0 | V1 |
|
||||
|------|----|----|
|
||||
| Worker | `vllm_br.v0.worker.worker.SUPAWorker` | `vllm_br.v1.worker.worker.SUPAWorker` |
|
||||
| Attention | `SUPAFlashAttentionBackend` (V0) | `SUPAFlashAttentionBackend` (V1) |
|
||||
| MLA | 不支持 | `SupaFlashMLABackend` / `SupaFlashMLASparseBackend` |
|
||||
| 投机解码 | 不支持 | 支持（EAGLE） |
|
||||
|
||||
推荐使用 V1 引擎（设置 `VLLM_USE_V1=1`）。
|
||||
|
||||
### 图优化（SUPA Graph）
|
||||
|
||||
类似 NVIDIA CUDA Graph 的机制，通过 `SUPAGraphWrapper` 实现：
|
||||
- 捕获（Capture）推理计算图并重放（Replay），减少 kernel launch 开销
|
||||
- 支持多种模式：`FULL`、`FULL_DECODE_ONLY`、`PIECEWISE`、`FULL_AND_PIECEWISE`
|
||||
- 图池管理，优化显存复用
|
||||
|
||||
### 分布式通信
|
||||
|
||||
`SUPACommunicator` 基于 SCCL 库实现：
|
||||
- 自动检测 P2P 直连拓扑，决定 fused allreduce 策略
|
||||
- 支持 FP32 allreduce（提升数值稳定性）
|
||||
- CPU allreduce 回退方案
|
||||
- 张量并行（TP）与数据并行（DP）支持
|
||||
|
||||
### 内存管理
|
||||
|
||||
- NUMA 感知的权重分配（默认 `VLLM_BR_WEIGHT_TYPE=NUMA`）
|
||||
- 禁用不必要的 memset 操作以提升性能
|
||||
- 自定义内存 profiling（`SUPAMemorySnapshot`）
|
||||
|
||||
## 支持的模型
|
||||
|
||||
| 模型系列 | 具体模型 |
|
||||
|----------|---------|
|
||||
| DeepSeek | DeepSeek V2/V3、DeepSeek MTP |
|
||||
| Qwen | Qwen2、Qwen3、Qwen3-MoE |
|
||||
| Qwen-VL | Qwen2-VL、Qwen2.5-VL、Qwen3-VL、Qwen3-VL-MoE |
|
||||
| GLM | ChatGLM、GLM-4、GLM-4-MoE、GLM-4-1V |
|
||||
| LLaMA | LLaMA 系列 |
|
||||
| InternLM | InternLM2、InternViT |
|
||||
| BERT | RoBERTa、BERT |
|
||||
|
||||
## 环境变量
|
||||
|
||||
| 变量名 | 默认值 | 说明 |
|
||||
|--------|--------|------|
|
||||
| `VLLM_USE_V1` | - | 设为 `1` 启用 V1 引擎（推荐） |
|
||||
| `SUPA_VISIBLE_DEVICES` | - | 可见的 SUPA 设备列表 |
|
||||
| `VLLM_BR_WEIGHT_TYPE` | `NUMA` | 权重存储类型 |
|
||||
| `VLLM_BR_QUANT_METHOD` | `INT8` | 量化方法 |
|
||||
| `VLLM_BR_USE_FUSED_ALLREDUCE` | 自动检测 | Fused AllReduce 设备数 |
|
||||
| `VLLM_BR_USE_FP32_ALL_REDUCE` | `0` | 启用 FP32 AllReduce |
|
||||
| `VLLM_BR_USE_CPU_ALL_REDUCE` | `0` | 启用 CPU AllReduce 回退 |
|
||||
| `VLLM_BR_DEVICE_SPC_NUM` | 自动检测 | 每设备计算单元数 |
|
||||
| `VLLM_BR_STATIC_MOE_DECODER_MAX_LEN` | `256` | MoE 静态解码最大长度 |
|
||||
| `VLLM_BR_ENABLE_TP_GROUPS_IN_SUPERNODE` | `0` | 超节点内张量并行分组 |
|
||||
| `VLLM_SCCL_SO_PATH` | `/usr/local/birensupa/base/latest/succl/lib/x86_64-linux-gnu/libsuccl.so` | SCCL 库路径 |
|
||||
|
||||
## 依赖
|
||||
|
||||
- `torch_br` — 壁仞 PyTorch 扩展（SUPA 设备支持）
|
||||
- `pybrml` — 壁仞设备管理库（设备信息查询、P2P 拓扑检测）
|
||||
- `SCCL` — SUPA 集合通信库
|
||||
- vLLM 及其标准依赖（torch、transformers 等）
|
||||
|
||||
## 代码模块关系
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ vLLM 核心框架 │
|
||||
│ (Engine, Scheduler, TokenizerPool, API Server...) │
|
||||
└──────────────────────┬──────────────────────────────┘
|
||||
│ OOT 插件接口
|
||||
┌──────────────────────▼──────────────────────────────┐
|
||||
│ vllm_br (壁仞适配层) │
|
||||
│ │
|
||||
│ ┌──────────┐ ┌────────────┐ ┌───────────────┐ │
|
||||
│ │ Platform │──▶│ Worker │──▶│ ModelRunner │ │
|
||||
│ │ (SUPA) │ │ (V0 / V1) │ │ │ │
|
||||
│ └────┬─────┘ └─────┬──────┘ └───────┬───────┘ │
|
||||
│ │ │ │ │
|
||||
│ ┌────▼─────┐ ┌─────▼──────┐ ┌──────▼────────┐ │
|
||||
│ │ Attention│ │Distributed │ │Model Executor │ │
|
||||
│ │ Backend │ │(SCCL Comm) │ │(Layers+Models)│ │
|
||||
│ └────┬─────┘ └─────┬──────┘ └──────┬────────┘ │
|
||||
│ │ │ │ │
|
||||
│ ┌────▼─────┐ ┌─────▼──────┐ ┌──────▼────────┐ │
|
||||
│ │SUPA Graph│ │ AllReduce │ │ NUMA Weights │ │
|
||||
│ │(图优化) │ │ (Fused/CPU)│ │ (线性层/MoE) │ │
|
||||
│ └──────────┘ └────────────┘ └───────────────┘ │
|
||||
└──────────────────────────────────────────────────────┘
|
||||
│
|
||||
┌────────────▼────────────┐
|
||||
│ 硬件抽象层 │
|
||||
│ torch_br / pybrml / SCCL│
|
||||
└────────────┬────────────┘
|
||||
│
|
||||
┌────────────▼────────────┐
|
||||
│ 壁仞 BR166M 算力卡 │
|
||||
└─────────────────────────┘
|
||||
```
|
||||
|
||||
数据流：
|
||||
1. vLLM 通过插件机制加载 `SUPAPlatform`
|
||||
2. Platform 根据配置选择对应的 Worker（V0/V1）和 Attention 后端
|
||||
3. Worker 创建 ModelRunner，加载模型权重到 SUPA 设备（NUMA 模式）
|
||||
4. 推理时通过 SUPA Graph 捕获计算图，后续请求直接重放
|
||||
5. 多卡场景下通过 SCCL 进行张量并行通信
|
||||
|
||||
## License
|
||||
|
||||
Apache License 2.0 — Copyright (c) 2020-2025 Shanghai Biren Technology Co., Ltd.
|
||||
|
||||
Reference in New Issue
Block a user