AutoDL下载大模型ckpt失败？镜像站+CLI断点续传方案全攻略

1. 问题场景：为什么在AutoDL上下载大型ckpt总是失败

先交代下背景。我在AutoDL上租过不少GPU实例，跑大模型微调和推理是家常便饭。入手一个开源模型的第一件事，就是去Hugging Face（后面简称HF）把预训练权重拉下来。如果你只是下载几百MB的小模型，用默认方式基本没戏或者很慢，但如果是动辄几十GB的大型ckpt文件，比如LLaMA系列的7B、13B、70B，或者SD系列的超大checkpoint，那问题就非常突出了：下载到一半中断、速度跌到几十KB/s、甚至直接超时失败，跑了一晚上的下载任务第二天一看还剩好几个文件没下完。

我先说个结论：在AutoDL上拉HF模型，问题的根源不是模型本身太大，而是网络路径不稳定，以及默认下载方式不擅长处理大文件断点续传。 你如果在本地电脑上下载同一个模型，可能速度还不错，但AutoDL的服务器部署在特定机房，访问HF主站的传输链路波动很大，大文件下载时经常因为连接超时导致前功尽弃。

这篇文章我结合自己实际踩坑的经验，把AutoDL下载HF大型ckpt的几种可行方案完整拆一遍。无论你是刚接触AutoDL的新手，还是已经下载过不少模型的老手，里面提到的思路和参数都值得收藏备用。适用人群很明确：想高效、稳定地拿到HF大模型权重文件，并且不希望在这个过程中反复重试的深度学习从业者。

2. 大型ckpt下载的根因分析与方案选型

2.1 为什么直接下载会失败：三个核心原因

先说为什么会失败。我把它拆成三个层面。

第一个原因是网络链路的稳定性问题。 HF主站的服务器主要在海外，国内服务器访问它的时候，数据包要经过多条国际线路。短连接请求可能还凑合，但下载大文件时长时间占用连接，中途任何一个节点出现波动，TCP连接就可能断开。断开后，如果你用的是不支持断点续传的下载方式，整个文件就要从头开始。几十GB的文件从头下，体验非常糟糕。

第二个原因是默认下载工具对大文件不友好。 很多人第一次在AutoDL上下载模型，用的命令是 git clone https://huggingface.co/xxx/model-name。这种方式对小项目还行，但对存放大型ckpt的模型仓库来说非常不靠谱。Git底层是面向代码仓库设计的，它需要一边下载一边维护文件元数据。当仓库里有几个GB级别的大文件时，Git的存储效率会急剧下降，而且因为每个文件都需要完整校验，任何一个分片丢失都会导致整个clone失败。在AutoDL上，我见过太多人卡在 git clone 这一步，下载到一半报 fatal: The remote end hung up unexpectedly。

第三个原因是缺少有效的断点续传机制。 官方推荐的 huggingface_hub 库虽然支持断点续传，但默认配置在极端网络环境下表现一般。如果你没有主动配置重试参数和并发参数，下载大型ckpt时一旦遇到网络抖动，进程退出后就得从头开始。很多人的做法是反复执行同一条下载命令，但每次都是从0%开始，永远下不完。

这三个原因叠加起来，就形成了“下载大型ckpt必然失败”的错觉。其实只要选对工具和参数，这个问题完全可控。

2.2 核心方案对比：镜像站、官方CLI、加速插件

针对上面的问题，我整理了几套主流方案，实际使用中可以根据场景灵活组合使用。

这几套方案并不是互斥的。我自己目前用得最多的组合是“镜像站 + 官方CLI + hf_transfer插件”，这也是今天这篇博文的核心内容。

3. 实操准备：环境检查和基础配置

3.1 进入你的AutoDL实例终端

在AutoDL控制台，选择你租用的GPU实例，点击“JupyterLab”或“终端”进入命令行环境。如果是首次使用，建议先确认Python版本和pip可用，我这里的基准环境是Python 3.10 + CUDA 11.8镜像，下面的操作基本都是通用的。

3.2 安装huggingface_hub库

