HuggingFace CLI 命令全面指南

文章目录

安装与认证

1.1 安装 HuggingFace Hub 库

在使用 HuggingFace CLI 命令之前，首先需要安装 HuggingFace Hub 库。以下是详细的安装步骤：

使用 pip 安装

pip install huggingface_hub 

使用 conda 安装

conda install -c huggingface huggingface_hub 

验证安装

安装完成后，可以通过以下命令验证是否安装成功：

huggingface-cli --help 

如果显示，则说明安装成功。

1.2 认证与登录

在使用 HuggingFace CLI 命令进行操作之前，需要进行认证。以下是详细的认证步骤：

生成访问令牌

1. 访问 。
2. 登录你的账户。
3. 进入 Settings -> Access Tokens。
4. 点击 New Token，生成一个新的访问令牌。

使用访问令牌登录

在终端中运行以下命令，使用生成的访问令牌进行登录：

huggingface-cli login 

输入访问令牌后，系统会提示登录成功。

环境变量认证

你也可以通过设置环境变量来进行认证：

export HUGGINGFACE_TOKEN=your_access_token 

将 your_access_token 替换为你生成的访问令牌。

验证认证

认证完成后，可以通过以下命令验证是否认证成功：

huggingface-cli whoami 

如果显示你的用户信息，则说明认证成功。

通过以上步骤，你已经成功安装并认证了 HuggingFace Hub 库，可以开始使用 HuggingFace CLI 命令进行各种操作。

下载文件

2.1 下载单个文件

在使用 HuggingFace CLI 下载单个文件时，您需要确保已经安装了 huggingface_hub 库，并且已经通过认证。以下是详细的步骤：

安装 huggingface_hub 库

首先，确保您已经安装了 huggingface_hub 库。您可以使用以下命令进行安装：

$ python -m pip install huggingface_hub 

安装过程中可能会遇到一些依赖项，如 filelock、fsspec、requests 等，这些依赖项会自动安装。

认证与登录

在使用 HuggingFace CLI 下载文件之前，您需要进行认证。您可以使用以下命令进行登录：

$ huggingface-cli login 

系统会提示您输入访问令牌。您可以在 HuggingFace 网站上生成一个访问令牌，并将其粘贴到命令行中。

下载单个文件

一旦您完成了认证，就可以使用以下命令下载单个文件：

$ huggingface-cli download <repo_id> <filename> 

其中，<repo_id> 是仓库的 ID，<filename> 是您要下载的文件名。例如，如果您想下载 bert-base-uncased 模型中的 config.json 文件，可以使用以下命令：

$ huggingface-cli download bert-base-uncased config.json 

该命令会将 config.json 文件下载到当前目录。

2.2 下载特定版本的文件

有时候，您可能需要下载特定版本的文件。HuggingFace CLI 提供了下载特定版本文件的功能。以下是详细的步骤：

下载特定版本的文件

要下载特定版本的文件，您需要在命令中指定版本号。例如，如果您想下载 bert-base-uncased 模型中版本号为 1.0.0 的 config.json 文件，可以使用以下命令：

$ huggingface-cli download bert-base-uncased config.json --revision 1.0.0 

该命令会将版本号为 1.0.0 的 config.json 文件下载到当前目录。

指定下载路径

您还可以指定下载路径。例如，如果您想将文件下载到 /path/to/download 目录，可以使用以下命令：

$ huggingface-cli download bert-base-uncased config.json --revision 1.0.0 --local-dir /path/to/download 

该命令会将版本号为 1.0.0 的 config.json 文件下载到 /path/to/download 目录。

通过以上步骤，您可以轻松地使用 HuggingFace CLI 下载单个文件和特定版本的文件。

创建与管理仓库

3.1 创建仓库

在使用 HuggingFace Hub 进行模型和数据集的管理时，首先需要创建一个仓库。以下是创建仓库的详细步骤：

3.1.1 使用 CLI 创建仓库

安装 HuggingFace CLI：
确保你已经安装了 huggingface_hub 库。如果没有安装，可以使用以下命令进行安装：

pip install huggingface_hub 

登录 HuggingFace 账号：
在使用 CLI 创建仓库之前，需要先登录你的 HuggingFace 账号。可以使用以下命令进行登录：

huggingface-cli login 

这将提示你输入 HuggingFace 的访问令牌。

创建新仓库：
使用 huggingface-cli 创建新仓库的命令如下：

huggingface-cli repo create <repo_name> 

其中 <repo_name> 是你想要创建的仓库名称。例如，创建一个名为 my-first-repo 的仓库：

