必须走api接入路径，因客户数据需全程离线处理且团队无cuda经验，而当前账号仅开通api配额、无本地部署授权，不满足本地部署的硬件与系统硬性条件。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
你需要在腾讯混元大模型的云端API接入和本地部署之间做决策，但又不确定哪种方式更适合当前业务场景——比如你刚接到一个客户数据必须全程离线处理的需求，同时团队里只有1名熟悉Python但没碰过CUDA的工程师。
先判断核心约束条件
打开腾讯云控制台 → 进入“混元大模型”服务页 → 查看当前账号下已开通的服务类型。如果页面顶部显示【已开通 API 调用配额】且无【私有化部署包下载入口】，说明你当前仅拥有公有云访问权限，【必须走API接入路径】，本地部署选项不可见。
若你已在“企业版服务协议”中签署过《本地化部署授权书》，且收到邮件含“Hunyuan-Local-Deploy-2026Q3”字样附件，则跳过此阶段，直接进入环境准备环节。
云端接入：3步完成最小可用验证
方法一：直连腾讯云API（无需安装任何客户端）
① 在腾讯云密钥管理控制台生成新密钥，勾选“hunyuan:Invoke”最小权限策略；
② 用curl命令测试连通性：curl -X POST https://api.hunyuan.cloud.tencent.com/v1/chat/completions -H "Authorization: Bearer YOUR_SK_XXX" -H "Content-Type: application/json" -d '{"model":"hunyuan-pro","messages":[{"role":"user","content":"你好"}]}'；
这一步必须返回HTTP 200且含"choices"字段，否则检查密钥是否复制完整、区域是否选对（目前仅支持ap-guangzhou和ap-beijing两个地域）。
方法二：通过CherryStudio图形界面快速验证
下载v1.8.3以上版本CherryStudio → 启动后点击左下角“设置” → 搜索“腾讯混元” → 填入API密钥和地址https://api.hunyuan.cloud.tencent.com/v1/ → 点击“检查”按钮；
弹窗显示“连接成功”即完成，此时可立即切换到“助手”标签页发起对话。注意：该方式默认使用hunyuan-standard模型，如需调用hunyuan-pro需手动添加模型ID。
本地部署：只在满足三个硬性条件时启动
条件一：服务器已安装NVIDIA驱动版本≥535.104.05；
条件二：显存总量≥24GB（实测hy4-preview FP16需占用21.7GB，预留缓冲空间）；
条件三：操作系统为Ubuntu 22.04 LTS或CentOS Stream 9（Windows子系统WSL2不被官方支持，会出现vLLM无法绑定GPU的报错）。
不满足任一条件就停止操作——强行部署会导致模型加载失败后反复重试，消耗大量磁盘IO并触发系统OOM Killer强制杀进程。
混合架构：用Dify桥接云端与本地能力
当你需要同时使用混元的云端多模态能力（如文生视频）和本地OCR解析能力时：
① 部署Dify开源平台（推荐用docker-compose方式，配置文件中network_mode设为host）；
② 在Dify后台“模型配置”页新增两个模型：一个指向https://api.hunyuan.cloud.tencent.com/v1/（命名hunyuan-cloud），另一个指向本地vLLM服务地址http://127.0.0.1:8000/v1（命名hunyuan-local）；
③ 创建工作流时，在“图像理解”节点选择hunyuan-local，在“视频生成”节点选择hunyuan-cloud；
Dify会自动按节点需求分发请求，无需修改任何代码。这一步的关键是确保两个模型的API格式完全兼容OpenAI标准，否则工作流执行时会卡在schema校验环节。
