[AI/GPT] Hugging Face : 开源大模型社区 | 机器学习（ML）和数据科学平台和社区、AI领域的Github

0 序

笔者近期在研究/实践 AI智能体应用开发的相关技术栈。
AI LLM基础模型的训练、研究也好，AI应用开发也罢，除了Github外，也必然都离不开 Hugging Face(抱抱脸社区) 或 ModelScope(阿里版/魔搭社区)。

这类社区的核心价值————提供了：

提供了AI技术开发者的交流平台

提供了丰富的模型 / 数据集

本文对 Hugging Face(抱抱脸社区) 的使用经验m进行一点记录/总结。

1 概述：Hugging Face

简介

Hugging Face（抱抱脸）是一个机器学习（ML）和数据科学平台和社区，帮助用户构建，部署和训练机器学习模型，成立于2016年的人工智能公司。

作为一个流行的自然语言处理 (NLP) 模型库和社区，提供了大量预训练模型、工具和资源，使得 NLP 的开发者和研究人员能够快速高效地构建和应用各种文本相关应用。
抱脸相当于Ai界的GitHub，里面的模型都是开源免费的，非常适合AI开发者使用。

https://github.com/huggingface

https://huggingface.co

专注领域: 开源人工智能库

Hugging Face提供了在实时应用程序中演示、运行和部署人工智能（AI）的基础设施。用户还可以浏览其他人上传的模型和数据集。

Hugging Face通常被称为机器学习的GitHub，因为它允许开发人员公开分享和测试他们的工作。

开源大模型社区： HuggingFace vs ModelScope(魔搭社区)

HuggingFace：类似于github，模型比较全，但是需要 ke.xue 上网；

https://huggingface.co/

ModelScope/魔搭：阿里开源的大模型平台，模型相对不是很全，速度比较快；

https://modelscope.cn/

HuggingFace的优点：

丰富的预训练模型资源：

广泛的适用性：Hugging Face 提供了大量的预训练模型，这些模型已经在海量的数据上进行了训练，能够处理各种自然语言处理任务，如文本分类、情感分析、问答、机器翻译等。无论您是从事学术研究、商业应用还是个人项目开发，都可以找到适合的预训练模型，节省大量从头训练模型的时间和资源。

高质量与不断更新：其预训练模型经过了专业的训练和优化，具有较高的性能和准确性。而且，Hugging Face 平台不断更新和改进模型，以适应不断变化的自然语言处理需求和技术发展。

方便的工具和库：

Transformers 库：Hugging Face 的 Transformers 库是自然语言处理领域的重要工具，它支持多种预训练模型的加载、使用和微调，如 BERT、GPT、RoBERTa 等。该库提供了简单易用的接口，使得开发者可以轻松地将这些强大的模型集成到自己的项目中，快速实现自然语言处理功能。

数据集管理工具：Hugging Face 提供了方便的数据集管理工具，如 Datasets 库，可以帮助用户轻松地下载、处理和管理各种公开的数据集。这使得数据的准备工作变得更加高效，减少了数据处理过程中的繁琐操作。

发展历程

2016年，公司成立。首席执行官&联合创始人为Clément Delangue。

2016年，法国创业者三名创业者Clément Delangue、Julien Chaumond 和 Thomas Wolf 在纽约成立了Hugging Face。

2016-2017:聊天机器人(第一个产品)

Hugging Face，它的第一个产品是一个聊天机器人。

到2017年，Hugging Face聊天机器人拥有了独特的功能，并可以进行高效的对话。

团队将其产品定位为为无聊青少年量身打造的个性鲜明的聊天机器人。

2018年5月，完成种子融资。通过本轮融资，Hugging Face团队继续专注于以下领域：改进产品；建立一支优秀的工程师团队；深入研发自然语言对话，并撰写了几篇研究论文。

虽然当时产品还没有带来可观的收入，但团队对核心价值和技术共享的强调为Hugging Face创造了一个转折点。

2018 年，Hugging Face迎来了关键时刻，Hugging Face的创始人在网上免费分享该应用的部分代码，其中一个重要的开源框架名为Transformers，目前已被下载超过一百万次。

