当前位置：首页 > ops >正文

huggingface离线下载模型使用方法

ops 2025/8/23 13:18:17

在使用 Hugging Face 的 transformers 库时，如果你需要离线下载模型（即在没有网络连接的环境下加载模型），可以按照以下步骤操作：

✅ 步骤一：在线环境下下载并缓存模型

首先，在有网络的机器上下载模型并保存到本地。

from transformers import AutoTokenizer, AutoModelForSequenceClassification# 指定模型名称
model_name = "bert-base-uncased"# 下载模型和分词器，并保存到本地目录
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForSequenceClassification.from_pretrained(model_name)# 保存到本地目录
save_directory = "./local_bert_model"
tokenizer.save_pretrained(save_directory)
model.save_pretrained(save_directory)

这会在当前目录下创建 ./local_bert_model 文件夹，包含：

config.json
pytorch_model.bin（或 tf_model.h5）
tokenizer.json, vocab.txt 等分词器文件

✅ 步骤二：离线加载模型

将整个 local_bert_model 文件夹复制到离线环境的机器上，然后通过本地路径加载：

from transformers import AutoTokenizer, AutoModelForSequenceClassification# 使用本地路径加载（无需网络）
local_model_path = "./local_bert_model"tokenizer = AutoTokenizer.from_pretrained(local_model_path)
model = AutoModelForSequenceClassification.from_pretrained(local_model_path)

⚠️ 关键点：只要模型文件完整，即使断网也可以加载。

✅ 高级技巧：使用 `transformers-cli` 下载模型

你也可以使用命令行工具提前下载：

# 安装 CLI 工具（如果还没装）
pip install huggingface_hub# 登录（可选，用于私有模型）
huggingface-cli login# 下载模型到本地
huggingface-cli download bert-base-uncased --local-dir ./local_bert_model

✅ 设置离线模式（可选）

如果你确定要强制离线，可以设置环境变量或使用 transformers 的配置：

方法 1：设置环境变量

export TRANSFORMERS_OFFLINE=1

方法 2：在代码中设置

import os
os.environ["TRANSFORMERS_OFFLINE"] = "1"# 然后尝试加载（必须已缓存或本地存在）
from transformers import AutoModel
model = AutoModel.from_pretrained("./local_bert_model")  # 必须是本地路径

⚠️ 如果设置 TRANSFORMERS_OFFLINE=1，但模型不在本地，会直接报错。

✅ 注意事项

模型完整性：确保所有文件都复制完整（包括 .bin, .json, .txt, tokenizer_config.json 等）。
版本兼容性：确保离线机器上的 transformers 版本与模型兼容。
缓存路径：Hugging Face 默认缓存路径是 ~/.cache/huggingface/transformers，你也可以手动复制缓存内容。
大模型：像 Llama-2, ChatGLM 等大模型，建议使用 huggingface-cli download 或 git lfs 克隆仓库。

✅ 示例：下载并离线使用中文 BERT

# 在线下载
tokenizer = AutoTokenizer.from_pretrained("bert-base-chinese")
model = AutoModelForSequenceClassification.from_pretrained("bert-base-chinese")
tokenizer.save_pretrained("./bert-base-chinese-offline")
model.save_pretrained("./bert-base-chinese-offline")# 离线加载
tokenizer = AutoTokenizer.from_pretrained("./bert-base-chinese-offline")
model = AutoModelForSequenceClassification.from_pretrained("./bert-base-chinese-offline")