SPACES_SETUP.md

Hugging Face Spaces 部署指南

📋 概述

这个项目已经配置好可以部署到 Hugging Face Spaces，使用 @spaces.GPU 装饰器来动态分配 GPU 资源。

🎯 关键文件

1. app.py - 主应用文件

import spaces
from depth_anything_3.app.gradio_app import DepthAnything3App
from depth_anything_3.app.modules.model_inference import ModelInference

# 使用 monkey-patching 将 GPU 装饰器应用到推理函数
original_run_inference = ModelInference.run_inference

@spaces.GPU(duration=120)  # 请求 GPU，最多 120 秒
def gpu_run_inference(self, *args, **kwargs):
    return original_run_inference(self, *args, **kwargs)

ModelInference.run_inference = gpu_run_inference

工作原理：

• @spaces.GPU 装饰器在函数调用时动态分配 GPU
• duration=120 表示单次推理最多使用 GPU 120 秒
• 通过 monkey-patching，我们将装饰器应用到已有的推理函数上，无需修改核心代码

2. README.md - Spaces 配置

---
title: Depth Anything 3
sdk: gradio
sdk_version: 5.49.1
app_file: app.py
pinned: false
license: cc-by-nc-4.0
---

这个 YAML 前置内容告诉 Hugging Face Spaces：

• 使用 Gradio SDK
• 入口文件是 app.py
• 使用的 Gradio 版本

3. pyproject.toml - 依赖配置

已经更新，包含了 spaces 依赖：

[project.optional-dependencies]
app = ["gradio>=5", "pillow>=9.0", "spaces"]

🚀 部署步骤

方式 1：通过 Hugging Face 网页界面

1. 在 Hugging Face 创建一个新的 Space
2. 选择 Gradio 作为 SDK
3. 上传你的代码（包括 app.py, src/, pyproject.toml 等）
4. Space 会自动构建并启动

方式 2：通过 Git

# 克隆你的 Space 仓库
git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
cd YOUR_SPACE_NAME

# 添加你的代码
cp -r /path/to/depth-anything-3/* .

# 提交并推送
git add .
git commit -m "Initial commit"
git push

🔧 配置选项

GPU 类型

Hugging Face Spaces 支持不同的 GPU 类型：

• Free (T4): 免费，适合小型模型
• A10G: 付费，更强大
• A100: 付费，最强大

GPU Duration

在 app.py 中可以调整：

@spaces.GPU(duration=120)  # 120 秒

• 设置太短：复杂推理可能超时
• 设置太长：浪费资源
• 推荐：根据实际推理时间设置（可以先设长一点，然后根据日志调整）

环境变量

可以在 Space 设置中配置环境变量：

• DA3_MODEL_DIR: 模型目录路径
• DA3_WORKSPACE_DIR: 工作空间目录
• DA3_GALLERY_DIR: 图库目录

📊 监控和调试

查看日志

在 Spaces 界面点击 "Logs" 标签可以看到：

🚀 Launching Depth Anything 3 on Hugging Face Spaces...
📦 Model Directory: depth-anything/DA3NESTED-GIANT-LARGE
📁 Workspace Directory: workspace/gradio
🖼️  Gallery Directory: workspace/gallery

GPU 使用情况

在装饰的函数内部，可以检查 GPU 状态：

print(torch.cuda.is_available())  # True
print(torch.cuda.device_count())  # 1 (通常)
print(torch.cuda.get_device_name(0))  # 'Tesla T4' 或其他

🎓 示例代码

查看 example_spaces_gpu.py 了解 @spaces.GPU 装饰器的基本用法。

❓ 常见问题

Q: 为什么使用 monkey-patching？

A: 这样可以在不修改核心代码的情况下添加 Spaces 支持。如果你想更优雅的方式，可以：

1. 直接在 ModelInference.run_inference 方法上添加装饰器
2. 创建一个继承自 ModelInference 的新类

Q: 如何测试本地是否能运行？

A: 本地运行时，spaces.GPU 装饰器会被忽略（如果没有安装 spaces 包），或者会直接执行函数而不做特殊处理。

# 本地测试
python app.py

Q: 可以装饰多个函数吗？

A: 可以！你可以给任何需要 GPU 的函数添加 @spaces.GPU 装饰器。

@spaces.GPU(duration=60)
def function1():
    pass

@spaces.GPU(duration=120)
def function2():
    pass

Q: 如何优化 GPU 使用？

A: 一些建议：

1. 只装饰必要的函数：不要装饰整个 app，只装饰实际使用 GPU 的推理函数
2. 设置合适的 duration：根据实际需求设置
3. 清理 GPU 内存：在函数结束时调用 torch.cuda.empty_cache()
4. 批处理：如果可能，批量处理多个请求

🔗 相关资源

• Hugging Face Spaces 文档
• Spaces GPU 使用指南
• Gradio 文档

📝 许可证

Apache-2.0