Google DeepMind发布 Genie 3 SDK安装与避坑指南（含Docker镜像）

“一句话、一张草图、甚至一句哼唱，十秒后即可在浏览器里实时漫游一个带物理碰撞、昼夜循环、PBR 材质的 3D 世界，而且还能一键导出到 Unity / Unreal。”

这不是官方放出的炫技 Demo，而是 已经 Apache-2.0 开源、免费商用 的正式 SDK。
但！社区第一天就炸出 200+ Issue：
• CUDA 版本地狱
• 25 GB 镜像下载失败
• AMD 显卡直接 Segmentation fault
• WSL2 挂载目录 0x80070005
…

于是有了这篇「热血又硬核」的安装与避坑指南——一篇就够，复制粘贴即可跑通。

2. 30 秒速览：读完你能带走什么

1. 官方 & 社区镜像一键脚本（x86_64 + ARM 双架构）
2. CUDA 12.4 / 11.8 双栈并存方案
3. WSL2 + Ubuntu 22.04 最佳实践
4. macOS Apple Silicon 打通 Rosetta + Metal
5. 15 个高频报错逐行拆解
6. Python API 最小可运行示例
7. 免费申请 Cloud TPU / GPU 的隐藏通道

3. 安装前检查清单（TL;DR）

4. 官方资源索引

• GitHub 主仓库：搜索 “google-deepmind / genie3”
• 官方文档：DeepMind 官网 → Products → Genie 3 → Docs
• Docker Hub 认证镜像：Docker Hub 搜索 “deepmind/genie3”
• Hugging Face 权重：搜索 “deepmind/genie3-2b / 7b / 20b”
• Colab 体验：GitHub 仓库内 notebooks/quickstart.ipynb
• Discord 实时答疑：DeepMind 官方 Discord 频道 #genie3

5. 路线选择：裸机 vs Docker vs Cloud

6. 裸机安装（Ubuntu 22.04 示例）

6.1 系统级依赖

sudo apt update && sudo apt install -y \
  build-essential git wget curl ca-certificates \
  python3.11 python3.11-venv python3-pip

6.2 CUDA 12.4 双栈并存（兼容 11.8）

# 下载官方 runfile
wget https://developer.download.nvidia.com/compute/cuda/12.4.0/local_installers/cuda_12.4.0_550.54.15_linux.run
sudo sh cuda_12.4.0_550.54.15_linux.run --toolkit --samples --override

# 写入环境变量
echo 'export PATH=/usr/local/cuda-12.4/bin:$PATH' > >  ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda-12.4/lib64:$LD_LIBRARY_PATH' > > ~/.bashrc
source ~/.bashrc

技巧：用 update-alternatives 一键切换 CUDA 版本。

6.3 创建虚拟环境

python3.11 -m venv ~/venv-genie3
source ~/venv-genie3/bin/activate
pip install -U pip wheel

6.4 安装核心包

pip install "genie3[torch]" \
  --extra-index-url https://pypi.nvidia.com

坑 1：国内用户请将 pypi.nvidia.com 换成 清华镜像。

6.5 验证 GPU 可见

python - < < 'PY'
import torch, genie3
print("Torch:", torch.__version__)
print("CUDA:", torch.cuda.is_available())
print("GPU:", torch.cuda.get_device_name(0))
PY

7. Docker 镜像（最推荐）

7.1 一行命令启动官方镜像

# 官方镜像
docker run --rm -it --gpus all \
  -p 8080:8080 \
  -v $(pwd)/data:/data \
  deepmind/genie3:2025.08-cuda12.4

# 国内镜像（阿里云同步）
docker run --rm -it --gpus all \
  registry.cn-hangzhou.aliyuncs.com/deepmind/genie3:2025.08-cuda12.4

7.2 本地开发镜像（含调试工具）

Dockerfile.dev

FROM deepmind/genie3:2025.08-cuda12.4
RUN apt update && apt install -y vim gdb python3.11-dbg
COPY requirements-dev.txt /tmp/
RUN pip install -r /tmp/requirements-dev.txt
WORKDIR /workspace

构建并挂载源码：

docker build -t genie3:dev -f Dockerfile.dev .
docker run -it --gpus all \
  -v $(pwd):/workspace \
  -p 8080:8080 -p 5678:5678 \
  genie3:dev

7.3 docker-compose.yml（懒人福音）

version: "3.9"
services:
  genie3:
    image: deepmind/genie3:2025.08-cuda12.4
    runtime: nvidia
    environment:
      - NVIDIA_VISIBLE_DEVICES=all
    ports:
      - "8080:8080"
    volumes:
      - ./data:/data
      - ./outputs:/workspace/outputs
    stdin_open: true
    tty: true

