Hugging Face 是全球最大的AI模型与数据集分享平台。对于国内开发者来说，下载模型时常会遇到网络连接慢、甚至超时的问题。本教程将通过几条简单的命令，带你轻松完成数据集和模型的下载，并解决网络访问障碍。

读完这篇教程，你将学到：

• 如何安装并使用 Hugging Face 下载工具
• 如何配置国内镜像源，实现高速下载
• 如何下载数据集和模型，并保存到本地
• 一个实用案例：下载多模态大模型到本地

第一步：安装 Hugging Face 下载工具

首先，我们需要安装 huggingface_hub 这个 Python 包。它自带了一个叫做 hf 的命令行工具，方便我们直接在终端里下载资源。

pip install huggingface_hub

安装完成后，建议检查一下是否成功：

hf --help

如果出现帮助信息，说明工具已经可以正常使用了。本教程使用的是 0.36.2 版本（0.23.0 以上版本均自带 hf 命令）。

💡 小提示：hf login 命令用于登录 Hugging Face 账号，下载公开资源时并非必要，但如果你需要下载私有仓库或上传文件，则需要先登录。

第二步：配置国内镜像源（关键！）

由于网络环境限制，直接从 Hugging Face 官方服务器下载往往速度极慢，甚至直接超时。这里我们使用 hf-mirror.com 提供的镜像服务。

在终端中执行以下命令：

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

这行命令会让 hf 工具从国内镜像站下载资源，速度会大幅提升。

⚠️ 注意：这个设置仅在当前终端窗口有效。关闭窗口后需要重新设置。如果想永久生效，可以将这行命令添加到 ~/.bashrc 或 ~/.zshrc 文件中。

第三步：下载数据集

设置好镜像源后，我们就可以开始下载了。首先下载一个示例数据集 unsloth/Radiology_mini：

hf download unsloth/Radiology_mini --repo-type dataset --local-dir ./radiology_mini

命令参数说明：

• unsloth/Radiology_mini：数据集的名称（格式为 作者/数据集名）
• --repo-type dataset：指定资源类型为"数据集"
• --local-dir ./radiology_mini：指定下载到本地的 radiology_mini 文件夹中

执行后，你会在当前目录下看到一个名为 radiology_mini 的新文件夹，里面就是下载好的数据。

第四步：下载模型

下载模型的方式与数据集几乎一模一样，唯一的区别是不需要指定 --repo-type 参数（因为默认为 model 类型）。

以常用的中文嵌入模型 BAAI/bge-small-zh-v1.5 为例：

hf download BAAI/bge-small-zh-v1.5 --local-dir ./bge-small-zh-v1.5

下载完成后，模型文件就会保存在 bge-small-zh-v1.5 文件夹中。之后在代码中就可以直接通过本地路径加载模型，无需再联网：

from langchain_huggingface import HuggingFaceEmbeddings

embeddings = HuggingFaceEmbeddings(
    model_name="./bge-small-zh-v1.5",
    model_kwargs={'device': 'cuda'},
    encode_kwargs={'normalize_embeddings': True}
)

进阶实战：下载多模态大模型

掌握了基本的下载方法后，我们来挑战一个更高级的任务——下载一个多模态大模型。多模态模型可以同时处理文本和图像等多种类型的数据，是当下AI应用的热门方向。

下面以 Qwen2.5-VL-7B-Instruct-bnb-4bit 为例（一个已经做过 4-bit 量化的视觉-语言模型，体积更小，适合本地部署）：

hf download unsloth/Qwen2.5-VL-7B-Instruct-bnb-4bit --local-dir ./Qwen2.5-VL-7B-Instruct-bnb-4bit

💡 知识点：bnb-4bit 表示该模型已经使用 BitsAndBytes 技术进行了 4-bit 量化压缩。量化后的模型占用显存更少，适合在普通显卡上运行，是入门学习多模态大模型的一个不错起点。

总结

回顾一下，我们通过以下四个步骤完成了从零到一的下载之旅：

步骤	命令/操作
安装工具	pip install huggingface_hub
配置镜像	export HF_ENDPOINT=https://hf-mirror.com
下载数据集	hf download unsloth/Radiology_mini --repo-type dataset --local-dir ./radiology_mini
下载模型	hf download BAAI/bge-small-zh-v1.5 --local-dir ./bge-small-zh-v1.5

现在，你已经掌握了在国内环境下高效下载 Hugging Face 资源的方法。无论是构建 RAG 应用需要的数据集和嵌入模型，还是运行多模态大模型，这套流程都能帮你扫清网络障碍，让学习之路更加顺畅。