HuggingFace CLI 命令全面指南

文章目录

• • 安装与认证
  • • [1.1 安装 HuggingFace Hub 库](#1.1 安装 HuggingFace Hub 库)
    • • [使用 pip 安装](#使用 pip 安装)
      • [使用 conda 安装](#使用 conda 安装)
      • 验证安装
    • [1.2 认证与登录](#1.2 认证与登录)
    • • 生成访问令牌
      • 使用访问令牌登录
      • 环境变量认证
      • 验证认证
  • 下载文件
  • • [2.1 下载单个文件](#2.1 下载单个文件)
    • • [安装 `huggingface_hub` 库](#安装 huggingface_hub 库)
      • 认证与登录
      • 下载单个文件
    • [2.2 下载特定版本的文件](#2.2 下载特定版本的文件)
    • • 下载特定版本的文件
      • 指定下载路径
  • 创建与管理仓库
  • • [3.1 创建仓库](#3.1 创建仓库)
    • • [3.1.1 使用 CLI 创建仓库](#3.1.1 使用 CLI 创建仓库)
      • [3.1.2 使用网页创建仓库](#3.1.2 使用网页创建仓库)
    • [3.2 上传文件](#3.2 上传文件)
    • • [3.2.1 使用 CLI 上传文件](#3.2.1 使用 CLI 上传文件)
      • [3.2.2 使用网页上传文件](#3.2.2 使用网页上传文件)
  • 高级操作
  • • [4.1 环境变量设置](#4.1 环境变量设置)
    • • 设置自定义下载路径
      • 设置镜像站
      • 启用多线程下载
      • 设置代理
    • [4.2 认证方法参数](#4.2 认证方法参数)
    • • [使用 Access Token 进行认证](#使用 Access Token 进行认证)
      • [在 Python 中进行认证](#在 Python 中进行认证)
      • 设置环境变量进行认证
      • [使用 Git 进行认证](#使用 Git 进行认证)
  • 常见问题与解决方案
  • • [5.1 Huggingface-cli 命令未找到](#5.1 Huggingface-cli 命令未找到)
    • [5.2 文件未找到错误](#5.2 文件未找到错误)
    • [5.3 下载失败的处理方法](#5.3 下载失败的处理方法)
  • 高级功能与配置
  • • [6.1 自定义下载路径](#6.1 自定义下载路径)
    • • [使用 `--local-dir` 选项](#使用 --local-dir 选项)
      • 注意事项
    • [6.2 多线程下载](#6.2 多线程下载)
    • • 启用多线程下载
    • [6.3 下载受限模型](#6.3 下载受限模型)
    • • 使用访问令牌下载受限模型
      • 注意事项
  • 镜像站使用指南
  • • [7.1 设置环境变量的命令](#7.1 设置环境变量的命令)
    • [7.2 环境变量的持续生效](#7.2 环境变量的持续生效)
  • 各类下载方法总结
  • • [8.1 浏览器网页下载](#8.1 浏览器网页下载)
    • [8.2 多线程下载器](#8.2 多线程下载器)
    • [8.3 CLI工具gitclone命令](#8.3 CLI工具gitclone命令)
    • [8.4 专用CLI工具huggingface-cli+hf_transfer](#8.4 专用CLI工具huggingface-cli+hf_transfer)
    • [8.5 Python方法snapshot_download](#8.5 Python方法snapshot_download)
    • [8.6 Python方法from_pretrained](#8.6 Python方法from_pretrained)
    • [8.7 Python方法hf_hub_download](#8.7 Python方法hf_hub_download)

安装与认证

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