上传模型/数据集到huggingface

文章目录

上传模型/数据集到huggingface
- 一、环境准备：安装依赖
- - [1. 安装 huggingface-hub（包含 cli 工具）](#1. 安装 huggingface-hub（包含 cli 工具）)
  - [2. 验证安装成功（查看版本）](#2. 验证安装成功（查看版本）)
- [二、登录 Hugging Face（核心步骤）](#二、登录 Hugging Face（核心步骤）)
- - 方式1：交互式登录（推荐）
  - [方式2：直接传入 token（适合脚本/服务器）](#方式2：直接传入 token（适合脚本/服务器）)
- [三、下载数据（huggingface-cli download）](#三、下载数据（huggingface-cli download）)
- [四、上传数据（huggingface-cli upload）](#四、上传数据（huggingface-cli upload）)
- 五、常用进阶参数
- 总结

一、环境准备：安装依赖

首先需要安装 huggingface-hub 包（huggingface-cli 是这个包的内置工具），建议在虚拟环境中操作：

bash

运行

1. 安装 huggingface-hub（包含 cli 工具）

bash 复制代码

pip install huggingface-hub

2. 验证安装成功（查看版本）

bash 复制代码

huggingface-cli --version

或者

bash 复制代码

pip show huggingface-hub

如果安装后提示 huggingface-cli: command not found，可能是 Python 的 Scripts/bin 目录未加入系统环境变量，可改用 python -m huggingface_hub.cli 替代 huggingface-cli（下文所有 huggingface-cli 均可替换）。

二、登录 Hugging Face（核心步骤）

上传 / 下载私有数据或修改自己的仓库，必须先登录认证：

方式1：交互式登录（推荐）

bash 复制代码

huggingface-cli login

方式2：直接传入 token（适合脚本/服务器）

bash 复制代码

huggingface-cli login --token your_hf_token

执行后按提示操作：

访问 Hugging Face 个人主页 → Settings → Access Tokens → 生成 token（至少勾选 write 权限用于上传）；

复制 token 粘贴到终端（输入时无显示，粘贴后回车即可）；

提示 Login successful 即完成认证。

三、下载数据（huggingface-cli download）

支持下载整个仓库、指定文件 / 文件夹，核心语法：

bash 复制代码

huggingface-cli download [仓库名] [文件/文件夹路径] --local-dir [本地保存路径]

示例 1：下载整个公开仓库

bash 复制代码

# 下载 huggingface.co/datasets/imdb 仓库到本地 ./imdb 目录
huggingface-cli download datasets/imdb --local-dir ./imdb

示例 2：下载指定文件 / 文件夹

bash 复制代码

# 仅下载仓库中 data/train 文件夹
huggingface-cli download datasets/imdb data/train --local-dir ./imdb_train
# 仅下载单个文件（如 test.json）
huggingface-cli download your-username/your-dataset test.json --local-dir ./my_data

示例 3：下载私有仓库

只要你有权限（自己的仓库 / 协作仓库），登录后直接下载即可，无需额外参数：

bash 复制代码

huggingface-cli download your-username/private-dataset --local-dir ./private_data

四、上传数据（huggingface-cli upload）

上传本地文件到 Hugging Face Hub（仓库需先在网页端创建，或用 cli 创建），核心语法：

bash 复制代码

huggingface-cli upload [仓库名] [本地文件/文件夹路径] [仓库内目标路径]

前置：创建仓库（可选，网页 / CLI 均可）

如果还没有仓库，可先在 Hugging Face 网页端（https://huggingface.co/new）创建，或用 CLI 创建：

bash 复制代码

# 创建公开仓库（--private 可选私有）
huggingface-cli repo create my-first-dataset --type dataset

示例 1：上传单个文件

bash 复制代码

# 上传本地 ./data/train.csv 到仓库 your-username/my-first-dataset 的根目录
huggingface-cli upload your-username/my-first-dataset ./data/train.csv .

示例 2：上传整个文件夹

bash 复制代码

# 上传本地 ./my_data 文件夹到仓库的 data 目录下
huggingface-cli upload your-username/my-first-dataset ./my_data data/

示例 3：覆盖已有文件 + 显示上传进度

bash 复制代码

# --force 覆盖仓库中同名文件，--verbose 显示详细进度
huggingface-cli upload your-username/my-first-dataset ./new_train.csv . --force --verbose

五、常用进阶参数

表格

参数	作用	示例
--local-dir-use-symlinks	用软链接代替复制文件（节省空间）	--local-dir-use-symlinks auto
--revision	指定分支 / 版本（如 main、v1.0）	--revision v1.0
--exclude	排除指定文件（如 .gitignore）	--exclude "*.tmp"
--delete	上传时删除仓库中本地不存在的文件（谨慎使用）	--delete

总结

核心流程：pip install huggingface-hub → huggingface-cli login → 下载（download）/ 上传（upload）；

关键命令：

下载：huggingface-cli download 仓库名路径 --local-dir 本地路径；

上传：huggingface-cli upload 仓库名本地路径仓库路径；

注意事项：上传前需确保仓库已创建，token 至少有 write 权限，私有仓库需登录后操作。