大模型和数据集管理工具huggingface实际使用体验

背景

最近看到个微信公众号，名称带有数据集，专门销售数据集。锐英源软件开发过语音识别系统和语音采集软件，语音识别系统当时预研模型时，用的是清华的中文语音数据集，没有试用的数据集，后面的开发就无从说起，huggingface能下载数据集，对项目有至关重要的作用。前几天使用BGE-M3模型，用huggingface下载BGE-M3大模型，下载成功，但是用不成，因为没大模型调用参数配置文件，参数文件用了复杂办法才解决。huggingface方便快捷给我带来了深刻的印象。

huggingface功能特色

完美兼容Python，同时支持其它语言，可以脱离Python环境使用。

高效下载与管理：支持断点续传（--resume-download）、指定下载路径（--local-dir）等，专门为大文件优化，比手动下载可靠得多。
身份验证与权限管理：通过 huggingface-cli login 或 hf auth login 命令登录，获取访问私有或受限模型的权限。这有点像百度网盘。
统一管理：一个工具即可完成模型（--repo-type model）、数据集（--repo-type dataset）和应用空间（--repo-type space）的所有操作。

可搜索有哪些模型，比如：hf datasets ls --search "finepdfs"。

可配置国内镜像源，

$env:HF_ENDPOINT = "https://hf-mirror.com"

Windows下必须用PowerShell打开，以管理员身份打开，不能用cmd。

Python里调用命令在2026年换为了hf，不再使用huggingface-cli，Warning: `huggingface-cli` is deprecated and no longer works. Use `hf` instead. 。

参数文件问题解决办法

Trae配置Anaconda里pythonexe

问题已解决。总结如下问题根因

BGE-M3的GGUF文件(XLM-RoBERTa架构)无法被sentence-transformers或transformers直接加载

sentence-transformers 6.0.1不支持 backend="gguf"(支持torch/onnx/openvio)

transformers 5.16.1的GGUF加载器不支持 xlmr 架构

解决方案
从hf-mirror下载了BAAl/bge-m3的完整配套文件，现在 bge-m3-gguf目录包含:
文件大小说明
pytorch_model.bin 2.12 GB PyTorch权重(核心，新下载)
config.json 687 B 模型架构配置
tokenizer. json 16.3 MB Fast tokenizer
sentencepiece.bpe.nodel 4.8 MB SentencePiece 分词模型
tokenizer_config. json 444 B Tokenizer 配置
nodules.json 349 B ST模块定义
sentence_bert_config.json 54 B ST配置
config_sentence_transformers.json 123 B ST框架配置
special_tokens_nap.json 964 B 特殊 token 映射
1_Pooling/config.json 191 B 池化层配置
代码修复:storyparser.py:157 去掉了 backend="gguf"参数，改用默认torch后。验证结果:向量维度1024，编码和相似度计算均正常。

具体下载过程

当时下载用的命令如下。核心思路：先在 PowerShell 里设置 HF_ENDPOINT 环境变量指向 hf-mirror，再用 Python 的 huggingface_hub.hf_hub_download 逐文件下载到 D:/123/models/bge-m3-gguf。

1. 下载配置文件（逐文件）
第一个文件（验证镜像可用）：

PowerShell

运行
$env:HF_ENDPOINT="https://hf-mirror.com"; python -c "from huggingface_hub import hf_hub_download; f = hf_hub_download('BAAI/bge-m3', 'config.json', local_dir='D:/123/models/bge-m3-gguf'); print('Downloaded:', f)"
批量下载其余小文件（一条 Python 脚本）：

PowerShell

运行
$env:HF_ENDPOINT="https://hf-mirror.com"; python -c "
from huggingface_hub import hf_hub_download
model_dir = 'D:/123/models/bge-m3-gguf'
repo_id = 'BAAI/bge-m3'
files = [
'config_sentence_transformers.json',
'sentence_bert_config.json',
'special_tokens_map.json',
'sentencepiece.bpe.model',
'1_Pooling/config.json',
]
for f in files:
path = hf_hub_download(repo_id, f, local_dir=model_dir)
print('OK:', f)
"
tokenizer.json（17MB，单独下）：

PowerShell

运行
$env:HF_ENDPOINT="https://hf-mirror.com"; python -c "from huggingface_hub import hf_hub_download; f = hf_hub_download('BAAI/bge-m3', 'tokenizer.json', local_dir='D:/123/models/bge-m3-gguf'); print('Downloaded:', f)"
2. 下载 pytorch_model.bin（2.2GB，后台跑）
PowerShell

运行
$env:HF_ENDPOINT="https://hf-mirror.com"; python -c "from huggingface_hub import hf_hub_download; f = hf_hub_download('BAAI/bge-m3', 'pytorch_model.bin', local_dir='D:/123/models/bge-m3-gguf'); print('Downloaded:', f)"
关键点
$env:HF_ENDPOINT="https://hf-mirror.com" 必须和 python 在同一条命令里（用 ; 分隔），因为环境变量只在当前 PowerShell 进程生效，换窗口就失效了。
local_dir 指定落盘目录，下载的临时文件会放在 D:/123/models/bge-m3-gguf/.cache/huggingface/download/，完成后移动为正式文件。
支持断点续传——如果中断，重跑同一条命令会从未完成的 .incomplete 文件继续。
更省事的写法（一条命令下整个仓库）
其实也可以用 snapshot_download 一次性把需要的文件全下下来，不用逐个列：

