Idol 3D · 一张图生成 3D 物体

上传一张物体照片，几十秒后得到一个可以在网页里任意旋转的 3D 模型，可导出标准 3D Gaussian Splatting（.ply）。 镜像开箱即用：模型权重、推理环境、网页界面都在里面，使用者不需要 Hugging Face 账号。

---

一、这是什么

Idol 是 speridlabs 的单图重建模型：输入一张物体图片，输出最多 104 万个 3D 高斯点，包括照片里没拍到的背面和侧面。

本镜像把这套能力封装成了一个开箱即用的网页服务：

输入	一张 jpg / png / webp 图片（单个物体）
输出	model.ply（标准 3DGS，任何 splat 查看器都能打开）+ 预处理图 + 预测相机
交互	浏览器内实时旋转、缩放、换背景、全屏
速度	RTX 3090 上 26 万高斯 / 50 步约 40 秒；H100 约 7 秒
显存	峰值约 7.2 GB，最低 8GB 显卡可跑，建议 12GB 以上
离线	权重内置，全程不联网

模型本身约 18 亿参数（DiT 去噪器 + 八叉树解码器 + 高斯解码器 + BiRefNet 抠图 + DINOv3 与 FLUX.2 VAE 编码器）。

---

二、镜像里有什么

/root/idol-web/            网页服务与前端
/root/idol-env/            Python 3.10 虚拟环境（torch 2.11.0+cu128）
/root/idol-sdk/            idol-sdk 源码
/root/.cache/huggingface/  约 6.5 GB 权重（Idol + DINOv3 + FLUX.2 VAE）
/var/log/idol.out.log      运行日志

服务由 supervisor 托管（/etc/supervisor/conf.d/idol.conf），容器启动后自动运行，端口 7860。 镜像体积约 14~20 GB，需要 NVIDIA GPU 与已安装驱动的宿主机。

---

三、快速开始

方式 A：在算力平台上启动（推荐）

1. 用本镜像创建实例，选择带 GPU 的机型（显存 ≥ 8GB）。
2. 安全组 / 端口映射里放行 TCP 7860。
3. 浏览器打开 http://<实例公网IP>:7860。
4. 第一次打开会显示"模型加载中"，等 30~60 秒（加载权重 + torch.compile 预热），之后一直是就绪状态。

方式 B：Docker

# 自行构建（构建期需要网络和 HF token 才能下载 gated 编码器）
docker build -t idol-3d:latest .

# 或直接运行已有镜像
docker run -d --gpus all -p 7860:7860 \
  -v idol-data:/root/idol-web/data \
  --name idol3d idol-3d:latest

-v 挂载可让生成记录在容器重启后保留；不挂载则记录随容器消失。

常用运维命令

supervisorctl status idol        # 状态
supervisorctl restart idol       # 重启（约 30 秒就绪）
tail -f /var/log/idol.out.log    # 运行日志
tail -f /var/log/idol.err.log    # 错误日志
bash /root/idol-web/setup.sh     # 环境被破坏后一键重建

---

四、配置项

配置写在 /root/idol-web/.env（模板见 .env.example），改完 supervisorctl restart idol 生效。

变量	默认	说明
IDOL_PORT	7860	监听端口
IDOL_OFFLINE	1	1 离线模式，用镜像内权重，不联网、无需账号；0 联网模式
IDOL_OPTIMIZE	1	1 开启 torch.compile，推理快约 1.7 倍，首次启动多 20~30 秒编译；0 启动更快、显存更省
HF_TOKEN	空	仅联网模式需要。账号须已同意 DINOv3 与 FLUX.2-dev 的使用条款
HF_ENDPOINT	https://hf-mirror.com	联网模式下的下载源
IDOL_WEIGHTS	speridlabs/idol	换成自己的权重仓库或本地目录

换模型 / 第一次下载权重时才需要 IDOL_OFFLINE=0。注意镜像里已把 HF_HUB_DISABLE_XET=1 设为默认——hf-mirror 上 Xet 传输会卡在几十 KB/s。

---

五、界面怎么用

