模型下载全攻略HuggingFace、hf-mirror、ModelScope 国内实操本篇解决本地部署第一道坎模型文件从哪下、怎么下、下了怎么保证没下坏国内直连 huggingface.co 时快时慢、动不动连接重置是新手劝退第一因素。这篇把 HuggingFace 生态结构讲清楚给 hf-mirror、ModelScope、直链三种可复制命令的国内方案外加下载验证、断点续传和目录规划。读完你能把几十 GB 的模型稳稳下进非 C 盘的 SSD 里。一、为什么需要它本地部署大模型第一步永远是下载模型而它恰恰是最容易翻车的一步huggingface.co 在国内访问不稳定“模型下载慢”“HuggingFace 连不上”“ModelScope 怎么用” 是搜索量长期居前的词。我见过太多人花一整天卡在一个 4GB 的分片上——其实问题不在耐心在于没选对源、没配好断点续传。更典型的翻车姿势是对着 huggingface.co 的网页直接点下载按钮浏览器进度条走到 70% 就断重来一次又是 60% 断最后气得转投 ModelScope 才发现人家一条命令就下完了。正确的姿势是用带断点续传的命令行工具 选对源这两件事本篇分别放在第三节和第六节。更麻烦的是模型文件动辄十几 GB、拆成十几个分片下了一半断了、或者下完缺了分片加载时才报错此时重新下载代价很大。所以本篇除了给命令还要给一套下载后先验证、再加载的纪律。配合《AI-05 显存计算与模型选择》先选对量化版本7B 级 fp16 权重约 14-15 GBQ4 量化约 4-5 GB下载前心里就有底了。二、环境要求项目要求检查方式Python3.10 / 3.11 / 3.12建议 3.11python --version网络能访问 hf-mirror.com 或 modelscope.cn 即可浏览器能打开磁盘SSD 优先放非 C 盘预留模型体积 1.5 倍空间磁盘管理pip 镜像国内建议配清华源装依赖不折腾见下方命令工具huggingface-cli 或 modelscope 二选一本文都讲pip show huggingface_hub装工具国内 pip 用清华源pip install -U huggingface_hub[cli] -i https://pypi.tuna.tsinghua.edu.cn/simple pip install modelscope -i https://pypi.tuna.tsinghua.edu.cn/simple预期两个包都安装成功huggingface-cli version能出版本号。如果 pip 本身装得慢先检查是不是直连了国外 PyPI——换清华源后速度通常是数量级提升。两个工具不冲突可以都装huggingface-cli 走 hf-mirrorModelScope 走阿里源哪个顺用哪个。三、下载实操四种路径3.1 先懂 HuggingFace 的 repo 结构一个 HF 模型仓库repo通常包含权重文件大模型拆成多个分片如model-00001-of-00008.safetensors…model-00008-of-00008.safetensors外加一个model.safetensors.index.json记录分片索引tokenizer 文件tokenizer.json/tokenizer_config.json词表与分词规则配置文件config.json模型结构超参数量化版很多社区量化权重以.gguf单文件发布llama.cpp 家族Ollama 底层就是它。记住一点权重和 tokenizer 必须来自同一个 repo混搭会输出乱码。这也是后面下载验证要核对的事。另外注意一个常见误区HuggingFace 网页上的Files标签页显示的是**当前分支通常是 main**的全部文件一个 repo 里可能同时挂着 fp16、int8、多种 GGUF 量化版本体积加起来远超单个模型。下载前先在文件列表里确认你要的那个文件真实存在、大小符合预期再用--include精确过滤比整库拉下来再挑省心得多。量化后缀q4_k_m、q5_k_m 等和参数量要和你《AI-05 显存计算与模型选择》里算好的显存预算对得上。3.2 方案 Ahuggingface-cli hf-mirror推荐一行搞定huggingface-cli download是官方下载器支持--include只下指定文件和--local-dir指定落盘目录缓存目录由环境变量HF_HOME控制Windows 默认%USERPROFILE%\.cache\huggingfaceLinux 默认~/.cache/huggingface。国内的关键只有一行把下载端点指向 hf-mirror:: Windows当前终端生效 set HF_ENDPOINThttps://hf-mirror.com :: Linux / WSL export HF_ENDPOINThttps://hf-mirror.com然后下模型以 Qwen2.5-7B-Instruct 为例落到非 C 盘的 D:\modelshuggingface-cli download Qwen/Qwen2.5-7B-Instruct --local-dir D:\models\Qwen2.5-7B-Instruct只要量化文件时用--include过滤省掉 14-15 GB 的 fp16 权重Q4 文件通常只有 4-5 GBhuggingface-cli download Qwen/Qwen2.5-7B-Instruct-GGUF --include *.gguf --local-dir D:\models\Qwen2.5-7B-Instruct-GGUF预期逐文件显示进度结束后D:\models\...下出现完整文件。重跑同一条命令会自动跳过已完成的文件这是它内置的断点续传。几个高频参数再展开说一遍--include支持通配符*.gguf表示只要 GGUF 量化文件能帮你省掉十几 GB 的 safetensors--local-dir指定的目录会被直接当模型目录用不是缓存目录Ollama/llama.cpp 可以直接指向它。如果你不想落盘到自定义目录也可以不传--local-dir让它进HF_HOME缓存Windows 默认%USERPROFILE%\.cache\huggingface后续 Python 代码里用from_pretrained时会自动命中缓存但记得定期清缓存防止 C 盘膨胀。3.3 方案 BModelScope阿里系国内源国内网络下 ModelScope 的速度通常最稳。两种用法pip install modelscope -i https://pypi.tuna.tsinghua.edu.cn/simple命令行modelscope download --model Qwen/Qwen2.5-7B-Instruct --local_dir D:\models\Qwen2.5-7B-InstructPython APIfrom modelscope import snapshot_download snapshot_download(Qwen/Qwen2.5-7B-Instruct, local_dir./models)预期输出分片下载进度目录结构完整落盘。ModelScope 的 repo 命名与 HuggingFace 不完全一致组织名可能不同比如同一模型在两边前缀不同不确定时直接在 modelscope.cn 上搜模型名把页面右上角的下载命令复制下来改个--local_dir即可。它同样支持中断后重跑续传行为与 huggingface-cli 一致。3.4 方案 C直链 wget / curl最轻量知道 resolve 直链规则后任意文件都能单独拉。hf-mirror 的 resolve 链接形如https://hf-mirror.com/repo/resolve/main/file:: 示例只拉一个 Q4_K_M GGUF 单文件 wget -c https://hf-mirror.com/Qwen/Qwen2.5-7B-Instruct-GGUF/resolve/main/qwen2.5-7b-instruct-q4_k_m.gguf -O D:\models\qwen2.5-7b-instruct-q4_k_m.gguf :: 或 curl-L 跟随重定向-C - 断点续传 curl -L -C - https://hf-mirror.com/Qwen/Qwen2.5-7B-Instruct-GGUF/resolve/main/qwen2.5-7b-instruct-q4_k_m.gguf -o D:\models\qwen2.5-7b-instruct-q4_k_m.gguf-c/-C -就是断点续传参数中断后原命令重跑即可接着下。3.5 常用模型下载量参考先算好空间模型规格下载量约7B fp1614-15 GB7B Q8 量化7-8 GB7B Q4 量化如 Q4_K_M4-5 GB更大规格按同一比例放大即可参数量翻倍体积约翻倍再按位宽折半或再翻倍具体以各 repo 页面标注的文件大小为准。下载前养成一个习惯先打开 repo 页面看文件列表把总大小心算一遍再决定下到哪个盘、选哪个量化。这一步能避免下到一半发现 D 盘只剩 8G的尴尬。四、验证下完先体检再加载看目录分片是否齐全*of-00008*一个不能少且index.json在.gguf场景则确认只有一个完整的.gguf文件对大小把本地文件体积和 repo 文件列表页标的大小对一遍明显偏小就是中断残留走框架加载一次真正试金石ollama list ollama run qwen2.5:7b 你好用一句话自我介绍预期模型正常加载并输出通顺中文。若加载报connection reset by peer说明下载没完成回到断点续传重跑即可若加载成功但输出乱码/重复多半是权重与 tokenizer 不同源见第六节第 4 条。验证通过的标准很简单能加载、输出通顺、速度符合预期GPU 上 7B Q4 一般远快于每 token 一秒慢到个位数 tokens/s 就要怀疑 offload 占比太高或框架没吃到 GPU。三项都满足这个模型才算入库可以安心接到 OpenWebUI、Dify 这类前端工具后面用。五、进阶技巧目录规划模型统一放非 C 盘的 SSD如D:\modelsOllama 用户可用环境变量OLLAMA_MODELS把模型库搬走Windows 默认在%USERPROFILE%\.ollama\modelsHF 系改HF_HOME。C 盘塞满 50GB 模型是系统卡顿的常见原因。长连接保护大文件下载开着路由器别断电公司/校园网若限速换家庭网络或错峰凌晨下载。多文件 repo 建议顺序下载而不是开多个窗口并行——单条连接跑满带宽通常比多条互相抢带宽更稳也更容易断点续传。只下需要的文件跑 GGUF 就不要整个 repo 全拉--include *.gguf只想要 tokenizer 也同理。省下的带宽和空间都很可观。下载完成后立刻验证别等要用的那天才发现缺分片——那时你大概率忘了用的是哪个量化版本。验证通过后再把模型接入 Ollama详见《AI-07 Ollama本地部署大模型》或 llama.cpp详见《AI-12 llama.cpp与GGUF格式》流程就顺了。六、故障排查按层定位#症状报错原文层原因解决1HuggingFace 下载卡住 / ConnectionError / 超时网络国内直连 huggingface.co 受限set HF_ENDPOINThttps://hf-mirror.comWindows或export HF_ENDPOINThttps://hf-mirror.comLinux或改走 ModelScope2大文件下载中途断连接重置/超时网络大文件长连接被掐断重跑原命令huggingface-cli download自动跳过已完成分片wget/curl 带-c/-C -续传Ollama 场景重新ollama pull即可续传3下载报 403 / 401 或文件被 404网络/源仓库私有或需要登录或文件名写错私有 repo 先在 HF 网页确认可见性并登录核对文件名大小写resolve 链接区分大小写4模型加载成功但输出乱码、重复文件权重与 tokenizer 不匹配混源删除后从同一个 repo重新下载整套文件5加载时报缺文件 / 分片缺失文件下载中断只下了部分分片对照 repo 文件列表补齐缺失分片重跑 download 命令6pip install modelscope/huggingface_hub失败依赖直连 PyPI 慢加清华源-i https://pypi.tuna.tsinghua.edu.cn/simple重装7磁盘空间不足C 盘爆满磁盘模型默认落盘 C 盘缓存目录HF_HOME/--local-dir/OLLAMA_MODELS指向非 C 盘 SSD七、本篇自检清单能说出 HF repo 的结构权重分片 tokenizer config且必须同 repo会配HF_ENDPOINThttps://hf-mirror.com并用huggingface-cli download --local-dir下载到指定目录会用 ModelScopeCLI 与 Python API 两种作为国内备选源会拼 hf-mirror resolve 直链wget/curl 带断点续传参数知道 7B fp16 约 14-15 GB、Q4 约 4-5 GB下载前会先核对磁盘空间下载后做过三步验证目录齐全、大小对得上、框架能加载模型目录已放到非 C 盘 SSD参考Hugging Face Hub 文档huggingface-cli / HF_HOMEhttps://huggingface.co/docs/hubhf-mirror 镜像站https://hf-mirror.comModelScope 模型库与文档https://modelscope.cn清华 PyPI 镜像https://pypi.tuna.tsinghua.edu.cn