GitHub项目获得了上万颗星，这表明开源社区认为它很有价值。

微软、谷歌和 Facebook 的研究人员一直在用它做实验，某些公司甚至在生产中使用了它。

Transformers 可用于各种任务，包括文本分类、信息提取、总结、文本生成和对话式人工智能。

最终，Hugging Face团队迎来了一个转折点，将公司从一家不太赚钱的AI聊天机器人初创公司转变为未来估值十亿美元的AI独角兽。

在接下来的几年里，Hugging Face 团队继续专注于产品建设和社区发展，并取得了令人瞩目的成就：
2024年1月，Hugging Face宣布与谷歌云（Google Cloud）建立战略合作伙伴关系。
2024年10月，Hugging Face更新了月度榜单，智源研究院的BGE模型登顶榜首，这是中国国产AI模型首次成为Hugging Face月榜冠军。BGE在短短一年时间内，总下载量已超数亿次，是目前下载量最多的国产AI系列模型。
Hugging Face 已成为扩展最快的社区和使用最广泛的机器学习平台！

平台上有 10 万个预训练模型和 1 万个数据集，涵盖 NLP、语音、时间序列、强化学习、计算机视觉、生物、化学等领域。

Hugging Face Hub 已发展成为机器学习构建者开发、协作和部署尖端模型的家园。

目前有10000 多家公司使用 Hugging Face来构建机器学习技术，Hugging Face 帮助这些机器学习工程师和数据科学家团队节省了大量时间，加快了机器学习项目的进度。

Hugging Face还领导着 BigScience，一个专注于研究和构建大语言模型的合作研讨会。这项计划汇集了来自不同领域和背景的1000多名研究人员，BigScience 致力于训练世界上最大的开源多语言模型。

Hugging Face为什么能成功？

赶上Transformer相继在AI的细分领域NLP、泛AI领域爆火；
军阀混战，谷歌TensorFlow Bert, FaceBook PyTorch，跑一下模型需要各种环境；
人家是一个舞台/平台，不是一个工具，那后来的人，也只能在这上面玩。

Models / Spaces / Datasets

Hugging Face 是一个旨在推动自然语言处理（NLP）技术和工具发展的开源社区和公司。

平台有海量的开源模型，以及数据集，致力于提供各种NLP任务中的最新技术、模型和工具，为开发者提供便捷的方式来使用、微调和部署这些技术。

https://pic2.zhimg.com/v2-c656c728e5c1f378972e7d3bcc5d20eb_1440w.jpg

模型Model

https://pic2.zhimg.com/v2-9691c0bbe5ac744be87468198bc7adb5_1440w.jpg

自然语言处理：文本分类、文本生成，文本转语音、文本填空、文本摘要等；
计算机视觉：图片分类、物体识别、文本转图片、题、图片转文本、图片特征提取等；
音频：文本转语音、语音转文本、语音识别、语音分类等；
多模态：Image-Text-to-Text、Video-Text-to_text

数据集/DataSet

https://pic4.zhimg.com/v2-682e9023c1951264abb6ad74e3781e0d_1440w.jpg

互联网开源的一些最标准的语料库，可以用来训练或者微调你的模型，其特点为：

包含丰富的数据集：IMDB, CoNLL-2003和GLUE等；

简化数据集的下载、预处理操作；

提供数据集分割、采样和迭代器的功能；

应用/Spaces

https://pic4.zhimg.com/v2-b7fe3f9d7c2147d40bc38925e80cfe61_1440w.jpg

2 应用指南

安装篇 for Hugging Face

安装 Hugging Face

在命令行中输入 pip install transformers 就可以安装 Hugging Face 的 transformers 库。
两大模块的对比 : transformers vs. huggingface-hub

