emotion summary/UPLOAD_GUIDE.md

# Emotion Summary 模型上传到 Hugging Face 指南

## 📦 文件清单

此文件夹包含上传到 Hugging Face 所需的所有文件：

### 必需文件（9个）：

1. **config.json** (1.93 KB)
   - 模型配置文件
   - 定义模型架构和参数

2. **generation_config.json** (188 Bytes)
   - 生成配置文件
   - 定义文本生成参数（beam search等）

3. **model.safetensors** (1,145.1 MB = 1.12 GB)
   - 模型权重文件
   - 使用SafeTensors格式存储
   - ⚠️ 需要Git LFS上传

4. **special_tokens_map.json** (280 Bytes)
   - 特殊token映射
   - 定义[PAD], [CLS], [SEP]等特殊标记

5. **spiece.model** (4.11 MB)
   - SentencePiece词表模型
   - mT5使用的分词器

6. **tokenizer.json** (15.59 MB)
   - Tokenizer配置
   - 包含词表和分词规则

7. **tokenizer_config.json** (20 KB)
   - Tokenizer配置参数
   - 定义分词器的行为

8. **README.md**
   - 模型卡片（Model Card）
   - 描述模型用途、性能、使用方法

9. **.gitattributes**
   - Git LFS配置
   - 标记大文件使用LFS上传

10. **inference_example.py**
    - 推理示例代码
    - 展示如何使用模型

---

## 📊 文件大小统计

| 文件名 | 大小 | 类型 |
|--------|------|------|
| model.safetensors | 1,145.1 MB | 模型权重 |
| tokenizer.json | 15.59 MB | Tokenizer |
| spiece.model | 4.11 MB | 词表 |
| tokenizer_config.json | 20 KB | 配置 |
| config.json | ~2 KB | 配置 |
| README.md | ~3 KB | 文档 |
| 其他JSON文件 | < 1 KB | 配置 |
| **总计** | **~1.16 GB** | - |

---

## 🚀 上传到 Hugging Face 的步骤

### 方法1：使用 Web 界面上传（推荐）

1. **登录 Hugging Face**
   - 访问：https://huggingface.co
   - 登录您的账号

2. **创建新模型仓库**
   - 点击右上角头像 → "New Model"
   - 填写信息：
     - Model name: `emotion-summary-mt5`
     - License: MIT
     - 勾选 "Public" 或 "Private"

3. **上传文件**
   - 进入模型页面
   - 点击 "Files and versions" 标签
   - 点击 "Add file" → "Upload files"
   - 拖拽或选择本文件夹中的所有文件
   - ⚠️ **重要**：确保上传 `.gitattributes` 文件在上传其他文件之前！

4. **等待处理**
   - 大文件会自动使用 Git LFS
   - model.safetensors (1.1GB) 需要较长时间

### 方法2：使用命令行 + Git

```bash
# 1. 安装 Git LFS（如果还没安装）
git lfs install

# 2. 克隆你的模型仓库
git clone https://huggingface.co/<your-username>/emotion-summary-mt5
cd emotion-summary-mt5

# 3. 复制所有文件到仓库
cp ../emotion_summary_huggingface/* .

# 4. 添加所有文件
git add .

# 5. 提交
git commit -m "Upload emotion summary model"

# 6. 推送（需要 Hugging Face token）
git push
```

### 方法3：使用 huggingface_hub 库

```python
from huggingface_hub import HfApi, create_repo

# 创建API对象
api = HfApi()

# 创建仓库
repo_id = "your-username/emotion-summary-mt5"
create_repo(repo_id, repo_type="model", exist_ok=True)

# 上传整个文件夹
api.upload_folder(
    folder_path="./emotion_summary_huggingface",
    repo_id=repo_id,
    repo_type="model"
)

print(f"✓ Model uploaded to https://huggingface.co/{repo_id}")
```

---

## 🔑 获取 Hugging Face Token

如果使用命令行或Python上传，需要访问token：

1. 访问：https://huggingface.co/settings/tokens
2. 点击 "New token"
3. 给token命名（如 "upload-models"）
4. 选择权限：**Write** 
5. 复制token并保存

**设置token：**
```bash
# 方式1：使用 huggingface-cli
huggingface-cli login

# 方式2：设置环境变量
export HF_TOKEN="your_token_here"
```

---

## ⚠️ 注意事项

1. **Git LFS 必需**
   - model.safetensors 文件很大 (1.1GB)
   - 必须使用 Git LFS 上传
   - `.gitattributes` 文件已配置好

2. **上传顺序**
   - 先上传 `.gitattributes`
   - 再上传其他所有文件

3. **网络要求**
   - 上传 1.1GB 文件需要稳定网络
   - 建议使用有线连接
   - 预计时间：10-30分钟（取决于网速）

4. **仓库设置**
   - 建议设置为 Public 以便团队使用
   - 添加适当的 tags（如：mt5, emotion-analysis, chinese）

---

## 📝 模型信息

- **模型名称**: Emotion Summary Model
- **基础模型**: google/mt5-small
- **任务类型**: Text2Text Generation
- **语言**: Chinese (中文)
- **用途**: 从心理咨询案例中提取情感信息
- **训练数据**: 8,000条心理咨询对话
- **模型大小**: ~1.2 GB

---

## ✅ 验证上传成功

上传完成后，访问您的模型页面：
```
https://huggingface.co/<your-username>/emotion-summary-mt5
```

检查：
- ✓ 所有10个文件都存在
- ✓ model.safetensors 显示为 LFS 文件
- ✓ README.md 正确显示
- ✓ 可以在 "Files and versions" 中看到所有文件

---

## 🎯 测试模型

上传成功后，可以使用以下代码测试：

```python
from transformers import MT5ForConditionalGeneration, MT5Tokenizer

# 从 Hugging Face 加载
model_name = "your-username/emotion-summary-mt5"
model = MT5ForConditionalGeneration.from_pretrained(model_name)
tokenizer = MT5Tokenizer.from_pretrained(model_name)

# 测试推理
input_text = "Extract cause from: ..."
inputs = tokenizer(input_text, return_tensors="pt", max_length=512, truncation=True)
outputs = model.generate(**inputs, max_length=256, num_beams=4)
result = tokenizer.decode(outputs[0], skip_special_tokens=True)
print(result)
```

---

## 📞 问题排查

### 问题1：上传失败 "file too large"
**解决方案**：确保安装并启用了 Git LFS
```bash
git lfs install
git lfs track "*.safetensors"
```

### 问题2：权限错误
**解决方案**：检查 Hugging Face token 是否有 Write 权限

### 问题3：上传中断
**解决方案**：Git 会自动续传，只需重新运行 `git push`

---

## 📚 相关文档

- Hugging Face 上传指南：https://huggingface.co/docs/hub/models-uploading
- Git LFS 文档：https://git-lfs.github.com/
- mT5 模型：https://huggingface.co/docs/transformers/model_doc/mt5

---

创建日期：2025-10-31
模型版本：v1.0