Hy4-preview 详细部署教程

1. 部署前必读：硬件门槛与模型定位

Hy4-preview 是腾讯混元团队开源的 770B 总参数 / 49B 激活参数 的 MoE 旗舰模型，原生支持 100 万 token 上下文。它是一个面向生产力场景的重型模型，而非轻量级本地玩具。

1.1 硬件要求（关键）

精度 权重体积 推荐硬件
BF16 ~1.5 TB 16×B200 或 8×B300（配合 MTP 投机解码）
FP8（推荐） ~760 GB 8×H100/H200 或 8×B200（Tensor Parallelism）

⚠️ 重要提醒：如果你没有 8 卡及以上 GPU 的服务器环境，本地部署 Hy4-preview 是不现实的。对于个人开发者，官方建议的方案是使用云端 API，而非本地部署。

1.2 推理引擎选择

引擎 推荐场景 官方支持
vLLM 生产环境，性能最优，官方预构建镜像 ✅ 官方 Recipe
SGLang 多架构（x86 + Arm），高级调度特性 ✅ 官方 Cookbook

核心要点：Hy4-preview 的注意力机制是 Gated DeepSeek Sparse Attention (Gated DSA)，必须使用 FLASHMLA_SPARSE 后端，这不是可选项。

2. vLLM 部署（官方推荐）

2.1 前置要求

  • GPU：8×H100/H200 或 8×B200（FP8 量化版）
  • vLLM 版本：0.29.0 或更新版本
  • Docker 已安装
  • 磁盘空间：至少 800 GB（存放 FP8 权重）

2.2 下载模型权重

从 Hugging Face 或 ModelScope 下载 FP8 量化版本（体积更小，性能优秀）：

1
2
3
4
5
6
# 使用 huggingface-cli
huggingface-cli download tencent/Hy4-preview-FP8 --local-dir ./Hy4-preview-FP8

# 或使用 ModelScope（国内网络更快）
pip install modelscope
modelscope download --model tencent/Hy4-preview-FP8 --local_dir ./Hy4-preview-FP8

2.3 启动推理服务（官方 Docker 镜像）

使用官方预构建镜像 vllm/vllm-openai:hy4-preview：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
docker run --gpus all \
  -p 8000:8000 \
  --ipc=host \
  -e VLLM_ENABLE_HPC_OPS=1 \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  vllm/vllm-openai:hy4-preview tencent/Hy4-preview-FP8 \
    --tensor-parallel-size 8 \
    --speculative-config '{"num_speculative_tokens":3,"method":"mtp"}' \
    --attention-backend FLASHMLA_SPARSE \
    --tool-call-parser hy_v4 \
    --reasoning-parser hy_v4 \
    --enable-auto-tool-choice \
    --port 8000 \
    --served-model-name hy4-preview

关键参数解读：

参数 作用
--tensor-parallel-size 8 8 卡张量并行，将 770B 模型分布到 8 张 GPU
--speculative-config '{"num_speculative_tokens":3,"method":"mtp"}' 启用内置 MTP 投机解码，加速生成
--attention-backend FLASHMLA_SPARSE 必需，支持 Gated DSA 稀疏注意力
--tool-call-parser hy_v4 解析混元专用工具调用格式
--reasoning-parser hy_v4 解析混元专用推理链格式
--enable-auto-tool-choice 启用自动工具选择

💡 VLLM_ENABLE_HPC_OPS=1：启用高性能计算算子，提升推理效率。

2.4 验证服务

1
2
3
4
5
6
7
8
curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hy4-preview",
    "messages": [{"role": "user", "content": "你好，请介绍一下你自己"}],
    "temperature": 0.9,
    "top_p": 1.0
  }'

2.5 Python 客户端调用

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
from openai import OpenAI

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

response = client.chat.completions.create(
    model="hy4-preview",
    messages=[
        {"role": "user", "content": "你好！请简要介绍一下你自己"},
    ],
    temperature=0.9,
    top_p=1.0,
)

# 默认推理模式（high）会返回 reasoning_content（思维链）
print("推理过程：", response.choices[0].message.reasoning_content)
print("最终回答：", response.choices[0].message.content)

关闭深度推理模式（直接回答，不输出思维链）：

