depth-anything-3

Running on Zero

App Files Files Community

depth-anything-3 / UPLOAD_EXAMPLES.md

linhaotong

update examples

d55de36 29 days ago

preview code

raw

history blame

7.37 kB

📤 上传 Examples 到 Hugging Face Spaces 指南

🚨 问题：二进制文件被拒绝

Hugging Face Spaces 会拒绝大文件（>100MB）或二进制文件，需要使用 Git LFS 来上传。

✅ 解决方案

方案 1：使用 Git LFS（推荐）⭐

步骤 1：配置 Git LFS

我已经为你创建了 .gitattributes 文件，配置了图片文件的 Git LFS：

# Images in examples directory
workspace/gradio/examples/**/*.png filter=lfs diff=lfs merge=lfs -text
workspace/gradio/examples/**/*.jpg filter=lfs diff=lfs merge=lfs -text
workspace/gradio/examples/**/*.jpeg filter=lfs diff=lfs merge=lfs -text
workspace/gradio/examples/**/*.bmp filter=lfs diff=lfs merge=lfs -text
workspace/gradio/examples/**/*.tiff filter=lfs diff=lfs merge=lfs -text
workspace/gradio/examples/**/*.tif filter=lfs diff=lfs merge=lfs -text

步骤 2：安装 Git LFS（如果还没有）

# macOS
brew install git-lfs

# Linux
sudo apt-get install git-lfs

# Windows
# 下载安装：https://git-lfs.github.com/

步骤 3：初始化 Git LFS

cd /Users/bytedance/depth-anything-3

# 初始化 Git LFS
git lfs install

# 验证配置
git lfs track

步骤 4：添加示例场景

# 创建 examples 目录
mkdir -p workspace/gradio/examples/my_scene

# 添加图像文件
cp your_images/* workspace/gradio/examples/my_scene/

# 添加文件到 Git LFS
git add workspace/gradio/examples/
git add .gitattributes

# 提交
git commit -m "Add example scenes with Git LFS"

# 推送到 Spaces
git push origin main

步骤 5：验证

# 检查哪些文件使用了 LFS
git lfs ls-files

# 应该看到你的图片文件

方案 2：使用持久存储（推荐用于大量数据）⭐

如果示例场景很大，可以使用 Hugging Face Spaces 的持久存储功能。

步骤 1：在 Spaces 设置中启用持久存储

进入你的 Space 设置
启用 "Persistent storage"
设置存储大小（如 50GB）

步骤 2：在应用启动时下载示例

修改 app.py，在启动时从外部源下载示例：

import os
import subprocess

def download_examples():
    """Download examples from external source if not exists"""
    examples_dir = "workspace/gradio/examples"
    if not os.path.exists(examples_dir) or not os.listdir(examples_dir):
        print("Downloading example scenes...")
        # 从 Hugging Face Dataset 下载
        # 或从其他存储服务下载
        # subprocess.run(["huggingface-cli", "download", "dataset/examples", ...])
        pass

if __name__ == "__main__":
    download_examples()
    # ... 启动应用

步骤 3：上传到 Hugging Face Dataset

# 安装依赖
pip install huggingface_hub datasets

# 上传到 Dataset
python -c "
from datasets import Dataset
from huggingface_hub import HfApi

# 创建 dataset 并上传
api = HfApi()
api.upload_folder(
    folder_path='workspace/gradio/examples',
    repo_id='your-username/your-examples-dataset',
    repo_type='dataset'
)
"

方案 3：压缩后上传（小文件）

如果图片文件较小（<100MB），可以压缩后上传：

# 压缩 examples 目录
tar -czf examples.tar.gz workspace/gradio/examples/

# 添加到 Git（作为普通文件）
git add examples.tar.gz
git commit -m "Add compressed examples"
git push

# 在应用启动时解压
# 在 app.py 中添加：
import tarfile
if not os.path.exists("workspace/gradio/examples"):
    print("Extracting examples...")
    tarfile.open("examples.tar.gz").extractall()

方案 4：运行时下载（推荐用于生产）⭐

在应用启动时从外部源下载示例场景：

修改 `app.py`

import os
import subprocess
from huggingface_hub import hf_hub_download

def setup_examples():
    """Setup examples directory by downloading if needed"""
    examples_dir = "workspace/gradio/examples"
    os.makedirs(examples_dir, exist_ok=True)
    
    # 如果 examples 目录为空，从外部源下载
    if not os.listdir(examples_dir):
        print("📥 Downloading example scenes...")
        
        # 方式 1: 从 Hugging Face Dataset 下载
        try:
            from datasets import load_dataset
            dataset = load_dataset("your-username/your-examples-dataset")
            # 处理并保存到 examples_dir
        except:
            pass
        
        # 方式 2: 从 URL 下载压缩包
        # import urllib.request
        # urllib.request.urlretrieve("https://...", "examples.zip")
        # 解压到 examples_dir
        
        print("✅ Examples downloaded")

if __name__ == "__main__":
    setup_examples()
    # ... 启动应用

🎯 推荐方案对比

方案	优点	缺点	适用场景
Git LFS	✅ 简单直接 ✅ 版本控制	⚠️ 需要 LFS 配额 ⚠️ 大文件可能慢	小到中等示例（<1GB）
持久存储	✅ 无大小限制 ✅ 快速访问	⚠️ 需要手动上传 ⚠️ 需要付费	大量示例（>1GB）
运行时下载	✅ 不占用仓库空间 ✅ 灵活	⚠️ 首次启动慢 ⚠️ 需要网络	生产环境
压缩上传	✅ 简单	⚠️ 大小限制 ⚠️ 需要解压	小文件（<100MB）

📝 完整 Git LFS 设置步骤

1. 确保 Git LFS 已安装

git lfs version
# 如果未安装，按照上面的步骤安装

2. 初始化 Git LFS

cd /Users/bytedance/depth-anything-3
git lfs install

3. 检查 .gitattributes

确保 .gitattributes 包含图片文件配置（我已经添加了）。

4. 添加示例场景

# 创建场景
mkdir -p workspace/gradio/examples/scene1
cp your_images/* workspace/gradio/examples/scene1/

# 添加文件
git add workspace/gradio/examples/
git add .gitattributes

# 检查哪些文件会使用 LFS
git lfs ls-files

# 提交
git commit -m "Add example scenes with Git LFS"

# 推送
git push origin main

5. 验证上传

在 Spaces 中检查文件是否成功上传，图片文件应该显示为 LFS 指针。

🔧 故障排除

问题 1：Git LFS 配额不足

解决方案：

使用方案 2（持久存储）或方案 4（运行时下载）
压缩图片文件
只上传必要的示例

问题 2：推送失败

检查：

# 检查 LFS 文件
git lfs ls-files

# 检查 LFS 状态
git lfs status

# 重新推送
git push origin main --force

问题 3：文件仍然被拒绝

可能原因：

.gitattributes 配置不正确
文件没有通过 LFS 添加

解决：

# 移除并重新添加
git rm --cached workspace/gradio/examples/**/*.png
git add workspace/gradio/examples/
git commit -m "Fix: Add images via Git LFS"
git push

💡 最佳实践

小示例（<100MB）：使用 Git LFS
中等示例（100MB-1GB）：使用 Git LFS 或持久存储
大示例（>1GB）：使用持久存储或运行时下载
生产环境：使用运行时下载，从外部源获取