Emotion Summary 模型上传到 Hugging Face 指南

📦 文件清单

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

必需文件（9个）：

config.json (1.93 KB)
- 模型配置文件
- 定义模型架构和参数
generation_config.json (188 Bytes)
- 生成配置文件
- 定义文本生成参数（beam search等）
model.safetensors (1,145.1 MB = 1.12 GB)
- 模型权重文件
- 使用SafeTensors格式存储
- ⚠️ 需要Git LFS上传
special_tokens_map.json (280 Bytes)
- 特殊token映射
- 定义[PAD], [CLS], [SEP]等特殊标记
spiece.model (4.11 MB)
- SentencePiece词表模型
- mT5使用的分词器
tokenizer.json (15.59 MB)
- Tokenizer配置
- 包含词表和分词规则
tokenizer_config.json (20 KB)
- Tokenizer配置参数
- 定义分词器的行为
README.md
- 模型卡片（Model Card）
- 描述模型用途、性能、使用方法
.gitattributes
- Git LFS配置
- 标记大文件使用LFS上传
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 界面上传（推荐）

登录 Hugging Face
- 访问：https://huggingface.co
- 登录您的账号
创建新模型仓库
- 点击右上角头像 → "New Model"
- 填写信息：
  - Model name: emotion-summary-mt5
  - License: MIT
  - 勾选 "Public" 或 "Private"
上传文件
- 进入模型页面
- 点击 "Files and versions" 标签
- 点击 "Add file" → "Upload files"
- 拖拽或选择本文件夹中的所有文件
- ⚠️ 重要：确保上传 .gitattributes 文件在上传其他文件之前！
等待处理
- 大文件会自动使用 Git LFS
- model.safetensors (1.1GB) 需要较长时间

方法2：使用命令行 + Git

# 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 库

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：

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

设置token：

# 方式1：使用 huggingface-cli
huggingface-cli login

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

⚠️ 注意事项

Git LFS 必需
- model.safetensors 文件很大 (1.1GB)
- 必须使用 Git LFS 上传
- .gitattributes 文件已配置好
上传顺序
- 先上传 .gitattributes
- 再上传其他所有文件
网络要求
- 上传 1.1GB 文件需要稳定网络
- 建议使用有线连接
- 预计时间：10-30分钟（取决于网速）
仓库设置
- 建议设置为 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" 中看到所有文件

🎯 测试模型

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

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

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