Hugging Face 快速上手：Hub、Python 客户端与命令行工具

Hugging Face 是一个围绕机器学习模型、数据集与应用演示构建的协作平台。它的核心是 Hub：模型、数据集和 Spaces 都以仓库的形式托管在这里，每个仓库都有版本历史、文件浏览和在线预览。围绕 Hub，平台提供了一组客户端工具，让开发者可以在自己的代码、终端或网页应用里直接读写这些仓库，而不必手动下载文件再搬运。这篇教程面向第一次使用 Hugging Face 的开发者，讲清楚三件事：Hub 上的资源是怎么组织的、怎样准备账号与访问令牌、以及怎样用 Python 客户端和命令行工具完成登录、下载、上传、创建仓库这些日常操作。如果你更习惯在浏览器里操作，也可以先通过 Hugging Face 了解平台的整体结构，再回到本文按步骤动手。

准备工作

账号与访问令牌

使用 Hub 的读写能力需要一个 Hugging Face 账号。注册完成后，很多公开仓库的读取不需要登录，但涉及上传、创建仓库、访问私有仓库时，必须提供访问令牌（access token）。令牌在账号设置中生成，可以按用途区分权限范围：只读令牌适合在推理服务或 CI 中拉取模型，写入令牌用于上传与创建仓库。生成后请把令牌当作密码保管，不要提交到公开仓库里。

令牌的使用方式有两种：一是通过命令行工具登录，凭据会被保存到本地，后续命令自动读取；二是在代码里显式传入，或通过环境变量提供。前者适合本地开发，后者适合容器与自动化环境。

安装客户端库

Python 客户端库名为 huggingface_hub，它同时提供了 Python API 和命令行入口 hf。安装方式：

pip install huggingface_hub

安装完成后可以用下面的命令确认版本与可用子命令：

hf --help

如果你主要做模型推理与训练，通常还会安装 transformers、datasets、diffusers 等核心库，它们内部都依赖 huggingface_hub 来下载权重与数据。这些库各自有独立的文档，本文只围绕 Hub 的读写操作展开。

了解 Hub 上的三类仓库

Hub 上的仓库分为三种类型，客户端 API 与命令行参数里都会用到这个类型区分：

model：模型仓库，存放权重文件、配置文件、分词器文件以及模型卡（README）。
dataset：数据集仓库，存放数据文件与数据集卡。Hub 提供数据集查看器，可以读取数据集的元数据、统计信息和内容预览。
space：应用仓库，通常是一个 Gradio 或其它框架搭建的演示应用，推送代码后平台会自动构建并运行。

每个仓库由「用户名或组织名 / 仓库名」唯一标识，例如 username/my-model。仓库名在同一个所有者下必须唯一。仓库可以是公开的，也可以是私有的；私有仓库只有所有者与受邀协作者能访问。

操作步骤

第一步：登录并保存凭据

在终端执行登录命令，按提示粘贴访问令牌：

hf auth login

登录成功后，凭据会写入本地配置目录，后续的下载、上传命令会自动使用它。需要确认当前登录的是哪个账号时：

hf auth whoami

在多人共用的机器或临时环境里，用完可以退出登录：

hf auth logout

如果不想在磁盘上留下凭据，可以跳过登录，改为在运行时通过环境变量提供令牌，Python 客户端会自动读取。这种方式在容器和流水线里更常见。

第二步：在代码中初始化客户端

Python 里最常用的入口是 HfApi，它封装了仓库管理、文件上传下载、搜索等操作。最小初始化方式：

from huggingface_hub import HfApi

api = HfApi()

如果本地没有登录，或者想显式指定令牌，可以在构造时传入：

from huggingface_hub import HfApi

api = HfApi(token="hf_xxxxxxxxxxxxxxxxxxxx")

初始化之后可以先验证身份，确认令牌有效：

who = api.whoami()
print(who["name"])

返回结果里包含当前账号的名称、所属组织等信息，可以用来在脚本里做前置检查。

第三步：创建仓库

用 create_repo 创建仓库，需要指定仓库标识与类型：

api.create_repo(repo_id="my-username/my-first-model", repo_type="model")

常用参数包括：

repo_id：形如 用户名/仓库名 的完整标识。
repo_type：model、dataset 或 space。
private：设为 True 时创建私有仓库。
exist_ok：设为 True 时，仓库已存在不会报错，适合放在可重复执行的脚本里。

命令行等价操作：

hf repo create my-username/my-first-model --repo-type model

创建 Space 时还需要指定所用的 SDK，具体可选值以平台当前支持为准。

第四步：上传文件

单个文件上传用 upload_file：

api.upload_file(
    path_or_fileobj="local/config.json",
    path_in_repo="config.json",
    repo_id="my-username/my-first-model",
    repo_type="model",
)

这里有两个路径需要区分：path_or_fileobj 是本地文件路径或文件对象，path_in_repo 是文件在仓库中的目标路径。两者可以不同，例如把本地的 local/config.json 放到仓库根目录的 config.json。

整个目录上传用 upload_folder：

api.upload_folder(
    folder_path="./my-model",
    repo_id="my-username/my-first-model",
    repo_type="model",
)

目录上传时可以用 allow_patterns 与 ignore_patterns 控制包含与排除的文件，避免把日志、缓存、临时文件一起推上去。大文件会被自动处理为适合 Hub 存储的形式，不需要手动切分。

命令行等价操作：

hf upload my-username/my-first-model ./my-model

上传单个文件时把路径指向文件即可。命令还支持指定仓库类型、提交说明等参数。

