企业官网建设流程全解析

我先把话说在前面：开源模型这事，圈子里每天都有人问“模型在哪下”“怎么下这么慢”“有没有国内快一点的办法”。如果你这段时间刷到了 Qwen、Llama、DeepSeek、GLM 这些名字，想在自己电脑上跑个开源大模型或者小模型，那第一步永远卡在下载。HuggingFace 和 ModelScope（魔搭）是全球被用得最多的两个模型托管平台，一个偏国际生态，一个偏国内环境，很多新手一上来就被弄糊涂：到底该用哪个？为什么网页一直打不开？文件下到一半断掉怎么办？还有“pip install modelscope 报 externally-managed-environment”这种报错，网上搜了一堆答案没一个讲清楚。这篇文章就把我实际跑过的下载流程、踩过的坑、教训全盘写出来，从网页、命令行、Python 代码、镜像站四个角度把下载这件事捋明白，适合想在本地部署开源模型的开发者、AI 初学者，以及一切被大模型下载折磨过的人。

1. 先搞清楚你要面对的两个平台

1.1 HuggingFace：全球最大的模型社区，但不是为国内网络设计的

HuggingFace 是开源模型的中心仓库，GPT、Llama、Qwen、Stable Diffusion 这些模型几乎都会在 HuggingFace 上发布官方权重。它不光是存模型文件，还附带模型卡（Model Card）、推理代码示例、数据集、Space 在线 Demo，甚至能直接在网页上测试模型效果。你可以理解成 GitHub 和模型领域的 PyPI 合体，社区氛围浓，生态工具全，很多框架默认就是从 HuggingFace 拉模型。

但问题也很现实：这个平台的服务器在海外，国内直连的时候下载速度不稳定，有时候几 MB 的文件几分钟都拉不下来，几 GB 的权重文件更是折磨。而且 HuggingFace 经常有整站或者 API 连接超时的情况，不是你代码写得不对，是网络环境本身不够顺畅。所以国内开发者面对 HuggingFace 的第一课题，不是“怎么下”，而是“在现有网络条件下怎么下得快、下得稳”。

1.2 ModelScope（魔搭）：阿里开源的本土平台

ModelScope 是阿里开源的一个模型托管与推理平台，中文名叫“魔搭”，目前上面托管了数千个模型，尤其是中文优化过的模型，比如 Qwen 系列、通义系列，以及大量中文社区贡献的微调模型，很多会在 ModelScope 上首发。因为服务器在国内，下载速度普遍比 HuggingFace 直连快得多，网页加载也顺滑，不需要额外的网络适配，这对国内开发者来说是实打实的方便。

ModelScope 的定位是“全流程”，不只是下载，还包括在线体验、Notebook、训练微调、部署推理等功能。你可能会问：那我是不是只用 ModelScope 就够了？也不尽然。很多国际社区新出的模型，或者一些比较小众的仓库，首发还是在 HuggingFace，ModelScope 上的同步有一定滞后，甚至有些英文模型根本没有转载。所以两个平台其实是互补关系，最好的做法是两个都会用，按模型和网络情况灵活选择。

2. 模型下载前的准备工作

2.1 确认模型文件结构：哪些文件必须下载

很多人下载模型时，直接把整个仓库的几百个文件全拉下来，结果磁盘爆了，还根本用不上。我在本地跑开源模型时总结过一个经验：先看清仓库里的文件结构，再决定下载范围。一个典型的 HuggingFace 模型仓库至少包含这几类文件：

• config.json：模型架构、层数、注意力头数、词汇表大小等配置，这是模型能不能正确加载的地基，缺了它整个模型都启动不了。
• model.safetensors或pytorch_model.bin：真正的权重文件，也是体积最大的部分。safetensors是现代的推荐格式，加载更快、更安全。
• tokenizer.json、tokenizer_config.json、vocab.json：分词器相关文件，文本模型基本都会用到。
• generation_config.json：生成参数配置，比如 temperature、max_length 等默认值。
• 扩展文件如chat_template、README.md、示例脚本等，这些对核心运行不是必要的。

如果你只想跑一个 7B 参数的模型，model.safetensors往往就有 14GB 以上，而整个仓库可能有几十个不同版本的文件。我建议用allow_patterns只下载必要的文件，不要全仓下拉，后面我会给出具体代码。

2.2 用 Python 虚拟环境规避 externally-managed-environment

热词里有一个很典型的报错：pip install modelscope error: externally-managed-environment。这个错误我在新系统的 Ubuntu 和 Debian 环境上都遇到过，本质不是 modelscope 的问题，而是新版 Python 对系统环境的保护机制。

