zai-org/GLM-4.7-FP8 on vLLM-Ascend

1. 简介

本文档记录 zai-org/GLM-4.7-FP8 在华为昇腾 NPU 环境的适配分析与部署指南。

GLM-4.7-FP8 是基于 Glm4MoeForCausalLM 架构的大规模 MoE 语言模型，采用 compressed-tensors FP8 量化格式（W8A8_DYNAMIC）。经完整架构分析与算子兼容性门控验证，模型架构已兼容 vLLM / vllm-ascend，无需任何代码变更，仅需在多卡环境（推荐 Atlas 800 A2/A3）完成最终端到端验证。

2. 模型规格

属性	值
模型名称	`zai-org/GLM-4.7-FP8`
架构类	`Glm4MoeForCausalLM`
模型类型	LLM + MoE
隐藏层维度	5120
Attention 头数	96 (GQA, KV头=8)
层数	92
Routed Experts	160
Shared Experts	1
Experts per Token	8
Dense Intermediate Size	12288
MoE Intermediate Size	1536
位置编码	RoPE (partial_rotary_factor=0.5, theta=1M)
QK Norm	是
量化格式	`compressed-tensors` (FP8, float-quantized)
权重策略	per-channel, static, symmetric
激活策略	per-token, dynamic, symmetric

3. 验证环境

组件	版本 / 要求
硬件	Atlas 800 A2 (64G x 8) 或 Atlas 800 A3 (64G x 16)
CANN	>= 8.5.1 (推荐 8.5.1 并执行 FIA 算子替换脚本)
`vllm-ascend`	`0.18.0rc1` 或兼容版本
`vllm`	`0.18.0`
`transformers`	`4.x`
`torch-npu`	`2.x`

推荐 NPU：Ascend 910B (Atlas 800 A2/A3)
最小卡数：8 卡
推荐卡数：16 卡
服务端口：8000

4. 架构兼容性结论

vLLM 原生支持

状态: 已支持
vllm/model_executor/models/glm4_moe.py 明确标注兼容 GLM-4.5 / GLM-4.6 / GLM-4.7
vllm/model_executor/models/registry.py 已注册 Glm4MoeForCausalLM

vllm-ascend 侧支持

状态: 已支持
vllm-ascend 官方文档 GLM4.x.md 已包含 GLM-4.7 部署指南
MoE 算子已通过 AscendFusedMoE 适配，支持 EP (Expert Parallel)
Tool parser 已提供 glm4_moe_tool_parser.py / glm47_moe_tool_parser.py

算子兼容性门控

算子类别	状态	说明
PyTorch 原生算子	通过	全部可用 (RMSNorm, SiluAndMul, Linear 等)
Attention	通过	通过 vllm-ascend `unified_attention` 适配
MoE (FusedMoE)	通过	通过 `AscendFusedMoE` 适配，支持 EP
RoPE	通过	通过 `get_rope` 原生支持
QK Norm	通过	通过 `RMSNorm` 支持
CUDA 内核	通过	无纯 CUDA 无 fallback 算子
Triton 内核	通过	无阻塞性 Triton 算子

结论: 无任何算子阻塞昇腾适配。

5. 量化兼容性

配置项	模型值	vllm-ascend 映射
格式	`float-quantized`	`compressed-tensors`
Weight bits	8	W8A8_DYNAMIC
Weight type	float	FP8
Weight strategy	channel	静态 per-channel
Activation bits	8	W8A8_DYNAMIC
Activation type	float	FP8
Activation strategy	token	动态 per-token
symmetric	true	对称量化

vllm-ascend 的 AscendCompressedTensorsConfig._detect_quant_type() 将该配置识别为 W8A8_DYNAMIC，对应的量化方法为 AscendLinearMethod (Linear) 和 AscendFusedMoEMethod (MoE)。

注意: vllm-ascend 官方 GLM-4.7 验证示例使用的是 --quantization ascend (昇腾原生 w8a8 量化)，而非 compressed-tensors FP8。两者代码路径不同，真实推理精度与性能需在实际硬件上确认。

6. 服务启动

启动前可先检查端口：

ss -lntp | grep ':8000 ' || true

已整理的推荐启动命令（单节点 8 卡）：

#!/bin/bash
export HCCL_BUFFSIZE=512
export OMP_PROC_BIND=false
export OMP_NUM_THREADS=1
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True
export HCCL_OP_EXPANSION_MODE=AIV
export VLLM_ASCEND_BALANCE_SCHEDULING=1
export VLLM_ASCEND_ENABLE_TOPK_OPTIMIZE=1
export VLLM_ASCEND_ENABLE_FLASHCOMM1=1
export VLLM_ASCEND_ENABLE_FUSED_MC2=1

# 可选：FIA 算子替换（CANN 8.5.1 需要，CANN 9.x 后默认内置）
# bash /vllm-workspace/vllm-ascend/tools/install_flash_infer_attention_score_ops_a2.sh