1
2
3
4
5
6
7
8
response = client.chat.completions.create(
    model="hy4-preview",
    messages=[{"role": "user", "content": "1+1等于几？"}],
    temperature=0.9,
    top_p=1.0,
    extra_body={"chat_template_kwargs": {"reasoning_effort": "no_think"}},
)
print(response.choices[0].message.content)

3. SGLang 部署（多架构支持）

SGLang 提供 x86 和 Arm 多架构的官方镜像。

3.1 拉取镜像

1
docker pull lmsysorg/sglang:hy4-preview

3.2 启动服务

1
2
3
4
5
6
7
8
9
10
11
12
docker run --gpus all --ipc=host -p 8000:8000 lmsysorg/sglang:hy4-preview \
  python3 -m sglang.launch_server \
    --model tencent/Hy4-preview-FP8 \
    --tp-size 8 \
    --reasoning-parser auto \
    --tool-call-parser auto \
    --speculative-algorithm NEXTN \
    --speculative-num-steps 3 \
    --speculative-eagle-topk 1 \
    --speculative-num-draft-tokens 4 \
    --port 8000 \
    --served-model-name hy4-preview

SGLang 参数说明：

参数 作用
--tp-size 8 张量并行度
--speculative-algorithm NEXTN 使用 MTP 投机解码
--reasoning-parser auto 自动选择混元推理解析器
--tool-call-parser auto 自动选择混元工具调用解析器

4. 其他部署方案

4.1 华为昇腾 NPU（实验性）

如果你使用 Atlas 800I A3（16 卡昇腾 NPU），可使用 vllm-ascend 的专用镜像：

1
2
3
4
5
6
7
docker pull quay.io/ascend/vllm-ascend:hy4-a3

# 创建容器（需挂载 16 个 NPU 设备和权重目录）
docker run -itd --name vllm_ascend_hy4 --shm-size=1000g \
  --device /dev/davinci_manager --device /dev/devmm_svm --device /dev/hisi_hdc \
  -v /mnt/weight:/mnt/weight \
  quay.io/ascend/vllm-ascend:hy4-a3 bash

⚠️ 注意：昇腾支持目前是实验性的，源码安装尚不支持，必须使用提供的 Docker 镜像。

4.2 GGUF 格式（llama.cpp，不推荐）

社区提供了 GGUF 量化版本，但 llama.cpp 原生不支持 Hy4 的 hyv4 架构，需要手动打补丁编译，且性能远不如 vLLM/SGLang。仅建议在特殊场景下尝试。

5. 常见问题与调优

5.1 CUDA out of memory

这是部署 Hy4-preview 最常见的问题。显存规划不合理是根本原因。

解决步骤：

  1. 将 --gpu-memory-utilization 从默认的 0.95 降至 0.85
  2. 如果仍不足，将 --max-model-len 从 8192 降至 4096（在上下文长度和显存之间权衡）

5.2 性能优化（延迟敏感场景）

优化方向 参数 效果
控制上下文长度 将 --max-model-len 设为任务真正需要的值 KV Cache 按最大长度预分配，设得越长越占显存
前缀缓存 --enable-prefix-caching 多个请求共享相同系统 Prompt 时，复用已计算的 KV Cache
流水线并行 --pipeline-parallel-size 比张量并行更省显存，但吞吐量较低

5.3 模型已知局限

官方明确说明 Hy4-preview 是早期预览版，存在以下已知问题：

  • 推理时间过长：在复杂任务上可能花费超出必要的时间
  • 过度自我验证：倾向于反复检查自己的工作

这是有意为之的“早发布、早反馈”策略。

6. 许可与合规

  • 许可证：Apache License 2.0，可自由用于商业用途
  • 模型权重：可从 Hugging Face、ModelScope、GitCode、CNB 获取
  • 数据隐私：所有推理在你的本地硬件上完成，数据不出内网

7. 部署路径建议

你的情况 推荐方案
有 8×H100/H200 服务器 vLLM Docker 一键部署（官方推荐）
有 16×B200 服务器，追求极致性能 vLLM + BF16 + MTP 投机解码
有 16 卡昇腾 Atlas 800I A3 vllm-ascend 专用镜像（实验性）
个人开发者，无多卡环境 使用云端 API，不要尝试本地部署
需要 Arm 架构支持 SGLang 多架构镜像