Hunyuan-A13B 单卡部署：显存、量化与吞吐调优

适用场景

Hunyuan-A13B 是 MoE 架构模型，总参数量与每 token 激活参数量不在一个量级——通常说法是总参数约 80B、每 token 激活约 13B（具体以官方模型卡和技术报告为准）。这套单卡方案适合：手上只有一张 48GB 或 80GB 显存的卡，想跑一个接近 80B 总参数、但推理算力开销接近 13B 稠密模型的场景，比如内部知识问答、代码补全、批量文档摘要。

要解决的问题有三个：显存到底够不够、该选哪种量化、批大小怎么调才能把吞吐拉上去。

环境与前置条件

• 操作系统：Linux（Ubuntu 22.04 及以上），GPU 驱动与 CUDA 版本匹配。
• GPU：单卡，显存 48GB 是现实起点，80GB 余量更舒服。24GB 卡需要 CPU 卸载，吞吐会明显下降，不建议作为主力。
• Python 与运行时：Python 3.10 以上，PyTorch 版本与 CUDA 对应，具体版本组合以官方文档当前版本为准。
• 内存：建议 64GB 以上。加载权重、做量化转换时宿主内存占用会短时间冲高。
• 磁盘：BF16 权重是上百 GB 量级，INT4 权重是数十 GB 量级，建议预留 1.5 倍空间放权重和临时文件。
• 推理框架：vLLM、SGLang、llama.cpp 都可以，本教程以 vLLM 为例（提供 OpenAI 兼容接口，方便压测）。Hunyuan 官方也提供部署文档，遇到架构适配问题优先查官方页面。

分步骤部署

第 1 步：先算显存账，再决定量化

这是 MoE 部署最容易踩坑的地方：专家路由是动态的，任意 token 都可能命中任意专家，所以整份权重必须常驻显存（除非显式做专家卸载）。激活 13B 影响的是算力和显存带宽，不影响权重占用。

权重占用估算：

```

权重显存 ≈ 总参数量 × 每个参数的字节数

BF16/FP16 → 2 字节

FP8/INT8 → 1 字节

INT4 → 0.5 字节，实际再叠加 5%~15% 的量化元数据（scale、zero-point）

```

按总参数约 80B 估算：BF16 约 160GB，单卡放不下；INT8 约 80GB，80GB 卡也几乎放不下，因为没有余量给 KV cache；INT4 约 40~46GB，48GB 卡能装下，80GB 卡余量充足。

KV cache 估算：

```

KV 显存 ≈ 2 × 层数 × KV头数 × head_dim × 序列长度 × 并发数 × KV字节数

```

举个数（下面的层数、头数都是假设值，只演示算法，真实值以模型 config.json 为准）：假设 64 层、8 个 KV 头、head_dim 128、KV 用 FP16，那么单序列单 token 的 KV 约 2 × 64 × 8 × 128 × 2 = 256KB；跑到 32K 上下文，单序列约 8GB，并发 4 路就是 32GB。这就是为什么单卡上「量化到 INT4」之后，还要老老实实限制 max-model-len 和并发数。

中间激活张量在 prefill 阶段是大头，与 batch × 序列长度 成正比，长 prompt 一次性灌进来时最容易 OOM。

第 2 步：准备运行环境

```bash

python3 -m venv venv

source venv/bin/activate

pip install -U pip

推理框架

pip install vllm

拉权重用

pip install -U huggingface_hub

pip install hf_transfer

export HF_HUB_ENABLE_HF_TRANSFER=1

```

这一步在做什么：建一个干净的虚拟环境，装 vLLM 和权重下载工具。hf_transfer 能明显加快大文件下载。

成功的标志：

```bash

python -c "import vllm, torch; print(vllm.__version__, torch.cuda.is_available())"

```

能打印出版本号，并且第二个值是 True。

第 3 步：拉取模型权重

```bash

hf download <官方模型仓库ID> --local-dir ./hunyuan-a13b

```

如果用的是社区量化版（AWQ / GPTQ / FP8），换成对应仓库即可，仓库 ID 以官方页面为准。成功的标志：目录下能看到 config.json、tokenizer.json、以及若干 .safetensors 分片文件。

```bash

ls -lh ./hunyuan-a13b | head -20

du -sh ./hunyuan-a13b

```

第 4 步：量化选型

选择建议：优先用已经量化好的 INT4 权重，而不是自己在线量化。在线量化既吃宿主内存，又容易因为校准集不匹配掉点。如果你手上是 80GB 卡、且框架支持 FP8，FP8 的精度损失通常比 INT4 更小，值得试。

第 5 步：启动 OpenAI 兼容服务

