LocalAI 3D 生成实战：用 /3d/generations 从单张图像生成 PBR 纹理 3D 模型

本文介绍 LocalAI 的 3D 生成能力：如何通过 POST /3d/generations 端点，借助 trellis2cpp 后端（Microsoft TRELLIS.2 的 C++/GGML 移植）从一张条件图像生成带 PBR 材质的 glTF（.glb）资产，并覆盖模型安装、请求/响应参数、/3d/remesh 水密化后处理、Base64 输入输出、WebUI 3D 预览以及性能与环境的注意事项。读完本文，你可以独立完成 3D 模型的本地化生成、参数调优与打印级网格的再处理。

核心机制：图像条件化的 TRELLIS.2 管线

LocalAI 可以经由 /3d/generations 端点，基于 trellis2cpp 后端——即 Microsoft TRELLIS.2 的 C++/GGML 移植版本（trellis2.cpp）——从单张条件图像生成带纹理的 3D 网格，输出为含 PBR 材质的二进制 glTF（.glb）资产。

需要明确的关键约束：生成仅有图像条件化路径，没有文本提示词路径。请提供单个物体的照片或渲染图（理想情况下背景干净），TRELLIS.2 将从中重建完整 3D 网格。从源码结构看，这一能力在核心中对应 FLAG_3D 用例标记与 3d 模态：导入器 Trellis2CppImporter 声明 Modality() 为 "3d"，生成的模型配置携带 KnownUsecaseStrings: ["FLAG_3D"]，并将 backend 固定为 trellis2cpp。

安装模型：从 Gallery 一键拉取

local-ai run trellis2-4b          # 完整管线：1024³ 级联 + PBR 纹理（约 18 GB）
# 或
local-ai run trellis2-4b-geometry # 仅 512³ 无纹理几何（约 7 GB）

后端会检测当前存在哪些组件 GGUF，并优雅降级：缺少纹理模型时生成无纹理几何，缺少 fine-flow 模型时退回到粗略的 marching-cubes 预览。Gallery 中的最小配置可参见 gallery/trellis2cpp.yaml，其中声明了 backend: trellis2cpp、known_usecases: [3d]，以及默认 step: 12 与 cfg_scale: 7.5（与 API 默认值一致）。

完整管线由 10 个 GGUF 组件构成

从 core/gallery/importers/trellis2cpp.go 的 trellis2Files 清单可以确认，完整管线横跨三个 HuggingFace 源仓库（TRELLIS.2-4B、用于 SS 解码器的 TRELLIS-image-large、以及 DINOv3 镜像），任何一个单一仓库都无法完整描述该管线，因此任何一条导入 URI 都会展开为完整的组件集合：

组件文件	作用
dino_f16.gguf	DINOv3 视觉编码器（图像条件特征提取）
ss_flow_f16.gguf	体素结构（sparse structure）流模型，也是 GGUF 目录的锚点文件
ss_dec_f16.gguf	体素结构解码器
slat_flow_f16.gguf / slat_flow_1024_f16.gguf	512³ / 1024³ 级联的 Slat 流模型
shape_dec_f16.gguf / shape_enc_f16.gguf	形状解码器 / 编码器
tex_dec_f16.gguf	PBR 纹理解码器
tex_slat_flow_512_f16.gguf / tex_slat_flow_1024_f16.gguf	纹理 Slat 流模型（512/1024 分辨率）

清单中的每个组件都带 SHA256 校验和。配置中 BasicModelRequest.Model 指向 ss_flow_f16.gguf——它是 GGUF 目录的锚点，后端从它旁边按默认文件名解析其余组件，无需额外选项。此外，导入器通过组件文件名（如 ss_flow_f16.gguf 等 9 个特征文件名）与 URI 中的 "trellis" 标记来自动识别模型；preferences.backend="trellis2cpp" 可强制覆盖检测。

API：POST /3d/generations

• 方法： POST
• 端点： /3d/generations（路由注册见 core/http/routes/localai.go）

请求参数

请求体为 JSON，字段如下：

参数	类型	必填	默认值	说明
model	string	是	—	要使用的模型名
image	string	是	—	条件图像：base64、data URI 或公开 URL
quality	string	否	auto	网格管线：auto、coarse、512 或 1024
background	string	否	auto	背景处理：auto、keep、black 或 white
step	int	否	12	形状采样步数
texture_steps	int	否	12	PBR 材质采样步数
cfg_scale	float	否	7.5	无分类器引导（CFG）强度
seed	int	否	随机	随机种子，用于复现
response_format	string	否	url	url 返回文件 URL；b64_json 返回 base64
params	object	否	—	后端专属字符串参数（texture_size、components）

参数校验在端点层即完成：端点 core/http/endpoints/localai/model3d.go 中定义了 valid3DQualities（auto/coarse/512/1024）与 valid3DBackgrounds（auto/keep/black/white），未知枚举值会立即返回 400，避免模型加载后才暴露晦涩的后端错误；若 image 为空也会直接报 "3D generation is image-conditioned"。条件输入图像有 32 MiB 的上限（max3DInputBytes），远小于视频输入的限制——条件图像只是单帧。

quality 决定网格分辨率：

• coarse：快速的 marching-cubes 预览；
• 512：精细的 dual-grid 网格；
• 1024：高分辨率级联（慢——需要数分钟，约 10 GB 显存）；
• auto：为当前安装的模型集选择其支持的最优管线。

