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

LocalAI 3D 生成实战用 /3d/generations 从单张图像生成 PBR 纹理 3D 模型【免费下载链接】LocalAILocalAI is the open-source AI engine. Run any model - LLMs, vision, voice, image, video - on any hardware. No GPU required.项目地址: https://gitcode.com/GitHub_Trending/lo/LocalAI本文介绍 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.ggufDINOv3 视觉编码器图像条件特征提取ss_flow_f16.gguf体素结构sparse structure流模型也是 GGUF 目录的锚点文件ss_dec_f16.gguf体素结构解码器slat_flow_f16.gguf/slat_flow_1024_f16.gguf512³ / 1024³ 级联的 Slat 流模型shape_dec_f16.gguf/shape_enc_f16.gguf形状解码器 / 编码器tex_dec_f16.ggufPBR 纹理解码器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.backendtrellis2cpp可强制覆盖检测。APIPOST /3d/generations方法POST端点/3d/generations路由注册见 core/http/routes/localai.go请求参数请求体为 JSON字段如下参数类型必填默认值说明modelstring是—要使用的模型名imagestring是—条件图像base64、data URI 或公开 URLqualitystring否auto网格管线auto、coarse、512或1024backgroundstring否auto背景处理auto、keep、black或whitestepint否12形状采样步数texture_stepsint否12PBR 材质采样步数cfg_scalefloat否7.5无分类器引导CFG强度seedint否随机随机种子用于复现response_formatstring否urlurl返回文件 URLb64_json返回 base64paramsobject否—后端专属字符串参数texture_size、components参数校验在端点层即完成端点 core/http/endpoints/localai/model3d.go 中定义了valid3DQualitiesauto/coarse/512/1024与valid3DBackgroundsauto/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严格保留图像 alphablack/white强制移除对应颜色。后端专属params字符串键值对texture_size在启用 atlas 烘焙时的 UV atlas 分辨率提示componentstiny移除小岛状碎片largest仅保留最大的连通分量all默认全部保留。另外请求中的step/cfg_scale若未显式给出端点会回退到模型配置中的Step/CFGScale 值Gallery 默认即 12 与 7.5。响应结构返回 LocalAI 的 OpenAI 风格生成信封字段类型说明createdint生成的 Unix 时间戳idstring唯一标识符UUIDdataarray生成的资产数组data[].urlstringurl模式下/generated-3d下的.glbURL 路径data[].b64_jsonstringb64_json模式下 base64 编码的 GLB从端点实现看url模式下输出文件保留在generated-content-dir/3d/目录响应 URL 由middleware.BaseURL与generated-3d/basename拼接而成b64_json模式下临时 GLB 在返回后即被清理preserveOutput保持为 false。水密打印重网格POST /3d/remeshPOST /3d/remesh应用与 trellis2.cpp 演示相同的生成后 CGAL Alpha Wrap 工作流。它接受multipart/form-data并直接以model/gltf-binary返回重网格化的 GLB字段类型必填默认值说明modelstring是—已安装的 TRELLIS.2 模型名meshfile是—TRELLIS.2 生成的源 GLBdetailfloat否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 modeltrellis2-4b \ -F meshgenerated.glb \ -F detail0.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.glbWebUIStudio 中的 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_DEVICEcpu强制 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自动选择可用管线。【免费下载链接】LocalAILocalAI is the open-source AI engine. Run any model - LLMs, vision, voice, image, video - on any hardware. No GPU required.项目地址: https://gitcode.com/GitHub_Trending/lo/LocalAI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考