智川云
智川云RIVERMIND

主题

HuggingFace 使用指南 ​

HuggingFace 是最流行的 AI 模型和数据集托管平台。本文介绍如何在智川云中高效使用 HuggingFace 资源。

修改缓存目录 ​

HuggingFace 默认将模型缓存到 /root/.cache/huggingface/，会占用系统盘空间。建议修改到数据盘：

方法一：环境变量（推荐） ​

bash
# 临时设置
export HF_HOME=/root/rivermind-data/cache/huggingface

# 永久设置
echo 'export HF_HOME=/root/rivermind-data/cache/huggingface' >> ~/.bashrc
source ~/.bashrc

方法二：代码中设置 ​

python
import os
os.environ['HF_HOME'] = '/root/rivermind-data/cache/huggingface'

# 必须在导入 transformers 之前设置
from transformers import AutoModel, AutoTokenizer

下载模型 ​

使用 transformers 库 ​

python
from transformers import AutoModel, AutoTokenizer

# 自动下载并缓存
model = AutoModel.from_pretrained("bert-base-chinese")
tokenizer = AutoTokenizer.from_pretrained("bert-base-chinese")

使用 huggingface-cli ​

bash
# 安装 CLI 工具
pip install huggingface_hub

# 下载模型到指定目录
huggingface-cli download bert-base-chinese --local-dir ./models/bert-base-chinese

# 下载特定文件
huggingface-cli download bert-base-chinese config.json --local-dir ./models/

使用 snapshot_download ​

python
from huggingface_hub import snapshot_download

# 下载整个仓库
snapshot_download(
    repo_id="bert-base-chinese",
    local_dir="/root/rivermind-data/models/bert-base-chinese",
    local_dir_use_symlinks=False
)

使用镜像加速 ​

国内访问 HuggingFace 可能较慢，可使用镜像：

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

或在代码中：

python
import os
os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'

离线使用模型 ​

下载后离线加载 ​

python
# 先下载
model = AutoModel.from_pretrained("bert-base-chinese")
model.save_pretrained("/root/rivermind-data/models/bert-base-chinese")

# 离线加载
model = AutoModel.from_pretrained(
    "/root/rivermind-data/models/bert-base-chinese",
    local_files_only=True
)

设置离线模式 ​

bash
export HF_HUB_OFFLINE=1

下载数据集 ​

python
from datasets import load_dataset

# 下载并缓存
dataset = load_dataset("squad")

# 指定缓存目录
dataset = load_dataset("squad", cache_dir="/root/rivermind-data/datasets")

# 保存到本地
dataset.save_to_disk("/root/rivermind-data/datasets/squad")

# 从本地加载
dataset = load_dataset("path", data_dir="/root/rivermind-data/datasets/squad")

常用环境变量 ​

变量说明示例值
HF_HOME缓存根目录/root/rivermind-data/cache/huggingface
HF_ENDPOINTAPI 端点https://hf-mirror.com
HF_HUB_OFFLINE离线模式1
TRANSFORMERS_CACHEtransformers 缓存/root/rivermind-data/cache/transformers

清理缓存 ​

bash
# 查看缓存大小
du -sh /root/.cache/huggingface/

# 清理缓存
rm -rf /root/.cache/huggingface/hub/

# 使用 CLI 清理
huggingface-cli delete-cache

常见问题 ​

下载中断 ​

使用 huggingface-cli 下载支持断点续传，中断后重新执行相同命令即可继续。

模型太大 ​

  • 使用量化版本（如 GPTQ、AWQ）
  • 下载到数据盘
  • 使用 device_map="auto" 自动分配显存

网络超时 ​

python
from huggingface_hub import snapshot_download

snapshot_download(
    repo_id="model-name",
    local_dir="./model",
    resume_download=True,  # 支持断点续传
    max_workers=4  # 并行下载
)

智算无疆 川流不息

Copyright © 2026 智川云