PEP 668 规定，从 Python 3.11 开始，很多 Linux 发行版会给系统级 Python 标记externally-managed，意思是你不能再直接用pip install往系统环境里塞包，避免破坏系统自带的 Python 工具链。解决办法有两个：一个是创建虚拟环境，用python3 -m venv .venv隔离出独立空间，在虚拟环境里随便装；另一个是给 pip 加--break-system-packages参数，但这个操作等于无视系统的保护措施，不建议在生产环境使用。我个人的建议是：把所有模型下载、推理相关的依赖都装进虚拟环境，这样既不会污染系统，也能避免很多环境依赖冲突。

python3 -m venv .venv source .venv/bin/activate pip install --upgrade pip pip install modelscope huggingface_hub

虚拟环境看起来多了一步操作，但长期用下来能省很多事。模型下载完要推理时，经常还要装torch、transformers、accelerate这些大包，如果全塞进系统 Python，一旦某个包版本冲突，排查成本非常高。虚拟环境相当于给每个项目一个独立的包仓库，出问题直接删掉重建，干净利落。

2.3 工具链准备与网络环境检查

下载开源模型之前，我建议先确认三样东西：git、git-lfs、huggingface_hub或modelscope。git用来拉取仓库信息，git-lfs用来拉大文件，huggingface_hub是 HuggingFace 官方提供的 Python 工具库，后面讲的代码下载方式全靠它。

git --version git lfs install pip show huggingface_hub modelscope

如果git lfs没有安装，下载大文件时会发现仓库里全是几百字节的指针文件，而非真实的权重内容，这个问题很隐蔽，等会儿我会专门讲。网络环境方面，国内访问 HuggingFace 时可以先做一次小测试：用浏览器打开一个模型页面，如果加载慢或者打不开，那就不建议硬等，直接上镜像站或者换 ModelScope。

3. HuggingFace 下载实操：四种主流方法

3.1 网页直接下载：适合小模型和临时取用

HuggingFace 每个模型仓库的页面右上角都有一个“下载”图标，点开后会弹出文件列表，勾选想下载的文件就能直接下载。这种方式最简单，适合几十 MB 到几百 MB 的小模型、分词器文件或者配置文件。但网页下载也有明显的坑：第一，大文件容易断，断了浏览器未必支持断点续传，经常重新来过；第二，有些仓库有几十个文件，手动一个一个点又累又容易漏；第三，如果网页本身加载不顺畅，下载体验会雪上加霜。所以网页下载只适合“临时拿个小文件”，真正要拉整个模型还是得走命令行或者代码。

3.2 git clone + Git LFS：适合整仓同步，但要防指针坑

如果你熟悉 Git 操作，可以像克隆代码仓库一样克隆模型仓库：

git clone https://huggingface.co/Qwen/Qwen2.5-7B-Instruct

这条命令会把你带入一个巨大的坑：如果没装git-lfs，克隆下来的仓库里，大文件全是指针文本，一个几 GB 的模型文件可能只有几百字节。原因是 HuggingFace 用 Git LFS 存放大文件，普通 Git 拉不下来真实内容。解决方法是先git lfs install，然后再次git lfs pull，或者用GIT_LFS_SKIP_SMUDGE=1跳过 LFS 下载但之后手动管理。

git lfs install git clone https://huggingface.co/Qwen/Qwen2.5-7B-Instruct cd Qwen2.5-7B-Instruct git lfs pull

如果网络环境一般，git clone大仓库时经常会中途卡住，要么超时，要么 LFS 下载中断。这时候可以先用GIT_LFS_SKIP_SMUDGE=1把代码和元数据先拉下来，再单独对 LFS 文件做断点继续，虽然操作复杂了一点，但至少比反复重来强。

3.3 huggingface_hub 代码下载：可控性最强

我个人最常用的是huggingface_hub的snapshot_download，因为它有断点续传、本地目录控制、文件过滤、并发下载这些优势，比git clone更适合大模型文件。

from huggingface_hub import snapshot_download snapshot_download( repo_id="Qwen/Qwen2.5-7B-Instruct", local_dir="./models/Qwen2.5-7B-Instruct", allow_patterns=["*.json", "*.safetensors", "*.txt", "*.model"], )

几个参数说明一下：

• repo_id：模型仓库的唯一标识，格式是“用户名/仓库名”。
• local_dir：下载后存放的本地目录，不填的话会存到 HuggingFace 的默认缓存目录。
• allow_patterns：只下载匹配规则的文件，用*.safetensors匹配所有权重文件，用*.json匹配配置文件，灵活控制体积。
• resume_download在老版本里可以显式开启，较新的版本默认支持断点续传，下载中断后重新执行同一条命令，会自动跳过已完成的文件。

代码下载最大的好处是可以写进脚本，比如做一个批量下载工具，把多个模型放进列表循环拉取，下载失败后自动重试，这在手动操作时完全不敢想。

3.4 用社区镜像站加速：网络环境下的常见替代方案