新版 huggingface_hub 集成了很多下载相关的功能，也是官方CLI工具的命令来源。如果你环境里还没有，先装一下：

bash复制pip install -U huggingface_hub

装完之后验证版本：

bash复制huggingface-cli version

3.3 设置镜像站环境变量

镜像站的作用是把HF的下载域名重定向到一个国内可以快速访问的镜像服务。操作方式很简单，在终端执行：

bash复制export HF_ENDPOINT=https://hf-mirror.com

这个环境变量对后续所有HF相关操作都生效。不过要注意，这个设置只在当前终端会话中有效，如果你关掉终端重新打开，环境变量就丢了。为了省事，我一般会写入启动配置文件。如果你用的是bash，执行：

bash复制echo 'export HF_ENDPOINT=https://hf-mirror.com' >> ~/.bashrc
source ~/.bashrc

用zsh的话，把 ~/.bashrc 换成 ~/.zshrc 即可。设置完成后再检查一下：

bash复制echo $HF_ENDPOINT

能看到 https://hf-mirror.com 就说明设置成功。这一步做完，你已经解决了80%的网络问题。

4. 使用镜像站下载大型ckpt的完整流程

4.1 下载单个模型的官方CLI命令

镜像站设置好之后，就可以用官方CLI来下载模型了。最基本的一条命令：

bash复制huggingface-cli download meta-llama/Llama-2-7b-hf --local-dir ./llama2-7b

这里的 --local-dir 指定下载到当前目录下的 llama2-7b 文件夹。如果你不指定，模型会默认下载到系统缓存目录 ~/.cache/huggingface/，下次用 from_pretrained 加载时能够自动识别，但不利于你直接查看和管理文件。

实际操作中，推荐永远用 --local-dir 显式指定目录。原因很直接：大模型仓库里通常除了模型权重，还有配置文件、tokenizer词典、README等。全部放到一个自己指定的目录里，后续做模型合并、转换格式、清理磁盘都方便。

4.2 只下载需要的文件，避免无效流量

大型ckpt的仓库里往往有多个分支或格式。比如有的仓库同时包含 pytorch_model.bin 和 model.safetensors，有的仓库带了多个epoch的checkpoint，其实你只需要其中一个。

为了避免把不需要的文件也下载下来，CLI支持 --include 和 --exclude 参数。举个例子，我只想下载7B模型的safetensors格式权重，不下载bin格式：

bash复制huggingface-cli download meta-llama/Llama-2-7b-hf \
  --include "*.safetensors" \
  --local-dir ./llama2-7b

反过来，如果仓库里有多个检查点文件，你可以用排除法：

bash复制huggingface-cli download some-org/some-model \
  --exclude "*.bin" \
  --exclude "*.msgpack" \
  --local-dir ./some-model

这个技巧在下载大型ckpt时特别实用。有一些大模型仓库会把推理用的 pytorch_model.bin 之外的所有历史checkpoint全部保留，加起来几十上百GB，一次全下载既浪费空间又折腾网络。学会筛选文件，等于给下载任务减负。

注意：使用通配符时，建议提前到模型仓库页面确认一下文件名规律。有些仓库命名很坑，比如 model-00001-of-00002.safetensors 这种分片格式，你要确保通配符能匹配到所有分片。

4.3 断点续传与重试参数

大型ckpt下载最怕中断。好在官方CLI自带断点续传能力，但你需要给它一点耐心。默认行为是：如果下载中途失败，已经下载好的部分会保留在临时文件中，下次执行相同命令时，会从断点继续，而不是从零开始。

为了减少中断概率，我强烈建议加上重试相关参数。具体来说，环境变量 HF_HUB_DOWNLOAD_TIMEOUT 可以控制下载超时时间，默认10秒。在AutoDL这种网络环境下，10秒太短，稍微抖动一下就会断。建议调大：

bash复制export HF_HUB_DOWNLOAD_TIMEOUT=60

同时，CLI命令上加 --max-workers 控制并发线程数。默认4个并发不够跑满带宽，建议调高到8或16：

bash复制huggingface-cli download meta-llama/Llama-2-7b-hf \
  --local-dir ./llama2-7b \
  --max-workers 8

