面向 vLLM 部署的每卡参数 / 存储 / 每 token 计算量剖析器。给定一个
Hugging Face / ModelScope 模型 id（或本地 config.json）与一组并行配置
（TP / EP / DP / PP），它计算：
- 每张 GPU 上实际驻留的权重参数量与存储字节数（含 FP8/MXFP4 量化侧车 scale）；
- 每个 decoder layer、每个算子矩阵的切分结果（column / row / QKV / vocab / expert）；
- 官方口径的 A 值（每 token 激活参数量，DeepSeek-V3 报告 A37.55B）；
- 每 token FLOPs 与 DRAM 访存量，区分 decode 与 prefill（平均因果 前缀），包含无参数的 attention / recurrent state 核心；
- 与
model.safetensors.index.json的逐名称 + 字节总量交叉验证； - 一个零依赖、可离线打开的 HTML 仪表盘，浏览器内实时拖动 TP/EP/DP/PP 与序列长度 S，所有数字即时重算。
切分语义直接镜像本仓库 vllm/ 中的实现（FusedMoEParallelConfig、
ColumnParallelLinear、RowParallelLinear、VocabParallelEmbedding、
get_pp_indices），这是本项目与手工估算工具的根本区别。
项目运行时零第三方依赖（Python ≥ 3.10，仅标准库）。建议从源码目录直接 运行：
# Windows（PowerShell）
$env:PYTHONPATH = "src"
python -m profiler --config .hfconfig_cache/dsv4flash.json --tp 8 --ep 8
# Linux / macOS
PYTHONPATH=src python -m profiler --model deepseek-ai/DeepSeek-V3 \
--tp 8 --ep 8 --with-mtp --format html --output dsv3.html也可以安装为命令行工具（可选）：
python -m pip install .
vllm-profiler --config config.json --tp 8 --ep 8
vllm-profiler-view report.json -o report.html# 文本报告（默认格式）
vllm-profiler --config model.json --tp 8 --ep 8 --dp 1 --pp 1
# JSON（供脚本或 dashboard 二次加载）
vllm-profiler --config model.json --tp 8 --ep 8 --format json -o report.json
# 自包含 HTML 仪表盘（无网络、无第三方 JS，file:// 直接打开）
vllm-profiler --config model.json --tp 8 --ep 8 --format html -o report.html
# 校验：config 推理出的张量清单 vs 真实 safetensors index
vllm-profiler --config model.json --index model.safetensors.index.json \
--validate --tp 8 --ep 8
# 多网格对比
vllm-profiler compare --config model.json \
--grids "tp=8,ep=8;tp=8,ep=1;tp=4,dp=2,ep=8"
# 从既有 JSON 生成 dashboard（不需要模型 config）
vllm-profiler viewer report.json -o report.html
# 仅生成一个“加载 JSON”的 viewer 页
vllm-profiler viewer --viewer-only -o viewer.html旧式扁平参数仍然可用：vllm-profiler --config ... --tp ... 会自动走
profile 子命令。
在线模式只允许访问 huggingface.co / hf.co / modelscope.cn，并且只
下载 config.json 与 model.safetensors.index.json；HTTP 重定向同样受
白名单约束。成功下载的配置会缓存在
~/.cache/vllm-profiler/configs/（可用 VLLM_PROFILER_CACHE 覆盖）。
| 并行轴 | 本项目语义 |
|---|---|
| TP | Column/merged-column/QKV 切输出维；row 切输入维；vocab 先按 vLLM 规则 pad 到 64 的倍数再切 vocab 维 |
| EP | 只是扁平 dp × tp 网格上的分组，不增加 GPU。开 EP 时 MoE 内部 tp=1，专家数量按 ceil(E/(dp·tp)) 切分、专家矩阵保持完整；关 EP 时专家矩阵被扁平 dp·tp 切内维 |
| DP | 复制非专家权重计划；不额外复制 routed experts（无 EP 时专家矩阵切片横跨 DP） |
| PP | 每层连续且仅属于一个 stage；stage 边界采用 vLLM get_pp_indices 的余数分配规则 |
| 总 GPU 数 | dp × tp × pp（不是 dp × tp × ep × pp） |
不可整除场景不会静默丢参数：报告会给出 residue_params/warning
（vLLM 本身通常要求整除，这里仍以 ceil 给出可读结果）。
- GEMM 算子：
FLOPs/token = 2 × activated params。 - Embedding：0 FLOPs，按 lookup 读取一个 hidden 向量计访存 （不把整个 vocab 矩阵当 matmul，这是相对朴素估算的一处修正）。
- RMSNorm/LayerNorm：
4 × elements；bias 为1 × elements。 - Attention 核心：
- dense/GQA：
2·T·H·(qk_dim+v_dim) + 3·T·H，KV cache 读 T 个 token + 写新 token； - MLA：相同评分子，但 KV cache 只存一个共享 latent+RoPE 向量，V
现场重算；DeepSeek-V4 使用 vLLM 的
fp8_ds_mla布局（584 B/token）； - recurrent（Qwen3-Next GatedDeltaNet、MiniMax-M1 linear attention）：
4·state + 2·convFLOPs、2·state字节，与序列长度无关； - 稀疏 indexer（DSV4
index_topk、GLM DSA）把有效 lookback 截断到 top-k。
- dense/GQA：
- Phase：
decode使用完整 lookback；prefill使用因果前缀平均 （约一半）。JSON 同时输出两套数字，dashboard 可切换。 - 存储访存 = 激活权重 × 存储 dtype 字节 + bf16 输出写；量化侧车 scale 计入驻留字节。
| 架构 | vLLM 参考实现 |
|---|---|
DeepseekV3ForCausalLM / DeepseekV32ForCausalLM |
model_executor/models/deepseek_v2.py、deepseek_mtp.py |
DeepseekV4ForCausalLM |
models/deepseek_v4/nvidia/model.py、attention.py、compressor.py、mtp.py |
Qwen3NextForCausalLM |
model_executor/models/qwen3_next.py + GatedDeltaNet 实现 |
GlmMoeDsaForCausalLM |
model_executor/models/deepseek_v2.py（DSA indexer） |
MiniMaxForCausalLM / MiniMaxText01ForCausalLM / MiniMaxM1ForCausalLM |
上游已移除的 minimax_text_01.py 最后状态 |
| Llama/Mistral/Qwen2/Qwen3/Gemma 等 dense | 通用 dense fallback |
覆盖的 checkpoint 细节：DeepSeek-V4 融合/分离命名、hash/compress/indexer
层、GLM DSA indexer 放置公式、Qwen3-Next mtp.layers 命名、
tied embedding、DSV4 MTP 的 mtp.<i> 前缀、fp8/fp4 量化侧车。
config.json ──> archs/*.py ──> ModelSpec
│ TensorSpec（形状/切分/count/dtype/量化）
│ AttentionOp（dense/mla/recurrent）
▼
Deployment(tp,ep,dp,pp) ──> engine.py ──> Report
│ layer / stage / operator / totals
│ params / bytes / A / FLOPs / DRAM
├──> render/json.py (schema_version=2)
├──> render/text.py (text / markdown)
└──> render/html.py + assets/dashboard.html
^ 浏览器内镜像同一套数学
model.safetensors.index.json ──> validate.py ──> 名称集合 + 字节总量校验
PYTHONPATH=src python -m unittest discover -s tests -v测试使用仓库内 .hfconfig_cache/（不提交；测试会因缺失而跳过，仓库随附
的 workspace 副本包含六个公开模型的 config 与 index）：
- 黄金总量：六模型参数总量与 A 值逐位断言（DSV3 671B/A37.55B、 DSV4-Pro 1.573T/A49.78B 等）；
- 名称/字节校验：六个真实
safetensors.index.json全部0 missing / 0 extra；除 DSV3（推断误差 3.2e-8）外，其余五个模型的 字节总量比值精确为 1.0； - 并行语义：EP 只影响专家、PP 不改变每卡平铺值、DP×TP 专家切片、 vLLM stage 边界；
- JS 对拍：Node.js 可用时，直接执行 dashboard 自身 JavaScript， 断言浏览器重算与 Python 报告逐位一致（含备用网格）。
# 可选：只跑 browser-JS 对拍
python -m unittest discover -s tests -p "test_dashboard_js.py" -vprofiler/
├── pyproject.toml
├── src/profiler/
│ ├── cli.py # profile / compare / viewer + legacy flat CLI
│ ├── deployment.py # TP/EP/DP/PP 语义
│ ├── sharding.py # vLLM 切分规则的单一事实源
│ ├── model.py # TensorSpec / AttentionOp / LayerSpec / ModelSpec
│ ├── engine.py # Report 汇总
│ ├── fetch.py # 白名单网络 + 缓存
│ ├── validate.py # safetensors index 交叉验证
│ ├── archs/ # 六类架构解析器 + dense fallback
│ ├── render/ # text / markdown / json / html
│ └── assets/dashboard.html
└── tests/ # stdlib unittest，无需 pytest
- 字节校验：DSV4 / MiniMax-M1 / GLM-5.2 / Qwen3-Next 五个索引精确为
1.0；DSV3 的 bf16 scale-sidecar 布局有约 43 KB 的推断误差（比值
1.000000032，相对误差 3.2e-8）。 prefill是按“每 token 平均因果前缀”的工程估算，不是完整O(S²)矩阵乘的精确积分。- 未计 TP all-reduce / MoE all-to-all 通信量、KV cache 分配器 padding、 activation 与 runtime buffer 显存；报告明确只做权重驻留与稳态 per-token 成本剖析。