本文主要是介绍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 命令进行操作之前,需要进行认证。以下是详细的认证步骤:
生成访问令牌
- 访问 HuggingFace 官网。
- 登录你的账户。
- 进入
Settings
->Access Tokens
。 - 点击
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:
访问 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 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 工具未正确安装或未添加到系统路径中。以下是解决此问题的步骤:
-
检查安装:
首先,确保你已经安装了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
文件夹中。
注意事项
- 目录创建:如果指定的本地目录不存在,HuggingFace CLI 会自动创建该目录。
- 文件更新:如果本地目录中已存在同名文件,并且该文件的元数据与远程文件不一致,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_****
替换为您实际的访问令牌。
注意事项
- 令牌权限:确保您的访问令牌具有下载受限模型的权限。
- 安全性:不要在公共场合或与他人共享您的访问令牌,以防止未经授权的访问。
通过上述方法,用户可以灵活地自定义下载路径、利用多线程加速下载,并安全地下载受限模型。这些高级功能使得 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_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 命令全面指南的文章就介绍到这儿,希望我们推荐的文章对编程师们有所帮助!