如果中途失败，不要急着骂娘，直接再跑一遍相同命令，它会自动从上次断点继续。

另外，我还会配合一个简单的循环脚本，让它在失败后自动重试：

bash复制for i in {1..5}; do
  huggingface-cli download meta-llama/Llama-2-7b-hf \
    --local-dir ./llama2-7b \
    --max-workers 8
  if [ $? -eq 0 ]; then
    break
  fi
  echo "下载失败，第${i}次重试..."
  sleep 5
done

这个脚本保证最多重试5次，如果某次成功就退出循环。实测下来，配上镜像站之后，很少会需要用到第二次重试。

5. 用hf_transfer插件进一步提速

5.1 hf_transfer是什么，为什么有效

hf_transfer 是HF官方推出的一个用Rust语言编写的加速下载插件。它的核心思路是：将单个文件拆成多个分片，并发地从服务端拉取数据，然后本地合并。这个方式特别适合大文件下载，相当于把一条慢速车道变成多条并行的车道。

安装方法很简单：

bash复制pip install hf_transfer

然后设置环境变量：

bash复制export HF_HUB_ENABLE_HF_TRANSFER=1

设置这个变量后，下次执行 huggingface-cli download 时，系统会自动优先使用 hf_transfer 做下载。实测下来，在AutoDL普通实例上，原本可能只有1-2MB/s的速度，开启后能跑到10-20MB/s以上，具体取决于你的实例带宽和文件大小。

5.2 实操注意事项

用 hf_transfer 时有一个小坑：它对断点续传的支持和默认下载器不太一样，任务被中断之后，重启命令需要重新校验已有分片，如果你的网络属于“频繁断连”类型，反而可能更慢。这种情况我建议还是关闭 hf_transfer，只用默认下载器 + 镜像站就够了。

另外，hf_transfer 在部分镜像站版本上可能不兼容，表现是下载到99%卡住不动。如果发现进度条停滞，可以先等几分钟，还不动的就直接 Ctrl+C 终止，然后执行不带 HF_HUB_ENABLE_HF_TRANSFER 的下载命令，它会自动校验已经下载的部分并继续。

经验之谈：“镜像站 + 默认下载器 + 调大超时”是最稳的组合；“镜像站 + hf_transfer”是第二快但不那么稳的组合。优先求稳的话，可以不用 hf_transfer。但如果你的目标是快速拉取80GB级别的大checkpoint，且网络还算平稳，大胆开 hf_transfer。

6. 实操案例：从零下载一个完整的LLaMA-2-7B模型

6.1 确认仓库结构和磁盘空间

先确认当前机器磁盘剩余空间，避免下载到一半磁盘写满：

bash复制df -h

以 meta-llama/Llama-2-7b-hf 为例，仓库里通常包含：

• config.json：模型结构配置文件
• tokenizer.json、tokenizer.model：分词器文件
• model-00001-of-00002.safetensors、model-00002-of-00002.safetensors：分片权重
• pytorch_model.bin：另一种格式的权重（可选）

如果要下载完整仓库，需要预留约13-14GB空间。如果磁盘不够，先把AutoDL系统盘里的垃圾文件清一清，再用前面介绍的 --exclude 参数跳过不需要的格式。

6.2 执行下载命令

在确认磁盘后，我直接在终端执行：

bash复制cd ~
mkdir -p models/llama2-7b
cd models/llama2-7b

export HF_ENDPOINT=https://hf-mirror.com
export HF_HUB_DOWNLOAD_TIMEOUT=60

huggingface-cli download meta-llama/Llama-2-7b-hf \
  --local-dir ./ \
  --max-workers 8

注意这里的 --local-dir ./，表示直接把模型下载到当前目录。这样后续代码加载时，路径就是 ./models/llama2-7b，非常直观。

执行后，你会看到类似下面的输出：

code复制Fetching 11 files: 100%|██████████████████| 11/11 [00:00<?, ?it/s]
Downloading model-00001-of-00002.safetensors: 100%|██████████| 9.84G/9.84G [04:12<00:00, 39.0MB/s]
...