huggingface-cli repo create my-first-repo 

验证仓库创建：
创建成功后，你可以在 HuggingFace Hub 的网页上查看新创建的仓库。

3.1.2 使用网页创建仓库

登录 HuggingFace Hub：
访问  并登录你的账号。

创建新仓库：
在网页右上角点击“New”按钮，选择“New repository”，然后按照提示输入仓库名称和其他相关信息，最后点击“Create repository”按钮。

3.2 上传文件

创建仓库后，下一步是将文件上传到仓库中。以下是上传文件的详细步骤：

3.2.1 使用 CLI 上传文件

初始化本地仓库：
在本地创建一个目录，并初始化为 Git 仓库：

mkdir my-first-repo cd my-first-repo git init 

添加文件：
将需要上传的文件添加到本地仓库目录中。

添加远程仓库：
将本地仓库与 HuggingFace Hub 上的远程仓库关联：

git remote add origin https://huggingface.co/<username>/<repo_name> 

其中 <username> 是你的 HuggingFace 用户名，<repo_name> 是仓库名称。

上传文件：
使用以下命令将文件上传到远程仓库：

git add . git commit -m "Initial commit" git push -u origin master 

3.2.2 使用网页上传文件

访问仓库页面：
在 HuggingFace Hub 上访问你创建的仓库页面。

上传文件：
在仓库页面中，点击“Add file”按钮，选择“Upload files”，然后按照提示上传文件。

通过以上步骤，你可以轻松地在 HuggingFace Hub 上创建和管理仓库，并上传文件。

高级操作

4.1 环境变量设置

在使用 HuggingFace CLI 进行高级操作时，环境变量的设置是一个关键步骤。通过设置环境变量，可以实现自定义下载路径、多线程下载、配置代理等功能。以下是一些常用的环境变量及其设置方法：

设置自定义下载路径

通过设置 HF_HOME 环境变量，可以指定 HuggingFace 工具链的缓存目录。默认情况下，缓存目录位于 ~/.cache/huggingface。

export HF_HOME="/path/to/your/custom/cache" 

设置镜像站

通过设置 HF_ENDPOINT 环境变量，可以使用 HuggingFace 的镜像站来加速下载。

export HF_ENDPOINT="https://hf-mirror.com" 

启用多线程下载

通过设置 HF_HUB_ENABLE_HF_TRANSFER 环境变量，可以启用 HuggingFace 的多线程下载模块 hf_transfer。

export HF_HUB_ENABLE_HF_TRANSFER=1 

设置代理

通过设置 HTTP_PROXY 和 HTTPS_PROXY 环境变量，可以配置代理服务器来加速或绕过网络限制。

export HTTP_PROXY="http://localhost:7890" export HTTPS_PROXY="http://localhost:7890" 

4.2 认证方法参数

在使用 HuggingFace CLI 进行操作时，认证是一个必不可少的步骤。以下是一些常用的认证方法参数及其使用示例：

使用 Access Token 进行认证

通过 --token 参数，可以在命令行中使用 Access Token 进行认证。

huggingface-cli download --token hf_*** --resume-download bigscience/bloom-560m --local-dir bloom-560m 

在 Python 中进行认证

在 Python 脚本中，可以使用 huggingface_hub 库的 login 方法进行认证。

from huggingface_hub import login login("hf_***") 

设置环境变量进行认证

通过设置 HUGGINGFACE_TOKEN 环境变量，可以在不显式传递 token 的情况下进行认证。

export HUGGINGFACE_TOKEN="hf_***" 

使用 Git 进行认证

通过在 Git 命令中使用 token，可以实现对私有仓库的克隆和操作。

git clone https://<hf_username>:<hf_token>@huggingface.co/meta-llama/Llama-2-7b-chat-hf 

通过以上环境变量设置和认证方法参数的使用，可以大大提高使用 HuggingFace CLI 的灵活性和效率。

常见问题与解决方案

在使用 HuggingFace CLI 命令与 HuggingFace Hub 进行交互的过程中，用户可能会遇到一些常见问题。本文将详细介绍这些问题及其解决方案，帮助用户顺利进行操作。

5.1 Huggingface-cli 命令未找到

在使用 HuggingFace CLI 命令时，有时会遇到“命令未找到”的错误。这通常是由于 HuggingFace CLI 工具未正确安装或未添加到系统路径中。以下是解决此问题的步骤：

检查安装：
首先，确保你已经安装了 huggingface_hub 库。你可以通过以下命令进行检查：

pip show huggingface_hub 

