Tencent-Hunyuan-Large：超详细部署与使用教程

Tencent-Hunyuan-Large（混元大模型，内部代号 Hunyuan-MoE-A52B）是腾讯开源的旗舰级 Transformer MoE 大语言模型，总参数 3890 亿、激活参数 520 亿，是业界已开源的最大 Transformer MoE 模型之一，预训练模型支持最长 256K 上下文、指令模型支持 128K 上下文。

目录

• 一、项目概述
• 二、环境要求
• 三、部署方式
• 四、使用方法
• 五、常见问题排查（FAQ）
• 六、部署注意事项与最佳实践
• 七、参考资料

一、项目概述

1.1 项目定位

Hunyuan-Large 是腾讯混元团队开源的 MoE（混合专家）旗舰大模型，总参数规模 389B（3890 亿），每次前向推理仅激活 52B（520 亿）参数，在「总规模大、单次计算量小」之间取得平衡。项目于 2024 年 11 月 5 日开源，同时发布预训练模型（Hunyuan-A52B-Pretrain）、指令模型（Hunyuan-A52B-Instruct）与 FP8 量化指令模型（Hunyuan-A52B-Instruct-FP8），并配套发布技术报告（arXiv:2411.02265）、训练/推理操作手册、vLLM 推理后端与训练脚本。模型完全兼容 Hugging Face 格式，可直接基于 hf-deepspeed 框架进行微调。

1.2 核心功能

• 超大 MoE 架构：总参数 389B、激活 52B，在 MMLU、CMMLU、C-Eval、GSM8K、MATH、HumanEval 等基准上，官方公布其综合表现优于 Llama3.1-405B、Mixtral-8x22B、DeepSeek-V2 等同激活量级模型。
• 超长上下文：预训练模型支持最长 256K Token 序列，指令模型支持最长 128K。
• KV Cache 压缩（GQA + CLA）：采用 Grouped Query Attention 与 Cross-Layer Attention（跨层注意力）策略，官方实测 KV-Cache 部分显存占用降低约 50%，显著提升长文本场景推理吞吐。
• FP8 量化：提供 W8A8C8 格式 FP8 量化模型，相比传统 FP16/BF16 显存占用降低约 50%，吞吐提升约 70%，且精度损失极小（官方 benchmark 中 MMLU 89.9→88.9、C-Eval 88.6→89.2）。
• 双推理后端：开源 vLLM 后端（基于 vLLM 的 hunyuan 分支）；TRT-LLM 后端（腾讯内部混元项目大规模使用，性能比 vLLM 高 30% 以上，官方称后续开放）。
• 完整训练工具链：基于 Hugging Face Transformers Trainer + DeepSpeed，支持全参微调与 LoRA 微调，支持 flash-attention 加速，提供单机/多机训练脚本。
• 自研分词器：在 tiktoken 10 万 Token 词表基础上额外训练 2.9 万中文 Token，压缩率从 LLaMA3 的 2.78 字符/Token 提升到 3.13 字符/Token，中文效率更高。
• 云侧托管：已接入腾讯云 TI 平台（机器学习平台），可在控制台几步完成训练与部署；同时提供混元 API 云端调用。

1.3 技术架构

官方未在 README 中提供公开可用的架构图，以下说明基于官方技术报告与 README 描述整理（以官方技术报告 arXiv:2411.02265 为准）。

Hunyuan-Large 为 Transformer Decoder-only MoE 结构：每个 Transformer Block 中 FFN 部分替换为专家路由结构（Router 选择 Top-K 专家），配合 GQA 注意力降低 KV Cache；推理时通过张量并行（tensor_parallel）切分专家权重跨多卡部署。整体推理链路为：模型权重（BF16 / Int8-weight-only / W8A8C8-FP8 三种精度）→ vLLM 引擎（Ray 多机通信）→ OpenAI 兼容风格 HTTP 服务。

下图为混元官方 Logo（官方 README 头部图片）：

说明：官方 README 与官方文档站未提供可公开直接引用的 MoE 架构图；技术报告中的架构图发表在 arXiv 论文中，如需引用请查阅技术报告原文。

二、环境要求

Hunyuan-Large 属于百亿到千亿级 MoE 模型，硬件门槛是本项目最重要的部署约束，下表为官方 README 明确给出的测试配置（测试机为 H20 GPU）：

其他环境要求：

