腾讯混元hy4 preview接入需升级sdk至v2.4.0，绑定专属api权限，使用新端点https://api.hunyuan.tencent.com/v1/hy4-preview/chat/completions，显式声明model字段，并添加x-hunyuan-speculative:mtp-3请求头。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
腾讯混元接入新版本SDK后连接失败，通常是因为Hy4 preview的认证方式、端点路径或请求头结构已变更，旧版SDK仍按Hy3或更早协议发起请求，导致401/404/502等错误响应。
确认SDK版本与Hy4 preview兼容性
打开终端，执行 pip show tencent-hunyuan-sdk 或查看项目 requirements.txt 中的版本号；当前官方支持Hy4 preview的最低SDK版本为 【v2.4.0】，低于此版本（如 v2.3.7）无法解析 MTP 推测解码层返回的 multi-token 响应格式，会直接抛出 JSONDecodeError。
若版本过低，运行：pip install --upgrade tencent-hunyuan-sdk==2.4.0；注意不要跳过 ==2.4.0 直接用 --upgrade，否则可能升级到尚未适配FP8权重加载逻辑的预发布版。
检查API密钥与授权域是否匹配
Hy4 preview 的 API 密钥必须在 TokenHub 控制台中显式绑定「Hy4 preview」服务权限，旧密钥即使能调通 Hy3，也无法访问新模型端点。
登录 TokenHub 控制台 → 进入「密钥管理」→ 找到对应密钥 → 点击「编辑权限」→ 勾选 【Hy4 preview（770B-MoE）】 并保存。
未勾选该权限时，请求会返回 {"code":403,"message":"Access denied: model not authorized"}，而非常规的鉴权失败提示。
更新请求参数与端点URL
Hy4 preview 不再复用 Hy3 的 /v1/chat/completions 路径，必须使用专属端点：
将原请求 URL 从 https://api.hunyuan.tencent.com/v1/chat/completions 替换为：https://api.hunyuan.tencent.com/v1/hy4-preview/chat/completions。
请求体中必须显式声明 "model": "hy4-preview" 字段；若遗漏，服务端会拒绝路由并返回 400 错误，且不提供具体缺失字段提示。
启用 MTP 推测解码时，需在请求头中添加：X-Hunyuan-Speculative: mtp-3；该头不可省略，否则即使模型支持也不会激活多 token 预测路径，导致吞吐量下降 40% 以上。
验证本地FP8推理环境是否就绪
方法一：检查 CUDA 与 cuBLAS 版本
运行 nvidia-smi 确认驱动 ≥ 535.104.05；再执行 python -c "import torch; print(torch.version.cuda, torch.__version__)"，输出需满足 CUDA 12.1+ 且 PyTorch ≥ 2.3.1；低于此组合将无法加载 FP8 权重，SDK 初始化时直接报 RuntimeError: fp8 requires CUDA >= 12.1。
方法二：绕过FP8加载进行快速验证
在初始化客户端时传入参数：fp8_enabled=False，例如：HunYuanClient(..., fp8_enabled=False)；这会让 SDK 自动回退至 BF16 加载，可排除硬件兼容性干扰，快速定位是环境问题还是配置问题。
