DEPLOYMENT_CHECKLIST.md

🚀 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. 文件检查

# 确认所有必需文件存在
[ -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 必须包含：

import spaces
@spaces.GPU(duration=120)
def gpu_run_inference(self, *args, **kwargs):
    ...

3. 本地测试（推荐）

# 测试 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

# 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：gsplat 构建失败 ⚠️

症状：

Building wheel for gsplat (setup.py) ... error

快速修复：

# 方法 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 开头添加：

   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

---
title: Depth Anything 3
sdk: gradio
sdk_version: 5.49.1
app_file: app.py
python_version: 3.11
---

app.py 关键部分

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 关键依赖

torch>=2.0.0
gradio>=5.0.0
spaces
gsplat @ git+https://github.com/nerfstudio-project/gsplat.git@0b4dddf04cb687367602c01196913cde6a743d70

packages.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 文档
• Gradio 文档
• gsplat GitHub

---

📞 获取帮助

如果遇到问题：

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
• 可以嵌入到网页、博客等

祝你使用愉快！🚀