特性	`transformers`	`huggingface-hub`
核心目的	运行和训练模型	管理和传输模型文件
是否包含模型架构	是 (BERT, GPT, ViT 等代码)	否 (只管文件，不管内容)
能否直接推理	能 (`pipeline`, `model.generate`)	不能 (只能下载文件)
能否上传模型	能 (通过内置的 `push_to_hub` 方法，底层调用 hub 库)	能 (原生支持上传功能)
安装包大小	较大 (包含大量模型代码)	较小 (轻量级工具)
依赖关系	包含 `huggingface-hub`	不包含 `transformers`
典型用户	算法工程师、数据科学家、应用开发者	MLOps 工程师、需要自定义下载逻辑的开发者

前置环境安装

conda
python 3.10
cuda 安装（可选）

安装 Hugging Face 底层交互工具库 : hf_hub_download

安装 Hugging Face 底层交互工具库

安装的是底层交互工具库。它主要用于与 Hugging Face Hub（模型托管平台）进行交互，比如下载文件、上传模型、管理仓库、登录账号等。它不包含运行模型所需的神经网络架构代码。

主要功能：提供了一个 Python 客户端，用于与 https://huggingface.co 网站进行文件级交互。它不关心模型内部是怎么运行的，只关心文件的下载、上传和管理。

核心功能：

hf_hub_download: 下载特定的文件（不仅仅是模型权重，也可以是数据集、配置文件等）。

upload_folder: 将本地文件夹上传到 Hub 仓库。

login / logout: 管理访问令牌。

创建仓库、删除文件等管理操作。

# 代码示例
from huggingface_hub import hf_hub_download
# 仅下载文件到本地缓存，返回文件路径
file_path = hf_hub_download(
    repo_id="bert-base-uncased", 
    filename="pytorch_model.bin"
)
print(f"文件已下载到: {file_path}")
# 注意：这里你还无法直接运行模型，因为没有加载逻辑

使用场景：

你想下载一个大模型的权重文件，但不想立即加载它，或者想手动管理缓存。
你训练好了自己的模型，想要上传到 Hugging Face Hub 分享给社区。
你在编写一个轻量级工具，只需要下载资源而不需要完整的 transformers 重型依赖。

依赖关系：非常轻量，主要依赖 requests, filelock, fsspec 等。它不会安装 transformers 或 torch。

#pip install huggingface-hub
#pip install --upgrade huggingface-hub
pip install -U huggingface_hub

安装 Hugging Face 核心模型库 : transformers

安装 Hugging Face 核心模型库

安装的是核心模型库。如果你想要加载、运行或微调具体的 AI 模型（如 BERT, GPT, Llama 等），你需要这个。它通常会自动把 huggingface-hub 作为依赖项一起安装。

主要功能：提供了数千种预训练模型（用于文本、图像、音频等）的架构实现和推理/训练代码。

核心类：AutoModel, AutoTokenizer, Pipeline 等。

使用场景：

加载一个模型进行推理（例如：情感分析、文本生成）。

微调（Fine-tuning）一个预训练模型。

使用 pipeline 快速调用任务。
例如：

from transformers import pipeline
# 直接加载并运行模型
classifier = pipeline("sentiment-analysis")
print(classifier("I love using Hugging Face!"))

依赖关系：安装 transformers 时，pip 自动会安装 huggingface-hub、torch (PyTorch) 或 tensorflow、numpy 等必要的依赖库。

pip install transformers

安装 Hugging Face : datasets / tokenizers

pip install datasets tokenizers

查验版本

#(ai-env) PS D:\xxxx\> huggingface-cli version
⚠️  Warning: 'huggingface-cli version' is deprecated. Use 'hf version' instead.
huggingface_hub version: 0.36.2
#(ai-env) PS D:\xxxx\> hf version
huggingface_hub version: 0.36.2

模型管理

使用场景

浏览 Hugging Face 的模型库

找到适合你项目需求的模型。
可以通过搜索或筛选来缩小范围。
点击模型名称进入模型主页，可以查看模型的详细信息、用法示例、源代码等。

下载并使用模型

使用 from transformers import MODEL_NAME 导入模型。
实例化模型：model = MODEL_NAME.from_pretrained('MODEL_NAME')。其中 MODEL_NAME 是模型的名称或路径。
准备输入数据，转换为模型支持的格式。（如 tokenizer 后的文本、图像等）
调用模型并获得输出：outputs = model(inputs)。其中 inputs 是模型的输入数据。

