TRELLIS

环境要求

• Linux 系统 + NVIDIA GPU（官方模型在 NVIDIA A100 上训练）
• 已安装 conda（用于创建 trellis 环境）
• CUDA Toolkit（--new-env 默认使用 CUDA 11.8，也可自备其他版本）
• 默认环境为 PyTorch 2.4.0 + CUDA 11.8（由 setup.sh --new-env 安装）
• 磁盘空间与网络充足，依赖数量多、编译耗时长

安装与启动步骤

1. 1克隆代码仓库

   必须带 --recurse-submodules，否则子模块缺失会导致后续编译失败；克隆后进入 TRELLIS 目录。

   git clone --recurse-submodules https://github.com/microsoft/TRELLIS.git
   cd TRELLIS

   复制

2. 2一键安装依赖

   加 --new-env 会新建名为 trellis 的 conda 环境；想用已有环境则去掉该参数。安装耗时较长请耐心等待。

   . ./setup.sh --new-env --basic --xformers --flash-attn --diffoctreerast --spconv --mipgaussian --kaolin --nvdiffrast

   复制

3. 3指定 CUDA 版本路径

   仅在机器装了多个 CUDA Toolkit 版本时需要，把 PATH 指向正确的那个版本，再执行上一步安装。

   export PATH=/usr/local/cuda-11.8/bin:$PATH

   复制

4. 4运行生成流水线

   README 的 Usage 只给出核心调用，需自行准备 image 输入与 pipeline 对象。seed、采样步数与 cfg_strength 均可调。

   outputs = pipeline.run(
       image,
       seed=1,
       # Optional parameters
       # sparse_structure_sampler_params={
       #     "steps": 12,
       #     "cfg_strength": 7.5,
       # },
       # slat_sampler_params={
       #     "steps": 12,
       #     "cfg_strength": 3,
       # },
   )

   复制

5. 5训练环境准备

   训练需额外安装 --train 依赖，使用 Linux + NVIDIA GPU，数据集组织方式参考 TRELLIS-500K，超参与模型结构在 configs/ 下配置。

关键配置

如何确认成功

setup.sh 安装无报错并成功进入 trellis 环境（可执行 . ./setup.sh --help 查看参数）；pipeline.run 正常返回 outputs 即为跑通。

常见问题

注意事项

• setup.sh 的完整参数可用 . ./setup.sh --help 查看，--demo 会安装 demo 所需的全部依赖。
• 依赖数量庞大，安装过程可能很慢，请预留足够时间。
• 训练并未包含在 --basic 中，需要额外安装 --train 依赖。
• 各模块（VAE、生成模型）的配置文件和预训练权重见 configs/ 目录与 HuggingFace 上的 TRELLIS-image-large、TRELLIS-text-base/large/xlarge 仓库。