HUGGINGFACE_DEPLOY.md

# HuggingFace Spaces 部署指南

## 🚀 部署步骤

### 1. 准备文件
确保您的项目包含以下文件：
- `app.py` - 主应用代码
- `run_hf.py` - HuggingFace启动脚本
- `requirements.txt` - Python依赖
- `packages.txt` - 系统依赖
- `README.md` - Spaces配置
- `prohibited_rules.py` - 巨量引擎规则
- `minigpt4_video_demo.py` - MiniGPT4-Video核心模块
- `test_configs/llama2_test_config.yaml` - 模型配置

### 2. 创建HuggingFace Space
1. 访问 [HuggingFace Spaces](https://huggingface.co/spaces)
2. 点击 "Create new Space"
3. 设置以下参数：
   - **Space name**: `minigpt4-video-safety`
   - **License**: Apache 2.0
   - **SDK**: Gradio
   - **Hardware**: GPU (推荐T4或更高)

### 3. 上传文件
```bash
git clone https://huggingface.co/spaces/YOUR_USERNAME/minigpt4-video-safety
cd minigpt4-video-safety
cp /path/to/your/files/* ./
git add .
git commit -m "Initial deployment"
git push
```

### 4. 配置模型权重
由于MiniGPT4-Video需要预训练权重，您需要：

1. 上传模型权重到HuggingFace Hub
2. 修改`app.py`中的模型路径
3. 或者使用HuggingFace的模型仓库

### 5. 环境变量设置
在Space设置中添加环境变量：
- `PYTORCH_CUDA_ALLOC_CONF=max_split_size_mb:512`
- `GRADIO_SERVER_PORT=7860`

## 🔧 配置选项

### Hardware要求
- **最低配置**: CPU Basic (仅安全检测)
- **推荐配置**: GPU T4 (完整功能)
- **高性能**: GPU A10G (大规模使用)

### 内存要求
- CPU模式: 4GB RAM
- GPU模式: 16GB GPU内存

## 🛠️ 故障排除

### 常见问题

1. **模型加载失败**
   - 检查模型权重路径
   - 确认GPU内存充足
   - 验证依赖版本兼容性

2. **依赖安装失败**
   - 检查`requirements.txt`格式
   - 验证PyTorch版本兼容性
   - 确认CUDA版本匹配

3. **内存不足**
   - 减少batch_size
   - 使用量化模型
   - 升级硬件配置

### 调试模式
在开发阶段，可以设置环境变量：
```bash
export DEBUG=1
export GRADIO_DEBUG=1
```

## 📝 注意事项

1. **模型权重**: 需要单独下载MiniGPT4-Video权重
2. **GPU内存**: 确保有足够的GPU内存加载模型
3. **网络访问**: YouTube下载功能需要网络访问
4. **文件存储**: 临时文件会占用存储空间

## 🔗 相关链接

- [MiniGPT4-Video官方仓库](https://github.com/Vision-CAIR/MiniGPT4-video)
- [HuggingFace Spaces文档](https://huggingface.co/docs/hub/spaces)
- [Gradio文档](https://gradio.app/docs/)

## 📞 技术支持

如遇到部署问题，请：
1. 检查控制台日志
2. 验证配置文件
3. 确认依赖版本
4. 联系技术支持