手动下载模型

huggingface-cli --resume-download BAAI/bge-m3 --local-dir D:/Program-Data/ai-models/bge-m3

或
huggingface-cli --endpoint=https://hf-mirror.com download --resume-download BAAI/bge-m3 --local-dir D:/Program-Data/ai-models/bge-m3

保存和加载模型

使用 model.save_pretrained('PATH') 将模型保存到指定路径。
使用 MODEL_NAME.from_pretrained('PATH') 来加载模型。

效果展示-文本分类

from transformers import pipeline, AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")
model = pipeline("text-classification", model="distilbert-base-uncased-finetuned-sst-2-english")

text = "This movie is really good!"
inputs = tokenizer(text, return_tensors="pt")
outputs = model(**inputs)

print(f"Input text: {text}")
print(f"Predicted label: {outputs[0]['label']}, score: {outputs[0]['score']:.2f}")

out:

Input text: This movie is really good!
Predicted label: POSITIVE, score: 0.99

效果展示-命名实体识别

from transformers import pipeline, AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("bert-base-cased")
model = pipeline("ner", model="dslim/bert-base-NER")

text = "Hugging Face is a startup based in New York City"
inputs = tokenizer(text, return_tensors="pt")
outputs = model(**inputs)

for entity in outputs:
    print(f"Entity: {entity['word']}, Type: {entity['entity']}, Score: {entity['score']:.2f}")

out:

Entity: New, Type: B-LOC, Score: 0.24
Entity: York, Type: I-LOC, Score: 0.28
Entity: City, Type: I-LOC, Score: 0.25

高阶玩法

Fine-tuning 模型

在 Hugging Face 中，我们可以使用预训练模型进行 fine-tuning，以适应特定任务或领域的需求。以下是一个简单的示例：

from transformers import Trainer, TrainingArguments

training_args = TrainingArguments(
    output_dir='./results',
    num_train_epochs=1,
    per_device_train_batch_size=16,
    per_device_eval_batch_size=64,
    warmup_steps=500,
    weight_decay=0.01,
    logging_dir='./logs',
)

trainer = Trainer(
    model=model,
    args=training_args,
    train_dataset=train_dataset,
    eval_dataset=eval_dataset,
)

trainer.train()

自定义模型和 Tokenizer: 如果 Hugging Face 提供的现成模型无法满足需求，我们可以通过继承 PreTrainedModel 和 PreTrainedTokenizer 类来创建自己的模型和 Tokenizer。
使用Hugging Face Hub: Hugging Face Hub 是一个在线平台，可以轻松共享、发现和使用各种 NLP 模型。我们可以使用 upload() 函数将自己的模型上传到 Hub 上，并使用 from_pretrained() 函数来加载其他人分享的模型。

J 最佳实践

CASE `bge-m3`嵌入模型的下载示例

假设需将模型下载至本地路径:

D:\Program-Data\ai-models\bge-m3

model_download.py

# @install-command pip install -U huggingface_hub

from huggingface_hub import snapshot_download

# 下载完整模型到指定目录
model_local_dir=r"D:\Program-Data\ai-models\bge-m3"
snapshot_download(
    endpoint="https://hf-mirror.com", # 可选配置项
    repo_id="BAAI/bge-m3",
    local_dir=model_local_dir,  # 使用 r"" 处理 Windows 路径
    local_dir_use_symlinks=False,  # Windows 建议禁用符号链接 (deprecated 配置项)
    resume_download=True,  # 支持断点续传 (deprecated 配置项)
    ignore_patterns=[".DS_Store", "**/.DS_Store"],  # 关键：忽略指定的 .DS_Store 等无关紧要但又阻塞下载使用的文件 (可选配置项)
    max_workers=4 # 可选配置项
)

CASE `bge-m3`嵌入模型的使用示例

假设已将模型下载至本地路径:

D:\Program-Data\ai-models\bge-m3

