enginex-vastai-va16-vllm/README.md

# vLLM for VastAI VA16 (VACC)

基于 [vLLM v0.11.0](https://github.com/vllm-project/vllm) 的 VastAI VA16 加速卡适配版本，通过 Out-of-Tree (OOT) 插件机制将 vLLM 的推理能力扩展到 VA16 硬件平台。

## 项目结构

```
enginex-vastai-va16-vllm/
├── vllm/              # vLLM v0.11.0 核心代码
├── vllm_vacc/         # VA16 适配层（运行时 Patch 机制）
├── torch_vacc/        # VA16 PyTorch 后端（设备管理、算子库、驱动）
└── vacc_tools/        # 调试工具（Trace、内存分析）
```

## 支持的模型

| 模型系列 | 具体模型 | 备注 |
|---------|---------|------|
| **Qwen** | Qwen2, Qwen2-VL, Qwen2.5-VL, Qwen3, Qwen3-MoE, Qwen3-VL | 支持 Fused Attention |
| **DeepSeek** | DeepSeek-V2/V3, DeepSeek-MTP | 支持 MLA、Fused Prefill |
| **BERT/RoBERTa** | BERT, RoBERTa | 支持 Fused Attention |

同时支持通过 vLLM 原生代码运行的 LLaMA 等其他模型（经 VA16 Patch 适配）。

## Docker

### 镜像信息

| 镜像地址 | 标签 | 大小 |
|---------|------|------|
| `git.modelhub.org.cn:9443/enginex/xc-llm-va16` | `26.03` | 3.82GB |

### 拉取镜像

```bash
docker pull git.modelhub.org.cn:9443/enginex/xc-llm-va16:26.03
```

### 构建镜像

```bash
docker build -t git.modelhub.org.cn:9443/enginex/xc-llm-va16:26.03 .
```

### 使用 Docker 运行

```bash
docker run --rm -it --device /dev/vacc0 \
    -v /tmp/va16_model_cache:/models \
    -p 8000:8000 \
    git.modelhub.org.cn:9443/enginex/xc-llm-va16:26.03 \
    python -m vllm.entrypoints.openai.api_server \
        --model /models/leaderboard/modelHubXC/Qwen/Qwen2-1.5B-Instruct \
        --host 0.0.0.0 --port 8000
```

## 快速开始

### 启动 OpenAI 兼容 API 服务

```bash
# 基本启动
python -m vllm.entrypoints.openai.api_server \
    --model /path/to/model \
    --tensor-parallel-size 1

# 示例：使用 Qwen2-1.5B-Instruct
python -m vllm.entrypoints.openai.api_server \
    --model /tmp/va16_model_cache/leaderboard/modelHubXC/Qwen/Qwen2-1.5B-Instruct \
    --tensor-parallel-size 1
```

### 调用 API

```bash
curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen2-1.5B-Instruct",
    "messages": [{"role": "user", "content": "你好"}]
  }'
```

## 环境变量

| 环境变量 | 默认值 | 说明 |
|---------|--------|------|
| `VACC_VISIBLE_MODULES` | - | 控制可见的 VA16 设备（类似 CUDA_VISIBLE_DEVICES） |
| `VLLM_VACC_KVCACHE_SPACE` | `16` | KV Cache 显存大小（单位：GB） |
| `VLLM_USE_V1` | `1` | 是否使用 vLLM V1 引擎（`0` 使用 V0） |
| `BLOCK_GROUP_SIZE` | `8192` | KV Cache Block 组大小 |
| `USE_FLASH_ATTENTION` | `1` | 是否使用 Flash Attention |
| `USE_FUSED_QWEN_ATTENTION` | `1` | 是否使用 Qwen 融合 Attention |
| `USE_FUSED_BERT_ATTENTION` | `1` | 是否使用 BERT 融合 Attention |
| `USE_DECODER_LAYER_FUSE_MODE` | `1` | Decode 阶段层融合模式 |
| `FUSE_ALL_DECODER_LAYERS` | `1` | 是否融合所有 Decoder 层（CMCU 循环） |
| `LLM_MAX_PREFILL_SEQ_LEN` | `57344` | 最大 Prefill 序列长度 |
| `CUT_PREFILL_SEQ_LEN` | `-1` | 切分 Prefill 序列长度（-1 为不切分） |
| `VLLM_VACC_DUMP_LOGITS` | - | 设置后将 Logits 导出到指定目录（调试用） |

## 技术架构

### 插件机制

项目通过 vLLM 的 OOT Platform 插件机制注册 `VaccPlatform`，并在加载时通过 `VllmPatchManager` 对 vLLM 核心模块进行运行时 Patch，包括：

- **Attention 后端**：`VACCAttentionBackend`（标准注意力）和 `VACCMLABackend`（Multi-head Latent Attention）
- **Worker**：`VACCWorker`（V0/V1 引擎）和 `VACCModelRunner`
- **算子替换**：RMSNorm、RoPE、SiLU、GPTQ/FP8 量化等
- **分布式通信**：all_reduce、all_gather、broadcast 等

### 支持特性

- Tensor Parallel (TP)
- 投机采样 (Speculative Decoding)
- FP8 / GPTQ 量化
- Chunked Prefill & Prefix Caching
- OpenAI 兼容 API（Chat/Completion/Embedding）
- LoRA 适配器
- 多模态模型（VL 系列）

## 调试工具

`vacc_tools/` 提供以下工具：

- **memory_analyzer.py** — VA16 显存使用监控与分析
- **generate_trace.py / trace_logger.py** — 硬件执行 Trace 采集
- **parse_vacc_log_for_tracing.py** — 硬件日志解析

## 版本信息

- **vLLM 基线版本**：v0.11.0
- **torch_vacc 版本**：1.3.3.777
- **Docker 镜像标签**：`git.modelhub.org.cn:9443/enginex/xc-llm-va16:26.03`