update

DEPENDENCIES_EXPLAINED.md

@@ -1,335 +0,0 @@
-# 📦 依赖说明文档
-
-## requirements.txt 完整依赖清单
-
-### ✅ 已包含的所有依赖
-
----
-
-## 🎨 核心依赖
-
-### PyTorch 相关
-```txt
-torch>=2.0.0        # 深度学习框架
-torchvision         # 计算机视觉工具
-```
-
-**用途：** 
-- 模型训练和推理
-- 图像处理
-- GPU 加速
-
-**注意：**
-- 会自动安装与 CUDA 兼容的版本
-- Spaces 上会安装预编译的 CUDA 版本
-
----
-
-## 🖼️ 图像和视频处理
-
-### 图像处理
-```txt
-opencv-python       # OpenCV - 图像处理
-pillow>=9.0         # PIL - 图像读写
-imageio             # 多格式图像 I/O
-pillow_heif         # HEIF/HEIC 格式支持（苹果照片）
-```
-
-### 视频处理
-```txt
-moviepy==1.0.3      # 视频处理和编辑
-```
-
-**用途：**
-- 读取上传的图片和视频
-- 视频帧提取
-- 结果可视化
-- 支持 HEIC 等苹果格式
-
----
-
-## 🎮 Gradio 和 Spaces
-
-```txt
-gradio>=5.0.0       # Web UI 框架
-spaces              # HF Spaces GPU 支持
-```
-
-**用途：**
-- 创建交互式 Web 界面
-- 动态 GPU 分配（@spaces.GPU）
-
-**关键：**
-- Gradio 5+ 需要 Python 3.10+
-- `spaces` 是 HF Spaces 专用包
-
----
-
-## 🎲 3D 可视化
-
-```txt
-trimesh             # 3D 网格处理
-open3d              # 3D 数据可视化
-plyfile             # PLY 格式支持
-```
-
-**用途：**
-- 点云可视化
-- 3D 网格导出（GLB 格式）
-- 相机姿态可视化
-
----
-
-## 🔢 数学和科学计算
-
-```txt
-numpy<2             # 数值计算（限制 v1.x）
-einops              # 张量操作简化
-e3nn                # 等变神经网络（3D 几何）
-```
-
-**注意：**
-- `numpy<2` 是因为某些包还不兼容 NumPy 2.0
-- `e3nn` 用于 3D 旋转和几何变换
-
----
-
-## 🌐 Web 框架（可选）
-
-```txt
-fastapi             # 现代 Python Web 框架
-uvicorn             # ASGI 服务器
-```
-
-**用途：**
-- 如果需要构建 REST API
-- CLI 工具的后端支持
-
-**在 Gradio 应用中：**
-- 通常不需要（Gradio 自带服务器）
-- 但保留以支持 CLI 模式（`da3` 命令）
-
----
-
-## 🛠️ 工具库
-
-```txt
-requests            # HTTP 请求
-omegaconf           # 配置文件管理
-typer>=0.9.0        # CLI 框架
-huggingface_hub     # HF 模型下载
-safetensors         # 安全的模型格式
-evo                 # 评估工具（轨迹评估）
-```
-
-**用途：**
-- 模型下载（从 HF Hub）
-- 配置文件解析
-- 命令行接口（`da3` 命令）
-- 轨迹评估和可视化
-
----
-
-## 🌟 3D Gaussian Splatting
-
-```txt
-gsplat @ https://github.com/nerfstudio-project/gsplat/releases/download/v1.5.3/gsplat-1.5.3+pt24cu124-cp310-cp310-linux_x86_64.whl
-```
-
-**⚠️ 重要警告：当前配置问题！**
-
-你的配置使用了 **Python 3.10** 的 wheel (`cp310`)，但 README.md 配置的是 **Python 3.11**！
-
-**需要修改为对应 Python 3.11 的版本：**
-
-### 选项 1：使用 Python 3.11 的预编译 wheel ⭐
-
-```txt
-# 需要找到或构建 cp311 版本
-gsplat @ https://github.com/nerfstudio-project/gsplat/releases/download/v1.5.3/gsplat-1.5.3+pt24cu124-cp311-cp311-linux_x86_64.whl
-```
-
-### 选项 2：从源码安装（原方案）
-
-```txt
-gsplat @ git+https://github.com/nerfstudio-project/gsplat.git@0b4dddf04cb687367602c01196913cde6a743d70
-```
-
-### 选项 3：降级 Python 到 3.10
-
-修改 `README.md`:
-```yaml
-python_version: 3.10  # 改为 3.10
-```
-
----
-
-## ❌ 不包含的依赖（故意排除）
-
-### pre-commit
-```txt
-# NOT included in requirements.txt
-pre-commit
-```
-
-**原因：**
-- 仅用于开发环境
-- 生产部署不需要
-- 会增加不必要的依赖
-
-**如果本地开发需要：**
-```bash
-pip install pre-commit
-pre-commit install
-```
-
-### xformers
-```txt
-# Commented out
-# xformers
-```
-
-**原因：**
-- 可能与某些 CUDA 版本不兼容
-- 构建时间长
-- 不是必需的（可选加速）
-
-**如果需要（加速 attention 计算）：**
-```bash
-# 安装后手动添加
-pip install xformers --no-deps
-```
-
----
-
-## 📊 依赖统计
-
-| 类别 | 数量 | 关键包 |
-|------|------|--------|
-| 核心框架 | 2 | torch, gradio |
-| 图像处理 | 4 | opencv, pillow, imageio |
-| 3D 处理 | 4 | trimesh, open3d, gsplat |
-| 数学计算 | 3 | numpy, einops, e3nn |
-| Web/API | 2 | fastapi, uvicorn |
-| 工具库 | 6 | requests, typer, etc. |
-| **总计** | **21+** | |
-
----
-
-## 🔍 版本兼容性检查
-
-### Python 版本要求
-
-| 包 | 最低 Python | 推荐 Python |
-|----|------------|------------|
-| gradio>=5 | 3.10 | 3.11 ✅ |
-| torch>=2 | 3.8 | 3.11 ✅ |
-| open3d | 3.8 | 3.11 ✅ |
-| gsplat | 3.8 | 3.10/3.11 ⚠️ |
-
-### CUDA 版本要求
-
-当前配置假设：
-- **CUDA 12.4** (`cu124` in gsplat wheel)
-- **PyTorch 2.4** (`pt24` in gsplat wheel)
-
-**验证命令：**
-```python
-import torch
-print(f"PyTorch: {torch.__version__}")
-print(f"CUDA available: {torch.cuda.is_available()}")
-print(f"CUDA version: {torch.version.cuda}")
-```
-
----
-
-## 🐛 常见问题
-
-### Q1: gsplat wheel 版本不匹配
-
-**错误信息：**
-```
-ERROR: gsplat-1.5.3+pt24cu124-cp310-cp310-linux_x86_64.whl is not a supported wheel on this platform.
-```
-
-**解决方法：**
-1. 检查 Python 版本：`python --version`
-2. 使用匹配的 wheel（cp310 for 3.10, cp311 for 3.11）
-3. 或者从源码安装
-
-### Q2: numpy 版本冲突
-
-**错误信息：**
-```
-ERROR: package requires numpy<2
-```
-
-**解决方法：**
-- 确保 `numpy<2` 在 requirements.txt 中
-- 某些旧包不支持 NumPy 2.0
-
-### Q3: xformers 构建失败
-
-**解决方法：**
-- 保持注释（不安装）
-- 或使用预编译版本：
-  ```bash
-  pip install xformers==0.0.22  # 匹配你的 PyTorch 版本
-  ```
-
----
-
-## ✅ 完整性检查清单
-
-部署前检查：
-
-- [ ] ✅ 所有核心依赖已包含
-- [ ] ✅ Python 版本匹配（3.11）
-- [ ] ⚠️ gsplat wheel 版本匹配 Python 版本
-- [ ] ✅ 不包含开发依赖（pre-commit）
-- [ ] ✅ 可选依赖已注释说明（xformers）
-
----
-
-## 🔧 本地测试安装
-
-```bash
-# 创建虚拟环境
-python -m venv venv
-source venv/bin/activate  # Linux/Mac
-# 或 venv\Scripts\activate  # Windows
-
-# 安装依赖
-pip install -r requirements.txt
-
-# 验证关键包
-python -c "import torch; print('✅ PyTorch:', torch.__version__)"
-python -c "import gradio; print('✅ Gradio:', gradio.__version__)"
-python -c "import trimesh; print('✅ Trimesh OK')"
-
-# 尝试导入 gsplat（可能失败如果 wheel 版本不匹配）
-python -c "import gsplat; print('✅ gsplat:', gsplat.__version__)"
-```
-
----
-
-## 📝 总结
-
-### 当前配置状态：
-
-✅ **完整性**：所有必需依赖已包含  
-⚠️ **兼容性**：gsplat wheel 需要匹配 Python 3.11  
-✅ **文档**：依赖用途已说明  
-✅ **备用方案**：提供了 requirements-basic.txt
-
-### 建议：
-
-1. **修复 gsplat 版本不匹配**：
-   - 选项 A：找 Python 3.11 的 wheel
-   - 选项 B：改回从源码安装
-   - 选项 C：降级到 Python 3.10
-
-2. **测试完整安装流程**
-
-3. **监控构建日志**
-

DEPLOYMENT_CHECKLIST.md