重要提示：H20 单卡显存 96GB（官方测试机型）。16×96GB≈1536GB 总显存承载 389B BF16 权重（约 778GB）+ KV Cache 与激活；量化到 FP8 后权重减半，8 卡即可承载。普通消费级显卡或单卡服务器无法运行本模型，个人开发者建议走「腾讯云 TI 平台托管」或「混元 API」路径（见 3.4）。

三、部署方式

下面给出四条部署路径：① 官方 Docker 镜像 + vLLM BF16 全精度部署（16 卡）→ ② FP8/Int8 量化轻量部署（8 卡，官方推荐的降本路径）→ ③ 源码训练环境（hf-deepspeed 微调）→ ④ 腾讯云 TI 平台托管（免自建 GPU）。

3.1 方式一：官方 Docker 镜像 + vLLM BF16 部署（16 张 H20）

官方提供预构建 Docker 镜像 hunyuaninfer/hunyuan-large，内置 vLLM hunyuan 分支与全部依赖，是最省事的部署路径。

步骤 1：下载模型权重

三选一（均为官方下载地址）：

BF16 全精度部署请下载 Hunyuan-A52B-Instruct（BF16） 并解压到 ${MODEL_PATH}。

步骤 2：启动官方推理容器

docker run --name hunyuanLLM_infer -itd --privileged --user root --net=host --ipc=host --gpus=8 hunyuaninfer/hunyuan-large:infer-open-source

说明：--gpus=8 表示单机 8 卡；BF16 全精度官方要求 16 卡，即两台 8 卡机器组成 Ray 集群（见步骤 3）。镜像 tag 为 infer-open-source（官方 README 给出的开源推理 tag）。

⚠️ 官方安全提示：上面使用了 --privileged 特权模式，会扩大容器权限、增加数据泄露与集群安全风险；非必要不使用特权模式，确需使用时须做充分安全评估与加固。

步骤 3：多机无密码 SSH 与 Ray 组网（16 卡 = 2 台 8 卡机）

BF16 部署跨两台机器（示例 IP ${ip1}、${ip2}），在每台机器的容器内配置：

# 两台机器分别设置 root 密码（示例 Tmp123,./）
passwd

# 将仓库中 inference/login_ssh.py 拷入容器，批量配置无密码互信
python3 login_ssh.py --ips ${ip1},${ip2} --port 36000 --password=Tmp123,./

官方提醒：启动前务必先用 vLLM 官方调试脚本验证多机通信：https://docs.vllm.ai/en/latest/getting_started/debugging.html

设置环境变量后，在各节点启动 Ray：

export VLLM_HOST_IP=${LOCAL_IP}          # 本机 bond1 对应的 IP
export NCCL_SOCKET_IFNAME=bond1
export GLOO_SOCKET_IFNAME=bond1

主节点（head）：

ray start --block --head --node-ip-address=${LOCAL_IP} --port=6379

工作节点（worker）：

ray start --block --address={主节点LOCAL_IP}:6379 --node-ip-address=${LOCAL_IP}

若 Ray 启动失败，先执行 ray stop 再重试。 官方安全提示：Ray 默认端口（6379、8265 等）未开启认证，存在未授权访问与命令执行风险，仅应在可信内网部署，或用严格 ACL 控制这些端口。

步骤 4：执行推理（命令行方式）

在容器内、${MODEL_PATH} 指向 BF16 模型目录后：

import os
from vllm import LLM, SamplingParams

model_path = os.environ.get('MODEL_PATH')

llm = LLM(model=model_path,
        tokenizer=model_path,
        trust_remote_code=True,
        max_model_len=10240,
        dtype='bfloat16',
        tensor_parallel_size=16,      # 16 卡张量并行
        pipeline_parallel_size=1,
        disable_log_stats=False,
        gpu_memory_utilization=0.98,
        disable_custom_all_reduce=True,
        enforce_eager=True,
        max_num_seqs=8,
        use_v2_block_manager=True,
        quantization=None)

prompts = ["海水为什么是咸的"]

sampling_params = SamplingParams(
    temperature=0.7, top_p=0.6, max_tokens=200, top_k=20, repetition_penalty=1.05)

outputs = llm.generate(prompts, sampling_params)

for output in outputs:
    prompt = output.prompt
    generated_text = output.outputs[0].text
    print(f"Prompt: {prompt!r}, Generated text: {generated_text!r}")

3.2 方式二：FP8 / Int8 量化部署（8 卡，官方推荐的轻量降本路径）