`model_use.py`

model_use.py

import torch
from transformers import AutoModel, AutoTokenizer

# @install-command : pip install transformers -U

# 设置模型本地路径
MODEL_PATH = r"D:\Program-Data\ai-models\bge-m3"

def load_bge_m3_model(model_path):
    """
    加载本地的 BGE-M3 模型和分词器
    """
    # 加载(本地模型目录下的)分词器
    tokenizer = AutoTokenizer.from_pretrained(
        model_path,
        trust_remote_code=True  # 信任远程代码（本地模型也建议开启）
    )
    print(f"分词器(`{model_path}`)加载成功, 词汇表大小: {len(tokenizer)}")

    # 加载(本地模型目录下的)模型
    model = AutoModel.from_pretrained(
        model_path,
        trust_remote_code=True,
        torch_dtype=torch.float16 if torch.cuda.is_available() else torch.float32  # 根据GPU情况选择精度
    )
    model = AutoModel.from_pretrained(model_path)
    print(f"模型加载成功！model_path:{model_path}")

    # 如果有GPU则使用GPU
    if torch.cuda.is_available():
        model = model.cuda()
    model.eval()  # 设置为评估模式

    return tokenizer, model


def text_to_vector(text, tokenizer, model, max_length=512):
    """
    将文本转换为词向量
    :param text: 输入文本
    :param tokenizer: 分词器
    :param model: BGE-M3 模型
    :param max_length: 最大序列长度
    :return: 归一化后的词向量
    """
    # 文本预处理（BGE-M3 建议添加指令以提升效果）
    if isinstance(text, str):
        text = [text]

    # 为文本添加指令（BGE-M3 推荐的做法）
    texts = [f"为句子生成表示以用于检索：{t}" for t in text]

    # 分词处理
    inputs = tokenizer(
        texts,
        padding=True,
        truncation=True,
        max_length=max_length,
        return_tensors="pt"
    )

    # 如果有GPU则将数据移到GPU
    if torch.cuda.is_available():
        inputs = {k: v.cuda() for k, v in inputs.items()}

    # 模型推理（不计算梯度以提升速度）
    with torch.no_grad():
        outputs = model(**inputs)
        # 获取 cls token 的输出作为句子向量
        embeddings = outputs.last_hidden_state[:, 0]

    # 对向量进行归一化（重要：BGE-M3 推荐归一化后再使用）
    embeddings = torch.nn.functional.normalize(embeddings, p=2, dim=1)

    # 转换为 numpy 数组（方便后续使用）
    return embeddings.cpu().numpy()


# 主程序
if __name__ == "__main__":
    # 1. 加载模型
    print("正在加载 BGE-M3 模型...")
    tokenizer, model = load_bge_m3_model(MODEL_PATH)
    print("模型加载完成！")

    # 2. 待向量化的文本
    test_texts = [
        "人工智能的发展前景",
        "自然语言处理技术应用",
        "深度学习模型的优化方法"
    ]

    # 3. 转换为词向量
    print("\n正在将文本转换为词向量...")
    vectors = text_to_vector(test_texts, tokenizer, model)

    # 4. 输出结果
    print("\n===== 词向量结果 =====")
    for i, (text, vector) in enumerate(zip(test_texts, vectors)):
        print(f"\n文本 {i + 1}: {text}")
        print(f"向量维度: {vector.shape}")
        print(f"向量前10个值: {vector[:10]}")

    print("\n===== End =====")

output

正在加载 BGE-M3 模型...
`torch_dtype` is deprecated! Use `dtype` instead!
Loading weights: 100%|██████████| 391/391 [00:00<00:00, 5099.31it/s]
模型加载完成！

正在将文本转换为词向量...

===== 词向量结果 =====

文本 1: 人工智能的发展前景
向量维度: (1024,)
向量前10个值: [-0.02153006  0.02445538 -0.01284085 -0.00592102 -0.02642504 -0.01556859
 -0.02899093  0.01911393  0.02745656  0.01848436]