等所有文件都显示100%，模型就下载完成了。整个过程在镜像站加速下，通常只需要几分钟到十几分钟，具体取决于模型大小和AutoDL实例的带宽。

6.3 加载下载好的模型

下载完成后，在Python代码里这样加载：

python复制from transformers import AutoModelForCausalLM, AutoTokenizer

model_dir = "./models/llama2-7b"
tokenizer = AutoTokenizer.from_pretrained(model_dir)
model = AutoModelForCausalLM.from_pretrained(model_dir, device_map="auto")

因为权重文件已经在本地目录里，from_pretrained 不会再触发任何网络下载。这一点很重要：如果你之前没有指定 --local-dir，而是下载到了HF缓存目录，代码里传模型名（如 meta-llama/Llama-2-7b-hf）也能自动找到缓存，不会重复下载。

7. 备选方案：从ModelScope魔搭社区下载

7.1 什么时候需要备选方案

虽然镜像站解决了大部分问题，但有两种情况我会考虑从ModelScope（魔搭社区）下载。

第一种是镜像站同步不及时。有些最新的模型发布后，镜像站可能需要几小时甚至一天才完成同步。这时候如果你急用模型，走魔搭更靠谱。

第二种是AutoDL实例到魔搭的下载链路通常更稳定，毕竟魔搭的服务器就在国内。如果你觉得HF镜像站速度还是不够理想，可以试试从魔搭拉模型。

7.2 ModelScope的基本用法

魔搭的Python SDK是 modelscope，安装：

bash复制pip install modelscope

然后用一行命令下载模型：

bash复制modelscope download --model LLM-Research/Meta-Llama-3-8B-Instruct --local_dir ./models/meta-llama3-8b

这里要注意，魔搭上的模型目录结构和原始HF仓库不一定完全一样。有些模型是直接映射的，有些则经过了命名调整。实际使用前，最好先到魔搭网站搜索确认是否存在该模型，再复制对应的模型ID。

如果魔搭上也有对应模型，下载完成后，同样可以用 from_pretrained 加载本地目录：

python复制from transformers import AutoModelForCausalLM, AutoTokenizer

model_dir = "./models/meta-llama3-8b"
tokenizer = AutoTokenizer.from_pretrained(model_dir, trust_remote_code=True)
model = AutoModelForCausalLM.from_pretrained(model_dir, device_map="auto", trust_remote_code=True)

有些模型的代码实现依赖仓库内的自定义Python文件，必须加 trust_remote_code=True。初用者容易漏掉这个参数，结果加载时报错“找不到自定义类”，这时候其实就是这个原因。

7.3 双通道组合策略

我在实际项目中常用的策略是“HF镜像站优先，魔搭兜底”。也就是先试HF镜像站，如果下载中途反复失败，马上切到魔搭重新下载。因为大模型权重文件通常是直接可以互换的，只要版本一致，在HF下载一半的目录和魔搭下载的目录并不需要合并，直接选一个完整的用就行。

这套双通道组合的最大价值在于：你的下载任务不容易被单点故障卡死。AutoDL机房到HF主站的链路不稳定，但不代表到魔搭也不稳定，反过来也一样。学会“货比三家”，下载效率自然翻倍。

8. 下载后的常规检查与避坑指南

8.1 文件完整性与哈希校验

大文件下载完成后不能直接信任，需要确认下载过程中没有损坏。最简单的方法是检查文件数量：

bash复制ls -lh ~/models/llama2-7b

确认所有文件都齐全，特别是分片文件（safetensors 或 bin 文件）一个不少。很多仓库会在 README.md 里标注每个文件的SHA256值，你可以用 sha256sum 校验：

bash复制sha256sum ~/models/llama2-7b/model-00001-of-00002.safetensors

如果校验值与仓库标注一致，说明文件完整；如果不一致，说明下载过程中出现了损坏，需要重新下载这个文件。需要注意，不是所有仓库都会提供SHA256，那就至少确认一下文件大小是否和仓库页面标注的完全一致。

8.2 磁盘清理与文件管理