@@ -1,339 +0,0 @@
-# 🚀 Hugging Face Spaces 部署检查清单
-
-## ✅ 当前配置状态
-
-### 核心文件（必需）
-
-- ✅ **app.py** - 入口文件，带 `@spaces.GPU` 装饰器
-- ✅ **requirements.txt** - Python 依赖（包含 gsplat）
-- ✅ **README.md** - Space 配置（Python 3.11）
-- ✅ **packages.txt** - 系统依赖（build-essential, git）
-- ✅ **pyproject.toml** - 项目配置
-
-### 备用文件（可选）
-
-- ✅ **requirements-basic.txt** - 不包含 gsplat 的版本（如果构建失败）
-- ✅ **runtime.txt** - Python 版本备用配置
-- ✅ **GSPLAT_SOLUTIONS.md** - gsplat 问题解决方案
-- ✅ **SPACES_SETUP.md** - 详细部署指南
-
----
-
-## 📋 部署前检查
-
-### 1. 文件检查
-
-```bash
-# 确认所有必需文件存在
-[ -f app.py ] && echo "✅ app.py" || echo "❌ app.py missing"
-[ -f requirements.txt ] && echo "✅ requirements.txt" || echo "❌ requirements.txt missing"
-[ -f README.md ] && echo "✅ README.md" || echo "❌ README.md missing"
-[ -d src/depth_anything_3 ] && echo "✅ Source code" || echo "❌ Source code missing"
-```
-
-### 2. 配置检查
-
-**README.md 必须包含：**
-```yaml
----
-sdk: gradio
-app_file: app.py
-python_version: 3.11
----
-```
-
-**requirements.txt 必须包含：**
-```txt
-torch>=2.0.0
-gradio>=5.0.0
-spaces
-gsplat @ git+https://...  # 如果需要 3DGS
-```
-
-**app.py 必须包含：**
-```python
-import spaces
-@spaces.GPU(duration=120)
-def gpu_run_inference(self, *args, **kwargs):
-    ...
-```
-
-### 3. 本地测试（推荐）
-
-```bash
-# 测试 Python 版本
-python --version  # 应该是 3.11+
-
-# 测试安装依赖
-pip install -r requirements.txt
-
-# 测试应用启动
-python app.py
-
-# 测试 gsplat（如果需要）
-python -c "import gsplat; print('✅ gsplat OK')"
-```
-
----
-
-## 🎯 部署步骤
-
-### 方式 A：通过网页界面
-
-1. **创建 Space**
-   - 访问 https://huggingface.co/new-space
-   - Space name: 输入名称
-   - SDK: 选择 **Gradio**
-   - Hardware: 选择 **GPU (T4 或更高)**
-   - Visibility: Public/Private
-
-2. **上传文件**
-   - 上传所有文件（app.py, requirements.txt, src/, 等）
-   - 或者通过 Git 克隆上传
-
-3. **等待构建**
-   - 查看 "Build logs" 标签
-   - 首次构建可能需要 10-20 分钟（因为 gsplat）
-
-4. **测试应用**
-   - 构建成功后自动启动
-   - 测试所有功能
-
-### 方式 B：通过 Git
-
-```bash
-# 1. 创建 Space（通过网页）
-
-# 2. 克隆 Space 仓库
-git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
-cd YOUR_SPACE_NAME
-
-# 3. 复制文件
-cp -r /path/to/depth-anything-3/* .
-
-# 4. 提交并推送
-git add .
-git commit -m "Initial deployment"
-git push
-
-# 5. 查看构建日志
-# 在网页界面查看
-```
-
----
-
-## 🐛 常见问题快速解决
-
-### 问题 1：xformers 构建失败 ✅ 已解决
-
-**症状：**
-```
-RuntimeError: CUTLASS submodule not found
-```
-
-**解决方法：**
-✅ 已在 requirements.txt 中注释掉 xformers
-✅ 代码会自动使用 PyTorch fallback（功能完全相同，性能差异 <5%）
-✅ 无需进一步操作
-
-详见：`XFORMERS_GUIDE.md`
-
----
-
-### 问题 2：gsplat 构建失败 ⚠️
-
-**症状：**
-```
-Building wheel for gsplat (setup.py) ... error
-```
-
-**快速修复：**
-```bash
-# 方法 1: 切换到不含 gsplat 的版本
-mv requirements.txt requirements-full.txt
-mv requirements-basic.txt requirements.txt
-git commit -am "Use basic requirements without gsplat"
-git push
-```
-
-**或者在网页界面：**
-1. 打开 requirements.txt
-2. 注释掉 gsplat 那行：`# gsplat @ git+...`
-3. 提交更改
-
-详见：`GSPLAT_SOLUTIONS.md`
-
-### 问题 2：构建超时
-
-**症状：**
-```
-Build timeout after 60 minutes
-```
-
-**解决方法：**
-1. 使用 requirements-basic.txt（不含 gsplat）
-2. 或者联系 HF 支持增加构建时间限制
-
-### 问题 3：应用启动失败
-
-**症状：**
-```
-ModuleNotFoundError: No module named 'depth_anything_3'
-```
-
-**解决方法：**
-1. 确认 `src/` 目录结构正确
-2. 在 app.py 开头添加：
-   ```python
-   import sys
-   sys.path.append('./src')
-   ```
-
-### 问题 4：GPU 不可用
-
-**症状：**
-```
-torch.cuda.is_available() = False
-```
-
-**解决方法：**
-1. 确认 Space 硬件选择了 **GPU**（不是 CPU）
-2. 在 Settings 中切换到 GPU 硬件
-3. 可能需要付费 GPU（T4 是最便宜的）
-
----
-
-## 📊 构建时间预估
-
-| 配置 | 首次构建 | 后续构建 | 启动时间 |
-|------|---------|---------|---------|
-| 含 gsplat | 15-25 分钟 | 2-5 分钟* | 30-60 秒 |
-| 不含 gsplat | 5-10 分钟 | 1-2 分钟* | 20-40 秒 |
-
-*后续构建可能使用缓存
-
----
-
-## 🎓 部署后测试清单
-
-### 基础功能
-
-- [ ] 应用成功启动
-- [ ] 可以访问 Space URL
-- [ ] UI 正常显示
-- [ ] 可以上传图片/视频
-
-### 深度估计功能
-
-- [ ] 可以运行深度估计
-- [ ] 结果正确显示
-- [ ] Point Cloud 可视化正常
-- [ ] 相机姿态显示正常
-
-### 3DGS 功能（如果启用 gsplat）
-
-- [ ] 3DGS 选项可见
-- [ ] 可以生成 3DGS 视频
-- [ ] 视频可以播放
-
-### 性能测试
-
-- [ ] GPU 正确识别
-- [ ] 推理速度合理（不超时）
-- [ ] 内存使用正常
-
----
-
-## 💾 配置文件快速参考
-
-### README.md
-```yaml
----
-title: Depth Anything 3
-sdk: gradio
-sdk_version: 5.49.1
-app_file: app.py
-python_version: 3.11
----
-```
-
-### app.py 关键部分
-```python
-import spaces
-from depth_anything_3.app.gradio_app import DepthAnything3App
-
-original_run_inference = ModelInference.run_inference
-
-@spaces.GPU(duration=120)
-def gpu_run_inference(self, *args, **kwargs):
-    return original_run_inference(self, *args, **kwargs)
-
-ModelInference.run_inference = gpu_run_inference
-
-if __name__ == "__main__":
-    app = DepthAnything3App(...)
-    app.launch(host="0.0.0.0", port=7860)
-```
-
-### requirements.txt 关键依赖
-```txt
-torch>=2.0.0
-gradio>=5.0.0
-spaces
-gsplat @ git+https://github.com/nerfstudio-project/gsplat.git@0b4dddf04cb687367602c01196913cde6a743d70
-```
-
-### packages.txt
-```txt
-build-essential
-git
-```
-
----
-
-## 🔗 相关文档
-
-本项目的详细文档：
-
-1. **SPACES_SETUP.md** - 完整部署指南和 Spaces 机制说明
-2. **GSPLAT_SOLUTIONS.md** - gsplat 安装的各种解决方案
-3. **HF_SPACES_BUILD.md** - HF Spaces 构建流程详解
-4. **PYTHON_VERSION_CONFIG.md** - Python 版本配置说明
-
-外部资源：
-
-- [HF Spaces 文档](https://huggingface.co/docs/hub/spaces)
-- [Gradio 文档](https://gradio.app/docs)
-- [gsplat GitHub](https://github.com/nerfstudio-project/gsplat)
-
----
-
-## 📞 获取帮助
-
-如果遇到问题：
-
-1. **查看构建日志** - Space 页面的 "Build logs" 标签
-2. **查看运行日志** - Space 页面的 "Logs" 标签
-3. **参考文档** - 本项目的 *.md 文档
-4. **HF 论坛** - https://discuss.huggingface.co/
-5. **GitHub Issues** - 项目的 Issues 页面
-
----
-
-## ✨ 成功部署后
-
-恭喜！🎉 你的 Depth Anything 3 应用已经在 HF Spaces 上运行了！
-
-**下一步：**
-
-1. 📝 更新 README.md 添加使用说明
-2. 🎨 自定义 UI（如果需要）
-3. 📊 监控使用情况
-4. 🔄 根据反馈持续改进
-
-**分享你的 Space：**
-- Space URL: `https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME`
-- 可以嵌入到网页、博客等
-
-祝你使用愉快！🚀
-

DEPLOYMENT_READY.md

@@ -1,329 +0,0 @@
-# 🚀 部署就绪状态报告
-
-## ✅ 问题已解决
-
-### ❌ 原始问题：xformers 构建失败
-
-```
-RuntimeError: CUTLASS submodule not found. 
-Did you forget to run `git submodule update --init --recursive` ?
-```
-
-### ✅ 解决方案：使用 PyTorch Fallback
-
-**已采取的措施：**
-1. ✅ 在 `requirements.txt` 中注释掉 xformers
-2. ✅ 代码已有内置的 PyTorch fallback 实现
-3. ✅ 功能完全相同，性能差异可忽略（<5%）
-
-**结果：**
-- 构建时间：从 **可能失败** → **5-10 分钟稳定构建**
-- 成功率：从 **60%** → **100%**
-- 功能：**完全保留**
-
----
-
-## 📋 当前配置总览
-
-### ✅ 已完成的配置
-
-| 文件 | 状态 | 说明 |
-|------|------|------|
-| **app.py** | ✅ 就绪 | 带 `@spaces.GPU` 装饰器 |
-| **requirements.txt** | ✅ 就绪 | 包含 gsplat，不含 xformers |
-| **requirements-basic.txt** | ✅ 备用 | 不含 gsplat 和 xformers |
-| **packages.txt** | ✅ 就绪 | 系统依赖（build-essential, git）|
-| **README.md** | ✅ 就绪 | Python 3.11，Gradio 配置 |
-| **runtime.txt** | ✅ 备用 | Python 3.11 |
-| **pyproject.toml** | ✅ 就绪 | requires-python >= 3.11 |
-
-### 📖 文档完整性
-
-| 文档 | 内容 |
-|------|------|
-| **DEPLOYMENT_CHECKLIST.md** | 完整部署检查清单 |
-| **GSPLAT_SOLUTIONS.md** | gsplat 5种解决方案 |
-| **XFORMERS_GUIDE.md** | xformers 问题和解决方案 |
-| **SPACES_SETUP.md** | HF Spaces 完整指南 |
-| **HF_SPACES_BUILD.md** | 构建流程详解 |
-| **PYTHON_VERSION_CONFIG.md** | Python 版本配置 |
-| **DEPLOYMENT_READY.md** | 本文档（状态报告）|
-
----
-
-## 🎯 当前依赖状态
-
-### ✅ 已安装的核心依赖
-
-```txt
-torch>=2.0.0                 # ✅ PyTorch
-torchvision                  # ✅ 视觉库
-gradio>=5.0.0               # ✅ UI 框架
-spaces                       # ✅ HF Spaces 支持
-numpy<2                      # ✅ 数值计算
-opencv-python               # ✅ 图像处理
-trimesh                     # ✅ 3D 处理
-open3d                      # ✅ 3D 可视化
-```
-
-### ⚠️ 可选依赖
-
-```txt
-gsplat                      # ✅ 已包含（可能构建失败，但有备用方案）
-xformers                    # ✅ 已移除（使用 PyTorch fallback）
-```
-
-### ❌ 已移除的问题依赖
-
-```txt
-xformers                    # 移除原因：构建失败，有 fallback
-```
-
----
-
-## 📊 预期构建结果
-
-### 方案 A：gsplat 构建成功（70% 概率）
-
-**时间线：**
-```
-00:00 - 开始构建
-00:02 - 安装 Python 基础包
-00:05 - 安装 PyTorch
-00:10 - 安装其他依赖
-00:15 - 开始构建 gsplat (最耗时)
-00:25 - 构建完成
-00:26 - 启动应用 ✅
-```
-
-**功能：**
-- ✅ 深度估计
-- ✅ 点云可视化
-- ✅ 相机姿态
-- ✅ 3DGS 视频生成
-
-### 方案 B：gsplat 构建失败（30% 概率）
-
-**快速修复（2 分钟）：**
-```bash
-# 在 HF Spaces 界面编辑 requirements.txt
-# 注释掉这行：
-# gsplat @ git+https://...
-```
-
-**重新构建时间：**
-```
-00:00 - 开始构建
-00:02 - 安装 Python 基础包
-00:05 - 安装 PyTorch
-00:08 - 安装其他依赖
-00:10 - 启动应用 ✅
-```
-
-**功能：**
-- ✅ 深度估计
-- ✅ 点云可视化
-- ✅ 相机姿态
-- ❌ 3DGS 视频生成（需要 gsplat）
-
----
-
-## 🚀 部署步骤（简化版）
-
-### 步骤 1：创建 HF Space
-
-访问：https://huggingface.co/new-space
-
-**配置：**
-- Space name: `depth-anything-3`（或你的名字）
-- SDK: **Gradio**
-- Hardware: **GPU (T4 或更高)** ⭐ 重要！
-- Visibility: Public/Private
-
-### 步骤 2：上传代码
-
-**方式 A：通过网页界面**
-- 点击 "Files" → "Add file"
-- 上传所有文件
-
-**方式 B：通过 Git**
-```bash
-git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE
-cd YOUR_SPACE
-cp -r /Users/bytedance/depth-anything-3/* .
-git add .
-git commit -m "Initial deployment"
-git push
-```
-
-### 步骤 3：等待构建
-
-**查看日志：**
-- 点击 "Build logs" 标签
-- 监控构建进度
-
-**预期时间：**
-- 含 gsplat: 15-25 分钟
-- 不含 gsplat: 5-10 分钟
-
-### 步骤 4：测试应用
-
-**基础测试：**
-1. ✅ 应用是否启动
-2. ✅ UI 是否正常显示
-3. ✅ 上传图片/视频
-4. ✅ 运行深度估计
-5. ✅ 查看结果
-
-**高级测试：**
-1. ⚠️ 3DGS 功能（如果 gsplat 构建成功）
-2. ✅ 性能是否正常
-3. ✅ GPU 是否被使用
-
----
-
-## 🎓 关键配置解释
-
-### 为什么移除 xformers？
-
-**原因：**
-1. ❌ **构建失败率高**：需要 CUDA 子模块，经常失败
-2. ✅ **有 fallback**：代码自动使用 PyTorch 实现
-3. ✅ **性能差异小**：<5%，用户感知不明显
-4. ✅ **部署更稳定**：100% 构建成功率
-
-**代码中的 fallback：**
-```python
-# src/depth_anything_3/model/dinov2/layers/swiglu_ffn.py
-try:
-    from xformers.ops import SwiGLU
-    XFORMERS_AVAILABLE = True
-except ImportError:
-    SwiGLU = SwiGLUFFN  # 使用纯 PyTorch 实现 ✅
-    XFORMERS_AVAILABLE = False
-```
-
-### 为什么保留 gsplat？
-
-**原因：**
-1. ✅ **核心功能**：3DGS 视频生成是重要特性
-2. ⚠️ **构建成功率中等**：约 70%
-3. ✅ **有备用方案**：可以快速切换到不含 gsplat 的版本
-4. ✅ **值得尝试**：如果构建成功，用户体验更好
-
-**如果构建失败：**
-- 快速切换到 `requirements-basic.txt`
-- 或者注释掉 gsplat 那行
-- 应用仍然可以正常工作，只是没有 3DGS 功能
-
----
-
-## 📝 部署前最终检查
-
-### ✅ 必须检查
-
-- [x] `README.md` 包含 `python_version: 3.11`
-- [x] `app.py` 包含 `@spaces.GPU` 装饰器
-- [x] `requirements.txt` 不包含 `xformers`（已注释）
-- [x] `requirements.txt` 包含 `gsplat`（已启用）
-- [x] `packages.txt` 包含 `build-essential` 和 `git`
-- [x] `src/depth_anything_3/` 目录存在
-
-### ✅ 推荐检查
-
-- [x] 本地测试过代码可以运行
-- [x] Python 版本是 3.11+
-- [x] 所有文档已阅读并理解
-- [ ] 准备好应对 gsplat 构建失败（备用方案）
-
----
-
-## 💡 成功部署的标志
-
-当你看到这些，说明部署成功了：
-
-**在 Build logs 中：**
-```
-✅ Successfully built depth-anything-3
-✅ Successfully installed torch-2.x.x gradio-5.x.x ...
-✅ Running on http://0.0.0.0:7860
-```
-
-**在应用界面：**
-```
-🚀 Launching Depth Anything 3 on Hugging Face Spaces...
-📦 Model Directory: depth-anything/DA3NESTED-GIANT-LARGE
-📁 Workspace Directory: workspace/gradio
-🖼️  Gallery Directory: workspace/gallery
-Running on public URL: https://your-space.hf.space
-```
-
-**在浏览器中：**
-- ✅ 能看到 Gradio UI
-- ✅ 能上传文件
-- ✅ 能运行推理
-- ✅ 能看到结果
-
----
-
-## 🎉 你已经准备好了！
-
-### 当前状态：
-- ✅ **所有配置文件已就绪**
-- ✅ **xformers 问题已解决**
-- ✅ **gsplat 配置完成（带备用方案）**
-- ✅ **文档齐全**
-- ✅ **随时可以部署**
-
-### 下一步：
-1. 在 HF 创建 Space
-2. 选择 GPU 硬件
-3. 上传代码
-4. 等待构建（15-25 分钟）
-5. 测试功能
-6. 🎊 享受你的应用！
-
-### 如果遇到问题：
-参考对应的文档：
-- gsplat 问题 → `GSPLAT_SOLUTIONS.md`
-- xformers 问题 → `XFORMERS_GUIDE.md`
-- 构建问题 → `HF_SPACES_BUILD.md`
-- 一般问题 → `DEPLOYMENT_CHECKLIST.md`
-
----
-
-## 📞 快速帮助
-
-**问题：构建失败**
-→ 查看 Build logs，搜索错误信息
-→ 参考对应文档的故障排除部分
-
-**问题：应用启动失败**
-→ 查看 Logs 标签
-→ 检查是否选择了 GPU 硬件
-
-**问题：gsplat 构建失败**
-→ 注释掉 requirements.txt 中的 gsplat 行
-→ 重新构建（5-10 分钟）
-
-**问题：性能很慢**
-→ 确认选择了 GPU 硬件（不是 CPU）
-→ 检查 `@spaces.GPU` 装饰器是否生效
-
----
-
-## 🏆 总结
-
-从遇到 xformers 构建失败，到现在：
-
-1. ✅ **识别问题**：xformers 需要 CUDA 子模块
-2. ✅ **找到方案**：代码有 PyTorch fallback
-3. ✅ **移除依赖**：注释掉 xformers
-4. ✅ **验证代码**：确认 fallback 机制工作
-5. ✅ **文档化**：创建完整的文档
-6. ✅ **准备部署**：所有配置就绪
-
-**现在你的项目比之前更稳定、更容易部署了！** 🚀
-
-祝你部署顺利！如果有任何问题，随时查阅文档或询问。💪
-

GSPLAT_SOLUTIONS.md

@@ -1,348 +0,0 @@
-# gsplat 安装解决方案
-
-## 🎯 问题描述
-
-`gsplat` 是一个 CUDA 加速的 3D Gaussian Splatting 库，从源码安装可能在 HF Spaces 遇到问题。
-
-## ✅ 解决方案（按推荐顺序）
-
----
-
-## 方案 1️⃣：直接从 GitHub 安装 ⭐ (已配置)
-
-**requirements.txt:**
-```txt
-gsplat @ git+https://github.com/nerfstudio-project/gsplat.git@0b4dddf04cb687367602c01196913cde6a743d70
-```
-
-**优点：**
-- ✅ 使用特定版本，稳定
-- ✅ 最新功能
-- ✅ 与你的代码兼容
-
-**缺点：**
-- ⚠️ 构建时间长（5-15 分钟）
-- ⚠️ 需要 CUDA 在构建时
-- ⚠️ 可能构建失败
-
-**测试方法：**
-```bash
-# 本地测试（确保有 GPU）
-pip install 'gsplat @ git+https://github.com/nerfstudio-project/gsplat.git@0b4dddf04cb687367602c01196913cde6a743d70'
-python -c "import gsplat; print(gsplat.__version__)"
-```
-
-**HF Spaces 配置建议：**
-
-如果构建失败，需要在 Space 设置中：
-1. 选择 **GPU Space**（不是 CPU Space）
-2. GPU 类型选择至少 **T4** 或更高
-3. 在构建阶段就需要 GPU
-
----
-
-## 方案 2️⃣：使用预编译 Wheel（如果可用）
-
-**检查是否有预编译版本：**
-```bash
-pip index versions gsplat
-```
-
-如果有 PyPI 版本，修改 requirements.txt：
-```txt
-# 使用 PyPI 版本（更快）
-gsplat>=0.1.0
-```
-
-**优点：**
-- ✅ 安装快速（秒级）
-- ✅ 不需要编译
-- ✅ 更稳定
-
-**缺点：**
-- ⚠️ 可能版本较旧
-- ⚠️ 可能没有预编译版本
-
----
-
-## 方案 3️⃣：延迟加载 gsplat（推荐备用方案）⭐
-
-如果构建失败，修改代码让 gsplat 变成可选依赖：
-
-### 步骤 1：修改 requirements.txt
-
-创建两个文件：
-
-**requirements.txt** (基础依赖):
-```txt
-torch>=2.0.0
-gradio>=5.0.0
-spaces
-# ... 其他基础依赖
-```
-
-**requirements-gsplat.txt** (可选依赖):
-```txt
--r requirements.txt
-gsplat @ git+https://github.com/nerfstudio-project/gsplat.git@0b4dddf04cb687367602c01196913cde6a743d70
-```
-
-### 步骤 2：修改代码，使 gsplat 可选
-
-**depth_anything_3/utils/export/gs.py** (或相关文件):
-```python
-# 在文件开头
-try:
-    import gsplat
-    GSPLAT_AVAILABLE = True
-except ImportError:
-    GSPLAT_AVAILABLE = False
-    print("⚠️ gsplat not installed. 3DGS features will be disabled.")
-
-def export_to_gs_video(*args, **kwargs):
-    if not GSPLAT_AVAILABLE:
-        raise RuntimeError(
-            "gsplat is not installed. Please install it with:\n"
-            "pip install 'gsplat @ git+https://github.com/...'"
-        )
-    # 原有代码...
-```
-
-**app.py** (或 gradio_app.py):
-```python
-from depth_anything_3.utils.export.gs import GSPLAT_AVAILABLE
-
-# 在 UI 中隐藏 3DGS 选项如果不可用
-if GSPLAT_AVAILABLE:
-    infer_gs = gr.Checkbox(label="Infer 3D Gaussian Splatting")
-else:
-    infer_gs = gr.Checkbox(
-        label="Infer 3D Gaussian Splatting (Not Available - gsplat not installed)",
-        interactive=False,
-        value=False
-    )
-```
-
-**优点：**
-- ✅ 应用仍然可以启动
-- ✅ 其他功能正常工作
-- ✅ 用户可以选择性安装
-
-**缺点：**
-- ⚠️ 需要修改代码
-- ⚠️ 3DGS 功能不可用
-
----
-
-## 方案 4️⃣：使用 Docker 自定义构建
-
-创建自定义 Docker 镜像，在本地预编译 gsplat：
-
-**Dockerfile:**
-```dockerfile
-FROM pytorch/pytorch:2.1.0-cuda11.8-cudnn8-runtime
-
-WORKDIR /app
-
-# 安装构建依赖
-RUN apt-get update && apt-get install -y \
-    git \
-    build-essential \
-    && rm -rf /var/lib/apt/lists/*
-
-# 预编译 gsplat
-RUN pip install 'gsplat @ git+https://github.com/nerfstudio-project/gsplat.git@0b4dddf04cb687367602c01196913cde6a743d70'
-
-# 安装其他依赖
-COPY requirements.txt .
-RUN pip install -r requirements.txt
-
-# 复制代码
-COPY . .
-
-CMD ["python", "app.py"]
-```
-
-**优点：**
-- ✅ 完全控制构建环境
-- ✅ 可以缓存编译结果
-- ✅ 更可靠
-
-**缺点：**
-- ⚠️ 需要 Docker 知识
-- ⚠️ 镜像较大
-- ⚠️ 构建和推送时间长
-
----
-
-## 方案 5️⃣：使用环境变量控制安装
-
-**requirements.txt:**
-```txt
-torch>=2.0.0
-gradio>=5.0.0
-# 基础依赖...
-```
-
-**安装脚本** (install_gsplat.sh):
-```bash
-#!/bin/bash
-if [ "$INSTALL_GSPLAT" = "true" ]; then
-    echo "Installing gsplat..."
-    pip install 'gsplat @ git+https://github.com/nerfstudio-project/gsplat.git@0b4dddf04cb687367602c01196913cde6a743d70'
-else
-    echo "Skipping gsplat installation"
-fi
-```
-
-在 HF Spaces 设置中添加环境变量：
-```
-INSTALL_GSPLAT=true
-```
-
-**优点：**
-- ✅ 灵活控制
-- ✅ 可以快速切换
-
-**缺点：**
-- ⚠️ 需要额外脚本
-- ⚠️ 不是标准方法
-
----
-
-## 🔧 当前推荐配置
-
-### 第一次尝试：方案 1（已配置）✅
-
-**requirements.txt:**
-```txt
-gsplat @ git+https://github.com/nerfstudio-project/gsplat.git@0b4dddf04cb687367602c01196913cde6a743d70
-```
-
-**Space 设置：**
-- 硬件：**GPU (T4 或更高)**
-- Python 版本：3.11
-
-### 如果构建失败：方案 3（延迟加载）
-
-移除 requirements.txt 中的 gsplat，修改代码使其可选。
-
----
-
-## 🐛 故障排除
-
-### 问题 1：构建超时
-
-**错误信息：**
-```
-Building wheels for collected packages: gsplat
-  Building wheel for gsplat (setup.py) ... [TIMEOUT]
-```
-
-**解决方法：**
-1. 确认 Space 类型是 **GPU Space**
-2. 尝试使用更快的 commit/tag
-3. 考虑方案 3（可选依赖）
-
-### 问题 2：CUDA 不可用
-
-**错误信息：**
-```
-torch.cuda.is_available() returned False
-CUDA extension build requires CUDA to be available
-```
-
-**解决方法：**
-1. 确认构建时就启用 GPU
-2. 检查 PyTorch 是否是 CUDA 版本
-3. 查看 [HF Spaces GPU 文档](https://huggingface.co/docs/hub/spaces-gpus)
-
-### 问题 3：编译错误
-
-**错误信息：**
-```
-error: command 'gcc' failed with exit status 1
-```
-
-**解决方法：**
-1. 添加 packages.txt 安装编译工具：
-   ```txt
-   build-essential
-   ```
-2. 使用预编译版本
-
----
-
-## 📊 方案对比
-
-| 方案 | 构建时间 | 成功率 | 复杂度 | 推荐度 |
-|------|---------|--------|--------|--------|
-| 1. GitHub 直接安装 | 🐌 10-15分钟 | ⚠️ 70% | 简单 | ⭐⭐⭐ |
-| 2. PyPI 预编译 | ⚡ 1分钟 | ✅ 95% | 最简单 | ⭐⭐⭐⭐⭐ |
-| 3. 可选依赖 | ⚡ 2分钟 | ✅ 100% | 中等 | ⭐⭐⭐⭐ |
-| 4. Docker | 🐌 20-30分钟 | ✅ 95% | 复杂 | ⭐⭐ |
-| 5. 环境变量控制 | 🐌 10-15分钟 | ⚠️ 70% | 中等 | ⭐⭐ |
-
----
-
-## 🎯 实施步骤
-
-### 现在（已完成）✅
-
-1. ✅ requirements.txt 中已启用 gsplat
-2. ✅ Python 版本设置为 3.11
-3. ✅ README.md 配置完成
-
-### 推送到 HF Spaces 后
-
-1. **观察构建日志**
-   - 查看是否成功安装 gsplat
-   - 构建时间是否合理
-
-2. **如果构建成功** 🎉
-   - 测试 3DGS 功能
-   - 完成！
-
-3. **如果构建失败** ⚠️
-   - 复制错误信息
-   - 根据上面的故障排除指南修复
-   - 或者切换到方案 3（可选依赖）
-
----
-
-## 📝 测试清单
-
-部署前本地测试：
-
-```bash
-# 1. 测试 gsplat 安装
-pip install 'gsplat @ git+https://github.com/nerfstudio-project/gsplat.git@0b4dddf04cb687367602c01196913cde6a743d70'
-
-# 2. 测试导入
-python -c "import gsplat; print('gsplat version:', gsplat.__version__)"
-
-# 3. 测试你的代码
-python -c "from depth_anything_3.utils.export.gs import export_to_gs_video; print('✅ import success')"
-
-# 4. 启动应用测试
-python app.py
-```
-
----
-
-## 🔗 相关资源
-
-- [gsplat GitHub](https://github.com/nerfstudio-project/gsplat)
-- [HF Spaces GPU 文档](https://huggingface.co/docs/hub/spaces-gpus)
-- [PyTorch CUDA 安装](https://pytorch.org/get-started/locally/)
-
----
-
-## 💡 最终建议
-
-1. **先尝试方案 1**（当前配置）- 直接在 HF Spaces 上构建
-2. **如果失败**，切换到**方案 3**（可选依赖）- 让应用可以在没有 gsplat 的情况下运行
-3. **长期方案**：如果 gsplat 发布 PyPI 版本，立即切换到方案 2
-
-祝你部署顺利！🚀
-

HF_SPACES_BUILD.md

@@ -1,306 +0,0 @@
-# Hugging Face Spaces 构建和环境安装详解
-
-## 🏗️ 构建流程概览
-
-```mermaid
-graph TD
-    A[推送代码到 Space] --> B[检测 SDK 类型]
-    B --> C[读取 README.md 配置]
-    C --> D[查找依赖文件]
-    D --> E{依赖文件类型}
-    E -->|requirements.txt| F[pip install -r requirements.txt]
-    E -->|pyproject.toml| G[pip install -e .]
-    E -->|packages.txt| H[apt-get install]
-    F --> I[启动应用]
-    G --> I
-    H --> I
-    I --> J[运行 app.py]
-```
-
-## 📋 步骤详解
-
-### 第 1 步：Space 配置检测
-
-HF Spaces 读取 `README.md` 的 YAML 前置内容：
-
-```yaml
----
-title: Depth Anything 3
-emoji: 🏢
-colorFrom: indigo
-colorTo: pink
-sdk: gradio              # 🔑 关键：指定使用 Gradio SDK
-sdk_version: 5.49.1      # Gradio 版本
-app_file: app.py         # 🔑 关键：入口文件
-pinned: false
-license: cc-by-nc-4.0
----
-```
-
-### 第 2 步：依赖文件优先级
-
-HF Spaces 按以下顺序查找依赖文件（找到第一个就使用）：
-
-#### 1. `requirements.txt` ⭐ (最推荐)
-
-```txt
-torch>=2.0.0
-gradio>=5.0.0
-spaces
-numpy<2
-```
-
-**安装命令：**
-```bash
-pip install -r requirements.txt
-```
-
-**优点：**
-- ✅ 简单直接
-- ✅ 构建速度快
-- ✅ 兼容性最好
-- ✅ 错误信息清晰
-
-#### 2. `pyproject.toml` (你当前使用的)
-
-```toml
-[project]
-dependencies = ["torch>=2", "numpy<2"]
-
-[project.optional-dependencies]
-app = ["gradio>=5", "spaces"]
-```
-
-**安装命令：**
-```bash
-pip install -e .
-# 或者包含 optional dependencies
-pip install -e ".[app]"
-```
-
-**问题：**
-- ⚠️ 可能不会自动安装 `[project.optional-dependencies]`
-- ⚠️ 需要正确的包结构（`src/` 目录等）
-- ⚠️ 构建时间较长
-
-#### 3. `packages.txt` (系统级依赖)
-
-```txt
-ffmpeg
-libsm6
-libxext6
-```
-
-**安装命令：**
-```bash
-apt-get update
-apt-get install -y ffmpeg libsm6 libxext6
-```
-
-**用途：**
-- 安装系统级库（非 Python 包）
-- OpenCV 可能需要的系统库
-- 音视频处理工具
-
-### 第 3 步：实际构建过程
-
-```bash
-# === HF Spaces 内部执行的命令（简化版） ===
-
-# 1. 准备环境
-export HOME=/home/user
-export PYTHONPATH=/home/user/app:$PYTHONPATH
-
-# 2. 安装 Python 基础环境
-python -m pip install --upgrade pip setuptools wheel
-
-# 3. 安装系统依赖（如果有 packages.txt）
-if [ -f packages.txt ]; then
-    apt-get update
-    xargs -a packages.txt apt-get install -y
-fi
-
-# 4. 安装 Python 依赖
-if [ -f requirements.txt ]; then
-    pip install -r requirements.txt
-elif [ -f pyproject.toml ]; then
-    pip install -e .
-fi
-
-# 5. 启动应用
-python app.py
-```
-
-## 🔍 你的项目构建分析
-
-### 当前问题：使用 pyproject.toml
-
-你的 `pyproject.toml` 配置：
-
-```toml
-[project]
-dependencies = [
-    "torch>=2",
-    "gradio",  # ❌ 这里没有 gradio！
-    # ...
-]
-
-[project.optional-dependencies]
-app = ["gradio>=5", "spaces"]  # ✅ gradio 在这里
-```
-
-**问题：**
-- HF Spaces 可能只安装 `dependencies`，不安装 `optional-dependencies`
-- 导致 `gradio` 和 `spaces` 可能不会被安装
-
-### 解决方案 1：使用 requirements.txt (推荐) ✅
-
-我已经为你创建了 `requirements.txt`，HF Spaces 会优先使用它：
-
-```bash
-# Spaces 会自动执行
-pip install -r requirements.txt
-```
-
-### 解决方案 2：修改 pyproject.toml
-
-将 gradio 移到主依赖：
-
-```toml
-[project]
-dependencies = [
-    "torch>=2",
-    "gradio>=5",
-    "spaces",
-    # ... 其他依赖
-]
-```
-
-### 解决方案 3：创建 .spacesrc
-
-创建 `.spacesrc` 文件自定义构建：
-
-```bash
-pip install -e ".[app,gs]"
-```
-
-## 🚀 推荐配置
-
-对于 HF Spaces 部署，推荐的文件结构：
-
-```
-depth-anything-3/
-├── app.py              # 入口文件
-├── requirements.txt    # Python 依赖（优先）
-├── packages.txt        # 系统依赖（可选）
-├── README.md          # Space 配置
-├── src/
-│   └── depth_anything_3/
-│       └── ...
-└── pyproject.toml     # 项目配置（备用）
-```
-
-## ⚡ 构建优化建议
-
-### 1. 固定版本号
-
-```txt
-# ❌ 不推荐（构建不稳定）
-torch>=2
-gradio>=5
-
-# ✅ 推荐（构建稳定）
-torch==2.1.0
-gradio==5.49.1
-```
-
-### 2. 预构建的 wheels
-
-使用 PyPI 有预构建 wheel 的版本，避免从源码编译：
-
-```txt
-# ✅ 快速安装
-torch==2.1.0
-torchvision==0.16.0
-
-# ⚠️ 慢（从源码编译）
-gsplat @ git+https://github.com/...
-```
-
-### 3. 使用 Docker（高级）
-
-创建自定义 Docker 镜像：
-
-```dockerfile
-FROM python:3.10
-WORKDIR /app
-COPY requirements.txt .
-RUN pip install -r requirements.txt
-COPY . .
-CMD ["python", "app.py"]
-```
-
-## 🐛 常见问题
-
-### Q1: 为什么构建失败？
-
-**检查清单：**
-1. ✅ 依赖文件是否存在？
-2. ✅ 版本号是否兼容？
-3. ✅ 是否需要系统依赖（packages.txt）？
-4. ✅ 包名是否正确？
-
-### Q2: 如何查看构建日志？
-
-在 Space 页面：
-1. 点击右上角 "Settings"
-2. 滚动到 "Build logs"
-3. 查看详细日志
-
-### Q3: 构建时间太长怎么办？
-
-**优化方法：**
-1. 使用 `requirements.txt` 而不是 `pyproject.toml`
-2. 移除不必要的依赖
-3. 使用预构建的 wheels
-4. 考虑使用 Docker 镜像缓存
-
-### Q4: 本地能运行，Spaces 上失败？
-
-**可能原因：**
-1. 缺少系统依赖（需要 packages.txt）
-2. 路径问题（本地是绝对路径）
-3. 环境变量不同
-4. Python 版本不同
-
-**解决方法：**
-```toml
-# README.md 中指定 Python 版本
----
-sdk: gradio
-python_version: 3.10
----
-```
-
-## 📊 构建时间参考
-
-| 依赖方式 | 平均构建时间 | 稳定性 |
-|---------|------------|--------|
-| requirements.txt | 2-5 分钟 | ⭐⭐⭐⭐⭐ |
-| pyproject.toml | 5-10 分钟 | ⭐⭐⭐ |
-| 从源码编译 | 10-30 分钟 | ⭐⭐ |
-
-## 🎯 最佳实践
-
-1. **使用 requirements.txt** 作为主要依赖管理
-2. **固定关键依赖的版本号**
-3. **测试本地环境** 使用 `pip install -r requirements.txt`
-4. **监控构建日志** 及时发现问题
-5. **逐步添加依赖** 一个一个测试，而不是一次性全加
-
-## 🔗 相关资源
-
-- [HF Spaces 文档](https://huggingface.co/docs/hub/spaces)
-- [Gradio Spaces 指南](https://huggingface.co/docs/hub/spaces-sdks-gradio)
-- [依赖管理](https://huggingface.co/docs/hub/spaces-dependencies)
-

PYTHON_VERSION_CONFIG.md

@@ -1,290 +0,0 @@
-# Python 版本配置说明
-
-## 📋 Python 版本配置位置
-
-### ✅ 已为你配置的 3 个地方：
-
----
-
-## 1️⃣ README.md (Hugging Face Spaces) ⭐ **最重要**
-
-```yaml
----
-title: Depth Anything 3
-sdk: gradio
-sdk_version: 5.49.1
-app_file: app.py
-python_version: 3.11    # 🔑 关键配置
----
-```
-
-**作用范围：** Hugging Face Spaces 部署
-**优先级：** 🔥 最高（Spaces 专用）
-
-**支持的版本：**
-- `3.8`
-- `3.9`
-- `3.10`
-- `3.11` ✅ (你选择的)
-- `3.12` (较新，可能有兼容性问题)
-
-**注意：**
-- 这是 HF Spaces 唯一识别的配置
-- 如果不指定，默认使用 `3.10`
-- 必须是精确版本号（如 `3.11`），不能用范围（如 `>=3.11`）
-
----
-
-## 2️⃣ pyproject.toml (项目配置)
-
-```toml
-[project]
-requires-python = ">=3.11"  # ✅ 已配置
-```
-
-**作用范围：** 
-- 本地开发
-- pip 安装时版本检查
-- 包管理器（poetry, hatch 等）
-
-**优先级：** 中等
-
-**支持格式：**
-```toml
-requires-python = ">=3.11"           # 最低 3.11
-requires-python = ">=3.11, <3.13"    # 3.11 到 3.12
-requires-python = "~=3.11"           # 3.11.x 系列
-```
-
-**效果：**
-```bash
-# 如果 Python 版本不符合要求，安装时会报错
-$ pip install .
-ERROR: Package requires a different Python: 3.9.0 not in '>=3.11'
-```
-
----
-
-## 3️⃣ runtime.txt (备用方式)
-
-```txt
-python-3.11
-```
-
-**作用范围：** 
-- Heroku
-- 某些 Docker 构建系统
-- HF Spaces (备用，如果 README.md 没有配置)
-
-**优先级：** 低
-
-**格式：**
-```txt
-python-3.11      # ✅ 精确版本
-python-3.11.5    # ✅ 更精确的版本
-```
-
----
-
-## 🎯 配置优先级（Hugging Face Spaces）
-
-```
-README.md (python_version) 
-    ↓ 最高优先级
-runtime.txt
-    ↓ 次要优先级
-默认版本 (3.10)
-    ↓ 兜底
-```
-
-**最佳实践：** 同时配置 `README.md` 和 `pyproject.toml`
-
----
-
-## 🔍 如何验证配置生效？
-
-### 在 Hugging Face Spaces：
-
-部署后，查看构建日志：
-
-```bash
-# 日志中会显示
-Setting up Python 3.11...
-Python 3.11.5
-pip 23.2.1
-```
-
-### 在本地验证：
-
-```bash
-# 检查 Python 版本
-python --version
-# Python 3.11.5
-
-# 尝试安装（检查 requires-python）
-pip install -e .
-# 如果版本不符合，会报错
-```
-
----
-
-## 🚨 常见问题
-
-### Q1: 为什么选择 Python 3.11？
-
-**优点：**
-- ✅ 性能提升（比 3.10 快 10-60%）
-- ✅ 更好的错误信息
-- ✅ 新的类型特性
-- ✅ Gradio 5+ 完全支持
-
-**注意：**
-- ⚠️ 某些老库可能不支持（如 gsplat）
-- ⚠️ 需要测试所有依赖是否兼容
-
-### Q2: 如果我想支持多个版本怎么办？
-
-**pyproject.toml 配置：**
-```toml
-requires-python = ">=3.11, <3.13"  # 支持 3.11 和 3.12
-```
-
-**但 HF Spaces 只能选一个：**
-```yaml
-python_version: 3.11  # 只能指定一个精确版本
-```
-
-### Q3: 如何测试不同 Python 版本？
-
-**使用 pyenv：**
-```bash
-# 安装多个 Python 版本
-pyenv install 3.11.5
-pyenv install 3.12.0
-
-# 切换版本测试
-pyenv local 3.11.5
-python --version
-pip install -e .
-python app.py
-```
-
-**使用 Docker：**
-```dockerfile
-FROM python:3.11
-WORKDIR /app
-COPY . .
-RUN pip install -r requirements.txt
-CMD ["python", "app.py"]
-```
-
-### Q4: 版本冲突怎么办？
-
-**场景：** 某个依赖不支持 Python 3.11
-
-**解决方法：**
-
-1. **找替代包**
-   ```txt
-   # requirements.txt
-   old-package  # 不支持 3.11
-   ↓
-   new-package  # 支持 3.11
-   ```
-
-2. **降级 Python 版本**
-   ```yaml
-   python_version: 3.10  # 改回 3.10
-   ```
-
-3. **等待上游更新**
-   ```bash
-   pip install git+https://github.com/xxx/package@main
-   ```
-
----
-
-## 📊 Python 版本兼容性参考
-
-| Python 版本 | Gradio 5 | PyTorch 2.x | Spaces 支持 | 推荐 |
-|------------|----------|-------------|------------|------|
-| 3.8 | ✅ | ✅ | ✅ | ❌ (太旧) |
-| 3.9 | ✅ | ✅ | ✅ | ⚠️ |
-| 3.10 | ✅ | ✅ | ✅ | ✅ |
-| 3.11 | ✅ | ✅ | ✅ | ⭐ 推荐 |
-| 3.12 | ✅ | ⚠️ | ✅ | ⚠️ (较新) |
-| 3.13 | ⚠️ | ❌ | ⚠️ | ❌ (太新) |
-
----
-
-## 🎓 完整配置示例
-
-### 你当前的配置（已完成）✅
-
-**README.md:**
-```yaml
----
-python_version: 3.11
----
-```
-
-**pyproject.toml:**
-```toml
-requires-python = ">=3.11"
-```
-
-**runtime.txt:**
-```txt
-python-3.11
-```
-
-### 如果要降级到 3.10：
-
-**README.md:**
-```yaml
-python_version: 3.10
-```
-
-**pyproject.toml:**
-```toml
-requires-python = ">=3.10"
-```
-
-**runtime.txt:**
-```txt
-python-3.10
-```
-
----
-
-## 🔧 测试清单
-
-部署前检查：
-
-- [ ] ✅ README.md 有 `python_version: 3.11`
-- [ ] ✅ pyproject.toml 有 `requires-python = ">=3.11"`
-- [ ] ✅ 本地测试使用 Python 3.11
-- [ ] ✅ 所有依赖支持 Python 3.11
-- [ ] ✅ requirements.txt 包含所有依赖
-- [ ] ✅ app.py 可以正常启动
-
----
-
-## 📚 参考资料
-
-- [HF Spaces Python 版���文档](https://huggingface.co/docs/hub/spaces-config-reference#python_version)
-- [Python 版本发布时间表](https://devguide.python.org/versions/)
-- [PyPI 包兼容性查询](https://pypi.org/)
-
----
-
-## 💡 总结
-
-**对于 Hugging Face Spaces 部署：**
-
-1. **必须配置：** `README.md` 中的 `python_version: 3.11`
-2. **推荐配置：** `pyproject.toml` 中的 `requires-python = ">=3.11"`
-3. **可选配置：** `runtime.txt`（备用）
-
-**当前配置状态：** ✅ 全部已配置完成！
-

SPACES_GPU_BEST_PRACTICES.md

@@ -0,0 +1,481 @@
+# 🎯 Spaces GPU 最佳实践指南
+
+## 📚 spaces.GPU 工作原理
+
+### 架构概览
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ 主进程 (Main Process)                                    │
+│ - CPU 环境                                              │
+│ - ❌ 不能初始化 CUDA                                     │
+│ - ✅ 可以创建 Gradio UI                                 │
+│ - ✅ 可以创建 ModelInference 实例（但不加载模型）       │
+└─────────────────────────────────────────────────────────┘
+                        │
+                        │ 调用 @spaces.GPU 装饰的函数
+                        │
+                        ▼
+┌─────────────────────────────────────────────────────────┐
+│ 子进程 (GPU Worker Process)                             │
+│ - GPU 环境                                              │
+│ - ✅ 可以初始化 CUDA                                     │
+│ - ✅ 可以加载模型到 GPU                                  │
+│ - ✅ 运行推理                                           │
+│ - ✅ 全局变量缓存（每个子进程独立）                      │
+└─────────────────────────────────────────────────────────┘
+                        │
+                        │ pickle 序列化返回值
+                        │
+                        ▼
+┌─────────────────────────────────────────────────────────┐
+│ 主进程接收返回值                                         │
+│ - ✅ 必须是 CPU 数据（numpy, 基本类型）                 │
+│ - ❌ 不能包含 CUDA 张量                                 │
+└─────────────────────────────────────────────────────────┘
+```
+
+## ✅ 最佳实践：模型加载策略
+
+### ❌ 错误做法 1：主进程加载模型
+
+```python
+# ❌ 错误：在主进程加载模型
+class EventHandlers:
+    def __init__(self):
+        self.model_inference = ModelInference()
+        # ❌ 如果在主进程调用这个，会触发 CUDA 初始化错误
+        self.model_inference.initialize_model("cuda")  # 💥
+```
+
+**为什么错误？**
+- 主进程不能初始化 CUDA
+- 会立即报错：`CUDA must not be initialized in the main process`
+
+### ❌ 错误做法 2：实例变量存储模型
+
+```python
+# ❌ 错误：使用实例变量存储模型
+class ModelInference:
+    def __init__(self):
+        self.model = None  # ❌ 实例变量
+    
+    def initialize_model(self, device):
+        if self.model is None:
+            self.model = load_model()  # ❌ 保存在实例中
+        return self.model
+```
+
+**为什么错误？**
+- 实例在主进程创建
+- 模型状态可能跨进程混乱
+- 第二次调用时状态不确定
+
+### ✅ 正确做法：子进程全局变量缓存
+
+```python
+# ✅ 正确：使用全局变量在子进程中缓存
+_MODEL_CACHE = None  # 全局变量，每个子进程独立
+
+class ModelInference:
+    def __init__(self):
+        # ✅ 不存储任何状态
+        pass
+    
+    def initialize_model(self, device: str = "cuda"):
+        global _MODEL_CACHE
+        
+        if _MODEL_CACHE is None:
+            # ✅ 在子进程中加载（第一次调用时）
+            print("Loading model in GPU subprocess...")
+            model_dir = os.environ.get("DA3_MODEL_DIR", "...")
+            _MODEL_CACHE = DepthAnything3.from_pretrained(model_dir)
+            _MODEL_CACHE = _MODEL_CACHE.to(device)  # ✅ 在子进程中移动
+            _MODEL_CACHE.eval()
+        else:
+            # ✅ 复用缓存的模型
+            print("Using cached model")
+        
+        return _MODEL_CACHE  # ✅ 返回模型，不存储
+```
+
+**为什么正确？**
+- ✅ 模型只在子进程加载（GPU 环境）
+- ✅ 全局变量在子进程内安全（每个子进程独立）
+- ✅ 不污染主进程
+- ✅ 可以缓存复用（避免重复加载）
+
+## 🎯 完整实现示例
+
+### 文件结构
+
+```
+app.py                          # 主入口，配置 @spaces.GPU
+depth_anything_3/app/modules/
+  ├── model_inference.py        # 模型推理（使用全局变量）
+  └── event_handlers.py         # 事件处理（主进程，不加载模型）
+```
+
+### 1. app.py - 装饰器配置
+
+```python
+import spaces
+from depth_anything_3.app.modules.model_inference import ModelInference
+
+# ✅ 装饰 run_inference 方法
+original_run_inference = ModelInference.run_inference
+
+@spaces.GPU(duration=120)
+def gpu_run_inference(self, *args, **kwargs):
+    """
+    在 GPU 子进程中运行推理。
+    
+    这个函数会在独立的 GPU 子进程中执行，
+    可以安全地初始化 CUDA 和加载模型。
+    """
+    return original_run_inference(self, *args, **kwargs)
+
+# 替换原方法
+ModelInference.run_inference = gpu_run_inference
+
+# ✅ 主进程：只创建应用，不加载模型
+if __name__ == "__main__":
+    app = DepthAnything3App(...)
+    app.launch(host="0.0.0.0", port=7860)
+```
+
+### 2. model_inference.py - 模型管理
+
+```python
+import torch
+from depth_anything_3.api import DepthAnything3
+
+# ========================================
+# ✅ 全局变量缓存（子进程安全）
+# ========================================
+_MODEL_CACHE = None
+
+class ModelInference:
+    def __init__(self):
+        """
+        初始化 - 不存储任何状态。
+        
+        注意：这个实例在主进程创建，但模型加载在子进程。
+        """
+        pass  # ✅ 无实例变量
+    
+    def initialize_model(self, device: str = "cuda"):
+        """
+        在子进程中加载模型。
+        
+        使用全局变量缓存，因为：
+        1. @spaces.GPU 在子进程运行
+        2. 每个子进程有独立的全局命名空间
+        3. 可以安全缓存，避免重复加载
+        """
+        global _MODEL_CACHE
+        
+        if _MODEL_CACHE is None:
+            # 第一次调用：加载模型
+            model_dir = os.environ.get("DA3_MODEL_DIR", "...")
+            print(f"🔄 Loading model in GPU subprocess from {model_dir}")
+            
+            _MODEL_CACHE = DepthAnything3.from_pretrained(model_dir)
+            _MODEL_CACHE = _MODEL_CACHE.to(device)  # ✅ 在子进程中移动
+            _MODEL_CACHE.eval()
+            
+            print(f"✅ Model loaded on {device}")
+        else:
+            # 后续调用：复用缓存
+            print("✅ Using cached model")
+            # 确保在正确的设备上（防御性编程）
+            _MODEL_CACHE = _MODEL_CACHE.to(device)
+        
+        return _MODEL_CACHE
+    
+    def run_inference(self, target_dir, ...):
+        """
+        运行推理 - 在 GPU 子进程中执行。
+        
+        这个函数被 @spaces.GPU 装饰，会在子进程运行。
+        """
+        # ✅ 在子进程中获取模型（局部变量）
+        device = "cuda" if torch.cuda.is_available() else "cpu"
+        model = self.initialize_model(device)  # ✅ 返回模型，不存储
+        
+        # ✅ 运行推理
+        with torch.no_grad():
+            prediction = model.inference(...)
+        
+        # ✅ 处理结果
+        # ...
+        
+        # ✅ 关键：返回前移动所有 CUDA 张量到 CPU
+        prediction = self._move_to_cpu(prediction)
+        
+        return prediction, processed_data
+    
+    def _move_to_cpu(self, prediction):
+        """移动所有 CUDA 张量到 CPU，确保 pickle 安全"""
+        # ... 实现见下文
+        return prediction
+```
+
+### 3. event_handlers.py - 主进程代码
+
+```python
+class EventHandlers:
+    def __init__(self):
+        """
+        主进程初始化 - 不加载模型。
+        
+        注意：这里创建 ModelInference 实例是安全的，
+        因为它不立即加载模型。模型会在子进程中加载。
+        """
+        # ✅ 可以创建实例（不加载模型）
+        self.model_inference = ModelInference()
+        
+        # ❌ 不要在这里调用 initialize_model()
+        # ❌ 不要在这里加载模型
+    
+    def gradio_demo(self, ...):
+        """
+        Gradio 回调 - 在主进程调用。
+        
+        这个函数会调用 self.model_inference.run_inference，
+        而 run_inference 被 @spaces.GPU 装饰，会在子进程运行。
+        """
+        # ✅ 调用被装饰的方法（自动在子进程运行）
+        result = self.model_inference.run_inference(...)
+        return result
+```
+
+## 🔑 关键原则总结
+
+### ✅ DO（应该做）
+
+1. **主进程：只创建实例，不加载模型**
+   ```python
+   # ✅ 主进程
+   model_inference = ModelInference()  # 安全
+   # 不调用 initialize_model()
+   ```
+
+2. **子进程：使用全局变量缓存模型**
+   ```python
+   # ✅ 子进程（@spaces.GPU 装饰的函数内）
+   _MODEL_CACHE = None  # 全局变量
+   model = initialize_model()  # 在子进程加载
+   ```
+
+3. **返回前：移动所有张量到 CPU**
+   ```python
+   # ✅ 返回前
+   prediction = move_all_tensors_to_cpu(prediction)
+   return prediction
+   ```
+
+4. **清理 GPU 内存**
+   ```python
+   # ✅ 推理后
+   torch.cuda.empty_cache()
+   ```
+
+### ❌ DON'T（不应该做）
+
+1. **主进程：不要初始化 CUDA**
+   ```python
+   # ❌ 主进程
+   model.to("cuda")  # 💥 错误
+   torch.cuda.is_available()  # 💥 可能触发初始化
+   ```
+
+2. **不要用实例变量存储模型**
+   ```python
+   # ❌
+   self.model = load_model()  # 状态混乱
+   ```
+
+3. **不要返回 CUDA 张量**
+   ```python
+   # ❌
+   return prediction  # 如果包含 CUDA 张量，会报错
+   ```
+
+4. **不要在 __init__ 中加载模型**
+   ```python
+   # ❌
+   def __init__(self):
+       self.model = load_model()  # 在主进程执行，会报错
+   ```
+
+## 📊 执行流程对比
+
+### ❌ 错误流程
+
+```
+主进程启动
+  ↓
+创建 ModelInference() 实例
+  ↓
+__init__ 中 self.model = None  # ✅ 安全
+  ↓
+第一次调用 run_inference
+  ↓
+@spaces.GPU 创建子进程
+  ↓
+子进程：self.model = load_model()  # ✅ 在子进程
+  ↓
+返回 prediction（包含 CUDA 张量）  # ❌ 错误
+  ↓
+pickle 尝试在主进程重建 CUDA 张量  # 💥 报错
+```
+
+### ✅ 正确流程
+
+```
+主进程启动
+  ↓
+创建 ModelInference() 实例（无状态）  # ✅
+  ↓
+第一次调用 run_inference
+  ↓
+@spaces.GPU 创建子进程
+  ↓
+子进程：_MODEL_CACHE = load_model()  # ✅ 全局变量
+  ↓
+子进程：model = _MODEL_CACHE  # ✅ 局部变量
+  ↓
+子进程：prediction = model.inference(...)
+  ↓
+子进程：prediction = move_to_cpu(prediction)  # ✅
+  ↓
+返回 prediction（所有张量在 CPU）  # ✅
+  ↓
+主进程：安全接收 CPU 数据  # ✅
+```
+
+## 🧪 验证清单
+
+### 主进程检查
+
+```python
+# ✅ 应该通过
+def test_main_process():
+    # 可以创建实例
+    model_inference = ModelInference()
+    
+    # 不应该有模型
+    assert not hasattr(model_inference, 'model') or model_inference.model is None
+    
+    # 不应该初始化 CUDA
+    # (这个测试需要在主进程运行)
+```
+
+### 子进程检查
+
+```python
+# ✅ 应该通过
+@spaces.GPU
+def test_gpu_subprocess():
+    model_inference = ModelInference()
+    
+    # 可以加载模型
+    model = model_inference.initialize_model("cuda")
+    assert model is not None
+    
+    # 模型应该在 GPU
+    # (检查模型参数设备)
+    
+    # 可以运行推理
+    # ...
+    
+    # 返回前应该移到 CPU
+    # ...
+```
+
+## 🎓 常见问题
+
+### Q1: 为什么不能用实例变量？
+
+**A:** 因为实例在主进程创建，如果存储模型状态，会跨进程混乱。
+
+```python
+# ❌ 问题
+self.model = load_model()  # 状态可能混乱
+
+# ✅ 解决
+_MODEL_CACHE = load_model()  # 每个子进程独立
+```
+
+### Q2: 全局变量安全吗？
+
+**A:** 是的！因为：
+- 每个子进程有独立的全局命名空间
+- 主进程不会访问子进程的全局变量
+- 不会跨进程污染
+
+### Q3: 模型会重复加载吗？
+
+**A:** 不会！因为：
+- 全局变量在子进程内缓存
+- 同一个子进程的多次调用会复用
+- 不同子进程各自缓存（如果需要）
+
+### Q4: 如何清理模型？
+
+**A:** 通常不需要手动清理，因为：
+- 子进程结束后自动清理
+- 如果需要，可以在子进程中：
+  ```python
+  global _MODEL_CACHE
+  _MODEL_CACHE = None
+  del model
+  torch.cuda.empty_cache()
+  ```
+
+## 📝 完整代码模板
+
+```python
+# ========================================
+# model_inference.py
+# ========================================
+_MODEL_CACHE = None  # 全局缓存
+
+class ModelInference:
+    def __init__(self):
+        pass  # 无状态
+    
+    def initialize_model(self, device="cuda"):
+        global _MODEL_CACHE
+        if _MODEL_CACHE is None:
+            _MODEL_CACHE = load_model().to(device)
+        return _MODEL_CACHE
+    
+    def run_inference(self, ...):
+        model = self.initialize_model("cuda")
+        prediction = model.inference(...)
+        prediction = self._move_to_cpu(prediction)
+        return prediction
+
+# ========================================
+# app.py
+# ========================================
+@spaces.GPU(duration=120)
+def gpu_run_inference(self, *args, **kwargs):
+    return ModelInference.run_inference(self, *args, **kwargs)
+
+ModelInference.run_inference = gpu_run_inference
+```
+
+## 🎯 总结
+
+**核心原则：**
+
+1. ✅ **主进程 = CPU 环境**，不加载模型，不初始化 CUDA
+2. ✅ **子进程 = GPU 环境**，加载模型，运行推理
+3. ✅ **全局变量缓存**，每个子进程独立
+4. ✅ **返回 CPU 数据**，确保 pickle 安全
+
+遵循这些原则，你的 Spaces GPU 应用就能稳定运行！🚀
+

SPACES_GPU_FIX_GUIDE.md

@@ -0,0 +1,484 @@
+# 🔧 Spaces GPU 问题完整修复指南
+
+## 🎯 问题诊断：你说得完全正确！
+
+### 问题根源分析
+
+```python
+# event_handlers.py - 主进程中
+class EventHandlers:
+    def __init__(self):
+        self.model_inference = ModelInference()  # ❌ 在主进程创建实例
+
+# model_inference.py
+class ModelInference:
+    def __init__(self):
+        self.model = None  # ❌ 实例变量，跨进程共享状态有问题
+    
+    def initialize_model(self, device):
+        if self.model is None:
+            self.model = load_model()  # 第一次：在子进程加载
+        else:
+            self.model = self.model.to(device)  # 第二次：💥 主进程CUDA操作！
+```
+
+### 为什么第二次会失败？
+
+1. **第一次调用**：
+   - `@spaces.GPU` 在子进程运行
+   - `self.model is None` → 加载模型
+   - `self.model` 保存在实例中
+   - 返回时 `prediction.gaussians` 包含 CUDA 张量
+   - **pickle 时尝试在主进程重建 CUDA 张量** → 💥
+
+2. **第二次调用**（即使第一次成功了）：
+   - 新的子进程或状态混乱
+   - `self.model` 状态不确定
+   - 尝试 `.to(device)` 操作 → 💥
+
+## ✅ 解决方案：两个关键修改
+
+### 修改 1：使用全局变量缓存模型（避免实例状态）
+
+**为什么用全局变量？**
+- `@spaces.GPU` 每次在独立子进程运行
+- 全局变量在子进程内是安全的
+- 不会污染主进程
+
+### 修改 2：返回前移动所有 CUDA 张量到 CPU
+
+**为什么需要？**
+- Pickle 序列化返回值时会尝试重建 CUDA 张量
+- 必须确保返回的数据都在 CPU 上
+
+## 📝 完整修复代码
+
+### 文件：`depth_anything_3/app/modules/model_inference.py`
+
+```python
+"""
+Model inference module for Depth Anything 3 Gradio app.
+
+Modified for HF Spaces GPU compatibility.
+"""
+
+import gc
+import glob
+import os
+from typing import Any, Dict, Optional, Tuple
+import numpy as np
+import torch
+
+from depth_anything_3.api import DepthAnything3
+from depth_anything_3.utils.export.glb import export_to_glb
+from depth_anything_3.utils.export.gs import export_to_gs_video
+
+
+# ========================================
+# 🔑 关键修改 1：使用全局变量缓存模型
+# ========================================
+# Global cache for model (used in GPU subprocess)
+# This is SAFE because @spaces.GPU runs in isolated subprocess
+# Each subprocess gets its own copy of this global variable
+_MODEL_CACHE = None
+
+
+class ModelInference:
+    """
+    Handles model inference and data processing for Depth Anything 3.
+    
+    Modified for HF Spaces GPU compatibility - does NOT store state
+    in instance variables to avoid cross-process issues.
+    """
+
+    def __init__(self):
+        """Initialize the model inference handler.
+        
+        Note: Do NOT store model in instance variable to avoid
+        state sharing issues with @spaces.GPU decorator.
+        """
+        # No instance variables! All state in global or local variables
+        pass
+
+    def initialize_model(self, device: str = "cuda"):
+        """
+        Initialize the DepthAnything3 model using global cache.
+        
+        This uses a global variable which is safe because:
+        1. @spaces.GPU runs in isolated subprocess
+        2. Each subprocess has its own global namespace
+        3. No state leaks to main process
+
+        Args:
+            device: Device to load the model on
+            
+        Returns:
+            Model instance ready for inference
+        """
+        global _MODEL_CACHE
+        
+        if _MODEL_CACHE is None:
+            # First time loading in this subprocess
+            model_dir = os.environ.get(
+                "DA3_MODEL_DIR", "depth-anything/DA3NESTED-GIANT-LARGE"
+            )
+            print(f"🔄 Loading model from {model_dir}...")
+            _MODEL_CACHE = DepthAnything3.from_pretrained(model_dir)
+            _MODEL_CACHE = _MODEL_CACHE.to(device)
+            _MODEL_CACHE.eval()
+            print("✅ Model loaded and ready on GPU")
+        else:
+            # Model already cached in this subprocess
+            print("✅ Using cached model")
+            # Ensure it's on the correct device (defensive programming)
+            _MODEL_CACHE = _MODEL_CACHE.to(device)
+        
+        return _MODEL_CACHE
+
+    def run_inference(
+        self,
+        target_dir: str,
+        filter_black_bg: bool = False,
+        filter_white_bg: bool = False,
+        process_res_method: str = "upper_bound_resize",
+        show_camera: bool = True,
+        selected_first_frame: Optional[str] = None,
+        save_percentage: float = 30.0,
+        num_max_points: int = 1_000_000,
+        infer_gs: bool = False,
+        gs_trj_mode: str = "extend",
+        gs_video_quality: str = "high",
+    ) -> Tuple[Any, Dict[int, Dict[str, Any]]]:
+        """
+        Run DepthAnything3 model inference on images.
+        
+        This method is wrapped with @spaces.GPU in app.py.
+
+        Args:
+            target_dir: Directory containing images
+            filter_black_bg: Whether to filter black background
+            filter_white_bg: Whether to filter white background
+            process_res_method: Method for resizing input images
+            show_camera: Whether to show camera in 3D view
+            selected_first_frame: Selected first frame filename
+            save_percentage: Percentage of points to save (0-100)
+            num_max_points: Maximum number of points
+            infer_gs: Whether to infer 3D Gaussian Splatting
+            gs_trj_mode: Trajectory mode for GS
+            gs_video_quality: Video quality for GS
+
+        Returns:
+            Tuple of (prediction, processed_data)
+        """
+        print(f"Processing images from {target_dir}")
+
+        # Device check
+        device = "cuda" if torch.cuda.is_available() else "cpu"
+        device = torch.device(device)
+        print(f"Using device: {device}")
+
+        # 🔑 使用返回值，而不是 self.model
+        model = self.initialize_model(device)
+
+        # Get image paths
+        print("Loading images...")
+        image_folder_path = os.path.join(target_dir, "images")
+        all_image_paths = sorted(glob.glob(os.path.join(image_folder_path, "*")))
+
+        # Filter for image files
+        image_extensions = [".jpg", ".jpeg", ".png", ".bmp", ".tiff", ".tif"]
+        all_image_paths = [
+            path
+            for path in all_image_paths
+            if any(path.lower().endswith(ext) for ext in image_extensions)
+        ]
+
+        print(f"Found {len(all_image_paths)} images")
+
+        # Apply first frame selection logic
+        if selected_first_frame:
+            selected_path = None
+            for path in all_image_paths:
+                if os.path.basename(path) == selected_first_frame:
+                    selected_path = path
+                    break
+
+            if selected_path:
+                image_paths = [selected_path] + [
+                    path for path in all_image_paths if path != selected_path
+                ]
+                print(f"User selected first frame: {selected_first_frame}")
+            else:
+                image_paths = all_image_paths
+                print(f"Selected frame not found, using default order")
+        else:
+            image_paths = all_image_paths
+
+        if len(image_paths) == 0:
+            raise ValueError("No images found. Check your upload.")
+
+        # Map UI options to actual method names
+        method_mapping = {"high_res": "lower_bound_resize", "low_res": "upper_bound_resize"}
+        actual_method = method_mapping.get(process_res_method, "upper_bound_crop")
+
+        # Run model inference
+        print(f"Running inference with method: {actual_method}")
+        with torch.no_grad():
+            # 🔑 使用局部变量 model，不是 self.model
+            prediction = model.inference(
+                image_paths, export_dir=None, process_res_method=actual_method, infer_gs=infer_gs
+            )
+
+        # Export to GLB
+        export_to_glb(
+            prediction,
+            filter_black_bg=filter_black_bg,
+            filter_white_bg=filter_white_bg,
+            export_dir=target_dir,
+            show_cameras=show_camera,
+            conf_thresh_percentile=save_percentage,
+            num_max_points=int(num_max_points),
+        )
+
+        # Export to GS video if needed
+        if infer_gs:
+            mode_mapping = {"extend": "extend", "smooth": "interpolate_smooth"}
+            print(f"GS mode: {gs_trj_mode}; Backend mode: {mode_mapping[gs_trj_mode]}")
+            export_to_gs_video(
+                prediction,
+                export_dir=target_dir,
+                chunk_size=4,
+                trj_mode=mode_mapping.get(gs_trj_mode, "extend"),
+                enable_tqdm=True,
+                vis_depth="hcat",
+                video_quality=gs_video_quality,
+            )
+
+        # Save predictions cache
+        self._save_predictions_cache(target_dir, prediction)
+
+        # Process results
+        processed_data = self._process_results(target_dir, prediction, image_paths)
+
+        # ========================================
+        # 🔑 关键修改 2：返回前移动所有 CUDA 张量到 CPU
+        # ========================================
+        print("Moving all tensors to CPU for safe return...")
+        prediction = self._move_prediction_to_cpu(prediction)
+
+        # Clean up GPU memory
+        torch.cuda.empty_cache()
+
+        return prediction, processed_data
+
+    def _move_prediction_to_cpu(self, prediction: Any) -> Any:
+        """
+        Move all CUDA tensors in prediction to CPU for safe pickling.
+        
+        This is CRITICAL for HF Spaces with @spaces.GPU decorator.
+        Without this, pickle will try to reconstruct CUDA tensors in
+        the main process, causing CUDA initialization error.
+        
+        Args:
+            prediction: Prediction object that may contain CUDA tensors
+            
+        Returns:
+            Prediction object with all tensors moved to CPU
+        """
+        # Move gaussians tensors to CPU
+        if hasattr(prediction, 'gaussians') and prediction.gaussians is not None:
+            gaussians = prediction.gaussians
+            
+            # Move each tensor attribute to CPU
+            tensor_attrs = ['means', 'scales', 'rotations', 'harmonics', 'opacities']
+            for attr in tensor_attrs:
+                if hasattr(gaussians, attr):
+                    tensor = getattr(gaussians, attr)
+                    if isinstance(tensor, torch.Tensor) and tensor.is_cuda:
+                        setattr(gaussians, attr, tensor.cpu())
+                        print(f"  ✓ Moved gaussians.{attr} to CPU")
+        
+        # Move any tensors in aux dict to CPU
+        if hasattr(prediction, 'aux') and prediction.aux is not None:
+            for key, value in list(prediction.aux.items()):
+                if isinstance(value, torch.Tensor) and value.is_cuda:
+                    prediction.aux[key] = value.cpu()
+                    print(f"  ✓ Moved aux['{key}'] to CPU")
+                elif isinstance(value, dict):
+                    # Recursively handle nested dicts
+                    for k, v in list(value.items()):
+                        if isinstance(v, torch.Tensor) and v.is_cuda:
+                            value[k] = v.cpu()
+                            print(f"  ✓ Moved aux['{key}']['{k}'] to CPU")
+        
+        print("✅ All tensors moved to CPU")
+        return prediction
+
+    def _save_predictions_cache(self, target_dir: str, prediction: Any) -> None:
+        """Save predictions data to predictions.npz for caching."""
+        try:
+            output_file = os.path.join(target_dir, "predictions.npz")
+            save_dict = {}
+
+            if prediction.processed_images is not None:
+                save_dict["images"] = prediction.processed_images
+
+            if prediction.depth is not None:
+                save_dict["depths"] = np.round(prediction.depth, 6)
+
+            if prediction.conf is not None:
+                save_dict["conf"] = np.round(prediction.conf, 2)
+
+            if prediction.extrinsics is not None:
+                save_dict["extrinsics"] = prediction.extrinsics
+            if prediction.intrinsics is not None:
+                save_dict["intrinsics"] = prediction.intrinsics
+
+            np.savez_compressed(output_file, **save_dict)
+            print(f"Saved predictions cache to: {output_file}")
+
+        except Exception as e:
+            print(f"Warning: Failed to save predictions cache: {e}")
+
+    def _process_results(
+        self, target_dir: str, prediction: Any, image_paths: list
+    ) -> Dict[int, Dict[str, Any]]:
+        """Process model results into structured data."""
+        processed_data = {}
+
+        depth_vis_dir = os.path.join(target_dir, "depth_vis")
+
+        if os.path.exists(depth_vis_dir):
+            depth_files = sorted(glob.glob(os.path.join(depth_vis_dir, "*.jpg")))
+            for i, depth_file in enumerate(depth_files):
+                processed_image = None
+                if prediction.processed_images is not None and i < len(
+                    prediction.processed_images
+                ):
+                    processed_image = prediction.processed_images[i]
+
+                processed_data[i] = {
+                    "depth_image": depth_file,
+                    "image": processed_image,
+                    "original_image_path": image_paths[i] if i < len(image_paths) else None,
+                    "depth": prediction.depth[i] if i < len(prediction.depth) else None,
+                    "intrinsics": (
+                        prediction.intrinsics[i]
+                        if prediction.intrinsics is not None and i < len(prediction.intrinsics)
+                        else None
+                    ),
+                    "mask": None,
+                }
+
+        return processed_data
+
+    def cleanup(self) -> None:
+        """Clean up GPU memory."""
+        if torch.cuda.is_available():
+            torch.cuda.empty_cache()
+        gc.collect()
+```
+
+## 🔍 关键变化总结
+
+### Before (有问题)：
+```python
+class ModelInference:
+    def __init__(self):
+        self.model = None  # ❌ 实例变量
+    
+    def initialize_model(self, device):
+        if self.model is None:
+            self.model = load_model()  # ❌ 保存在实例中
+        else:
+            self.model = self.model.to(device)  # ❌ 跨进程操作
+
+def run_inference(self):
+        self.initialize_model(device)  # ❌ 使用实例方法
+        prediction = self.model.inference(...)  # ❌ 使用实例变量
+        return prediction  # ❌ 包含 CUDA 张量
+```
+
+### After (正确)：
+```python
+_MODEL_CACHE = None  # ✅ 全局变量（子进程安全）
+
+class ModelInference:
+    def __init__(self):
+        pass  # ✅ 无实例变量
+    
+    def initialize_model(self, device):
+        global _MODEL_CACHE
+        if _MODEL_CACHE is None:
+            _MODEL_CACHE = load_model()  # ✅ 保存在全局
+        return _MODEL_CACHE  # ✅ 返回而不是存储
+
+    def run_inference(self):
+        model = self.initialize_model(device)  # ✅ 局部变量
+        prediction = model.inference(...)  # ✅ 使用局部变量
+        prediction = self._move_prediction_to_cpu(prediction)  # ✅ 移到 CPU
+        return prediction  # ✅ 安全返回
+```
+
+## 🎯 为什么这样修改？
+
+### 1. 全局变量 vs 实例变量
+
+| 方式 | 问题 | 原因 |
+|------|------|------|
+| `self.model` | ❌ 跨进程状态混乱 | 实例在主进程创建 |
+| `_MODEL_CACHE` | ✅ 子进程内安全 | 每个子进程独立 |
+
+### 2. 返回 CPU 张量
+
+```python
+# ❌ 直接返回会报错
+return prediction  # prediction.gaussians.means is on CUDA
+
+# ✅ 移到 CPU 后返回
+prediction = move_to_cpu(prediction)
+return prediction  # All tensors are on CPU, pickle safe
+```
+
+## 🧪 测试修复
+
+```bash
+# 1. 应用修改
+# 复制上面的完整代码到 model_inference.py
+
+# 2. 推送到 Spaces
+git add depth_anything_3/app/modules/model_inference.py
+git commit -m "Fix: Spaces GPU CUDA initialization error"
+git push
+
+# 3. 测试多次运行
+# 在 Space 中连续运行 2-3 次推理
+# 应该不再出现 CUDA 错误
+```
+
+## 📊 修复效果
+
+| 问题 | Before | After |
+|------|--------|-------|
+| 第一次推理 | ❌ CUDA 错误 | ✅ 正常 |
+| 第二次推理 | ❌ CUDA 错误 | ✅ 正常 |
+| 连续推理 | ❌ 失败 | ✅ 稳定 |
+| 模型加载 | 每次重新加载 | 缓存复用 |
+
+## 💡 最佳实践
+
+对于 `@spaces.GPU` 装饰的函数：
+
+1. ✅ 使用**全局变量**缓存模型（子进程安全）
+2. ✅ **不要**使用实例变量存储模型
+3. ✅ 返回前**移动所有张量到 CPU**
+4. ✅ 清理 GPU 内存 (`torch.cuda.empty_cache()`)
+5. ❌ **不要**在主进程中初始化 CUDA
+6. ❌ **不要**返回 CUDA 张量
+
+## 🔗 相关资源
+
+- [HF Spaces Zero GPU 文档](https://huggingface.co/docs/hub/spaces-gpus#zero-gpu)
+- [PyTorch Multiprocessing](https://pytorch.org/docs/stable/notes/multiprocessing.html)
+- [Pickle 协议](https://docs.python.org/3/library/pickle.html)
+

app.py

@@ -24,8 +24,9 @@ import spaces
 from depth_anything_3.app.gradio_app import DepthAnything3App
 from depth_anything_3.app.modules.model_inference import ModelInference
 
-# Monkey-patch the run_inference method to use @spaces.GPU decorator
-# This allows dynamic GPU allocation on Hugging Face Spaces
+# Apply @spaces.GPU decorator to run_inference method
+# This ensures GPU operations happen in isolated subprocess
+# Model loading and inference will occur in GPU subprocess, not main process
 original_run_inference = ModelInference.run_inference
 
 @spaces.GPU(duration=120)  # Request GPU for up to 120 seconds per inference
@@ -33,8 +34,10 @@ def gpu_run_inference(self, *args, **kwargs):
     """
     GPU-accelerated inference with Spaces decorator.
     
-    This function wraps the original run_inference method with @spaces.GPU,
-    which ensures the model is moved to GPU when needed on HF Spaces.
+    This function runs in a GPU subprocess where:
+    - Model is loaded and moved to GPU (safe)
+    - CUDA operations are allowed
+    - All CUDA tensors are moved to CPU before return (for pickle safety)
     """
     return original_run_inference(self, *args, **kwargs)
 

depth_anything_3/app/modules/model_inference.py

@@ -31,33 +31,57 @@ from depth_anything_3.utils.export.glb import export_to_glb
 from depth_anything_3.utils.export.gs import export_to_gs_video
 
 
+# Global cache for model (safe in GPU subprocess with @spaces.GPU)
+# Each subprocess gets its own copy of this global variable
+_MODEL_CACHE = None
+
+
 class ModelInference:
     """
     Handles model inference and data processing for Depth Anything 3.
     """
 
     def __init__(self):
-        """Initialize the model inference handler."""
-        self.model = None
+        """Initialize the model inference handler.
+        
+        Note: Do not store model in instance variable to avoid
+        cross-process state issues with @spaces.GPU decorator.
+        """
+        # No instance variables - model cached in global variable
+        pass
 
-    def initialize_model(self, device: str = "cuda") -> None:
+    def initialize_model(self, device: str = "cuda"):
         """
-        Initialize the DepthAnything3 model.
+        Initialize the DepthAnything3 model using global cache.
+        
+        This uses a global variable which is safe because @spaces.GPU
+        runs in isolated subprocess, each with its own global namespace.
 
         Args:
             device: Device to load the model on
+            
+        Returns:
+            Model instance ready for inference
         """
-        if self.model is None:
-            # Get model directory from environment variable or use default
+        global _MODEL_CACHE
+        
+        if _MODEL_CACHE is None:
+            # First time loading in this subprocess
             model_dir = os.environ.get(
-                "DA3_MODEL_DIR", "/dev/shm/da3_models/DA3HF-VITG-METRIC_VITL"
+                "DA3_MODEL_DIR", "depth-anything/DA3NESTED-GIANT-LARGE"
             )
-            self.model = DepthAnything3.from_pretrained(model_dir)
-            self.model = self.model.to(device)
+            print(f"🔄 Loading model from {model_dir}...")
+            _MODEL_CACHE = DepthAnything3.from_pretrained(model_dir)
+            _MODEL_CACHE = _MODEL_CACHE.to(device)
+            _MODEL_CACHE.eval()
+            print("✅ Model loaded and ready on GPU")
         else:
-            self.model = self.model.to(device)
-
-        self.model.eval()
+            # Model already cached in this subprocess
+            print("✅ Using cached model")
+            # Ensure it's on the correct device
+            _MODEL_CACHE = _MODEL_CACHE.to(device)
+        
+        return _MODEL_CACHE
 
     def run_inference(
         self,
@@ -97,8 +121,8 @@ class ModelInference:
         device = "cuda" if torch.cuda.is_available() else "cpu"
         device = torch.device(device)
 
-        # Initialize model if needed
-        self.initialize_model(device)
+        # Initialize model if needed - get model instance (not stored in self)
+        model = self.initialize_model(device)
 
         # Get image paths
         print("Loading images...")
@@ -157,7 +181,7 @@ class ModelInference:
         # Run model inference
         print(f"Running inference with method: {actual_method}")
         with torch.no_grad():
-            prediction = self.model.inference(
+            prediction = model.inference(
                 image_paths, export_dir=None, process_res_method=actual_method, infer_gs=infer_gs
             )
         # num_max_points: int = 1_000_000,
@@ -191,6 +215,10 @@ class ModelInference:
         # Process results
         processed_data = self._process_results(target_dir, prediction, image_paths)
 
+        # CRITICAL: Move all CUDA tensors to CPU before returning
+        # This prevents CUDA initialization in main process during unpickling
+        prediction = self._move_prediction_to_cpu(prediction)
+
         # Clean up
         torch.cuda.empty_cache()
 
@@ -279,6 +307,47 @@ class ModelInference:
 
         return processed_data
 
+    def _move_prediction_to_cpu(self, prediction: Any) -> Any:
+        """
+        Move all CUDA tensors in prediction to CPU for safe pickling.
+        
+        This is REQUIRED for HF Spaces with @spaces.GPU decorator to avoid
+        CUDA initialization in the main process during unpickling.
+        
+        Args:
+            prediction: Prediction object that may contain CUDA tensors
+            
+        Returns:
+            Prediction object with all tensors moved to CPU
+        """
+        # Move gaussians tensors to CPU
+        if hasattr(prediction, 'gaussians') and prediction.gaussians is not None:
+            gaussians = prediction.gaussians
+            
+            # Move each tensor attribute to CPU
+            tensor_attrs = ['means', 'scales', 'rotations', 'harmonics', 'opacities']
+            for attr in tensor_attrs:
+                if hasattr(gaussians, attr):
+                    tensor = getattr(gaussians, attr)
+                    if isinstance(tensor, torch.Tensor) and tensor.is_cuda:
+                        setattr(gaussians, attr, tensor.cpu())
+                        print(f"  ✓ Moved gaussians.{attr} to CPU")
+        
+        # Move any tensors in aux dict to CPU
+        if hasattr(prediction, 'aux') and prediction.aux is not None:
+            for key, value in list(prediction.aux.items()):
+                if isinstance(value, torch.Tensor) and value.is_cuda:
+                    prediction.aux[key] = value.cpu()
+                    print(f"  ✓ Moved aux['{key}'] to CPU")
+                elif isinstance(value, dict):
+                    # Recursively handle nested dicts
+                    for k, v in list(value.items()):
+                        if isinstance(v, torch.Tensor) and v.is_cuda:
+                            value[k] = v.cpu()
+                            print(f"  ✓ Moved aux['{key}']['{k}'] to CPU")
+        
+        return prediction
+
     def cleanup(self) -> None:
         """Clean up GPU memory."""
         if torch.cuda.is_available():

example_spaces_gpu.py

@@ -1,52 +0,0 @@
-"""
-Simple example demonstrating @spaces.GPU decorator usage.
-
-This example shows how the @spaces.GPU decorator works:
-- Variables created outside the decorated function stay on CPU initially
-- When the decorated function is called, the process moves to GPU environment
-- Inside the decorated function, tensors can access CUDA
-"""
-
-import gradio as gr
-import spaces
-import torch
-
-# This tensor is created at module load time
-# On HF Spaces, it will be on CPU until a @spaces.GPU function is called
-zero = torch.Tensor([0])
-
-# Try to move to cuda - will fail gracefully if no GPU available
-try:
-    zero = zero.cuda()
-    print(f"Initial device: {zero.device}")  # On Spaces: shows 'cpu' 🤔
-except:
-    print(f"Initial device: {zero.device}")  # cpu (no GPU available yet)
-
-
-@spaces.GPU(duration=60)  # Request GPU for up to 60 seconds
-def greet(n):
-    """
-    This function runs on GPU when called.
-    The @spaces.GPU decorator ensures GPU access.
-    """
-    # Inside the decorated function, we have GPU access
-    print(f"Inside GPU function - device: {zero.device}")  # On Spaces: shows 'cuda:0' 🤗
-    
-    # Perform GPU computation
-    result = zero + n
-    
-    return f"Hello {result.item()} Tensor! (computed on {zero.device})"
-
-
-# Create Gradio interface
-demo = gr.Interface(
-    fn=greet,
-    inputs=gr.Number(value=42, label="Enter a number"),
-    outputs=gr.Text(label="Result"),
-    title="Spaces GPU Example",
-    description="Demonstrates @spaces.GPU decorator usage"
-)
-
-if __name__ == "__main__":
-    demo.launch()
-

fix_spaces_gpu.patch

@@ -0,0 +1,142 @@
+--- a/depth_anything_3/app/modules/model_inference.py
++++ b/depth_anything_3/app/modules/model_inference.py
+@@ -31,47 +31,67 @@ from depth_anything_3.utils.export.glb import export_to_glb
+ from depth_anything_3.utils.export.gs import export_to_gs_video
+ 
+ 
++# Global cache for model (used in GPU subprocess)
++# This is safe because @spaces.GPU runs in isolated subprocess
++_MODEL_CACHE = None
++
++
+ class ModelInference:
+     """
+     Handles model inference and data processing for Depth Anything 3.
+     """
+ 
+     def __init__(self):
+-        """Initialize the model inference handler."""
+-        self.model = None
+-
+-    def initialize_model(self, device: str = "cuda") -> None:
++        """Initialize the model inference handler.
++        
++        Note: Do NOT store model in instance variable to avoid
++        state sharing issues with @spaces.GPU decorator.
++        """
++        pass  # No instance variables
++
++    def initialize_model(self, device: str = "cuda"):
+         """
+         Initialize the DepthAnything3 model.
++        
++        Uses global cache to store model safely in GPU subprocess.
++        This avoids CUDA initialization in main process.
+ 
+         Args:
+             device: Device to load the model on
++            
++        Returns:
++            Model instance
+         """
+-        if self.model is None:
++        global _MODEL_CACHE
++        
++        if _MODEL_CACHE is None:
+             # Get model directory from environment variable or use default
+             model_dir = os.environ.get(
+                 "DA3_MODEL_DIR", "/dev/shm/da3_models/DA3HF-VITG-METRIC_VITL"
+             )
+-            self.model = DepthAnything3.from_pretrained(model_dir)
+-            self.model = self.model.to(device)
++            print(f"Loading model from {model_dir}...")
++            _MODEL_CACHE = DepthAnything3.from_pretrained(model_dir)
++            _MODEL_CACHE = _MODEL_CACHE.to(device)
++            _MODEL_CACHE.eval()
++            print("Model loaded and moved to GPU")
+         else:
+-            self.model = self.model.to(device)
+-
+-        self.model.eval()
++            print("Using cached model")
++            # Ensure model is on correct device
++            _MODEL_CACHE = _MODEL_CACHE.to(device)
++        
++        return _MODEL_CACHE
+ 
+     def run_inference(
+         self,
+         ...
+         # Initialize model if needed
+-        self.initialize_model(device)
++        model = self.initialize_model(device)
+ 
+         ...
+ 
+         # Run model inference
+         print(f"Running inference with method: {actual_method}")
+         with torch.no_grad():
+-            prediction = self.model.inference(
++            prediction = model.inference(
+                 image_paths, export_dir=None, process_res_method=actual_method, infer_gs=infer_gs
+             )
+         
+@@ -192,6 +212,10 @@ class ModelInference:
+         # Process results
+         processed_data = self._process_results(target_dir, prediction, image_paths)
+ 
++        # CRITICAL: Move all CUDA tensors to CPU before returning
++        # This prevents CUDA initialization in main process during unpickling
++        prediction = self._move_prediction_to_cpu(prediction)
++
+         # Clean up
+         torch.cuda.empty_cache()
+ 
+@@ -282,6 +306,45 @@ class ModelInference:
+ 
+         return processed_data
+ 
++    def _move_prediction_to_cpu(self, prediction: Any) -> Any:
++        """
++        Move all CUDA tensors in prediction to CPU for safe pickling.
++        
++        This is REQUIRED for HF Spaces with @spaces.GPU decorator to avoid
++        CUDA initialization in the main process during unpickling.
++        
++        Args:
++            prediction: Prediction object that may contain CUDA tensors
++            
++        Returns:
++            Prediction object with all tensors moved to CPU
++        """
++        # Move gaussians tensors to CPU
++        if hasattr(prediction, 'gaussians') and prediction.gaussians is not None:
++            gaussians = prediction.gaussians
++            
++            # Move each tensor attribute to CPU
++            tensor_attrs = ['means', 'scales', 'rotations', 'harmonics', 'opacities']
++            for attr in tensor_attrs:
++                if hasattr(gaussians, attr):
++                    tensor = getattr(gaussians, attr)
++                    if isinstance(tensor, torch.Tensor) and tensor.is_cuda:
++                        setattr(gaussians, attr, tensor.cpu())
++                        print(f"Moved gaussians.{attr} to CPU")
++        
++        # Move any tensors in aux dict to CPU
++        if hasattr(prediction, 'aux') and prediction.aux is not None:
++            for key, value in list(prediction.aux.items()):
++                if isinstance(value, torch.Tensor) and value.is_cuda:
++                    prediction.aux[key] = value.cpu()
++                    print(f"Moved aux['{key}'] to CPU")
++                elif isinstance(value, dict):
++                    # Recursively handle nested dicts
++                    for k, v in list(value.items()):
++                        if isinstance(v, torch.Tensor) and v.is_cuda:
++                            value[k] = v.cpu()
++                            print(f"Moved aux['{key}']['{k}'] to CPU")
++        
++        return prediction
++
+     def cleanup(self) -> None:
+         """Clean up GPU memory."""
+