国内访问 HuggingFace 不稳定，很多开发者会配置社区维护的镜像站。最常被提及的是hf-mirror.com，它通过设置环境变量HF_ENDPOINT就能让huggingface_hub把请求指向镜像地址，代码本身不用做任何修改。

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

设置之后，再用snapshot_download或者transformers的from_pretrained加载模型时，流量会走镜像站，下载速度和稳定性都有明显改善。这个镜像站是社区公开的合规加速服务，不属于任何非常规手段，国内开发者把它当成常规网络优化工具在用。

需要注意的是，镜像站是缓存同步机制，某些最新发布的模型可能暂时没有镜像缓存，这时候模型页面上会提示“Not cached”，那就只能换 HuggingFace 原站或者 ModelScope 碰碰运气。另外，环境变量设置是终端会话级的，新开一个终端窗口之后要重新 export，如果想永久生效，可以写进~/.bashrc。

4. ModelScope（魔搭）下载实操

4.1 网页端操作：模型详情页的“下载模型”按钮

ModelScope 的网页体验相比 HuggingFace 对国内用户友好太多，加载快，界面全中文，找模型也方便。进入一个模型详情页，页面上能看到模型卡、文件列表和“下载模型”的按钮。网页下载方式适合小文件，和 HuggingFace 一样有断点问题，所以我更多是用命令行或者 Python SDK。

ModelScope 上有不少热门模型，比如Qwen/Qwen2.5-7B-Instruct、ZhipuAI/glm-4-9b-chat、deepseek-ai/DeepSeek-R1-Distill-Qwen-7B等，模型页会标注参数规模、支持语言、推理示例，选型比 HuggingFace 更直观。

4.2 modelscope 库安装与 Python SDK 下载

ModelScope 的官方 Python 库就是modelscope，安装命令很简单：

pip install modelscope

之后用snapshot_download下载模型，函数的用法和 huggingface_hub 很像：

from modelscope import snapshot_download model_dir = snapshot_download( model_id="Qwen/Qwen2.5-7B-Instruct", local_dir="./models/Qwen2.5-7B-Instruct", )

注意这里的参数名和 HuggingFace 不一样：ModelScope 用的是model_id，HuggingFace 用的是repo_id。local_dir参数同样可以控制下载位置，如果不填，默认会存到~/.cache/modelscope/hub目录，里面按“用户名/模型名”的目录结构存放。

ModelScope 的下载速度在国内网络环境下通常很快，我在实际测试中拉一个 7B 模型的权重文件，速度比 HuggingFace 直连高出不少，而且断线续传的能力也不错。如果你要下载的模型在 ModelScope 上有同步版本，优先用它。

4.3 modelscope CLI 下载与缓存目录管理

除了 Python API，ModelScope 还提供了命令行工具。新版 modelscope 支持modelscope download命令，可以直接按模型 ID 下载：

modelscope download --model Qwen/Qwen2.5-7B-Instruct --local_dir ./models/Qwen2.5-7B-Instruct

用 CLI 的好处是简单直接，适合不想写 Python 脚本的读者，而且可以在服务器上配合tmux或screen挂后台下载。缓存目录方面，ModelScope 默认会缓存到~/.cache/modelscope/hub，下载过的模型如果你用model_id再次加载，SDK 会优先检查缓存，不会重复下载大文件。

这里我想特别提醒：ModelScope 的缓存目录和 HuggingFace 的缓存目录不通用。你在 HuggingFace 下载过 Qwen，不等于 ModelScope 就能直接复用，两个平台的文件组织方式、索引结构都不同。如果磁盘空间紧张，建议用local_dir集中存放下载好的模型，用一个总的目录统一管理多个模型，后续找文件也方便。

5. 下载后的常见问题与排查技巧

5.1 下载到一半断了怎么办

这是所有大文件下载场景中最高频的问题。无论 HuggingFace 还是 ModelScope，几 GB 的权重文件下载到一半断线，很容易让人崩溃。解决办法的核心是“支持断点续传”。huggingface_hub和modelscope的snapshot_download默认都会对已完成的文件做校验和跳过，所以重新执行一遍下载命令，就能接着上次的进度继续，而不是从零开始。

另外，如果你用curl或者wget直接拉单个文件，记得加上断点续传参数：

wget -c https://hf-mirror.com/Qwen/Qwen2.5-7B-Instruct/resolve/main/model.safetensors

-c参数就是 continue，中断后重新执行会从断点继续。实测中，大文件下载最怕的就是中断后忘记续传，直接重新下载，白白浪费时间。我现在的习惯是：所有大模型下载都写进 Python 脚本，配合重试机制，下载失败自动重新执行snapshot_download，彻底告别手动监控。

5.2 “文件不完整”或“safetensors 加载失败”怎么排查

