speridlabs/idol-sdk

项目介绍

Idol 接收一张物体图片——照片、渲染图或生成图均可——输出带完整侧面的 3D Gaussian splat 模型。流程先用 BiRefNet 去背景，再把图像交给基于 DINOv3 ViT-H+ 特征和 FLUX.2 VAE 潜变量的 370M 参数 DiT，最终解码出 32,768 至 1,048,576 个高斯点（默认 262,144），保存为标准 3DGS .ply。整个请求约 1.8B 参数，峰值显存 7.2 GB，能在消费级 GPU 上跑。

输出除 .ply 外，还有预处理后的输入图和预测的输入相机参数。.ply 可直接用任意高斯泼溅查看器打开。适合做 3D 资产、单图重建实验，或想把普通照片变成物体 splat 的用户。

快速使用

需要 Python >= 3.10 和 PyTorch >= 2.5。在仓库根目录安装：

pip install -e .

首次运行前，先在 Hugging Face 申请 facebook/dinov3-vith16plus-pretrain-lvd1689m 和 black-forest-labs/FLUX.2-dev 的访问权限，然后执行 hf auth login；模型权重会从 speridlabs/idol 在首次使用时下载。

对真实照片运行推理：

python -m idol.sample --image photo.jpg --mode real

会生成 photo.ply、photo_input.png（去背景并裁剪后的输入图）和 photo_camera.json（预测的输入相机）。计算机生成的图片用 --mode synthetic（也是默认值）。也可以传入图片目录并用 --out 指定输出目录。

Python API 与命令行一致：

from idol import IdolPipeline

pipeline = IdolPipeline.from_pretrained("speridlabs/idol")
output = pipeline("photo.jpg", mode="real", seed=42, num_gaussians=1_048_576)
output.gaussian.save_ply("photo.ply")
output.preprocessed_image.save("photo_input.png")

不想本地安装，可先用 Hugging Face Space 在线体验，那里有 93 个示例，也接受自己的图片。本地运行 Gradio 应用需安装 demo 扩展，然后执行 cd demo && python app.py。

使用约束

模型访问受限：首次下载前必须获得 DINOv3 ViT-H+ 和 FLUX.2 的 Hugging Face 审批。GPU 是主要使用场景；装了 flash-attn 会用它做注意力，否则退回 PyTorch 的 scaled dot-product attention，结果相同但更慢，可用 ATTN_BACKEND 切换。--dinov3_dtype fp32 会多占 1.7 GB 显存。GPU 上默认开启加速采样，但进程内第一张图会因编译而变慢。README 给出 262,144 高斯点、50 步时的请求耗时：B300 上 3.4 秒，L4 上 54.6 秒。代码采用 Apache-2.0 许可证。

HotRepo 点评

Idol 是一个很新的仓库，站内可用的 HotRepo 数据只覆盖最初几天：2026-10-30 14:45 UTC 为 131 Star，2026-11-01 09:45 UTC 到 385 Star。在这段窗口内，它进入了 Python 新项目榜，新增 131 Star，但没有全部语言日榜的名次记录。README 的分 GPU 耗时表值得对照“消费级 GPU”的说法：同样设置在 RTX 5090 上约 14 秒、RTX 4090 上约 19 秒，而 B300 上为 3.4 秒。与 TripoSplat、TRELLIS 的对比来自作者自己的基准，应视为其报告数字，而非独立评测。