章节索引
排查从最先失败的请求开始。先取一个体积小的配置文件,确认账号和写入目录;再观察大文件的传输记录,最后核对缓存能否复用。这样可以把访问许可、下载后端和存储故障分开处理,避免反复删除已经完成的文件。
先辨认 文件经由 Hub 、Xet 还是 Git LFS 获取
模型说明与 config.json 可以用来检查 Hub 的基本访问。权重传输还可能交给 Xet,把内容拆开获取;Git 工作流另有兼容路径。先找准发起下载的工具,再检查它对应的认证和缓存设置。
工具与传输路径的对应关系
| 使用入口 | 内容从哪里取得 | 适用任务 |
|---|---|---|
| huggingface_hub / hf CLI | 配合 hf_xet 取得 Xet 内容,具体依赖随安装版本核对 | 直接获取模型文件或数据集 |
| git clone + git-xet | Git 仓库操作配合 Xet 传输 | 要保留分支与提交记录的项目 |
| 沿用 Git LFS 的流程 | 借助兼容通道读取大文件 | 检查遗留项目能否继续完成检出 |
| 网页中的文件入口 | 使用 Hub 返回的文件地址 | 检查单个文件是否可取 |
旧指南里的下载组件不能直接视作当前环境的配置要求。hf_transfer、hf_xet 与 Git LFS 的作用应结合所装工具的说明辨认,避免同时启用已经无效的开关。
用 config.json 检查访问许可与基础连接
python -m pip install -U huggingface_hub
hf auth login
hf download gpt2 config.json
# 查看版本
python -c "import huggingface_hub; print(huggingface_hub.__version__)"公开文件能够保存到本地,可用于检查基础连接与缓存写入。遇到拒绝访问的响应,应转向仓库许可、当前账号和读取权限;单纯改变网络出口不能替代授权。
hf auth login 管理的访问凭据应留在受控环境。不要写入可分享的 YAML、交互笔记或代码文件;多人环境应使用各自受保护的凭据管理方式。
在加载 Python 库以前确定代理与存 储变量
HF_HOME 改动后,认证文件的默认位置也可能随之变化。HF_TOKEN 与 HF_TOKEN_PATH 分别影响使用的凭据值和文件位置,迁移缓存前先核对当前进程实际从哪里取得身份。
目录和代理设好后,用 hf auth whoami 检查身份,再尝试受限仓库。若当前环境没有对应登录状态,就在该环境完成认证。公开仓库下载成功不能代替受限仓库的许可检查。
CLASH_PORT=7890
export HTTPS_PROXY="http://127.0.0.1:$CLASH_PORT"
export HTTP_PROXY="http://127.0.0.1:$CLASH_PORT"
export HF_HOME="$HOME/hf-cache"
export HF_HUB_DOWNLOAD_TIMEOUT=30
mkdir -p "$HF_HOME"
hf download openai-community/gpt2 --include '*.json'
hf download openai-community/gpt2 --cache-dir "$HF_HOME/hub"库可能在 import 时保存环境设置。已经加载它的 Notebook 应在调整变量后重启内核,或提前在启动环境中配置。仅在连接建立以后读取迟缓时,才考虑调整下载等待时间。
若只迁移仓库内容,可考虑 HF_HUB_CACHE 或 --cache-dir;HF_HOME 的影响范围还包括身份文件。新位置要允许当前用户写入,并容纳模型版本、临时文件和解压产生的内容。
把网页访问与 Xet 大文件请求 分别 检查
短文本可以正常返回,而内容寻址或临时授权的存储请求仍可能失败。保持出口一致,记录失败请求的域名、响应和写入错误,再判断问题位于网络、认证还是磁盘。
先让 Hub 与 Xet 请求使用同一条稳定路径,完成对照后再恢复原选择方式。临时地址出错时,应查看授权响应;不能仅凭换过出口就判断地址已过期,也不宜把临时域名扩大为长期匹配规则。下面列出常见疑问。
访问被拒绝该检 查什么?
回到仓库许可和当前 token 的读取权限检查;延长等待时间无法补足授权。
读取超时应怎样分 开 处理 ?
先确定失败请求是否经过预期出口。Hub 文件的等待参数与 hf_xet 的分块错误需要分别查看,不能把它们视为同一种超时。
磁 盘写满 后怎样 保 留进度?
保存已完成内容,再调整 HF_HOME 或 HF_HUB_CACHE 的存储位置;网络出口不会改变剩余空间。
缓存目录 拒绝写 入
核对目录归属及挂载权限,让当前用户能够写入,避免换成高权限用户重新获取整份内容。
文件只是 大内容 的引用指针
检查 Git 的大文件检出是否结束,以及 git-xet、git-lfs 是否具备所需支持。
先盘点现有文 件,再 处理缓存路径与无效开关
Hub 与 Xet 的默认内容分别位于用户缓存路径下的 huggingface/hub 和 huggingface/xet。设置新的 HF_HOME 只影响后续寻址;先保存原位置,再决定继续使用还是迁移,不能假定文件已经自动搬过去。
refs、blobs、snapshots 共同组织 Hub 已完成的文件。重新发起中断的任务时,保持仓库标识、revision、使用者和目录相符,才能沿用对应内容。
不要把 HF_XET_CHUNK_CACHE_SIZE_BYTES 当作必然生效的加速开关。应先核对所用 hf_xet 对该变量的说明;处理下载故障时,保留 Hub 已完成文件比删除 blobs 后重新开始更便于定位。
from pathlib import Path
from huggingface_hub import snapshot_download
cache_dir = Path.home() / "hf-cache" / "hub"
path = snapshot_download(
repo_id="openai-community/gpt2",
revision="main",
cache_dir=cache_dir,
)
print(path)需要版 本历史 时再检 查 Git 的大 文件 支持
若任务只需要模型内容,hf download 已提供相应下载入口。要操作仓库分支或提交历史,再使用 Git,并把 Git 的下载链路单独检查。
git xet 不可用时,可从对应平台的项目安装说明核对 git-xet;页面提及的 Homebrew 和 winget 是不同平台的获取方式。遗留 LFS 流程遇到大文件问题,还应检查相关下载工具的版本与兼容要求。
HF_REPO='OWNER/MODEL'
# 例如 HF_REPO='openai-community/gpt2'
git lfs install
git xet install
git clone "https://huggingface.co/$HF_REPO"
cd "${HF_REPO##*/}"
git xet --version
git lfs version
git statusGit 的代理来自其配置与进程环境,不能用 Python SDK 的成功结果代替验证。若 hf CLI 可下载但 clone 停住,检查范围应收敛到 Git、Xet、LFS 及其代理设置。
以本地加载结果确 认下载内容 可以复用
完成后的收尾核对
沿用原参数重新请求
观察是否复用了对应 snapshot 中的已有内容,而非再次传输整套文件。
调用实际项目读取文件
让 transformers 或项目程序读取权重及 tokenizer,确认下载结果能用于原任务。
阻断额外的在线获取
已有所需文件时,按工具说明启用 HF_HUB_OFFLINE 或 local_files_only,检查是否能够依赖本地内容完成加载。
清点敏感信息与存储余量
检查笔记、运行输出及提交记录是否夹带访问凭据,并给缓存所在磁盘保留后续更新空间。
留 下提交标 识和本地位 置
保存 revision 与 snapshot 的对应关系,便于下次区分版本变更和文件损坏。