大模型常常伴随大体积缓存文件。如果下载过程中意外中断，HF缓存目录中会残留 .incomplete 临时文件，这些文件不清理的话会白白占用磁盘空间。用下面的命令查看缓存占用：

bash复制du -sh ~/.cache/huggingface

如果占用很大，可以清理无效的 .incomplete 文件：

bash复制find ~/.cache/huggingface -name "*.incomplete" -type f -delete

另外，AutoDL实例的数据盘和系统盘空间是分开的。大模型不要下载到系统盘根目录，建议放到 ~/autodl-tmp 或自己挂载的数据盘路径下，避免系统盘写满导致实例异常重启。

8.3 一个容易被忽略的坑：切换实例后环境变量丢失

如果你在AutoDL上使用了无卡模式、关机重启，或者重新创建了实例，那么你之前设置的 HF_ENDPOINT 环境变量可能已经丢失，需要重新执行：

bash复制export HF_ENDPOINT=https://hf-mirror.com

为了彻底解决这个问题，建议把环境变量写入 ~/.bashrc 或 ~/.zshrc，这样每次打开终端都不用手动设置。这个看起来是小问题，但确实能帮你节省很多重复踩坑的时间。

9. 常见问题与排查技巧实录

9.1 典型错误信息速查表

我整理了一份自己在AutoDL下载HF大模型时遇到过的常见错误处理表，建议截图保存。

9.2 关于Access Token获取

不是所有HF模型都能直接下载。有些仓库是Gated Model，要求你先在HF官网勾选同意许可协议，然后生成Access Token才能下载。在AutoDL终端执行：

bash复制huggingface-cli login

然后粘贴你的Access Token即可。Token的获取位置在HF官网的Settings → Access Tokens页面，建议把读权限token保存到本地笔记里，方便后续新建实例时使用。

9.3 两个独家调优技巧

最后分享两个我在长期使用中验证过的小技巧。

第一个是“本地缓存目录与自定义目录的结合使用”。有些情况下你希望模型下载到HF默认缓存目录，因为这样后续代码不需要传路径。但我也想保留一个显式的模型副本，方便打包转移到其他机器。这时候可以用 --cache-dir 和 --local-dir 同时指定：

bash复制huggingface-cli download meta-llama/Llama-2-7b-hf \
  --cache-dir ~/.cache/huggingface \
  --local-dir ~/models/llama2-7b

这样既不影响 from_pretrained 的自动加载逻辑，又保留了干净的自定义目录。

第二个是“下载完成后马上做一次文件数量快照”。把 ls -lh 的输出保存到文本文件里：

bash复制ls -lh > ~/models/llama2-7b/file_list.txt

这样以后处理模型文件时，随时可以对照快照确认有没有文件被误删或替换。对于需要反复搬运大型ckpt的场景，这个小习惯能省不少排查时间。

10. 个人经验总结与后续扩展方向

在实际使用中，我最深的体会是：在AutoDL上下载HF大型ckpt，方案永远不止一个，关键在于掌握“组合拳”。 镜像站解决网络速度问题，CLI解决断点续传问题，hf_transfer解决并发效率问题，魔搭解决镜像同步延迟问题。把这四者组合起来使用，基本能应对95%以上的模型下载需求。

最后再分享一个小技巧。如果你同时下载多个大型模型，建议把每个模型放到独立的目录下，并且用 nohup 或 tmux 将下载任务放到后台运行，避免SSH断开导致任务中断。比如：

bash复制tmux new -s download

然后在tmux会话中执行下载命令，即使关掉终端，下载任务也会持续运行。对于动辄几十GB的模型文件来说，这种操作方式能让你的等待过程轻松很多。

我最初研究这套流程，是因为一个70B模型的超大checkpoint反复失败了4次，每次都下载到一半就断了。后来老老实实按照“镜像站+CLI+超时设置”的组合重新操作，一次跑通。从那以后，我在AutoDL上拉任何大模型都会先检查环境变量有没有设置好。这篇内容里的每个坑，都是我自己花了真金白银的GPU时长踩出来的，希望能帮你在下载大型模型的路上少走一些弯路。