background 控制条件图像上纯色背景的移除：auto 检测与边界相连的近似黑/白色区域，keep 严格保留图像 alpha，black/white 强制移除对应颜色。

后端专属 params（字符串键值对）：

• texture_size：在启用 atlas 烘焙时的 UV atlas 分辨率提示；
• components：tiny 移除小岛状碎片，largest 仅保留最大的连通分量，all（默认）全部保留。

另外，请求中的 step/cfg_scale 若未显式给出，端点会回退到模型配置中的 Step/``CFGScale` 值（Gallery 默认即 12 与 7.5）。

响应结构

返回 LocalAI 的 OpenAI 风格生成信封：

字段	类型	说明
created	int	生成的 Unix 时间戳
id	string	唯一标识符（UUID）
data	array	生成的资产数组
data[].url	string	url 模式下 /generated-3d 下的 .glb URL 路径
data[].b64_json	string	b64_json 模式下 base64 编码的 GLB

从端点实现看：url 模式下输出文件保留在 <generated-content-dir>/3d/ 目录，响应 URL 由 middleware.BaseURL 与 generated-3d/<basename> 拼接而成；b64_json 模式下临时 GLB 在返回后即被清理（preserveOutput 保持为 false）。

水密打印重网格：POST /3d/remesh

POST /3d/remesh 应用与 trellis2.cpp 演示相同的生成后 CGAL Alpha Wrap 工作流。它接受 multipart/form-data，并直接以 model/gltf-binary 返回重网格化的 GLB：

字段	类型	必填	默认值	说明
model	string	是	—	已安装的 TRELLIS.2 模型名
mesh	file	是	—	TRELLIS.2 生成的源 GLB
detail	float	否	0.5	保留的最细细节，占源包围盒对角线的百分比（0.35–2.5）

该端点有意不提供独立的 offset 控制：包围偏移沿用 trellis2.cpp 演示的方式，由 detail / 30 导出——独立调节容易产生臃肿或退化的 wrap。detail 百分比越低，保留的细节越细，但耗时更长，三角形数量通常也更多。输出满足水密（watertight）、朝向一致、无自相交且为 2-manifold。对于带纹理的源模型，LocalAI 会对替换后的网格做 UV 展开，并将其 PBR 材质重投影到新的 UV atlas 上。

上传限制：源 GLB 最大 512 MiB。由于精细的 TRELLIS.2 网格常常会超过 LocalAI 默认的 --upload-limit，该路由使用独立的上传限制（见 core/http/body_limit_test.go 中对 3D 路由限额的测试）。

curl http://localhost:8080/3d/remesh \
  -F model=trellis2-4b \
  -F mesh=@generated.glb \
  -F detail=0.5 \
  --output printable.glb

实战示例

从图像生成 3D 模型

curl http://localhost:8080/3d/generations \
  -H "Content-Type: application/json" \
  -d '{
    "model": "trellis2-4b",
    "image": "https://example.com/photo-of-a-chair.png",
    "quality": "512"
  }'

响应包含形如 /generated-3d/b64123456789.glb 的 URL；从同一服务器获取该文件即可。GLB 是标准 glTF 2.0，可直接在 Blender、three.js、<model-viewer> 及大多数引擎中打开。

Base64 输入与输出

curl http://localhost:8080/3d/generations \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"trellis2-4b\",
    \"image\": \"$(base64 -w0 chair.png)\",
    \"response_format\": \"b64_json\"
  }" | jq -r '.data[0].b64_json' | base64 -d > chair.glb

WebUI：Studio 中的 3D 标签页

React UI 在 Studio 中提供了 3D 标签页（另有 /3d 页面），内含交互式 PBR 查看器（实现见 core/http/react-ui/src/pages/ThreeDGen.jsx 与 GlbViewer.jsx）：上传或从剪贴板粘贴图像，选择质量档位，即可通过轨道/平移/缩放预览生成的网格，并支持线框开关切换。历史生成结果保存在浏览器 IndexedDB 中。生成完成后，一个 Detail 滑杆与 Apply remeshing 按钮会替换预览，展示与 GLB 下载导出完全一致的水密模型；Show original 可无重新生成地切回原始预览。端到端行为由 core/http/react-ui/e2e/threed-gen.spec.js 的 Playwright 用例覆盖。

性能与环境变量注意事项

• 512³ 管线在现代 GPU 上大约需要 2 分钟；1024³ 级联约需 5 分钟，占用约 10 GB 显存并伴随临时的主机内存峰值。
• TRELLIS2_DEVICE=cpu 强制 CPU 推理（慢，主要用于调试）。
• 生成的网格绕向（winding）未定向——这是忠实还原 TRELLIS.2 的行为——并以 Y-up 导出、带顶点 PBR 材质；UV-atlas 纹理烘焙可通过后端环境变量 T2GLB_XATLAS 启用。
• 服务端路由与端点定义集中在 core/http/routes/localai.go 与 core/http/endpoints/localai/model3d.go，相关行为测试见 core/http/endpoints/localai/model3d_remesh_internal_test.go 与 model3d_internal_test.go，便于对照源码核实行号级行为。

适用前提：以上命令假设服务运行在 localhost:8080、且已通过 local-ai run trellis2-4b（或 -geometry 变体）安装了对应模型；1024³ 质量档位依赖完整纹理/级联组件集与约 10 GB 显存，仅安装 trellis2-4b-geometry 时 quality 应停留在 512 或让 auto 自动选择可用管线。