fix_upload_issues.md

# 🔧 Hugging Face上传问题解决方案

## ❌ 遇到的错误

```
403 Forbidden: Forbidden: pass `create_pr=1` as a query parameter to create a Pull Request.
Cannot access content at: https://huggingface.co/api/models/Wangchuk1376/ThangkaModels
Make sure your token has the correct permissions.
```

## 🎯 问题原因

1. **仓库不存在** - 需要先在Hugging Face创建仓库
2. **Token权限不足** - 需要确保Token有写入权限

## ✅ 解决步骤

### 步骤1: 在Hugging Face创建仓库

1. 访问 https://huggingface.co/new
2. 填写信息:
   - **Owner**: `Wangchuk1376`
   - **Model name**: `ThangkaModels`
   - **License**: `mit`
   - **Visibility**: `Public` (推荐)
3. 点击 **Create model**

### 步骤2: 检查Token权限

1. 访问 https://huggingface.co/settings/tokens
2. 找到您正在使用的Token
3. 确保权限是 **Write** (不是Read)
4. 如果不是，创建一个新的Write权限Token:
   - 点击 **New token**
   - Name: `thangka-upload`
   - Role: **Write**
   - 点击 **Generate a token**
   - **复制Token并保存**

### 步骤3: 重新登录

```bash
# 登出
hf auth logout

# 重新登录，使用新的Write权限Token
hf auth login
# 粘贴您的新Token
```

### 步骤4: 使用正确的上传命令

```bash
cd "/Users/xiang/SCU/Xiang/Thangka/Paddle 3/Thangka/thangka1376"

# 方式1: 上传整个目录 (推荐先创建仓库后使用)
hf upload Wangchuk1376/ThangkaModels . --repo-type model

# 方式2: 先上传小文件测试
hf upload Wangchuk1376/ThangkaModels README.md --repo-type model

# 方式3: 分批上传models目录
hf upload Wangchuk1376/ThangkaModels models/ --repo-type model
```

**注意**: `--num-workers`参数CLI不支持，这是Python API的参数。

### 步骤5: 如果文件夹太大，使用大文件夹上传

```bash
hf upload-large-folder Wangchuk1376/ThangkaModels . --repo-type model
```

## 🐍 使用Python脚本上传 (推荐)

创建 `upload_models.py`:

```python
from huggingface_hub import HfApi, create_repo
import os

# 初始化API
api = HfApi()

# 仓库信息
repo_id = "Wangchuk1376/ThangkaModels"
local_dir = "/Users/xiang/SCU/Xiang/Thangka/Paddle 3/Thangka/thangka1376"

print("🚀 开始上传唐卡模型...")

# 步骤1: 创建仓库 (如果不存在)
try:
    create_repo(
        repo_id=repo_id,
        repo_type="model",
        exist_ok=True,
        private=False
    )
    print(f"✅ 仓库 {repo_id} 已创建/验证")
except Exception as e:
    print(f"⚠️ 创建仓库: {e}")

# 步骤2: 上传README
print("\n📝 上传README...")
try:
    api.upload_file(
        path_or_fileobj=os.path.join(local_dir, "README.md"),
        path_in_repo="README.md",
        repo_id=repo_id,
        repo_type="model"
    )
    print("✅ README.md 上传成功")
except Exception as e:
    print(f"❌ README上传失败: {e}")

# 步骤3: 上传.gitattributes
print("\n📝 上传.gitattributes...")
gitattributes_content = """*.safetensors filter=lfs diff=lfs merge=lfs -text
*.pdparams filter=lfs diff=lfs merge=lfs -text
*.bin filter=lfs diff=lfs merge=lfs -text
"""

try:
    api.upload_file(
        path_or_fileobj=gitattributes_content.encode(),
        path_in_repo=".gitattributes",
        repo_id=repo_id,
        repo_type="model"
    )
    print("✅ .gitattributes 上传成功")
except Exception as e:
    print(f"❌ .gitattributes上传失败: {e}")

# 步骤4: 上传整个文件夹
print("\n📤 上传models目录 (这可能需要较长时间)...")
try:
    api.upload_folder(
        folder_path=local_dir,
        repo_id=repo_id,
        repo_type="model",
        ignore_patterns=[
            ".DS_Store",
            "*.pyc",
            "__pycache__",
            "*.sh",
            "*.py",
            "fix_upload_issues.md"
        ],
        multi_commits=True,  # 大文件夹分批上传
        multi_commits_verbose=True
    )
    print("✅ 所有文件上传成功!")
except Exception as e:
    print(f"❌ 上传失败: {e}")
    print("\n💡 提示: 如果是大文件问题，可以尝试:")
    print("   1. 分批上传小文件")
    print("   2. 使用Git LFS")
    print("   3. 联系Hugging Face支持")

print("\n🎉 完成!")
print(f"🌐 访问您的模型: https://huggingface.co/{repo_id}")
```

