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. 访问 HuggingFace 官网。
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 创建仓库

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

   pip install huggingface_hub
   

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

   huggingface-cli login
   

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

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

   huggingface-cli repo create <repo_name>
   

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

   huggingface-cli repo create my-first-repo
   

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

3.1.2 使用网页创建仓库

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

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

3.2 上传文件

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

3.2.1 使用 CLI 上传文件

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

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

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

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

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

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

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

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

3.2.2 使用网页上传文件

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

2. 上传文件：
   在仓库页面中，点击“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 工具未正确安装或未添加到系统路径中。以下是解决此问题的步骤：

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

   pip show huggingface_hub
   

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

   pip install --upgrade huggingface_hub
   

2. 添加到系统路径：
   如果你已经安装了 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 安装路径。

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

5.2 文件未找到错误

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

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

   ls /path/to/your/file
   

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

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

   chmod +r /path/to/your/file
   

5.3 下载失败的处理方法

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

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

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

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

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

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

   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，用户可以启用多线程下载功能。

启用多线程下载

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

1. 设置环境变量：

   export HF_HUB_ENABLE_HF_TRANSFER=1
   

2. 执行下载命令：

   huggingface-cli download gpt2 config.json
   

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

6.3 下载受限模型

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

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

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

1. 登录并获取访问令牌：

   huggingface-cli login
   

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

2. 使用 --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 配置文件中。以下是具体步骤：

1. 打开你的 shell 配置文件：

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

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

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

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

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

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

   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脚本自动化下载，都能高效地获取所需的模型和数据集。