Git——HuggingFace的使用

LFS 环境安装

  • 配置 HuggingFace 环境需要安装 git lfs
  • LFS全称 Large File Storge，即大文件存储，可以帮助我们管理比较大的文件
  • Ubuntu安装 
    1
    2
    3
    curl -s https://packagecloud.io/install/repositories/github/git-lfs/script.deb.sh | sudo bash
    sudo apt-get install git-lfs
    git lfs install

前置补充：HuggingFace 国内镜像代理

  • 专为无法访问 HuggingFace 的同学设计，还可以加速

  • 代理方式：添加环境变量即可

    1
    2
    3
    # 直接修改环境变量
    export HF_ENDPOINT=https://hf-mirror.com
    python demo.py

  • 也可以在 Python 中直接修改

    1
    2
    3
    4
    5
    import os
    os.environ["HF_ENDPOINT"] = "https://hf-mirror.com"

    from datasets import load_dataset
    dataset = load_dataset("openai/gsm8k", "main")

使用 hf 命令下载数据和模型（大模型推荐，并行化）

  • 安装

    1
    pip install -U "huggingface_hub[cli]"

  • 模型下载：

    1
    hf download Qwen/Qwen2.5-0.5B-Instruct --local-dir ./Qwen2.5-0.5B-Instruct
    • 不添加 --local-dir 参数会下载到默认目录而不是当前目录下

  • 仅下载某个文件：

    1
    hf download Qwen/Qwen2.5-0.5B-Instruct config.json --local-dir ./Qwen2.5-0.5B-Instruct

  • 数据下载：

    1
    hf download openai/gsm8k --repo-type=dataset --local-dir ./gsm8k

  • 在下载前可以使用 下面的环境变量切换镜像

    1
    2
    3
    4
    export HF_ENDPOINT=https://hf-mirror.com

    # 即使使用了 hf-mirror.com 镜像，Xet 组件仍然会尝试连接 Hugging Face 官方的 CAS 服务器（cas-server.xethub.hf.co），所以遇到 Xet 相关错误时需要添加下面的环境变量
    export HF_HUB_DISABLE_XET=1

  • 仅单次下载切换环境变量：

    1
    HF_HUB_DISABLE_XET=1 HF_ENDPOINT=https://hf-mirror.com hf download openai/gsm8k --local-dir ./gsm8k --repo-type=dataset

拉取 HuggingFace 项目（包含 git 文件，常出现别的问题，不推荐）

  • 执行拉取操作

    1
    git clone https://huggingface.co/xxx/xxx
    • 该命令可在 HuggingFace 网站每个项目的首页 ... 选项的 clone repository 中查找到
    • git clone 命令可以将整个项目下载下来，但是下载大的文件时可能会特别慢，最佳实践是：
      • 使用 git clone xxx 下载项目文件，待除大文件外的其他文件下载结束时结束命令
        • 一些未完成的项目会出现在 .git/lfs/incomplete 文件夹下，结束命令后可以删除该文件夹，该文件夹可能会存储较大的未完成文件，浪费存储
      • 使用网页或其他方式下载较大的模型权重文件到指定目录下
    • 最新：最新测试发现直接使用类似命令下载时不会下载大文件（包括数据和模型都不会下载）

  • 仅下载小文件，跳过大文件：

    1
    GIT_LFS_SKIP_SMUDGE=1 git clone https://huggingface.co/xxx/xxx

  • 补充下载大文件：

    1
    git lfs pull
    • 注：需提前安装 git-lfs 包 
      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      # MaxOS
      brew install git-lfs

      # Ubuntu
      sudo apt-get install git-lfs

      # 安装完成后，必须执行一次全局初始化，这样才能让 Git 识别 lfs 命令
      git lfs install

      # 确认安装成功
      git lfs version

使用 huggingface-cli/hf 命令下载数据和模型（已经不建议使用）

  • 安装

    1
    pip install huggingface-hub

  • 模型下载

    1
    huggingface-cli download Qwen/Qwen2.5-0.5B-Instruct  --local-dir ./Qwen2.5-0.5B-Instruct
    • 注：huggingface-cli 已经不能用，需要替换为 hf 命令

  • 数据下载

    1
    huggingface-cli download openai/gsm8k --repo-type=dataset --local-dir ./gsm8k --local-dir-use-symlinks False
    • 重点：增加了 --repo-type=dataset 参数，否则默认是搜索模型

  • --local-dir-use-symlinks 的特别说明：

    • 当 --local-dir-use-symlinks 设置为 True（默认值）时，工具会优先创建符号链接指向缓存目录中的文件，而不是直接复制文件到 --local-dir 指定的目录。这样可以节省磁盘空间，但依赖于系统对符号链接的支持
    • 当 --local-dir-use-symlinks 设置为 False 时，工具会直接将文件复制（而非创建符号链接）到 --local-dir 指定的目录。这会占用更多磁盘空间，但保证了文件在目标目录中是真实存在的实体文件，不依赖符号链接机制，兼容性更好（尤其在 Windows 系统或某些不支持符号链接的环境中）
    • 实际上，ubuntu 下，亲测这个参数也可以不加，加不加没发现不同

其他需要注意的点

  • 如果直接使用 transformers 包下载 Bert 等预训练模型时，默认安装在 ~/.cache/huggingface/hub 文件夹下

附录：使用 modelscope 下载模型（国内推荐）

  • 安装 modelscope

    1
    pip install modelscope

  • 模型下载命令

    1
    2
    # 注意：这里不能使用 `--local-dir`，必须是 `--local_dir`
    modelscope download --model Qwen/Qwen2.5-0.5B-Instruct  --local_dir ./Qwen2.5-0.5B-Instruct
    • 易错点：跟 huggingface 使用的 --local-dir 不同，modelscope 这里使用的是 --local_dir