PowerShell

运行
$env:HF_ENDPOINT="https://hf-mirror.com"; python -c "from huggingface_hub import snapshot_download; snapshot_download('BAAI/bge-m3', local_dir='D:/123/models/bge-m3-gguf', allow_patterns=['*.json', '*.model', '1_Pooling/*', 'pytorch_model.bin'])"
注意：不要加 *.gguf 之类的匹配（bge-m3 官方仓库本来就没有 GGUF），也不要把 onnx/ 目录下进来（那是 2GB+ 的 ONNX 权重，用 sentence-transformers 跑 PyTorch 后端用不到）。

相关异常

下面异常是没有参数文件或加载不了transformers时报如下异常错误：

Path ./models/bge-m3-q4_k.gguf is a file, not a directory. `model_name_or_path` must be a local directory containing a model, or a Hugging Face Hub model ID.
File "D:\123\storyparser.py", line 157, in _load_model self.model = SentenceTransformer("./models/bge-m3-q4_k.gguf", device=self.device,backend="gguf") ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "D:\123\storyparser.py", line 152, in __init__ self._load_model() File "D:\123\storyparser.py", line 324, in analyze_story_file analyzer = StoryAnalyzer(model_name=model_name) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "D:\123\storyparser.py", line 354, in <module> analyze_story_file("d:/123/asr_ai.txt") NotADirectoryError: Path ./models/bge-m3-q4_k.gguf is a file, not a directory. `model_name_or_path` must be a local directory containing a model, or a Hugging Face Hub model ID.

Unrecognized model in ./models/bge-m3-gguf/. Should have a `model_type` key in its config.json.
File "D:\123\storyparser.py", line 157, in _load_model self.model = SentenceTransformer("./models/bge-m3-gguf/", device=self.device,backend="gguf") ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "D:\123\storyparser.py", line 152, in __init__ self._load_model() File "D:\123\storyparser.py", line 324, in analyze_story_file analyzer = StoryAnalyzer(model_name=model_name) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "D:\123\storyparser.py", line 354, in <module> analyze_story_file("d:/123/asr_ai.txt") ValueError: Unrecognized model in ./models/bge-m3-gguf/. Should have a `model_type` key in its config.json.