文本 2: 自然语言处理技术应用
向量维度: (1024,)
向量前10个值: [ 0.00515539  0.01815949 -0.01342954 -0.01135934 -0.02229034 -0.0501532
  0.00661757  0.01158579  0.01313804  0.00444965]

文本 3: 深度学习模型的优化方法
向量维度: (1024,)
向量前10个值: [-0.00628681 -0.02844838 -0.0307115  -0.02349896 -0.03515806 -0.02898631
  0.03149441 -0.00161717  0.00621724  0.03546201]
pydev debugger: warning: trying to add breakpoint to file that does not exist: d:\python console.py (will have no effect)

===== End =====

Z FAQ for Hugging Face

Q: `huggingface-cli` 下载指定模型的过程很成功，但最后报403权限不足问题？

问题描述

执行命令 huggingface-cli --endpoint=https://hf-mirror.com download --resume-download BAAI/bge-m3 --local-dir D:/Program-Data/ai-models/bge-m3，执行过程很成功；
但最后报 403 错误：

...
File "C:\Users\EDY\.conda\envs\ai-env\Lib\site-packages\requests\models.py", line 1026, in raise_for_status
    raise HTTPError(http_error_msg, response=self)
requests.exceptions.HTTPError: 403 Client Error: Forbidden for url: https://hf-mirror.com/api/resolve-cache/models/BAAI/bge-m3/5617a9f61b028005a4858fdac845db406aefb181/imgs%2F.DS_Store

原因分析

这是一个典型的 Hugging Face 镜像站下载问题。让我分析错误并提供解决方案。
根本原因：.DS_Store 文件权限问题

错误信息显示下载 imgs/.DS_Store 文件时返回 403 Forbidden。
它是一种由MacOS系统自动创建的隐藏文件（存储文件夹图标位置和视图设置），存在于每一个用「访达」打开过的文件夹下面；但在 Hugging Face 仓库中通常没有设置公开的读取权限。
DS_Store，英文全称是 Desktop Services Store（桌面服务存储），开头的 DS 是 Desktop Services（桌面服务）的缩写。

为什么其他文件成功，只有这个失败？

模型权重文件（如 .bin, .safetensors）是公开的

但 .DS_Store 这类系统文件往往被误上传且权限未开放，或镜像站对隐藏文件有特殊限制

解决方案（按推荐顺序）

方案 0 : 使用 git 下载（仅下载代码，不下载模型文件）【亲测】

使用 Git LFS 的跳过下载模式

如果你只需要代码文件，不需要大模型文件时:

# 先安装 Git LFS
git lfs install

# 为避免 Git LFS (Large File Storage) 下载失败的问题，导致类似报错: `dial tcp: lookup cas-bridge.xethub.hf-mirror.org: no such host`( LFS 文件的存储域名无法解析)
## windows cmd
set GIT_LFS_SKIP_SMUDGE=1

# 克隆模型仓库 到指定目录下
git clone https://huggingface.co/BAAI/bge-m3 D:\Program-Data\ai-models\bge-m3

# 如果需要手动下载模型文件，可以后续用 wget/curl 单独下载

https://hf-mirror.com

方案 1：使用 `--include` 参数只下载必要文件（推荐）

huggingface-cli --endpoint=https://hf-mirror.com download \
  --resume-download BAAI/bge-m3 \
  --local-dir D:/Program-Data/ai-models/bge-m3 \
  --include "*.json" "*.bin" "*.safetensors" "*.txt" "*.md" "model*" "token*" "config*" "sentence*"

huggingface-cli --endpoint=https://hf-mirror.com download --resume-download BAAI/bge-m3 --local-dir D:/Program-Data/ai-models/bge-m3 --include ".json" ".bin" ".safetensors" ".txt" ".md" "model" "token" "config" "sentence*"
huggingface-cli --endpoint=https://hf-mirror.com download --resume-download BAAI/bge-m3 --local-dir D:/Program-Data/ai-models/bge-m3

这会显式包含模型必需的文件，自动排除 .DS_Store 等无关文件。

方案 2：使用 `--exclude` 参数排除问题文件

