DEPLOYMENT_GUIDE.md

# Hugging Face Spaces Deployment Guide

## 部署步骤

### 1. 创建 Hugging Face Space

1. 访问 [Hugging Face Spaces](https://huggingface.co/new-space)
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. 部署命令总结

```bash
# 在本地准备文件
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 的日志获取详细错误信息。