运行脚本:

```bash
cd "/Users/xiang/SCU/Xiang/Thangka/Paddle 3/Thangka/thangka1376"
python upload_models.py
```

## 📋 完整上传流程

### 选项A: 通过Web界面创建 + CLI上传

```bash
# 1. 先在Web创建仓库
#    https://huggingface.co/new

# 2. 重新登录CLI
hf auth logout
hf auth login

# 3. 测试上传README
hf upload Wangchuk1376/ThangkaModels README.md --repo-type model

# 4. 如果成功，上传全部
hf upload Wangchuk1376/ThangkaModels . --repo-type model
```

### 选项B: 使用Python脚本 (最稳定)

```bash
# 运行上面的Python脚本
python upload_models.py
```

### 选项C: 使用Git LFS (适合超大文件)

```bash
# 1. 安装Git LFS
brew install git-lfs
git lfs install

# 2. 克隆仓库 (先在Web创建)
git clone https://huggingface.co/Wangchuk1376/ThangkaModels
cd ThangkaModels

# 3. 配置LFS
git lfs track "*.safetensors"
git lfs track "*.pdparams"
git add .gitattributes

# 4. 复制文件
cp -r "/Users/xiang/SCU/Xiang/Thangka/Paddle 3/Thangka/thangka1376/"* .

# 5. 提交并推送
git add .
git commit -m "Initial upload of Thangka models"
git push
```

## 🔍 故障排查

### 错误1: 403 Forbidden

**原因**: 仓库不存在或Token权限不足

**解决**:
1. 先在 https://huggingface.co/new 创建仓库
2. 确保Token有Write权限
3. 重新登录: `hf auth login`

### 错误2: 文件太大

**原因**: 单次上传文件太多

**解决**:
```bash
# 使用大文件夹上传命令
hf upload-large-folder Wangchuk1376/ThangkaModels . --repo-type model

# 或分批上传
hf upload Wangchuk1376/ThangkaModels README.md --repo-type model
hf upload Wangchuk1376/ThangkaModels models/finetuned/ --repo-type model
hf upload Wangchuk1376/ThangkaModels models/sd2.1_base_paddle/ --repo-type model
```

### 错误3: Network timeout

**原因**: 网络不稳定

**解决**:
1. 使用VPN或更稳定的网络
2. 分批上传小文件
3. 使用Python脚本的`multi_commits=True`选项

## 💡 最佳实践

1. **先创建仓库**: 在Web界面手动创建
2. **测试小文件**: 先上传README测试
3. **分批上传**: 大文件分多次上传
4. **使用Python**: Python API更稳定可靠
5. **耐心等待**: 大文件上传需要时间

## 📞 需要帮助?

如果问题仍未解决:

1. 检查网络连接
2. 检查Token是否有效
3. 查看Hugging Face状态页: https://status.huggingface.co/
4. 联系Hugging Face支持: https://huggingface.co/support