huggingface-cli --endpoint=https://hf-mirror.com download \
  --resume-download BAAI/bge-m3 \
  --local-dir D:/Program-Data/ai-models/bge-m3 \
  --exclude ".DS_Store" "*/.DS_Store" "*.DS_Store"

方案 3：使用 `--ignore-patterns`（如果 CLI 版本支持）

huggingface-cli --endpoint=https://hf-mirror.com download \
  --resume-download BAAI/bge-m3 \
  --local-dir D:/Program-Data/ai-models/bge-m3 \
  --ignore-patterns ".DS_Store"

方案 4：手动完成下载（如果已下载大部分）

由于错误发生在最后阶段，模型核心文件可能已下载完成。检查目录：

dir D:\Program-Data\ai-models\bge-m3

如果已有 model.safetensors 或 pytorch_model.bin、config.json、tokenizer.json 等核心文件，说明模型已可用，可以手动删除未完成的临时文件：

# 删除未完成的下载临时文件
del D:\Program-Data\ai-models\bge-m3\*.lock
del D:\Program-Data\ai-models\bge-m3\*.incomplete

方案 5：使用 `huggingface_hub` Python 代码下载（更精细控制）【亲测/推荐】

# @install-command pip install -U huggingface_hub

from huggingface_hub import snapshot_download

# 下载完整模型到指定目录
model_local_dir=r"D:\Program-Data\ai-models\bge-m3"
snapshot_download(
    endpoint="https://hf-mirror.com", # 可选配置项
    repo_id="BAAI/bge-m3",
    local_dir=model_local_dir,  # 使用 r"" 处理 Windows 路径
    local_dir_use_symlinks=False,  # Windows 建议禁用符号链接 (deprecated 配置项)
    resume_download=True,  # 支持断点续传 (deprecated 配置项)
    ignore_patterns=[".DS_Store", "**/.DS_Store"],  # 关键：忽略指定的 .DS_Store 等无关紧要但又阻塞下载使用的文件 (可选配置项)
    max_workers=4 # 可选配置项
)

快速验证模型完整性

下载完成后，验证 BGE-M3 模型是否可用：

from transformers import AutoModel, AutoTokenizer

model_path = "D:/Program-Data/ai-models/bge-m3"

# 测试加载
tokenizer = AutoTokenizer.from_pretrained(model_path)
model = AutoModel.from_pretrained(model_path)

print("模型加载成功！")
print(f"词汇表大小: {len(tokenizer)}")

总结

方案	适用场景	命令复杂度
方案 1 `--include`	只想下载模型文件，不关心其他	⭐ 推荐
方案 2 `--exclude`	需要排除特定文件	简单
方案 3 Python 代码	需要精细控制或集成到脚本	中等
方案 4 手动处理	已下载大部分，只差最后一步	最简单

最可能的原因：hf-mirror.com 镜像站对 .DS_Store 这类隐藏文件有访问限制，或该文件在源仓库中本身权限设置不当。这不是你的网络或认证问题，而是特定文件的权限配置问题。

Q:`pip install --upgrade sentence-transformers transformers tokenizers huggingface_hub` 这些模块都是 huggingface社区的吗？模块间的关系是什么？

这四个模块都属于 Hugging Face 社区，但它们的功能定位和层级关系各不相同。让我为你梳理清楚：

pip install --upgrade transformers sentence-transformers tokenizers huggingface_hub

这四个模块构成了 Hugging Face 从底层分词 → 模型架构 → 应用封装 → 平台交互的完整工具链，形成了层次分明的依赖关系。

模块归属确认

模块名	包名	归属	核心功能
`transformers`	`transformers`	✅ Hugging Face	提供预训练模型架构（BERT、GPT、T5 等）和高层 API
`sentence-transformers`	`sentence-transformers`	✅ Hugging Face	专门用于生成句子嵌入（Sentence Embeddings）
`tokenizers`	`tokenizers`	✅ Hugging Face	高性能文本分词（Rust 实现）
`huggingface_hub`	`huggingface_hub`	✅ Hugging Face	与 Hugging Face Hub 交互（下载/上传模型）