第五步：下载文件与仓库

下载单个文件用 hf_hub_download，它返回本地缓存路径：

from huggingface_hub import hf_hub_download

path = hf_hub_download(
    repo_id="my-username/my-first-model",
    filename="config.json",
)
print(path)

下载整个仓库快照用 snapshot_download：

from huggingface_hub import snapshot_download

local_dir = snapshot_download(
    repo_id="my-username/my-first-model",
    repo_type="model",
)
print(local_dir)

同样可以用 allow_patterns 与 ignore_patterns 只取需要的文件。对于包含多个权重分片的大模型，只下载配置文件与分词器文件、跳过权重，是常见的做法。

命令行等价操作：

hf download my-username/my-first-model --local-dir ./my-model

下载行为默认走本地缓存：同一个文件第二次请求时不会重复传输。缓存目录的位置可以通过环境变量调整，在磁盘空间紧张的环境里值得提前规划。

第六步：浏览与搜索 Hub

在写代码之前，往往需要先找到合适的模型或数据集。HfApi 提供了列表与搜索方法：

models = api.list_models(search="text-generation", limit=5)
for m in models:
    print(m.id)

列表方法支持按任务、库、作者等条件过滤，也支持排序与分页。数据集与 Spaces 有对应的列表方法。命令行也可以直接搜索：

hf models list --search text-generation

找到目标仓库后，可以用仓库信息方法读取它的元数据，例如文件列表、标签、下载量等，用来在脚本里做选择判断。

第七步：管理仓库与文件

日常维护还会用到这些操作：

删除仓库中的某个文件：使用删除文件的方法，指定仓库标识与仓库内路径。
删除整个仓库：使用删除仓库的方法，指定仓库标识与类型。这个操作不可撤销，执行前确认清楚。
更新仓库可见性：把公开仓库改为私有，或反过来，通过仓库设置方法完成。
查看提交历史：仓库的每次上传都会形成一次提交，可以读取提交列表来追踪变更。

这些操作在命令行里也有对应子命令，具体参数可以用 hf --help 逐层查看。

一个完整示例

下面从一个空目录开始，走完「创建仓库 → 上传文件 → 下载验证」的完整流程。假设你已经完成登录，账号名为 my-username。

准备本地文件

mkdir -p demo-repo
cd demo-repo
printf '{"model_type": "demo"}\n' > config.json
printf '# Demo Model\n\nThis is a demo repository.\n' > README.md

这里准备了两个文件：一个配置文件和一个模型卡。模型卡就是仓库根目录的 README，平台会在仓库页面上渲染它。

创建仓库并上传

from huggingface_hub import HfApi

api = HfApi()
repo_id = "my-username/demo-repo"

api.create_repo(repo_id=repo_id, repo_type="model", exist_ok=True)

api.upload_folder(
    folder_path="./demo-repo",
    repo_id=repo_id,
    repo_type="model",
    commit_message="add config and model card",
)

exist_ok=True 让这段脚本可以重复执行：第一次创建仓库，之后直接上传新版本。

下载并校验

from huggingface_hub import snapshot_download

local_dir = snapshot_download(
    repo_id="my-username/demo-repo",
    repo_type="model",
    local_dir="./downloaded",
)
print(local_dir)

执行后检查 ./downloaded 目录，应当能看到 config.json 与 README.md。如果文件缺失，先确认上传时 folder_path 指向的目录是否正确，再看仓库页面的文件列表是否已经出现这些文件。

用命令行完成同样的流程

hf repo create my-username/demo-repo --repo-type model
hf upload my-username/demo-repo ./demo-repo
hf download my-username/demo-repo --local-dir ./downloaded

三条命令分别对应创建、上传、下载。命令行适合在脚本与 CI 里使用，Python API 适合嵌进训练或推理代码中。

注意事项

令牌权限最小化：只读场景不要使用写入令牌。令牌泄露后应立即在账号设置中撤销并重新生成。
不要把令牌写进代码：提交到公开仓库的令牌会被视为已泄露。用环境变量或本地登录凭据来提供。
仓库名与所有者：仓库标识由所有者与仓库名组成，创建前确认所有者是个人账号还是组织账号，两者不能混用。
缓存占用磁盘：下载默认写入本地缓存，反复下载大模型会持续占用空间。定期清理不再使用的缓存，或在下载时指定目标目录。
删除不可撤销：删除仓库或文件的操作没有回收站，执行前确认目标。
私有仓库的访问：私有仓库需要令牌才能读取，在推理服务或协作者环境中要单独配置凭据。
配额与限制：仓库大小、上传频率、Spaces 的运行资源等都有平台侧的限制，具体数值与当前政策以官网信息为准。
Space 的构建：推送 Space 代码后平台会自动构建，构建失败时应用不会启动，需要查看构建日志定位问题。

掌握以上流程后，Hub 上的模型、数据集与 Spaces 都可以用同一套客户端接口来读写。后续无论是把训练好的权重推上去，还是在推理服务里按需拉取文件，操作方式都是一致的。

全部分类

准备工作

账号与访问令牌

安装客户端库

了解 Hub 上的三类仓库

操作步骤

第一步：登录并保存凭据

第二步：在代码中初始化客户端

第三步：创建仓库

第四步：上传文件

第五步：下载文件与仓库

第六步：浏览与搜索 Hub

第七步：管理仓库与文件

一个完整示例

准备本地文件

创建仓库并上传

下载并校验

用命令行完成同样的流程

注意事项