```bash

vllm serve ./hunyuan-a13b \

--served-model-name hunyuan-a13b \

--dtype float16 \

--quantization awq \

--max-model-len 32768 \

--gpu-memory-utilization 0.90 \

--max-num-seqs 32 \

--enable-chunked-prefill \

--enable-prefix-caching \

--port 8000

```

几个参数的含义：

• --quantization awq：量化权重通常能从 config.json 自动识别，识别失败时才需要手动指定。如果你加载的是未量化权重，这一项要去掉。
• --max-model-len：单请求最大上下文。这个值直接决定 KV cache 上限，单卡部署时是第一个要压的参数。
• --gpu-memory-utilization：允许 vLLM 使用的显存比例，0.85~0.92 是常见区间。调太高会挤压其他进程，反而容易 OOM。
• --max-num-seqs：同时在跑的序列数上限，是吞吐调优的主要旋钮。
• --enable-chunked-prefill：把长 prompt 拆块处理，避免长请求把整卡卡死。
• --enable-prefix-caching：相同前缀复用 KV，多轮对话场景收益明显。

部分老版本没有 vllm serve 子命令，等价写法是 python -m vllm.entrypoints.openai.api_server ...，以官方文档当前版本为准。

成功的标志：日志里出现模型加载完成、KV cache 分配块数、以及 Uvicorn running on http://0.0.0.0:8000。日志中还会打印可用的最大并发数，这个数字是后面调优的参考。

第 6 步：批大小与吞吐调优

MoE 解码阶段的瓶颈是显存带宽：每生成一个 token，都要把当前命中的那部分专家权重读一遍。激活参数约 13B，意味着单 token 要读的权重量大概是 13B × 每参数字节数。批大小越大，同一份权重读进来可以服务更多请求，单位 token 的权重读取成本就被摊薄了。

调优路径：

1. 先跑单请求，确认能出结果、延迟可接受。

2. 逐步提高并发（--max-num-seqs 或客户端并发数），观察吞吐变化。

3. 吞吐曲线会在某个点开始走平甚至下降——此时多半是显存带宽或 KV 显存撞墙，或者请求开始排队。

4. 请求开始排队时，回到 /metrics 看 vllm:num_requests_running 和 vllm:num_requests_waiting，等待数持续大于 0 说明已经饱和。

两个额外注意点：

• 推理模式慎开：带思考链的输出会显著拉长生成长度，直接压低整体吞吐。批量任务里建议关掉或限制 max_tokens。
• 输入输出长度分布：长 prompt 多就加大 chunked prefill 的块大小；短问答多就把 max-model-len 压小，换来更大的 KV 池和更高并发。

第 7 步：写一个可复现的压测脚本

```python

import asyncio, time

from openai import AsyncOpenAI

client = AsyncOpenAI(base_url="http://127.0.0.1:8000/v1", api_key="EMPTY")

PROMPT = "用三句话解释什么是混合专家模型。"

CONCURRENCY = 8

ROUNDS = 4

async def one():

r = await client.chat.completions.create(

model="hunyuan-a13b",

messages=[{"role": "user", "content": PROMPT}],

max_tokens=128,

temperature=0.1,

)

return r.usage.completion_tokens

async def main():

total = 0

t0 = time.time()

for _ in range(ROUNDS):

total += sum(await asyncio.gather(*[one() for _ in range(CONCURRENCY)]))

dt = time.time() - t0

print(f"输出 token 数={total} 耗时={dt:.2f}s 吞吐={total/dt:.1f} tok/s")

asyncio.run(main())

```

改 CONCURRENCY 从 1 到 8、16、32 各跑一遍，把吞吐记下来，就能画出这台卡上的吞吐曲线。注意：这里统计的是输出 token 吞吐，不能和厂商宣传的跑分直接对比，只用于自己环境内的相对比较。

验证部署是否成功

1. 服务活着：

```bash

curl -s http://127.0.0.1:8000/v1/models | python -m json.tool

```

预期：返回 data 数组里能看到 hunyuan-a13b 这个 id。

2. 能推理：

```bash

curl -s http://127.0.0.1:8000/v1/chat/completions \

-H "Content-Type: application/json" \

-d '{"model":"hunyuan-a13b","messages":[{"role":"user","content":"你好，简单介绍一下你自己"}],"max_tokens":64}'

```

预期：返回 JSON 里有非空的 choices[0].message.content，且 usage 字段有 token 计数。

3. 显存占用合理：

```bash

nvidia-smi --query-gpu=memory.used,memory.total,utilization.gpu --format=csv

```

预期：memory.used 接近但不超过你设定的 gpu-memory-utilization × memory.total，空闲时 GPU 利用率接近 0，压测时会冲高。