模块间的关系图

┌─────────────────────────────────────────────────────────────┐
│                    Hugging Face 生态系统                      │
└─────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        │                     │                     │
        ▼                     ▼                     ▼
┌───────────────┐    ┌───────────────┐    ┌─────────────────┐
│  huggingface  │    │  tokenizers   │    │   transformers  │
│     _hub      │    │   (分词工具)   │    │    (模型架构)    │
│               │    │               │    │                 │
│ • 模型下载    │    │ • Rust 核心   │    │ • AutoModel     │
│ • 模型上传    │    │ • 极速分词    │    │ • AutoTokenizer │
│ • 仓库管理    │    │ • BPE/WordPiece│   │ • 管道 Pipeline │
└───────────────┘    └───────────────┘    └─────────────────┘
                                                   │
                                                   ▼
                                        ┌─────────────────┐
                                        │ sentence-       │
                                        │ transformers    │
                                        │                 │
                                        │ • 句子嵌入生成  │
                                        │ • 语义搜索      │
                                        │ • 文本相似度    │
                                        └─────────────────┘

层级关系详解

1. 基础层：`tokenizers`

定位：最底层的基础工具
特点：用 Rust 编写，速度极快（1GB 文本 < 20 秒）
功能：实现 BPE、WordPiece、Unigram 等分词算法
被依赖：transformers 的 AutoTokenizer 底层使用的就是这个库

2. 核心层：`transformers`

定位：Hugging Face 的核心库
功能：提供各种预训练 Transformer 模型架构
包含：
- AutoModel：自动加载模型
- AutoTokenizer：自动加载分词器（内部调用 tokenizers）
- pipeline：高层推理接口

3. 应用层：`sentence-transformers`

定位：建立在 transformers 之上的应用层库
关系：sentence-transformers = transformers + 池化层 + 对比学习微调
专门用途：
- 将句子编码为固定维度的向量
- 语义相似度计算
- 语义搜索、RAG 检索增强生成

4. 工具层：`huggingface_hub`

定位：与 Hugging Face Hub 平台交互的客户端
功能：
- 下载模型（from_pretrained 的底层实现）
- 上传模型到 Hub
- 管理仓库、搜索模型

依赖关系链

sentence-transformers 
    └── 依赖 transformers
            └── 依赖 tokenizers (底层分词)
            └── 依赖 huggingface_hub (模型下载)
    
tokenizers (可独立使用)
huggingface_hub (可独立使用，用于 CLI 工具)

使用场景对比

需求场景	推荐使用的库
快速生成句子向量/语义搜索	`sentence-transformers`
使用 BERT/GPT 做分类/生成任务	`transformers`
需要自定义分词器或超高速分词	`tokenizers`
下载/管理 Hugging Face 上的模型	`huggingface_hub`

Y 推荐文献

Hugging Face

https://huggingface.co

https://github.com/huggingface

https://github.com/huggingface/transformers

模型

https://hf-mirror.com/BAAI/bge-m3

https://modelscope.cn/models/BAAI/bge-m3

第三方镜像站

https://hf-mirror.com/

Windows PowerShell

$env:HF_ENDPOINT="https://hf-mirror.com"
$env:TRANSFORMERS_OFFLINE="0"
huggingface-cli --endpoint=https://hf-mirror.com download --resume-download BAAI/bge-m3 --local-dir D:/Program-Data/ai-models/bge-m3

ModelScope

https://modelscope.cn/models

样例

https://huggingface.co/BAAI/bge-m3 => https://hf-mirror.com/BAAI/bge-m3

[GIT] git lfs：大文件的版本管理 - 博客园/千千寰宇

X 参考文献

HuggingFace入门与实践 - Zhihu 【推荐】
抱脸-Hugging face AI模型库使用教程(快速入门) - 知乎/Ai小专家【推荐】

.DS_Store 文件是什么？ - Zhihu

MacOS 的隐藏文件

posted @ 2026-03-27 11:46 数据知音阅读(12) 评论(0) 收藏举报

刷新页面返回顶部