如果未安装，可以使用以下命令进行安装：

pip install --upgrade huggingface_hub 

添加到系统路径：
如果你已经安装了 huggingface_hub 库，但仍然无法找到 huggingface-cli 命令，可能是因为该命令未添加到系统路径中。你可以通过以下步骤手动添加：

• 找到 huggingface-cli 命令的位置。通常在 Python 的 Scripts 目录下，例如：

which huggingface-cli 

• 如果未找到，可以尝试以下命令：

export PATH=$PATH:/path/to/your/python/bin 

其中 /path/to/your/python/bin 是你的 Python 安装路径。

重新启动终端：
有时，添加路径后需要重新启动终端才能生效。

5.2 文件未找到错误

在下载或上传文件时，可能会遇到“文件未找到”的错误。以下是解决此问题的方法：

检查文件路径：
确保你提供的文件路径是正确的。你可以使用以下命令检查文件是否存在：

ls /path/to/your/file 

相对路径与绝对路径：
确保你使用的是正确的路径格式。相对路径是相对于当前工作目录的路径，而绝对路径是从根目录开始的完整路径。

权限问题：
确保你有权限访问该文件。你可以使用以下命令更改文件权限：

chmod +r /path/to/your/file 

5.3 下载失败的处理方法

在下载文件时，可能会遇到下载失败的情况。以下是一些常见的处理方法：

检查网络连接：
确保你的网络连接正常。你可以尝试访问其他网站或使用 ping 命令检查网络连接。

重试下载：
有时下载失败是由于网络波动引起的。你可以尝试重新下载文件：

from huggingface_hub import hf_hub_download hf_hub_download(repo_id="google/pegasus-xsum", filename="config.json") 

检查文件是否存在：
确保你要下载的文件在指定的仓库中存在。你可以通过浏览器访问仓库页面进行确认。

使用特定版本：
如果你尝试下载特定版本的文件，确保你提供的版本信息是正确的。例如：

from huggingface_hub import hf_hub_download hf_hub_download(repo_id="google/pegasus-xsum", filename="config.json", revision="4d33b01d79672f27f001f6abade33f22d993b151") 

通过以上方法，你应该能够解决在使用 HuggingFace CLI 命令时遇到的一些常见问题。如果问题仍然存在，建议查看官方文档或寻求社区帮助。

高级功能与配置

6.1 自定义下载路径

在使用 HuggingFace CLI 下载文件时，默认情况下文件会被下载到由 HF_HOME 环境变量定义的缓存目录中。然而，有时用户可能希望将文件下载到特定的本地目录，以便更好地管理和使用这些文件。为此，HuggingFace CLI 提供了 --local-dir 选项，允许用户指定自定义的下载路径。

使用 --local-dir 选项

以下是使用 --local-dir 选项将文件下载到特定本地目录的示例：

huggingface-cli download adept/fuyu-8b model-00001-of-00002.safetensors --local-dir fuyu 

执行上述命令后，文件 model-00001-of-00002.safetensors 将被下载到当前目录下的 fuyu 文件夹中。

注意事项

1. 目录创建：如果指定的本地目录不存在，HuggingFace CLI 会自动创建该目录。
2. 文件更新：如果本地目录中已存在同名文件，并且该文件的元数据与远程文件不一致，HuggingFace CLI 会重新下载该文件以确保其为最新版本。

6.2 多线程下载

为了提高下载速度，HuggingFace CLI 支持多线程下载。通过设置环境变量 HF_HUB_ENABLE_HF_TRANSFER，用户可以启用多线程下载功能。

启用多线程下载

以下是启用多线程下载的步骤：

设置环境变量：

export HF_HUB_ENABLE_HF_TRANSFER=1 

执行下载命令：

huggingface-cli download gpt2 config.json 

启用多线程下载后，HuggingFace CLI 会自动利用多个线程来加速文件的下载过程。

6.3 下载受限模型

某些模型可能因为版权或其他原因受到访问限制，只有特定用户或组织才能下载和使用这些模型。为了下载受限模型，用户需要进行身份验证，并使用有效的访问令牌。

使用访问令牌下载受限模型

以下是使用访问令牌下载受限模型的示例：

登录并获取访问令牌：

huggingface-cli login 

按照提示输入您的访问令牌。

使用 --token 选项下载受限模型：

huggingface-cli download gpt2 config.json --token=hf_**** 

将 hf_**** 替换为您实际的访问令牌。

注意事项

1. 令牌权限：确保您的访问令牌具有下载受限模型的权限。
2. 安全性：不要在公共场合或与他人共享您的访问令牌，以防止未经授权的访问。