hf download BAAI/bge-m3 --local-dir ./models/bge-m3-gguf --include "config*.json" "tokenizer*" "modules.json"
C:\Python311\Lib\site-packages\huggingface_hub\cli\download.py:158: UserWarning: Ignoring `--include` since filenames have been explicitly set.
warnings.warn("Ignoring `--include` since filenames have been explicitly set.")
Fetching 3 files: 67%|████████████████████████████████████████████                      | 2/3 [00:01<00:00, 1.05it/s]
Traceback (most recent call last):.):   0%|                                               | 0.00B / 17.1MB
File "<frozen runpy>", line 198, in _run_module_as_main                                        | 0/3 [00:00<?, ?it/s]
File "<frozen runpy>", line 88, in _run_code
File "C:\Python311\Scripts\hf.exe\__main__.py", line 7, in <module>
File "C:\Python311\Lib\site-packages\huggingface_hub\cli\hf.py", line 133, in main
app()
File "C:\Python311\Lib\site-packages\click\core.py", line 1631, in __call__
return self.main(*args, **kwargs)
^^^^^^^^^^^^^^^^^^^^^^^^^^
File "C:\Python311\Lib\site-packages\click\core.py", line 1552, in main
rv = self.invoke(ctx)
^^^^^^^^^^^^^^^^
File "C:\Python311\Lib\site-packages\huggingface_hub\cli\_cli_utils.py", line 131, in invoke
return super().invoke(ctx)
^^^^^^^^^^^^^^^^^^^
File "C:\Python311\Lib\site-packages\click\core.py", line 2032, in invoke
return _process_result(sub_ctx.command.invoke(sub_ctx))
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "C:\Python311\Lib\site-packages\click\core.py", line 1415, in invoke
return ctx.invoke(self.callback, **ctx.params)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "C:\Python311\Lib\site-packages\click\core.py", line 910, in invoke
return callback(*args, **kwargs)
^^^^^^^^^^^^^^^^^^^^^^^^^
File "C:\Python311\Lib\site-packages\huggingface_hub\cli\_framework.py", line 365, in handler
return func(**call_kwargs)
^^^^^^^^^^^^^^^^^^^
File "C:\Python311\Lib\site-packages\huggingface_hub\cli\download.py", line 225, in download
_print_result(run_download())
^^^^^^^^^^^^^^
File "C:\Python311\Lib\site-packages\huggingface_hub\cli\download.py", line 187, in run_download
return snapshot_download(
^^^^^^^^^^^^^^^^^^
File "C:\Python311\Lib\site-packages\huggingface_hub\utils\_validators.py", line 88, in _inner_fn
return fn(*args, **kwargs)
^^^^^^^^^^^^^^^^^^^
File "C:\Python311\Lib\site-packages\huggingface_hub\_snapshot_download.py", line 522, in snapshot_download
hf_thread_map(
File "C:\Python311\Lib\site-packages\huggingface_hub\utils\tqdm.py", line 441, in hf_thread_map
results[future_to_index[future]] = future.result()
^^^^^^^^^^^^^^^
File "C:\Python311\Lib\concurrent\futures\_base.py", line 449, in result
return self.__get_result()
^^^^^^^^^^^^^^^^^^^
File "C:\Python311\Lib\concurrent\futures\_base.py", line 401, in __get_result
raise self._exception
File "C:\Python311\Lib\concurrent\futures\thread.py", line 58, in run
result = self.fn(*self.args, **self.kwargs)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "C:\Python311\Lib\site-packages\huggingface_hub\_snapshot_download.py", line 502, in _inner_hf_hub_download
hf_hub_download( # type: ignore
File "C:\Python311\Lib\site-packages\huggingface_hub\utils\_validators.py", line 88, in _inner_fn
return fn(*args, **kwargs)
^^^^^^^^^^^^^^^^^^^
File "C:\Python311\Lib\site-packages\huggingface_hub\file_download.py", line 1007, in hf_hub_download
return _hf_hub_download_to_local_dir(
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "C:\Python311\Lib\site-packages\huggingface_hub\file_download.py", line 1466, in _hf_hub_download_to_local_dir
_download_to_tmp_and_move(
File "C:\Python311\Lib\site-packages\huggingface_hub\file_download.py", line 1976, in _download_to_tmp_and_move
xet_get(
File "C:\Python311\Lib\site-packages\huggingface_hub\file_download.py", line 571, in xet_get
with session.new_file_download_group(
RuntimeError: Task error: File reconstruction error: CAS Client Error: Request error: HTTP status client error (401 Unauthorized), domain: https://cas-server.xethub.hf.co/v2/reconstructions/cdfc491bf5688aac5406092735a63d64decbc5e6e7b9b614bedb73aad514d404

hf download BAAI/bge-m3 --local-dir ./models/bge-m3-pytorch
Downloading bytes:                                                                                 | 0.00B            Still waiting to acquire lock on D:\123\models\bge-m3-pytorch\.cache\huggingface\.gitignore.lock (elapsed: 0.1 seconds)ng 30 files:   0%|                                                                        | 0/30 [00:00<?, ?it/s]
Still waiting to acquire lock on D:\123\models\bge-m3-pytorch\.cache\huggingface\.gitignore.lock (elapsed: 0.1 seconds)
Fetching 30 files:   3%|██▏                                                             | 1/30 [00:03<01:36, 3.31s/it]
Error: 403 Forbidden: None.total...): 19%|█████████                                      | 636kB / 3.31MB
Cannot access content at: https://hf-mirror.com/api/resolve-cache/models/BAAI/bge-m3/5617a9f61b028005a4858fdac845db406aefb181/imgs%2F.DS_Store?%2FBAAI%2Fbge-m3%2Fresolve%2F5617a9f61b028005a4858fdac845db406aefb181%2Fimgs%2F.DS_Store=&etag=%225008ddfcf53c02e82d7eee2e57c38e5672ef89f6%22.
Make sure your token has the correct permissions.
Hint: set HF_DEBUG=1 as environment variable for full traceback.
Downloading bytes: █████████████████████████████▎                                                  | 1.21MB
Reconstructing (incomplete total...): 37%|█████████████████▏                             | 1.21MB / 3.31MB

发生异常: IncompleteSnapshotError

The cached snapshot for 'BAAI/bge-m3' (revision 'main', commit 5617a9f61b028005a4858fdac845db406aefb181) is incomplete: 15 file(s) are missing (colbert_linear.pt, imgs/.DS_Store, onnx/model.onnx, ... (12 more)). The Hub could not be reached (ConnectTimeout: [WinError 10060] 由于连接方在一段时间后没有正确答复或连接的主机没有反应，连接尝试失败。). Re-run the download with network access to complete the snapshot.
TimeoutError: [WinError 10060] 由于连接方在一段时间后没有正确答复或连接的主机没有反应，连接尝试失败。 During handling of the above exception, another exception occurred: httpcore.ConnectTimeout: [WinError 10060] 由于连接方在一段时间后没有正确答复或连接的主机没有反应，连接尝试失败。 The above exception was the direct cause of the following exception: httpx.ConnectTimeout: [WinError 10060] 由于连接方在一段时间后没有正确答复或连接的主机没有反应，连接尝试失败。 The above exception was the direct cause of the following exception: File "D:\123\download_bge.py", line 8, in <module> repo_id="BAAI/bge-m3", local_dir="./models/bge-m3-pytorch", local_dir_use_symlinks=False,

友情链接