开发者发布TRELLIS.2一键安装脚本，支持RTX 5090在WSL2下运行

一个用于在 WSL2 的 Ubuntu 中、于 NVIDIA Blackwell GPU（如 RTX 5090）上安装 Microsoft TRELLIS.2（图像 → 带纹理 3D 模型）的一键脚本安装器。

官方的 setup.sh 会安装 PyTorch 2.6 + CUDA 12.4 以及预编译的 flash-attn。这些都不支持 Blackwell（sm_120），因此安装要么失败，要么在运行时崩溃。本仓库安装一套可用的组合，并修补过程中出问题的少数几处。

GPU RTX 5090（32 GB） Windows 驱动 616.92 操作系统 Windows 11，WSL2 上的 Ubuntu 24.04 CUDA 工具包（WSL 内） 13.1 PyTorch 2.14.1 + cu130，xformers 0.0.35 结果 example.py 端到端运行约 4.5 分钟（含模型加载和 4K 纹理 GLB 导出）

前置条件 Windows 上安装最新的 NVIDIA 驱动。WSL 使用 Windows 驱动。不要在 WSL 内安装 Linux GPU 驱动。 WSL2 与 Ubuntu。BIOS 中必须保持启用虚拟化，因为 WSL2 需要它。 WSL 内安装 CUDA Toolkit 13.x。使用 https://developer.nvidia.com/cuda-downloads 上 Linux → x86_64 → WSL-Ubuntu 的安装器。它只安装工具包，不安装驱动。用 ls /usr/local/cuda-13* 检查。 构建工具： sudo apt install -y git python3-venv python3-dev build-essential 约 40 GB 可用磁盘空间：约 22 GB 模型权重加上 Python 环境。 64 GB 系统内存以及下面的 WSL 内存设置。一个 TRELLIS.2 进程在 WSL 中使用 17–35 GB 内存。

WSL 内存设置（重要） 在 WSL 默认设置下，或者给 WSL 几乎全部内存且没有 swap 时，TRELLIS.2 可能让整个 WSL 挂掉。你会被丢回 PowerShell，有时 WSL 拒绝再次启动（Wsl/Service/E_UNEXPECTED），直到重启 Windows。 发生的情况：TRELLIS.2 进程增长到 32–54 GB 内存。它在各阶段之间把模型副本保留在内存中，中间网格可能有 500 万–1700 万三角形，并且在 web UI 中反复生成时内存会逐渐上升。Linux 的 out-of-memory killer 随后会在 WSL 自己的 init.scope 内将其杀死，WSL 约一分钟后关闭。 使用下面的修复措施实测（RTX 5090，一个进程内三次 1536 生成，每次含预览渲染和 4K GLB 导出，2026-10-26）： 它在第二次生成后趋于平稳。未使用 swap，峰值 VRAM 约 10 GB，每次生成约 1 分钟。内存主要取决于图像内容（产生多少体素），而不是分辨率设置。例如，一幅平面 2D 绘图产生的体素比一幅彩绘全身角色多约 3 倍，仍可能超过 34 GB 上限。那时只有 TRELLIS.2 会被停止。 [wsl2] memory=40GB swap=16GB 然后在 PowerShell 中运行 wsl --shutdown 并重新启动 WSL。 run.sh 在自己的内存组中运行 TRELLIS.2（systemd-run --scope，上限 34 GB 内存加 12 GB swap）。如果超出，只有 TRELLIS.2 被停止并给出提示，WSL 继续运行。用 TRELLIS_MEM_MAX=30G ./run.sh 修改上限。 如果 WSL 仍无法启动（E_UNEXPECTED），在重启电脑前，先在管理员 PowerShell 中尝试： wsl --shutdown Restart-Service WslService

安装 git clone https://github.com/Creepybits/trellis2-blackwell-wsl.git cd trellis2-blackwell-wsl ./install.sh # 安装到 ~/TRELLIS.2（或传入其他路径） 脚本耗时约 10–15 分钟。大部分时间用于编译五个 CUDA 扩展。 TRELLIS.2 从 Hugging Face 下载两个模型，需要先接受许可： 在 huggingface.co 登录，打开每个链接并申请访问权限。RMBG 通常立即批准。Meta 可能需要一段时间。然后从 WSL 登录： ~/TRELLIS.2/.venv/bin/hf auth login 等待 DINOv3 批准？可以取消注释 ~/TRELLIS.2/run.sh 中的 DINOV3_MODEL 行，改用社区镜像。2026-10-09 时该镜像文件的 SHA-256 哈希与 Meta 的相同。请自行再次核对，因为镜像可能变化。无论哪种方式，DINOv3 许可仍然适用。 ~/TRELLIS.2/run.sh example.py # 测试：写出 sample.glb 和 sample.mp4 ~/TRELLIS.2/run.sh # web UI → 在 Windows 中打开 http://localhost:7860 ~/TRELLIS.2/run.sh app_texturing.py # 纹理 web UI 首次运行会下载约 22 GB 权重到 ~/.cache/huggingface。

Microsoft 没有记录这些。以下根据源代码说明它们的作用。 TRELLIS.2 分三个阶段构建模型：1. 稀疏结构（整体形状的粗略体素草图），2. 形状（详细几何），3. 材质（颜色、金属度、粗糙度）。每个阶段都从噪声开始，逐步去除噪声。每个阶段都有相同的四项设置： 材质（阶段 3）默认 Guidance Strength 为 1，这意味着颜色引导关闭。在我们的测试中，3–5（配合 Rescale 0.5–0.7）只略微改变结果。 来自多次测试运行（属观察，非官方指导）： Mixamo 可自动绑定人形角色，并有大量免费动画库。它不接受 GLB，所以先转换： ~/TRELLIS.2/run.sh glb_to_mixamo.py character.glb # 写出 character_mixamo.zip 按原样上传该 zip。它包含一个带纹理的 OBJ，材质为哑光，因此绑定后的 FBX 回来时不会看起来像闪亮的塑料。 如果导出结果太暗或“金属感”过强，或颜色发白： ~/TRELLIS.2/run.sh fix_materials.py input.glb output.glb --saturation 2.0 --metal 0 它将金属度设为 0 并提升颜色饱和度（在 CIELAB 中，因此保留色相和亮度）。它无法恢复模型已完全移除的颜色。

问题 修复 torch 2.6 / cu124 没有 sm_120 内核 torch 2.14.1 + cu130 flash-attn 没有 Blackwell wheel；从源码构建需要数小时 ATTN_BACKEND=xformers（TRELLIS.2 支持，且 xformers 提供 sm_120 wheel） 扩展失败：使用 PyTorch 需要 C++20 或更高版本的兼容编译器 setup.py 标志从 c++17 改为 c++20 nvdiffrec 链接失败：cannot find -lcuda LIBRARY_PATH=/usr/lib/wsl/lib（WSL 将 libcuda.so 放在那里） cv2.error ... !_src.empty() in function 'cvtColor' 加载 .exr opencv-python-headless<5 'DINOv3ViTModel' object has no attribute 'layer' 针对 transformers ≥ 5 的补丁（层移到 model.model.layer） Hugging Face 下载卡在 0 字节 HF_HUB_DISABLE_XET=1

（原文较长，此处译出前 6000 字，完整内容请点「打开原文」。）