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

安装过程中可能会遇到一些依赖项,如 filelockfsspecrequests 等,这些依赖项会自动安装。

认证与登录

在使用 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.0config.json 文件,可以使用以下命令:

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

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

指定下载路径

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

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

该命令会将版本号为 1.0.0config.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_PROXYHTTPS_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脚本自动化下载,都能高效地获取所需的模型和数据集。

  • 28
    点赞
  • 26
    收藏
    觉得还不错? 一键收藏
  • 打赏
    打赏
  • 1
    评论

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论 1
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

我就是全世界

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付:¥1
获取中
扫码支付

您的余额不足,请更换扫码支付或充值

打赏作者

实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值