HuggingFace CLI 命令全面指南

2024-06-19 19:20

本文主要是介绍HuggingFace CLI 命令全面指南,希望对大家解决编程问题提供一定的参考价值,需要的开发者们随着小编来一起学习吧!

文章目录

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

安装过程中可能会遇到一些依赖项,如 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 loginlogin("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_downloadsnapshot_download(repo_id="username/repo")

8.6 Python方法from_pretrained

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

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

8.7 Python方法hf_hub_download

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

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

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

这篇关于HuggingFace CLI 命令全面指南的文章就介绍到这儿,希望我们推荐的文章对编程师们有所帮助!



http://www.chinasem.cn/article/1075919

相关文章

Spring Boot结成MyBatis-Plus最全配置指南

《SpringBoot结成MyBatis-Plus最全配置指南》本文主要介绍了SpringBoot结成MyBatis-Plus最全配置指南,包括依赖引入、配置数据源、Mapper扫描、基本CRUD操... 目录前言详细操作一.创建项目并引入相关依赖二.配置数据源信息三.编写相关代码查zsRArly询数据库数

SpringBoot启动报错的11个高频问题排查与解决终极指南

《SpringBoot启动报错的11个高频问题排查与解决终极指南》这篇文章主要为大家详细介绍了SpringBoot启动报错的11个高频问题的排查与解决,文中的示例代码讲解详细,感兴趣的小伙伴可以了解一... 目录1. 依赖冲突:NoSuchMethodError 的终极解法2. Bean注入失败:No qu

JavaScript错误处理避坑指南

《JavaScript错误处理避坑指南》JavaScript错误处理是编程过程中不可避免的部分,它涉及到识别、捕获和响应代码运行时可能出现的问题,本文将详细给大家介绍一下JavaScript错误处理的... 目录一、错误类型:三大“杀手”与应对策略1. 语法错误(SyntaxError)2. 运行时错误(R

Python使用date模块进行日期处理的终极指南

《Python使用date模块进行日期处理的终极指南》在处理与时间相关的数据时,Python的date模块是开发者最趁手的工具之一,本文将用通俗的语言,结合真实案例,带您掌握date模块的六大核心功能... 目录引言一、date模块的核心功能1.1 日期表示1.2 日期计算1.3 日期比较二、六大常用方法详

MySQL中慢SQL优化方法的完整指南

《MySQL中慢SQL优化方法的完整指南》当数据库响应时间超过500ms时,系统将面临三大灾难链式反应,所以本文将为大家介绍一下MySQL中慢SQL优化的常用方法,有需要的小伙伴可以了解下... 目录一、慢SQL的致命影响二、精准定位问题SQL1. 启用慢查询日志2. 诊断黄金三件套三、六大核心优化方案方案

使用Python高效获取网络数据的操作指南

《使用Python高效获取网络数据的操作指南》网络爬虫是一种自动化程序,用于访问和提取网站上的数据,Python是进行网络爬虫开发的理想语言,拥有丰富的库和工具,使得编写和维护爬虫变得简单高效,本文将... 目录网络爬虫的基本概念常用库介绍安装库Requests和BeautifulSoup爬虫开发发送请求解

SpringBoot整合MybatisPlus的基本应用指南

《SpringBoot整合MybatisPlus的基本应用指南》MyBatis-Plus,简称MP,是一个MyBatis的增强工具,在MyBatis的基础上只做增强不做改变,下面小编就来和大家介绍一下... 目录一、MyBATisPlus简介二、SpringBoot整合MybatisPlus1、创建数据库和

Python中DataFrame转列表的最全指南

《Python中DataFrame转列表的最全指南》在Python数据分析中,Pandas的DataFrame是最常用的数据结构之一,本文将为你详解5种主流DataFrame转换为列表的方法,大家可以... 目录引言一、基础转换方法解析1. tolist()直接转换法2. values.tolist()矩阵

JDK多版本共存并自由切换的操作指南(本文为JDK8和JDK17)

《JDK多版本共存并自由切换的操作指南(本文为JDK8和JDK17)》本文介绍了如何在Windows系统上配置多版本JDK(以JDK8和JDK17为例),并通过图文结合的方式给大家讲解了详细步骤,具有... 目录第一步 下载安装JDK第二步 配置环境变量第三步 切换JDK版本并验证可能遇到的问题前提:公司常

Spring Boot中定时任务Cron表达式的终极指南最佳实践记录

《SpringBoot中定时任务Cron表达式的终极指南最佳实践记录》本文详细介绍了SpringBoot中定时任务的实现方法,特别是Cron表达式的使用技巧和高级用法,从基础语法到复杂场景,从快速启... 目录一、Cron表达式基础1.1 Cron表达式结构1.2 核心语法规则二、Spring Boot中定