模型下完了，结果加载时报Error no file named pytorch_model.bin或者safetensors文件损坏，这种情况通常有几个原因。

首先是文件没下全。经常有人用网页方式手动下载，少勾了一个分片文件，比如model-00001-of-00004.safetensors，只下了前三个，加载时自然会报错。排查方法很简单，打开模型仓库文件列表，对照本地文件逐一检查文件名和大小，重点看是否有分片编号缺失。

其次是磁盘空间不足。大模型仓库动辄十几 GB，如果下载目录所在磁盘空间不够，文件写到一半就停了，但下载工具没有报错，最后得到一个残缺的权重文件。建议下载前用df -h看一下磁盘剩余空间，至少留出模型体积的 1.5 倍余量，因为还可能要存临时文件。

最后是 LFS 指针文件问题。如果用了git clone且没配置好 Git LFS，本地文件可能是指针而非真实权重，文件体积很小，但内容完全不对。用git lfs pull补拉即可。

5.3 显存不够：优先考虑量化版模型

很多新手下载了一个 7B 模型，满心期待跑起来，结果程序直接报CUDA out of memory。这不是模型文件有问题，而是硬件配置支撑不住。7B 模型对应的是大约 14GB 的 float16 权重，要跑推理至少需要 16GB 以上的显存，很多人的消费级显卡根本带不动。

一个实际可用的方案是下载量化版模型。所谓量化，简单类比就是把高精度浮点数压缩成低精度整数，模型文件体积变小，显存占用量大幅下降，推理速度反而可能更快，代价是生成质量有一点点损失。现在社区里最常见的量化格式有 GGUF 和 GPTQ，其中 GGUF 系列里Q4_K_M、Q5_K_M这类文件是性价比很高的选择。如果你想在低显存设备上跑模型，优先找带 GGUF 后缀的文件，配合llama.cpp系列的推理工具，效果不错。

我在实际测试中，用 8GB 显存跑 7B 模型的 Q4 量化版，速度基本能接受，生成质量在大部分场景下和原版差别不大，内存换显存的思路尤其适合本地部署。

5.4 pip install modelscope 报 externally-managed-environment 的完整修复流程

这个报错的高频程度在我收到的反馈里排得上前三。完整报错内容大致是：

error: externally-managed-environment × This environment is externally managed

原因我在前面讲过，是 PEP 668 的保护机制。完整的修复流程分三步走。

第一步，创建虚拟环境：

python3 -m venv .venv

第二步，激活虚拟环境：

source .venv/bin/activate

第三步，再安装 modelscope：

pip install modelscope

激活后，终端提示符前面会出现一个(.venv)前缀，此时 pip 已经和系统 Python 隔离，不会再触发保护报错。如果你需要跑 PyTorch 推理，顺便把相关依赖一起装进去：

pip install modelscope torch transformers accelerate

这里面的torch体积很大，CPU 版本和 GPU 版本的安装命令有区别，GPU 版需要去 PyTorch 官网选对应 CUDA 版本的安装命令，直接pip install torch装的是 CPU 版还是 GPU 版因版本而异，这一步经常有人踩坑。

如果你实在不想用虚拟环境，还有一个临时方案：

pip install modelscope --break-system-packages

这个命令能强制安装到系统环境，但我不建议长期这么干，因为你装的包多了之后，系统 Python 环境会变得混乱，遇到依赖冲突想排查会非常痛苦。虚拟环境多花两分钟，后面能省两小时。

5.5 下载慢不是模型的问题，可能是并发和协议的问题

最后补充一个很多人忽略的点：同一个模型文件，用不同工具下载，速度差距会非常大。我在实验中对比过几种方式，仅就 HuggingFace 直连场景而言，git clone的速度通常不如snapshot_download，原因之一是snapshot_download会用多线程并发拉取多个文件，而git clone的 LFS 拉取往往是逐个进行的。镜像站配合snapshot_download，可能是国内环境下速度最稳的组合。

ModelScope 方面，官方 SDK 的下载优化在近几个版本里做了很多改进，如果发现某个版本下载速度不理想，先升级到最新版再试：

pip install -U modelscope huggingface_hub

写在最后

我个人的习惯是：模型在国内有官方同步或者中文优化版本时，优先用 ModelScope 下载，速度快、省心省事；模型需要最新权重或者只有 HuggingFace 有时，用huggingface_hub配镜像站下载，小模型直接网页拿，大模型一律脚本化处理。这几种方式配合起来，基本能覆盖 90% 的下载场景。至于下载后怎么加载、怎么做推理、怎么量化，那是另一篇长文的话题了，但你可以放心的是，只要模型文件完整地到了本地，后面的一切都有路可走。这篇东西如果对你有用，下次朋友再问“模型到底在哪下”，直接把链接甩给他就行。