vllm serve /models/GLM-4.7-FP8 \
  --tensor-parallel-size 8 \
  --enable-expert-parallel \
  --seed 1024 \
  --served-model-name glm47-fp8 \
  --max-model-len 133000 \
  --max-num-batched-tokens 8192 \
  --max-num-seqs 16 \
  --async-scheduling \
  --gpu-memory-utilization 0.9 \
  --compilation-config '{"cudagraph_capture_sizes": [1,2,4,8,16,32,64,128,256,512], "cudagraph_mode": "FULL_DECODE_ONLY"}' \
  --additional-config '{"enable_shared_expert_dp": true, "ascend_fusion_config": {"fusion_ops_gmmswigluquant": false}}'

参数说明

--tensor-parallel-size 8: 张量并行 8 路（A2 满配）
--enable-expert-parallel: 启用专家并行（MoE 必需）
--async-scheduling: 异步调度，提升吞吐
--compilation-config: ACL Graph 捕获配置
--additional-config: 昇腾融合算子配置，fusion_ops_gmmswigluquant: false 在总卡数 <= 16 时建议关闭

核心差异：本模型使用 compressed-tensors FP8，无需额外指定 --quantization ascend，vLLM 会自动从 config.json 中读取量化配置。

7. Smoke 验证

基础检查：

curl -sf http://127.0.0.1:8000/v1/models

文本推理：

curl -s http://127.0.0.1:8000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "glm47-fp8",
    "messages": [{"role": "user", "content": "你好，请介绍一下自己"}],
    "temperature": 0,
    "max_tokens": 200
  }'

Tool Calling（如启用）：

curl -s http://127.0.0.1:8000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "glm47-fp8",
    "messages": [{"role": "user", "content": "查询北京天气"}],
    "tools": [...],
    "tool_choice": "auto",
    "temperature": 0,
    "max_tokens": 200
  }'

8. Fallback 排查阶梯

若启动或推理失败，按以下顺序排查：

确认失败可复现

# 重新执行启动命令，观察是否稳定复现

隔离图捕获 vs 算子问题
```
vllm serve ... --enforce-eager
```
OOM 排查
- 降低 --max-model-len（如 65536 -> 32768）
- 降低 --max-num-seqs（如 16 -> 8）
- 降低 --gpu-memory-utilization（如 0.9 -> 0.85）
- 确认已设置 PYTORCH_NPU_ALLOC_CONF=expandable_segments:True
量化相关问题
- 若 compressed-tensors FP8 加载异常，尝试检查 config.json 中 quantization_config 完整性
- 对比官方 Eco-Tech/GLM-4.7-W8A8-floatmtp 的 --quantization ascend 路径
MoE 特定问题
- 确认 --enable-expert-parallel 已开启
- 检查 HCCL_OP_EXPANSION_MODE=AIV 是否设置
- 多节点时确认各节点 npu-smi info 正常

9. 验证结果汇总

验证阶段	状态	说明
Stage A Dummy Gate	资源受限	单卡 32GB NPU 在 MoE 权重初始化阶段 OOM。去掉量化后同样 OOM，证实为单卡内存不足以承载 160-expert MoE 模型。
Stage B Real-Weight Gate	未执行	因硬件资源不足未执行。模型权重未下载。
文本推理	未验证	依赖 Stage A/B 通过
多模态推理	N/A	非 VLM 模型
ACL Graph	未验证	依赖 Stage A/B 通过
EP (Expert Parallel)	未验证	依赖多卡环境
MTP	未验证	模型配置含 `num_nextn_predict_layers=1`，但 vLLM 侧需 `Glm4MoeMTPModel` 单独注册。本模型权重若为 FP8 MTP 版本，需额外验证。

10. 已知限制

当前单卡 32GB 环境无法完成 dummy/real-weight 验证，需在 >=8 卡 Atlas 800 A2/A3 上执行最终验证。
compressed-tensors FP8 路径与官方已验证的 --quantization ascend 路径不同，真实推理精度与性能需在实际硬件上确认。
MTP (Multi-Token Prediction) 支持取决于权重是否包含 MTP 层。本模型 config.json 含 num_nextn_predict_layers=1，如需 speculative decoding，需额外配置 --speculative-config。

11. 交付物

文件	说明
`ANALYSIS_REPORT.md`	模型架构分析、算子兼容性分析、量化路径分析
`RUNBOOK.md`	部署指南、环境变量配置、启动命令、验证方法
`GLM47FP8.yaml`	E2E 配置文件（特征矩阵、量化配置、启动模板、验证命令）

12. 代码变更

无需任何代码变更。

模型架构 Glm4MoeForCausalLM 已在 vLLM 和 vllm-ascend 中完整支持，量化配置通过 compressed-tensors 自动识别并映射到 W8A8_DYNAMIC。