Hunyuan-MT-7B WebUI 部署后无法访问网页的排查指南
在 AI 平台一键部署了 Hunyuan-MT-7B-WEBUI 镜像，运行启动脚本后终端提示服务已启动，但浏览器访问时出现空白、转圈或无法连接。这通常不是模型问题，而是 WebUI 服务启动成功不等于网页能被正常访问。中间涉及端口暴露、网络策略、服务绑定地址及浏览器访问方式等关键环节。
本文聚焦解决'部署完成但网页打不开'的问题，覆盖常见故障场景。
1. 先确认：服务到底启没启动？
终端输出'已启动'仅代表脚本执行成功，不代表 WebUI 服务真正监听端口。第一步必须验证服务进程是否存活。
1.1 查看服务进程是否存在
在终端中执行以下命令：
ps aux | grep "webui" | grep -v "grep"
如果返回类似结果，说明服务进程正在运行：
root 12345 0.1 12.3 12345678 9876543 ? Sl 10:23 0:45 python -m webui --model-path /models/Hunyuan-MT-7B --host 0.0.0.0 --port 7860 ...
- 有输出 → 进入第 2 步排查网络
- 无输出 → 服务根本没起来，跳转至第 1.2 节
1.2 检查启动失败的常见原因
若查不到进程，说明脚本执行中途报错退出。需回看日志。常见报错及解法如下：
-
报错：'CUDA out of memory'或'OOM when allocating tensor' → 显存不足。该模型 FP16 推理需至少 14–16GB 显存。 解法：换用高显存显卡（如 RTX 3090/A100）；或在脚本中添加
--load-in-4bit参数启用 4 位量化。 -
报错：'Address already in use'或'port 7860 is occupied' → 端口被其他进程占用。 解法：杀掉占用进程：
lsof -i :7860 | awk '{print $2}' | tail -n +2 | xargs kill -9 -
报错：'OSError: Can't load tokenizer'或'File not found' → 模型路径错误或权重未完整下载。 解法：确认模型目录是否存在：
ls -l /models/若为空，需手动从 Hugging Face 下载（需配置 HF_TOKEN）：
huggingface-cli download Tencent-Hunyuan/Hunyuan-MT-7B --local-dir /models/Hunyuan-MT-7B --revision main -
报错：'No module named 'transformers'' → Python 依赖缺失。 解法：手动安装最新版依赖：
pip install --upgrade transformers accelerate torch sentencepiece
2. 网络通不通？三步验证端口可达性
服务进程在跑，但网页打不开，90% 的问题出在网络层。服务器的端口没有'通向外面'。
2.1 确认服务监听的是 0.0.0.0，而非 127.0.0.1
这是最高频的配置陷阱。查看启动脚本中是否包含 参数。若写成 或 ，服务只接受本机内部请求，外部浏览器无法访问。