4. 指标端点可达：

```bash

curl -s http://127.0.0.1:8000/metrics | grep -E "num_requests|time_to_first_token" | head

```

预期：能看到请求数、排队数、首 token 延迟等指标。

常见报错与解决

报错 1：torch.OutOfMemoryError: CUDA out of memory

原因：权重 + KV cache + 中间激活超出显存。MoE 模型权重占满大部分显存时，留给 KV 的余量很小，长上下文或高并发会立刻打爆。

解决（从代价最小的开始）：

```bash

降低单请求上下文上限，直接减少 KV 需求

vllm serve ./hunyuan-a13b --max-model-len 16384 --max-num-seqs 8

降低显存占用比例，给中间激活留空间

把 --gpu-memory-utilization 从 0.90 调到 0.85

换更激进的量化：INT8 → INT4

```

如果以上都试过还是不行，说明这张卡的显存装不下这份权重，需要改用 CPU/专家卸载开关（不同框架的参数名不同，以官方文档为准），或者换更大的卡。

报错 2：量化相关的加载失败，例如 ValueError: unrecognized quantization method 或 Cannot find quantization config

原因：模型目录里的量化配置和启动参数不匹配。常见情况是权重本身是 AWQ，但没传 --quantization awq；或者权重是未量化的 BF16，却硬加了 --quantization。

解决：

```bash

先看一眼权重自带的量化配置

cat ./hunyuan-a13b/config.json | python -m json.tool | grep -A5 -i quant

自动识别失败时手动指定，值与权重格式一致

vllm serve ./hunyuan-a13b --quantization awq

未量化权重则直接去掉 --quantization

```

报错 3：模型架构不被支持，例如 The model type 'xxx' is not supported 或加载时 KeyError

原因：推理框架版本偏旧，还没有适配该模型结构。

解决：

```bash

pip install -U vllm

或者改用其他已适配的框架/官方提供的部署方式

python -c "import vllm; print(vllm.__version__)"

```

升级后仍不支持，就查官方部署文档确认推荐的框架版本。

报错 4：CUDA error: an illegal memory access 或启动阶段直接崩在 NCCL 初始化

原因：容器环境下共享内存不足，或者驱动/CUDA/PyTorch 版本不匹配。

解决：

```bash

Docker 启动时把共享内存调大

docker run --gpus all --shm-size 16g ...

确认驱动版本

nvidia-smi | head -5

确认 PyTorch 编译时的 CUDA 版本

python -c "import torch; print(torch.version.cuda)"

```

两者对不上时，重装与驱动匹配的 PyTorch（组合以官方文档为准）。

报错 5：请求返回 maximum context length is N tokens

原因：请求的 prompt + max_tokens 超过了启动时的 --max-model-len。

解决：要么在客户端截断历史，要么重启服务把 --max-model-len 调大——但要注意调大会等比例吃掉 KV 显存，可能触发报错 1。

报错 6：tokenizer 加载报错，提示需要 trust_remote_code

原因：模型使用了自定义 tokenizer 代码。

解决：在启动命令里加 --trust-remote-code。这个开关会执行仓库里的 Python 代码，只对可信来源开启。

后续维护

备份：把「能跑通的那一套」固化下来——启动脚本、量化权重的版本标识、框架版本锁定文件。权重目录如果是从网络拉取的，记下仓库 ID 和 commit 号，方便复现。可以用 pip freeze > requirements.txt 保存环境快照。

升级：推理框架迭代很快，升级前先在测试端口用同一份权重跑一遍第 7 步的压测脚本，对比吞吐和输出质量，确认没有回退再切生产。权重格式升级（比如从 FP16 换 INT4）要重新做一轮精度抽检，别只看吞吐。

日志与监控：

• 进程日志：用 vllm serve ... 2>&1 | tee server.log 落盘，便于事后排查；生产环境建议配日志轮转，避免撑爆磁盘。
• 性能指标：/metrics 里的请求排队数、首 token 延迟、每 token 输出间隔，是判断容量是否够用的核心。
• 显存与温度：nvidia-smi 定时采样，或接入本机监控。MoE 模型显存常年贴顶运行，需要关注是否出现显存碎片累积。
• 报警阈值建议：排队数持续大于 0、首 token 延迟超过业务可接受值、显存使用率长时间维持在高位。

容量规划：单卡部署的扩容方向有两个——换更大显存的卡，或者在多张卡上做张量并行。前者不用改配置，后者需要重新决定并行度并验证通信开销。无论哪种，都先用第 7 步的脚本在目标硬件上重新测一遍吞吐曲线，再定并发上限。