1. 选图片：拖入或点击选择；也可以直接点下方示例图试手。
2. 选物体来源：渲染图/生成图用"合成"，真实照片用"实拍"。
3. 点生成，进度条会显示当前处于预处理、采样第几步还是导出。
4. 看结果：拖动旋转、滚轮缩放、右键平移；右上角可重置视角、自动旋转、切换背景、全屏。
5. 导出：右下角下载 .ply，或下载"模型看到的图"（去背景裁切后的 1024×1024 输入）。

更细的参数说明和调参建议见 使用说明.md。

---

六、接口

服务是标准 HTTP，可以脱离页面直接调用。

# 提交任务
curl -X POST http://127.0.0.1:7860/api/generate \
  -F "image=@photo.jpg" \
  -F "mode=real" \
  -F "steps=50" \
  -F "num_gaussians=262144" \
  -F "seed=42"

# 返回 {"id": "afae2bc062cc", "status": "queued", ...}

# 查进度
curl http://127.0.0.1:7860/api/jobs/afae2bc062cc

# 下载结果
curl -O http://127.0.0.1:7860/files/afae2bc062cc/model.ply

方法	路径	说明
GET	/api/state	服务状态、GPU 型号、显存、队列长度
POST	/api/generate	提交生成任务（multipart/form-data）
GET	/api/jobs/{id}	任务状态、进度、阶段、结果文件
GET	/api/gallery	历史记录列表
DELETE	/api/jobs/{id}	删除记录与文件
GET	/files/{id}/model.ply	下载 3DGS 点云
GET	/files/{id}/input.png	下载模型实际看到的输入图
GET	/files/{id}/camera.json	预测的输入视角（yaw / pitch / radius / fov）
GET	/healthz	健康检查

单卡串行执行：多人同时提交会排队，前端会显示"前面还有 N 个"。

---

七、常见问题

打开页面一直在"模型加载中" 首次启动要加载约 4GB 权重并做 torch.compile 预热，30~60 秒正常。超过 2 分钟看 tail -100 /var/log/idol.err.log。

提示显存不足（CUDA out of memory） 把高斯数量降到 13 万、步数降到 30；或在 .env 里设 IDOL_OPTIMIZE=0 后重启。同一时间只能跑一个任务，多人并发时会排队而不是抢显存。

生成很慢（几分钟一张） nvidia-smi 看 GPU 占用率。如果显存占用很低、利用率 0%，说明 torch 退回了 CPU——通常是驱动版本太旧或容器没加 --gpus all。

3D 物体是倒立的 已在 static/app.js 里处理：Idol 输出的 .ply 是 y-up，而查看器按 3DGS 惯例当 y-down 解析，所以加载后会 splatMesh.rotation.z = Math.PI。如果你换了查看器或改了这段，需要自己处理朝向。

3D 区域一片空白，只有背景色 前端渲染器里 gpuAcceleratedSort 必须为 false。开启后在某些显卡/软件渲染环境下 draw call 会变成 0，画面全空。这是已踩过的坑，别改回去。

.ply 拿到别处能用吗 能。文件是标准 3DGS 格式（17 个属性：xyz、法线、球谐 DC、不透明度、缩放、旋转四元数），可以直接拖进 SuperSplat、antimatter15 的 web viewer、Blender 的 3DGS 插件、MeshLab 等。

怎么清空所有生成记录

rm -rf /root/idol-web/data/jobs/* /root/idol-web/data/index.json
supervisorctl restart idol

---

八、许可与合规

• idol-sdk 代码：Apache-2.0。
• speridlabs/idol 权重：遵循其模型页条款。
• 镜像内包含 facebook/dinov3-* 与 black-forest-labs/FLUX.2-dev（仅 VAE）的权重。这两个模型是 gated 仓库，许可可能与商用/再分发冲突（FLUX.2-dev 通常为非商业许可）。对外分发镜像或商用前，请自行确认许可，或让使用者自行提供账号在联网模式下下载。
• 生成结果的版权取决于输入图片与模型许可，商用前请自行评估。

---

九、出处

• 模型：speridlabs/idol
• 代码：speridlabs/idol-sdk
• 前端渲染：@mkkellogg/gaussian-splats-3d + three.js