一键启动：

docker compose up --build

8. Cloud 路线：白嫖 300 美元 GPU 配额

8.1 Google Cloud（最稳）

1. 打开 Google Cloud 控制台
2. 新建项目 → 激活 Vertex AI API
3. 表单申请 A100 80GB 配额（5 分钟通过）
4. 启动 Vertex Workbench：
   • 镜像选 “

deepmind-genie3\:latest”
• 机器类型 a2-ultragpu-1g
• 磁盘 150 GB
5. SSH 进入后直接 docker run 即可

8.2 AWS G5 竞价实例（最便宜）

aws ec2 run-instances \
  --image-id ami-0genie3cuda12 \
  --instance-type g5.xlarge \
  --key-name mykey \
  --user-data '#!/bin/bash
docker run -d --gpus all -p 80:8080 deepmind/genie3:2025.08-cuda12.4'

9. 15 个高频报错 & 逐行拆解

10. Python API 5 分钟上手

10.1 安装 Jupyter（可选）

pip install notebook ipywidgets
jupyter notebook --ip=0.0.0.0 --port=8080 --allow-root

10.2 Hello Genie 3（文字 → 3D）

from genie3 import GenieClient, TextPrompt

client = GenieClient(api_key="YOUR_API_KEY")   # 在 Hugging Face 账户设置页生成
prompt = TextPrompt(
    text="漂浮在云端的未来图书馆，玻璃穹顶，极光流动",
    style="cyberpunk",
    render_size=(1920, 1080),
    physics=True,
    seed=42
)

world = client.generate(prompt, timeout=300)   # 5 分钟
world.save_glb("/outputs/library.glb")         # 导出 Blender
world.launch_player(port=7001)                 # 浏览器实时漫游

浏览器打开 localhost:7001 即可 WASD 漫游。

10.3 草图 → 3D

from genie3 import Sketch
sketch = Sketch.load("cat_on_moon.png")
world = client.generate(sketch, add_animals=["cat"], time_of_day="night")

10.4 语音 → 3D（Whisper 链式）

pip install openai-whisper
python - < < 'PY'
import whisper, genie3
audio = whisper.load_audio("idea.m4a")
text = whisper.transcribe(audio)["text"]
world = genie3.TextPrompt(text).generate()
PY

11. Unity / Unreal 实时链路

11.1 Unity 插件（预览）

仓库名：google-deepmind/genie3-unity

git clone <该仓库>

双击 Genie3.unitypackage，拖拽 Genie3Streamer 预制体到场景，填写 API Key，Play。

11.2 Unreal Engine 5.4

插件已上架 Epic 官方商城，搜索 “Genie3”，支持 Lumen + Nanite。

12. 进阶：微调专属「世界模型」

12.1 数据集结构

dataset/

├── scene_0001/

│   ├── prompt.json

│   ├── mesh.glb

│   └── metadata.yaml

12.2 LoRA 微调 1 小时

pip install peft accelerate
torchrun --nproc_per_node=2 \
  -m genie3.train \
  --model_name_or_path deepmind/genie3-7b \
  --dataset_dir ./my_dataset \
  --output_dir ./checkpoints \
  --lora_rank 64 \
  --num_epochs 3

13. 性能优化：30 FPS 不是梦

14. FAQ 快问快答

Q1：无 NVIDIA GPU 能跑吗？
→ CPU 版 1 FPS，或用 Colab 免费 T4。

Q2：原生 Windows 支持？
→ 2025.08 暂不支持，WSL2 100 % 兼容。

Q3：商用收费？
→ Apache-2.0，免费商用，需保留版权。

Q4：如何卸载？
→ docker rmi <镜像 > 或 pip uninstall genie3。

15. 彩蛋：把 3D 世界嵌进 Notion

社区贡献的 Notion 第三方嵌入：仓库 genie3-notion-embed，复制 < iframe src="http://localhost:7001/embed?scene=xxx" / > > 即可在 Notion 实时旋转你的世界。

16. 结语：欢迎来到「人人都是 3D 导演」的时代

2022 年，Stable Diffusion 让 2D 平民化。
2025 年，Genie 3 让 3D 平民化。

今天，你只需一杯咖啡的时间，就能把脑海里的奇思妙想变成可漫游、可触摸、可二次开发的 3D 宇宙。
所以，还等什么？复制粘贴上面的命令，跑起来吧！

愿你的显卡永远风冷，显存永不溢出。
Happy Genie-ing!