HuggingFace模型压缩打包时符号链接引起的文件夹过大问题解决方法

windows电脑上python应用从huggingface上下载模型，默认会在保存位置生成类似目录：

models--Systran--faster-whisper-medium #模型名
   --blobs
      --242aa06a480a7b5509375c645097e87af5136774 #乱码文件名真实大小无格式文件 1GB
      --...
   --refs
   --snapshots
      --08e178d48790749d25932bbc082711ddcfdfbc4f #哈希值
         --config.json #正常文件名0K快捷方式
         --...

假设原来文件夹总共大小1GB,如果把模型文件夹直接压缩打包发给别人，别人解压后可能就会变成2GB。

原本只有blobs文件夹内的文件有实际大小，snapshots文件夹下的文件只是0K 的快捷方式不占用空间。但是压缩打包后这些快捷方式被实体化了，成为了有实际大小的文件。这样就会导致模型文件夹大小翻倍。

【删除blobs文件夹内文件，保留snapshots内有实际大小的文件】

解决方法：

打包时只压缩有实际大小的文件即可。

创建checkpoint文件夹，接着创建faster-whisper-medium模型名文件夹，将snapshots>08e178d48790749d25932bbc082711ddcfdfbc4f文件夹下的文件复制到faster-whisper-medium文件夹内，这时这些原本0KB的快捷方式都变成了有实际大小的文件。这时再把模型文件夹压缩打包的话就不会出现解压大小翻倍的问题了。

然后修改代码。

原本python内代码是使用模型ID来引用文件的，我们把它改成本地电脑内模型文件的相对路径即可。

如原来加载模型代码如下：

pipeline = Trellis2ImageTo3DPipeline.from_pretrained("microsoft/TRELLIS.2-4B")

改为：

pipeline = Trellis2ImageTo3DPipeline.from_pretrained("./hf/checkpoint/TRELLIS.2-4B")

有的模型是在json内配置的，也一并修改即可，如：

"image_cond_model": {
            "name": "DinoV3FeatureExtractor",
            "args": {
                "model_name": "facebook/dinov3-vitl16-pretrain-lvd1689m"
            }
        },

改为：

"image_cond_model": {
            "name": "DinoV3FeatureExtractor",
            "args": {
                "model_name": "./hf/checkpoint/dinov3-vitl16-pretrain-lvd1689m"
            }
        },

但是有时候需要注意代码里是使用的某个模型ID，还是某个模型内的仅仅几个文件

还一种情况，如果需要软件运行时自动从huggingface下载的模型文件就取消使用软连接的方式，

可以使用snapshot_download下载模型文件，然后在应用中指定模型的本地文件路径，如下面示例代码：

import os
from huggingface_hub import snapshot_download
from faster_whisper import WhisperModel, BatchedInferencePipeline

model_name = "Systran/faster-whisper-tiny" #模型ID
# 设置真实物理路径
save_path = "./models/faster-whisper-tiny"

# 1. 手动执行下载（仅在本地文件夹不存在时，或者需要检查更新时执行）
if not os.path.exists(save_path):
    snapshot_download(
        repo_id=model_name,
        local_dir=save_path,
        local_dir_use_symlinks=False, # 关键：禁用软链接
        ignore_patterns=["*.msgpack", "*.h5", "*.ot"] # 可选：忽略不需要的权重格式，节省空间
    )

# 2. 加载模型时，直接指向这个本地物理路径
model = WhisperModel(save_path, device="cuda", compute_type="float16")
batched_model = BatchedInferencePipeline(model=model)

Python应用内使用模型ID的话应用启动时会有联网检查这一步，如果使用本地电脑上的缓存文件的话就不会引起联网检查了。当然你也可以手动设置为离线。

一种简单有效的方法，设置环境变量

os.environ["HF_HUB_DISABLE_SYMLINKS"] = "1"

简单方便