UPLOAD_GUIDE.md

# KeyVID 上传到 Hugging Face 指南

## 📦 快速开始

### 方法1: 使用快速上传脚本 (推荐)

```bash
cd /dockerx/groups/KeyVID
python upload_fast.py
```

### 方法2: 使用完整功能上传脚本

```bash
cd /dockerx/groups/KeyVID
python upload.py
```

## 🚀 如何加快上传速度

### 1. 使用 `multi_commits=True` (已内置)
- ✅ 允许分批提交文件，不需要等待所有文件上传完成
- ✅ 大文件可以先开始上传，小文件可以并行
- ✅ 即使中断，已上传的文件也会保存

### 2. 网络优化
```bash
# 检查当前上传速度
speedtest-cli

# 如果使用代理，确保代理设置正确
export HTTP_PROXY=http://proxy:port
export HTTPS_PROXY=http://proxy:port
```

### 3. 减少上传文件大小
- ✅ 脚本已自动排除不必要的文件 (save_results, __pycache__, .git等)
- 💡 如果需要，可以手动排除更多文件，修改 `ignore_patterns`

### 4. 使用 Hugging Face CLI (备选方案)
```bash
# 安装 Hugging Face CLI
pip install -U huggingface_hub[cli]

# 登录
huggingface-cli login

# 直接上传整个文件夹
huggingface-cli upload RyanWW/KeyVID /dockerx/groups/KeyVID --repo-type model
```

### 5. 分批上传策略 (对于超大仓库)
如果上传经常失败，可以分批上传：

```python
# 只上传关键文件
huggingface-cli upload RyanWW/KeyVID /dockerx/groups/KeyVID/keyframe_generation --repo-type model --include "*.ckpt"
```

### 6. 使用 Git LFS (如果文件已在 Git 中)
如果文件已经在 Git LFS 中管理，可以直接推送：

```bash
cd /dockerx/groups/KeyVID
git remote add hf https://huggingface.co/RyanWW/KeyVID
git push hf main
```

## ⚙️ 优化配置

### 调整并发数 (upload.py)
编辑 `upload.py`，修改 `MAX_WORKERS`:
```python
MAX_WORKERS = 16  # 增加并发线程数（根据网络和CPU调整）
```

### 环境变量设置
```bash
# 设置 Hugging Face token
export HF_TOKEN=your_token_here

# 设置上传超时（秒）
export HF_HUB_TIMEOUT=3600

# 禁用进度条（如果终端有问题）
export HF_HUB_DISABLE_PROGRESS=0
```

## 📊 预估上传时间

基于你的数据量 (67GB):
- **10 Mbps**: 约 15 小时
- **100 Mbps**: 约 1.5 小时  
- **1 Gbps**: 约 9 分钟

实际时间取决于：
- 网络速度
- Hugging Face 服务器负载
- 文件大小分布（大文件需要更多时间）

## 🛠️ 故障排除

### 问题1: 上传中断
```bash
# 重新运行脚本，Hugging Face 支持断点续传
python upload_fast.py
```

### 问题2: 认证失败
```bash
# 重新登录
huggingface-cli login

# 或使用 token
export HF_TOKEN=your_token
```

### 问题3: 网络超时
```bash
# 增加超时时间
export HF_HUB_TIMEOUT=7200  # 2小时
```

### 问题4: 大文件上传慢
- 确保使用 `multi_commits=True` (已在脚本中)
- 检查网络连接稳定性
- 考虑使用更快的网络环境

## 📝 检查上传状态

```bash
# 查看仓库文件
huggingface-cli repo list-files RyanWW/KeyVID

# 或访问网页
# https://huggingface.co/RyanWW/KeyVID
```

## 💡 最佳实践

1. **首次上传**: 使用 `upload_fast.py`，它针对大文件优化
2. **增量更新**: 可以直接重新运行脚本，只会上传新文件
3. **监控进度**: 脚本会显示详细进度信息
4. **保持连接**: 确保网络连接稳定，避免中断