gr.Model3D does not display valid 3D models (PLY/GLB/OBJ) — only shows a blank canvas

问题场景

用户在使用 Gradio 5.49.1 时，通过 gr.Model3D 组件展示本地或 allowed_paths 白名单内的 3D 模型文件（PLY/GLB/OBJ/STL）。模型文件本身有效——在 Blender、MeshLab 中均可正常打开，但 Gradio 的 3D 查看器区域始终为空白灰色画布，且不抛出任何前端或后端错误。

报错原文

gr.Model3D does not display valid 3D models (PLY/GLB/OBJ) — only shows a blank canvas

此外无 JavaScript 控制台错误、无网络请求失败、Gradio 终端日志正常（仅显示文件白名单与本地 URL 信息）。

原因分析

可能原因：gr.Model3D 底层依赖 Three.js 渲染，而 Three.js 需要浏览器提供 WebGL2 上下文。当 Chrome 的 GPU 加速被关闭、GPU 进程异常或显卡驱动不兼容时，浏览器可能只能提供软件渲染（SwiftShader），导致 WebGL2 初始化失败或渲染异常，最终呈现为空白画布。该问题与 PLY/GLB/OBJ 文件格式本身无关——多个已验证模型均无法显示，说明问题出在渲染管线而非模型解析。

环境排查

• 在 Chrome 地址栏输入 chrome://gpu，检查 WebGL2 是否显示为 Enabled；若显示 Disabled 或 Software only，即为异常状态。
• 确认 Gradio 版本是否为 5.49.1（同一 Issue 中同时提及了 #12120 相关问题，可能存在版本共因）。
• 尝试其他浏览器（如 Firefox、Edge）访问同一页面，可快速判断是否为 Chrome 特有环境问题。
• 确认系统显卡驱动是否正常（Ubuntu 24.04 下尤其注意 NVIDIA 闭源驱动的安装情况）。
• 测试 gr.Model3D 在本地文件路径和 HTTP 路径下是否表现一致，排除 allowed_paths 配置差异。

解决步骤

1. 打开 Chrome，访问 chrome://settings/system，找到“使用图形加速（如可用）”或“GPU 加速”开关。
2. 关闭该开关，完全退出并重启 Chrome（建议通过 chrome://restart 或彻底关闭进程重启）。
3. 访问 chrome://gpu，确认 WebGL2 状态；此时可能变为 Software only 或仍为异常。
4. 回到 chrome://settings/system，重新开启 GPU 加速开关。
5. 再次完全重启 Chrome，然后访问 chrome://gpu，确认 WebGL2 显示为 Enabled。
6. 重新打开 Gradio 应用页面，检查 gr.Model3D 是否正常渲染模型。

如果上述方法无效，可以依次尝试：

1. 在 Chrome 地址栏访问 chrome://flags，搜索 WebGL，确认相关实验特性未被强制禁用。
2. 升级显卡驱动或更换浏览器（Firefox/Edge）做交叉验证。

验证方法

重新加载 Gradio 页面后，gr.Model3D 区域应正常显示彩色立方体或其他 3D 模型，能进行旋转、缩放等交互操作。同时在 chrome://gpu 页面确认 WebGL2 状态为 Enabled 而非 Disabled 或 Software only。

参考来源

gradio-app/gradio #12158

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。