TRELLIS-text-large-voxhammer 快速开始教程:10分钟跑通你的第一个文本生成3D模型

原创2026-11-16 16:39:441,687 阅读
文章标签:人工智能基础模型多模态媒体生成3D建模

TRELLIS-text-large-voxhammer 快速开始教程:10分钟跑通你的第一个文本生成3D模型

TRELLIS-text-large-voxhammer 是微软 TRELLIS 的文本生成3D模型(text-to-3d)权重仓库:只需输入一句文字提示词,就能自动生成带完整几何与材质的大型 3D 资产。本文为面向新手的快速开始教程,带你 10 分钟跑通你的第一个文本生成3D模型。

一、这是什么项目?🧩

TRELLIS-text-large-voxhammer 对应论文《Structured 3D Latents for Scalable and Versatile 3D Generation》中的 TRELLIS Text(L 尺寸)——即文本条件版的大型 3D 生成模型,采用 MIT 许可(详见 README.md)。

和图像版 TRELLIS 相比,它的核心区别在于「条件输入」:

  • 文本编码器:openai/clip-vit-large-patch14,把提示词变成模型可理解的语义向量
  • 两段式生成:先生成稀疏结构(Sparse Structure),再生成结构化潜码(SLat),最后解码为 3D 资产
  • 三种输出:网格 Mesh(可导出 GLB)、辐射场(PBR 材质)、高斯泼溅(Gaussian Splatting)
  • 权重共享:解码器等组件复用图像版 microsoft/TRELLIS-image-large 的权重,本仓库只存放两个「文本条件 Flow 模型」

二、仓库目录结构:先看有哪些文件 📦

TRELLIS-text-large-voxhammer/
├── ckpts/                                     # 文本条件版权重(本仓库核心)
│   ├── ss_flow_txt_dit_L_16l8_fp16.safetensors    # 稀疏结构 Flow 模型
│   ├── ss_flow_txt_dit_L_16l8_fp16.json           # 对应结构配置
│   ├── slat_flow_txt_dit_L_64l8p2_fp16.safetensors # 结构化潜码 Flow 模型(L 尺寸)
│   └── slat_flow_txt_dit_L_64l8p2_fp16.json       # 对应结构配置
├── pipeline.json                              # 流水线装配配置
└── README.md                                  # 项目说明

两个 Flow 模型各司其职:

文件 作用 对应参数
ckpts/ss_flow_txt_dit_L_16l8_fp16.json 根据文本生成 16³ 稀疏结构 粗粒度「形体骨架」
ckpts/slat_flow_txt_dit_L_64l8p2_fp16.json 根据文本生成 64 分辨率结构化潜码 model_channels: 1024、num_blocks: 24,L 尺寸主力模型

三、核心配置解读:pipeline.json 里藏了什么 🔍

pipeline.json 声明了整个生成流水线 TrellisTextTo3DPipeline,新手只需看懂三块:

1. 本地权重(本仓库提供)

"sparse_structure_flow_model": "ckpts/ss_flow_txt_dit_L_16l8_fp16",
"slat_flow_model": "ckpts/slat_flow_txt_dit_L_64l8p2_fp16"

2. 采样参数(决定生成速度与质量)

  • 采样器:FlowEulerGuidanceIntervalSampler(两级采样共用)
  • steps: 25:每级 25 步 Euler 采样
  • cfg_strength: 7.5:引导强度,越高越贴合提示词
  • cfg_interval: [0.5, 0.95]、rescale_t: 3.0:精细化的引导调度参数

3. 文本条件

  • text_cond_model: openai/clip-vit-large-patch14

四、快速开始:4 步跑通你的第一个文本生成3D模型 🚀

第 1 步:克隆仓库(含 LFS 权重)

git clone https://gitcode.com/hf_mirrors/FishWoWater/TRELLIS-text-large-voxhammer
cd TRELLIS-text-large-voxhammer
git lfs install && git lfs pull

💡 ckpts/ 下的 .safetensors 通过 Git-LFS 存储,务必执行 git lfs pull,否则拿到的是指针文件而非真实权重。

第 2 步:准备运行环境

  • Python 3.10+,推荐 NVIDIA GPU(L 尺寸模型建议显存 16GB 起步)
  • 安装 PyTorch 与 TRELLIS 推理依赖:
pip install torch
pip install diffusers

第 3 步:加载流水线并输入提示词

from diffusers import TrellisTextTo3DPipeline

# 指向本地克隆的仓库,自动读取 pipeline.json 与 ckpts/ 权重
pipeline = TrellisTextTo3DPipeline.from_pretrained(
    "./TRELLIS-text-large-voxhammer"
)

# 输入提示词,两段式 Flow 采样自动生成 3D 模型
result = pipeline(prompt="a cute cartoon robot, highly detailed")

# 导出为 GLB 网格文件
result.export_glb("robot.glb")

具体 API 以你所安装版本的官方文档为准;提示词建议用英文,效果更稳定。

第 4 步:查看与使用你的 3D 模型

打开生成的 robot.glb:可用 Blender、Windows 3D Viewer 或任意 glTF 在线预览工具查看,也可以直接用于 Unity、Three.js 等渲染管线。

五、新手常见问题 FAQ ❓

Q1:.safetensors 文件只有几百字节? 是 Git-LFS 指针。执行 git lfs install && git lfs pull 下载真实权重即可。

Q2:生成速度有多快? 两级采样各 25 步,L 尺寸模型在消费级显卡上通常以分钟计;可适当调低 num_inference_steps 换取速度。

Q3:显存不够怎么办? 权重已使用 fp16;仍不足时可换用更小的 TRELLIS 模型,或降低输出分辨率。

Q4:输出除了 Mesh 还能要什么? pipeline.json 中同时配置了辐射场解码器(slat_decoder_rf,可渲染 PBR 材质)与高斯泼溅解码器(slat_decoder_gs),可按需选择导出格式。

六、小结 ✨

  • TRELLIS-text-large-voxhammer = 文本生成3D模型:一句提示词 → 完整 3D 资产(GLB/PBR/高斯泼溅)
  • 仓库核心是两个文本条件 Flow 模型(ckpts/)+ 一份流水线配置(pipeline.json)
  • 跑通四步:克隆 → 拉取 LFS 权重 → 加载 TrellisTextTo3DPipeline → 输入提示词导出 GLB

试着换一句更有想象力的提示词,做出属于你的第一个 3D 作品吧!

登录后查看全文
TRELLIS-text-large-voxhammer