官方量化方案把 BF16 的 16 卡要求降到 8 卡，是资源有限时的首选。镜像与 BF16 相同。

Int8 weight-only 部署

# 1) 设置环境变量（${MODEL_PATH} 仍指向 BF16 模型路径，权重在线转 Int8）
export MODEL_PATH=/path/to/bf16/model
export LOCAL_IP=本机bond1对应的IP

# 2) 在容器 inference/ 目录启动 Int8 服务
cd inference
sh run_server_int8.sh

# 3) 服务就绪后发起请求
sh openapi.sh

FP8（W8A8C8）部署

# 1) 下载并解压 FP8 模型（Hunyuan-A52B-Instruct-FP8），${MODEL_PATH} 指向 FP8 目录
export MODEL_PATH=/path/to/fp8/model
export LOCAL_IP=本机bond1对应的IP

# 2) 启动 FP8 服务
cd inference
sh run_server_fp8.sh

# 3) 发起请求
sh openapi.sh

openapi.sh 中的 ${LOCAL_IP} 与 ${MODEL_PATH} 必须改成与实际服务一致的值后再执行。

官方 FP8 精度对照（BF16 → W8A8C8-FP8）：ARC-C 94.6→94.2、C-Eval 88.6→89.2、CMMLU 90.4→89.8、MMLU 89.9→88.9，精度基本持平。

官方推理性能参考（vLLM，H20，input_length=2048）

3.3 方式三：源码训练环境部署（hf-deepspeed 微调）

需要体验微调或二次开发时，按官方训练脚本部署。

单机 LoRA 微调（最低 8 卡）

cd train
pip install -r requirements.txt
bash train.sh

多机训练（在 train.sh 开头追加组网配置）

export HOST_GPU_NUM=8
export LOCAL_IP=${ip1}                          # 本机 IP
export NODE_IP_LIST="${ip1}:8,${ip2}:8"          # 多机 IP 列表，逗号分隔
export NODES=2
export NODE_NUM=$((${NODES} * ${HOST_GPU_NUM}))

多机前同样需配置节点间无密码 SSH（端口示例 36005，须放行且不被占用），并保证各节点代码、数据、脚本一致（推荐挂载共享网络盘）。

关键训练参数（train.sh / DeepSpeed 配置）

LoRA 权重合并（离线）

zero3 训练中 LoRA 权重无法在线合并到分片模型，用离线脚本：

bash merge_lora_weight.sh \
  --base_model_path /path/to/base/model \
  --adapter_model_path /path/to/lora/weights \
  --output_path /path/to/merged/output \
  --save_dtype bf16        # 可选 fp16 / bf16 / fp32

3.4 方式四：腾讯云 TI 平台托管部署（免自建 GPU，个人开发者首选）

没有 16 卡 H20 集群的团队，可使用腾讯云已集成 Hunyuan-Large 的机器学习平台：

• 平台入口：cloud.tencent.com/product/ti
• 最佳实践文档：Hunyuan-Large Best Practice on TI
• 在线对话体验：Chat with Hunyuan-Large（TI 控制台）

仅需在线体验而非自建时，也可直接调用混元 API：cloud.tencent.com/document/product/1729/97730，或访问 Hugging Face 在线 Demo：huggingface.co/spaces/tencent/Hunyuan-Large。

3.5 验证部署成功（通用）

1. 命令行推理：执行 3.1 步骤 4 的 Python 脚本，终端打印 Prompt: ..., Generated text: ... 且生成通顺中文回答，即部署成功。
2. 服务化推理：run_server.sh（BF16）/ run_server_int8.sh / run_server_fp8.sh 启动后，执行 sh openapi.sh，返回模型生成内容即服务可用。
3. 训练验证：bash train.sh 成功运行后每 step 打印 loss（官方示例中 loss 从 7.4 逐步下降到 0.1 量级），即训练环境就绪。
4. 资源核对：nvidia-smi 可见 16 卡（BF16）或 8 卡（量化）均被 vLLM 占用，显存利用率接近 gpu_memory_utilization=0.98。

四、使用方法

4.1 基础用法：vLLM Python 推理

最小可运行示例（与 3.1 步骤 4 一致，量化部署把 quantization=None 改为对应量化方式、tensor_parallel_size 改为 8）：

from vllm import LLM, SamplingParams

llm = LLM(model="/path/to/model",
          trust_remote_code=True,
          max_model_len=10240,
          dtype='bfloat16',
          tensor_parallel_size=16,
          gpu_memory_utilization=0.98)

