Idol-GGUF

Idol-GGUF

SperiD Labs 的 Idol 的 8-bit GGUF 版本，把一张图像变成 3D 高斯点云和网格，用 idol.cpp 在本地运行。适合做图像转 3D 的开发者。

由 TimeLordRaps 在 Hugging Face 上制作。这些说明是 Mindket 根据它的模型页面和模型卡写的，模型自己的文件和许可证在 Hugging Face 上。

简介

它是什么：Idol-GGUF 是 SperiD Labs 的 Idol 的 8-bit 混合精度 GGUF 版本。Idol 接收一张图像，重建出三维高斯点云。一个 967 MB 的文件里装着 Idol 的四个组件，idol.cpp 运行时为它提供本地服务器、浏览器界面和网格提取器。

适合谁：适合想在自己机器上把单张图像变成 3D 形状的开发者和研究人员。内存占用是这里的主要关切，这个版本为较小的配置提供了分阶段模式和精简模式。

Industry | Who uses it | How they use it | Example
3D 与图形 | 图形开发者 | 从一张照片重建 3D 形状并提取网格 | 上传一张物体照片，在浏览器里查看点云
研究 | 图像转 3D 研究人员 | 把这个量化版本和原版 Idol 做对比 | 在一组家居物品测试集上检查网格距离
工具开发 | 本地 AI 应用的开发者 | 通过服务器的 HTTP 接口调用模型 | 从另一个程序向本地服务器发送图像
游戏原型 | 原型美术师 | 从一张图片得到粗略的无纹理网格 | 提取网格并在 3D 工具里打开

如果你想只用文字提示词开始，可以跳过它。Idol 接收的是图像，不是文字。

用在哪里：

• 装有 Python 的 Windows、macOS 和 Linux，通过 idol.cpp
• 由你自己电脑提供的浏览器界面
• 命令行，使用生成脚本
• 通过 HTTP 调用本地服务器的程序

Use case | Who | What they get back
图像转点云 | 开发者 | 一个可以在浏览器里查看的高斯点云
网格提取 | 3D 美术师 | 从重建结果中提取的无纹理网格
质量对比 | 研究人员 | 在 32 个物体的测试集上与原版 Idol 对比的测量结果

如何设置：有几样东西在这个仓库之外，其中两样需要授权访问。

• Python 和一个 idol.cpp 构建
• 一个已经接受两个图像编码器条款的 Hugging Face 账户
• 两个编码器，即 Idol 的原始精度 DINOv3 和 FLUX.2-dev 自编码器

1. 按 idol.cpp 的 README 构建它。
2. 接受编码器的条款，并登录 Hugging Face。
3. 如果想要本地副本，下载这个模型的文件。
4. 用下面的命令启动服务器。

pip install -U huggingface_hub
hf download TimeLordRaps/Idol-GGUF

python tools/idol_server.py --repo TimeLordRaps/Idol-GGUF --file Idol-Q8_0.gguf

如何使用：启动服务器，然后在浏览器里打开它在 8127 端口上的本地地址。上传一张图像，再查看点云和提取出的网格。同一个文件也能从命令行和通过 HTTP 使用。

Tool | What it does
tools/idol_server.py | 启动本地服务器和它的浏览器界面
tools/idol_generate.py | 从命令行运行同一个文件
HTTP 接口 | 让其他程序向正在运行的服务器发送图像
网格提取器 | 从重建结果中提取无纹理网格

示例：你打开浏览器界面，上传一张单个家居物品的图片。页面会显示它重建出的高斯点云，并让你提取网格来查看。

新手与专家：你可以把它看成一个根据一张图片猜出物体 3D 形状的工具。第一次小试，可以运行服务器命令，打开页面，上传一张拍得清楚的单个物体照片。

这个文件保留了去噪器、八叉树解码器、高斯解码器和背景移除器，大部分使用 Q8_0 块，所以并不是每个张量的精度都相同。两个图像编码器不在里面。在一个 32 个物体的测试中，网格与原版 Idol 的中位差异是包围盒对角线的 0.09%。分阶段运行时，Idol 这一步在 PyTorch 显存中的峰值是 1,955 MiB，运行时会根据测得的空闲显存选择模式。精简模式把等待中的模型放在磁盘上，在 4 GB 的容器里完成了两次生成，而分阶段模式被终止了。

用 GGUF 文件启动本地服务器
在浏览器里上传一张图像
Idol 重建出高斯点云
查看它或提取无纹理网格

Title: 与原版 Idol 的网格一致程度，96 次对比的平均值
对角线 0.1% 内的 F1: 68.49 %
对角线 0.5% 内的 F1: 96.74 %
轮廓重叠: 98.63 %

注意事项：

• 观察到的最差情况与原版 Idol 的差距远大于平均值所显示的，模型卡也说一个案例不能证明普遍原因。
• Idol 只接收图像。你可以自己另外配置一个生成器，用文字生成图像。
• 编码器的权重和许可证与这个仓库是分开的。
• License: 本仓库为 apache-2.0。
• Cost to run: 没有提到付费服务，但你需要一个 Hugging Face 账户来接受编码器的条款。
• Data it reaches: 你上传到自己本地服务器的图像，以及从 Hugging Face 获取的文件。
• Not for: 没有单独的图像生成器时，直接把文字变成 3D。

Hugging Face 上的数据（2026年11月13日）

• 任务：image to 3d
• 框架：idol
• 参数量：879M
• Weights: about 440 MB at 4-bit (estimate)
• Formats: GGUF
• 最近 30 天下载：3,896
• 点赞：9
• 许可证：apache-2.0
• 基于：speridlabs/idol
• 标签：idol, gguf, gaussian-splatting, image-to-3d, 8-bit, idol.cpp

链接

• 模型：https://huggingface.co/TimeLordRaps/Idol-GGUF
• 文件：https://huggingface.co/TimeLordRaps/Idol-GGUF/tree/main

获取模型

用 Hugging Face 的命令行下载它的文件：

pip install -U huggingface_hub
hf download TimeLordRaps/Idol-GGUF

然后按它的模型卡使用它。这个工具包里没有会自己运行的东西。