通过上述方法，用户可以灵活地自定义下载路径、利用多线程加速下载，并安全地下载受限模型。这些高级功能使得 HuggingFace CLI 成为一个强大且灵活的工具，适用于各种复杂的下载需求。

镜像站使用指南

在使用 HuggingFace 平台时，为了提高下载速度和稳定性，有时需要使用镜像站。本文将详细介绍如何设置环境变量以使用镜像站，并确保这些设置在不同环境中持续生效。

7.1 设置环境变量的命令

为了使用镜像站，首先需要设置相应的环境变量。以下是设置环境变量的命令：

export HF_ENDPOINT="https://mirror.example.com" 

在这个命令中，HF_ENDPOINT 是 HuggingFace 提供的一个环境变量，用于指定镜像站的地址。你需要将 https://mirror.example.com 替换为你所使用的镜像站的实际地址。

例如，如果你使用的是中国大陆的镜像站，可以设置为：

export HF_ENDPOINT="https://hf.mirror.cn" 

设置好环境变量后，HuggingFace CLI 将会通过这个镜像站来下载模型和数据集，从而提高下载速度。

7.2 环境变量的持续生效

为了确保环境变量在不同的终端会话中持续生效，可以将设置环境变量的命令添加到你的 shell 配置文件中。以下是具体步骤：

打开你的 shell 配置文件：

• 如果你使用的是 bash，打开 ~/.bashrc 文件。
• 如果你使用的是 zsh，打开 ~/.zshrc 文件。

添加环境变量设置命令：
在文件的末尾添加以下内容：

export HF_ENDPOINT="https://mirror.example.com" 

同样，将 https://mirror.example.com 替换为你所使用的镜像站的实际地址。

保存并关闭文件：
保存文件并关闭编辑器。

使配置文件生效：
运行以下命令使配置文件生效：

source ~/.bashrc # 如果你使用的是 bash source ~/.zshrc # 如果你使用的是 zsh 

通过以上步骤，你的环境变量设置将会在每次打开新的终端会话时自动生效，从而确保在使用 HuggingFace CLI 时始终通过镜像站进行下载。

通过使用镜像站，你可以显著提高模型和数据集的下载速度，减少下载失败的情况，从而更加高效地进行自然语言处理项目。

各类下载方法总结

8.1 浏览器网页下载

浏览器网页下载是最直接的下载方式，适用于小文件或不需要频繁下载的场景。用户可以直接访问Hugging Face Hub上的模型或数据集页面，找到所需的文件并点击下载。这种方式简单易用，但不适合大量文件或需要自动化处理的场景。

8.2 多线程下载器

多线程下载器可以显著提高下载速度，适用于大文件或需要快速下载的场景。例如，使用aria2等工具可以同时开启多个线程进行下载，从而加快下载速度。以下是一个使用aria2的示例：

aria2c -x 16 -s 16 https://huggingface.co/path/to/file 

8.3 CLI工具gitclone命令

使用git clone命令可以从Hugging Face Hub上克隆整个仓库到本地。这种方式适用于需要完整仓库的场景，但需要注意仓库的大小，以免占用过多磁盘空间。以下是一个示例：

git clone https://huggingface.co/username/repo 

8.4 专用CLI工具huggingface-cli+hf_transfer

Hugging Face提供的专用CLI工具huggingface-cli结合hf_transfer可以高效地下载模型和数据集。hf_transfer是一个优化过的下载工具，可以显著提高下载速度。以下是一个使用huggingface-cli下载文件的示例：

huggingface-cli download username/repo filename 

8.5 Python方法snapshot_download

使用Hugging Face的Python库huggingface_hub中的snapshot_download方法可以方便地下载模型或数据集。以下是一个示例：

from huggingface_hub import snapshot_download snapshot_download(repo_id="username/repo") 

8.6 Python方法from_pretrained

对于使用Transformers库的用户，可以使用from_pretrained方法直接下载并加载预训练模型。以下是一个示例：

from transformers import AutoModel model = AutoModel.from_pretrained("username/repo") 

8.7 Python方法hf_hub_download

hf_hub_download方法可以直接从Hugging Face Hub下载特定文件。以下是一个示例：

from huggingface_hub import hf_hub_download file_path = hf_hub_download(repo_id="username/repo", filename="filename") 

通过以上几种方法，用户可以根据具体需求选择最适合的下载方式，无论是通过浏览器手动下载，还是通过命令行或Python脚本自动化下载，都能高效地获取所需的模型和数据集。