params = SamplingParams(temperature=0.7, top_p=0.6,
                        max_tokens=200, top_k=20,
                        repetition_penalty=1.05)

outputs = llm.generate(["用一句话解释 MoE 模型"], params)
print(outputs[0].outputs[0].text)

4.2 服务化用法：HTTP 服务 + 客户端请求

# 主节点启动服务
cd inference
sh run_server.sh          # 或 run_server_int8.sh / run_server_fp8.sh

# 另一终端执行请求脚本（先改好脚本内 LOCAL_IP / MODEL_PATH）
sh openapi.sh

请求报文格式遵循官方 openapi.sh 示例（OpenAI 兼容风格 chat 接口），具体字段以仓库 inference/openapi.sh 为准。

4.3 进阶功能

• 微调数据格式：训练数据为 messages 格式 JSONL，默认 system prompt 为 "You are a helpful assistant."，支持单轮与多轮对话：

```python messages = [ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "海水为什么是咸的"}, {"role": "assistant", "content": "海水咸是因为含有大量溶解的盐类……"} ]

from transformers import AutoTokenizer tokenizer = AutoTokenizer.from_pretrained("./models", use_fast=False, trust_remote_code=True) ids = tokenizer.apply_chat_template(messages) ```

• 训练案例：仓库 examples/ 提供汽车领域实体抽取案例（约 5k 条数据，基座为 Hunyuan-Large-Instruct），脚本为 examples/train_demo.sh，需修改其中 model_path、train_data_file、output_path 后运行。
• 显存不够时：参考 DeepSpeed 官方文档，在 zero3 配置中去掉 auto 并调小 stage3_param_persistence_threshold、stage3_prefetch_bucket_size、stage3_max_reuse_distance。
• 长上下文：预训练模型 256K / 指令模型 128K；KV Cache 经 GQA+CLA 压缩后可承载更长 batch（以官方文档为准）。
• 长文本评测基准：官方自研长文本评测集 PenguinScrolls（GitHub / HF 数据集）。

4.4 适用场景

• 企业级中文大模型私有化部署：混元在中文基准（CMMLU/C-Eval/CMATH）上表现突出，适合对中文能力要求高的内部知识库、智能客服；
• MoE 架构研究与二次预训练/微调：389B/52B 的 MoE 实现 + hf-deepspeed 脚本可直接作为研究底座；
• 长文档处理：128K/256K 上下文 + KV Cache 压缩，适合长文档摘要、代码库问答；
• 高吞吐在线推理：FP8 量化 + vLLM 可将成本压到 8 卡，适合有一定 GPU 资源的团队做 API 服务；
• 无自建算力时：直接用腾讯云 TI 平台或混元 API，零运维。

五、常见问题排查（FAQ）

Q1：启动服务时报 ModuleNotFoundError: No module named 'transformers_modules' - 原因：多机 Ray 模式下，工作节点缺少主节点缓存的远程代码模块。 - 解决：官方 README 给出的方案——把主节点的 ~/.cache/huggingface/modules/ 目录复制到所有工作节点的对应路径后重启服务。

Q2：Ray 启动失败或节点无法加入 - 原因：节点间网络不通、网卡绑定错误或端口被占用。 - 解决：先 ray stop 清理；确认 VLLM_HOST_IP 为本机 bond1 实际 IP、NCCL_SOCKET_IFNAME=bond1 网卡名正确；主节点 --port=6379 与工作节点 --address=主节点IP:6379 一致；用 vLLM 官方 debugging 脚本验证多机通信。

Q3：显存不足（OOM）或加载失败 - 原因：BF16 需要 16 卡而只起了 8 卡；或 batch / max_model_len 过大。 - 解决：BF16 确认 16 卡组网；优先改用 FP8 / Int8 量化（8 卡即可）；调小 max_num_seqs、max_model_len；训练侧换 ds_zero3_offload.json 或开启 --gradient_checkpointing。

Q4：trust_remote_code=True 是否有安全风险 - 原因：vLLM 的 trust_remote_code 会加载并执行模型仓库中的远程代码，可能执行恶意代码。 - 解决：官方建议——除非业务明确需要，保持关闭；本模型目录已随仓库提供 modeling_hunyuan.py 等实现，部署时确保模型来自官方 HF/腾讯云 CDN，不要使用来路不明的第三方权重。

