DEPLOYMENT_GUIDE.md

Hugging Face Spaces Deployment Guide

部署步骤

1. 创建 Hugging Face Space

1. 访问 Hugging Face Spaces
2. 选择 Gradio 作为 SDK
3. 选择合适的硬件（推荐 A10G 或更高配置，因为需要运行大模型）
4. 创建空间

2. 上传必要文件

将以下文件上传到你的 Hugging Face Space：

必需文件：

• demo/app.py - 主应用文件
• requirements_hf.txt - 重命名为 requirements.txt
• packages.txt - 系统依赖
• pre_build.py - 预构建脚本
• README_HF.md - 重命名为 README.md

项目文件：

• tools/ 目录及其所有内容
• demo/example_images/ 目录及示例图片
• 其他必要的项目文件

3. 配置文件说明

requirements.txt

包含所有 Python 依赖，特别是：

• PyTorch 2.6.0 with CUDA support
• Transformers, Gradio 等核心库
• GroundingDINO 相关依赖

packages.txt

系统级依赖，包括：

• Git, wget (用于下载)
• OpenCV 相关库
• 构建工具

pre_build.py

自动化设置脚本，负责：

• 克隆和安装 GroundingDINO
• 下载预训练权重
• 处理 torch 2.6 兼容性

4. 重要注意事项

硬件要求

• 最低配置: A10G Small (24GB VRAM)
• 推荐配置: A100-40GB 或更高
• 需要足够的 VRAM 来加载 7B 模型和 GroundingDINO

环境变量

无需额外配置环境变量，脚本会自动检测 HF Spaces 环境。

构建时间

首次部署可能需要 10-20 分钟，因为需要：

• 安装所有依赖
• 克隆和编译 GroundingDINO
• 下载模型权重

5. 常见问题

内存不足

如果遇到 CUDA OOM 错误：

• 升级到更高配置的硬件
• 考虑使用模型量化

构建失败

如果预构建脚本失败：

• 检查 packages.txt 中的系统依赖
• 确保所有文件路径正确
• 查看构建日志确定具体错误

模型加载失败

确保：

• 网络连接正常（用于下载模型）
• 有足够的存储空间
• CUDA 环境正确配置

6. 部署命令总结

# 在本地准备文件
cp requirements_hf.txt requirements.txt
cp README_HF.md README.md

# 上传到 HF Spaces（通过 Web 界面或 git）
git add .
git commit -m "Deploy to Hugging Face Spaces"
git push

7. 验证部署

部署成功后，应该能够：

1. 看到 Gradio 界面正常加载
2. 上传图片并运行推理
3. 看到 GroundingDINO 检测结果
4. 获得 Rex-Thinker 的推理输出

如果遇到问题，请查看 Space 的日志获取详细错误信息。