Q5：BF16 为什么必须 16 张 H20？能不能用 8 卡跑 BF16？ - 原因：389B 模型 BF16 权重约需 778GB+ 显存，官方在 H20（96GB/卡）上实测 16 卡（约 1536GB）才能承载权重+KV Cache。 - 解决：8 卡预算下请用 Int8 weight-only 或 FP8 量化模型（官方性能表显示 8 卡量化与 16 卡 BF16 单请求速度基本持平）。

Q6：全参微调为什么要 32 卡？LoRA 为什么也要 8 卡？ - 原因：389B MoE 即使在 zero3+offload、max_seq_length=2048、per_device_train_batch_size=1 的最低配置下，全参微调仍需 32 卡（官方 README 实测值）。 - 解决：资源不够时用 LoRA（8 卡），LoRA 只训练 q/k/v/o_proj，官方最低配置下单步约 35 秒（per_device_train_batch_size=1、gradient_accumulation_steps=1）。

Q7：模型下载慢或 HF 连不上 - 解决：改用腾讯云 CDN 直链 zip（见 3.1 步骤 1 表格），或使用 Gitee 镜像仓库 gitee.com/Tencent/Tencent-Hunyuan-Large；下载完成后校验文件完整性再解压。

Q8：续训时 loss 与上次略有偏差 - 原因：部分非确定性算法引入随机性，官方说明属正常现象。 - 解决：参考 Hugging Face Transformers Trainer 关于随机性的说明；如需严格复现请固定随机种子并关闭非确定性算子。

六、部署注意事项与最佳实践

1. 先量化后全精度：同等效果下 FP8/Int8 把 GPU 需求从 16 卡降到 8 卡，生产环境优先 W8A8C8-FP8（精度损失 <1%、吞吐 +70%）。
2. 不要用特权模式跑生产：--privileged 仅用于内网测试，生产需做安全评估、加固与监控（官方 README 明示风险）。
3. Ray/NCCL 只放内网：Ray 6379、8265 等端口默认无认证，务必绑定可信内网或加 ACL；--net=host 模式下尤其注意。
4. 模型来源只认官方：BF16/FP8 权重仅从官方 Hugging Face 仓库、腾讯云 CDN zip、Gitee 镜像获取，避免第三方二次打包权重。
5. 多机组网一致性：多机训练/推理时各节点代码、数据、脚本必须一致，推荐挂载共享盘；SSH 无密码互信与时钟同步（NTP）提前配好。
6. LoRA 权重需离线合并：zero3 下训练只存 LoRA adapter，上线前用 merge_lora_weight.sh 合并为完整权重，保存精度建议 bf16。
7. 监控与日志：关注 vLLM 日志中的 gpu_memory_utilization、KV Cache 命中率与 Ray 节点状态；长文本场景重点观察 KV Cache 占用（官方 GQA+CLA 已压缩 50%）。
8. 没算力就上云：16 卡 H20 自建成本极高，个人/小团队优先 TI 平台托管或混元 API，不要在消费级显卡上强行尝试。
9. 许可合规：模型采用腾讯混元社区许可协议（Tencent Hunyuan Community License Agreement），商用前须仔细阅读协议条款（该协议对欧盟地区有限制）。

七、参考资料

• GitHub 仓库：https://github.com/Tencent/Tencent-Hunyuan-Large
• Hugging Face 模型仓库：https://huggingface.co/tencent/Tencent-Hunyuan-Large
• 官方在线 Demo（HF Spaces）：https://huggingface.co/spaces/tencent/Hunyuan-Large
• 官方网站：https://llm.hunyuan.tencent.com/
• 技术报告（arXiv:2411.02265）：https://arxiv.org/abs/2411.02265
• 推理 Docker 镜像：https://hub.docker.com/r/hunyuaninfer/hunyuan-large
• Gitee 镜像：https://gitee.com/Tencent/Tencent-Hunyuan-Large
• 腾讯云 TI 平台：https://cloud.tencent.com/product/ti
• Hunyuan-Large 最佳实践（TI）：https://cloud.tencent.com/document/product/851/112032
• 混元 API 文档：https://cloud.tencent.com/document/product/1729/97730
• vLLM 多机调试脚本：https://docs.vllm.ai/en/latest/getting_started/debugging.html
• 长文本基准 PenguinScrolls：https://github.com/Penguin-Scrolls/PenguinScrolls
• 联系开源团队邮箱：hunyuan_opensource@tencent.com