Transformers 安装与离线运行完全指南pip / 源码 / conda 安装、缓存配置与离线模式实践【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers本指南以当前仓库 docs/source/ko/installation.md 为骨架系统讲解 Transformers 在 Python 3.10 环境下的四种安装方式pip、源码、可编辑安装、conda、模型缓存目录的配置优先级以及如何通过环境变量进入离线模式、预先下载模型文件实现无网络运行。读完本文你将掌握从零搭建 Transformers 开发/运行环境、管理本地模型缓存、并在防火墙或完全离线的机器上稳定运行推理与训练脚本的完整实战方案。环境要求Python 3.10 与深度学习框架 Transformers 在当前仓库中针对 Python 3.10 与 PyTorch 2.4 进行了测试。这一版本范围可以直接在仓库的 setup.py 中得到印证SUPPORTED_PYTHON_VERSIONS (10, 14) # 3.10 to 3.14setup.py 会基于该常量自动生成python_requiresf3.{min_version}.0参见 setup.py即最低要求 Python 3.10。因此在开始安装之前请先确认本机 Python 版本并准备好对应的深度学习框架如 PyTorch具体安装方式请参考 PyTorch 等框架的官方安装指引。注意仅安装 transformers 本身是不够的实际运行模型还需要 torch 等后端这点在下一节的transformers[torch]安装方式中会进一步体现。使用 pip 安装创建并激活虚拟环境官方强烈建议将 Transformers 安装在 Python 虚拟环境 中。虚拟环境可以隔离不同项目的依赖避免依赖冲突也便于整体清理。首先在项目目录下创建虚拟环境python -m venv .env激活虚拟环境Linux / macOSsource .env/bin/activate激活虚拟环境Windows.env/Scripts/activate安装 transformers 本体激活虚拟环境后执行安装pip install transformers如果只需要 CPU 环境可以使用一行命令同时安装 Transformers 与对应的深度学习库。例如同时安装 PyTorchpip install transformers[torch]这种extra安装方式确保 transformers 与 torch 的版本兼容性由 pip 一并解析省去手动对齐依赖的麻烦。验证安装是否成功安装完成后运行下面这行命令验证它会下载一个预训练的情感分析模型并执行推理python -c from transformers import pipeline; print(pipeline(sentiment-analysis)(we love you))如果输出类似下面的标签与分数说明安装成功[{label: POSITIVE, score: 0.9998704791069031}]提示首次运行该命令会从 Hugging Face Hub 下载模型文件并写入本地缓存因此需要网络连接具体缓存位置与配置方法见下文缓存配置小节。从源码安装main 分支如果想使用最新开发中的功能可以从源码安装pip install githttps://github.com/huggingface/transformers这条命令安装的是实验性较强的main分支而非稳定的stable版本。main分支适合希望紧跟开发进度、及时获得最新修复的用户——例如某个在最近一次正式发布之后才被修复的 bug可能还没有进入新版本但在main中已经可用。需要提醒的是main分支并不保证稳定。官方会在main分支上尽量保持可用绝大多数问题通常几小时到一天内就会得到修复如果遇到问题可以在官方 Issue 中报告以加速解决。安装完成后同样可以验证python -c from transformers import pipeline; print(pipeline(sentiment-analysis)(I love you))可编辑安装适合贡献者与源码调试以下两种场景建议使用可编辑安装editable install希望直接使用main分支源码希望为 Transformers 贡献代码并在修改后立即测试效果。做法是先克隆仓库再以可编辑模式安装git clone https://github.com/huggingface/transformers.git cd transformers pip install -e .这条命令会把克隆下来的源码目录与 Python 库搜索路径关联起来Python 在导入transformers时除了常规库目录例如~/anaconda3/envs/main/lib/python3.10/site-packages/还会去克隆目录例如~/transformers/中查找。⚠️ 警告以可编辑模式安装后必须保留transformers源码目录否则 Python 将无法再导入该库。可编辑安装的另一个好处是更新方便——拉取最新代码即可cd ~/transformers/ git pull重新启动 Python 环境后就会加载更新后的main版本代码。使用 conda 安装如果使用 conda 管理环境可以从conda-forge渠道安装conda install conda-forge::transformers注意conda 安装的 transformers 版本更新可能滞后于 pip且同样需要另外安装 PyTorch 等深度学习框架。缓存配置预训练模型与文件的本地存储预训练模型下载后默认缓存在本地路径~/.cache/huggingface/hubWindows 下为C:\Users\username\.cache\huggingface\hub。这是环境变量HF_HUB_CACHE的默认目录。可以通过以下 shell 环境变量按优先级从高到低自定义缓存位置HF_HUB_CACHEshell 环境变量最高优先级直接指定缓存目录HF_HOME指定 huggingface 相关文件的根目录XDG_CACHE_HOME/huggingface遵循 XDG 目录规范时的兜底路径从当前仓库源码看缓存机制由 huggingface_hub 库的常量驱动src/transformers/utils/hub.py中通过from huggingface_hub import constants引用constants.HF_HOME、constants.HF_HUB_CACHE等值参见 hub.py并在 hub.py 中以constants.HF_HOME为基础派生HF_MODULES_CACHE用于存放动态模块/自定义代码HF_MODULES_CACHE os.getenv(HF_MODULES_CACHE, os.path.join(constants.HF_HOME, modules))这意味着调整HF_HOME不仅会影响模型权重缓存也会连带影响transformers_modules等动态模块的存放位置。如果需要把缓存整体迁移到磁盘空间更大的目录例如挂载的大容量数据盘优先设置HF_HOME即可统一生效。离线模式让 Transformers 只使用本地文件在防火墙隔离或完全离线的环境中可以设置环境变量HF_HUB_OFFLINE1让 Transformers 只检索本地文件不再发起任何网络请求。若离线训练流程中还用到 Datasets可同时设置HF_DATASETS_OFFLINE1。这一行为在源码层面有明确支撑src/transformers/utils/hub.py的cached_file等下载路径会调用is_offline_mode()进行判断一旦检测到离线模式会强制将local_files_only置为True参见 hub.pyif is_offline_mode() and not local_files_only: logger.info(Offline mode: forcing local_files_onlyTrue) local_files_only Trueis_offline_mode正是由 huggingface_hub 根据HF_HUB_OFFLINE等环境变量判定见 hub.py 的导入。实际使用示例联网机器与离线机器在带防火墙的常规网络上通常这样运行翻译脚本见 run_translation.pypython examples/pytorch/translation/run_translation.py --model_name_or_path google-t5/t5-small --dataset_name wmt16 --dataset_config ro-en ...同样的脚本放到离线机器上只需在前面加上两个环境变量HF_DATASETS_OFFLINE1 HF_HUB_OFFLINE1 \ python examples/pytorch/translation/run_translation.py --model_name_or_path google-t5/t5-small --dataset_name wmt16 --dataset_config ro-en ...此时脚本只会搜索本地文件不会因网络超时或中断而长时间卡住能够稳定跑完。离线前准备预先下载模型与分词器另一种离线使用方案是提前下载好所有需要的文件离线时直接指定本地路径加载。共有三种方式方式一通过 Model Hub 网页下载在 Model Hub 模型页面点击下载↓图标手动下载模型仓库中的文件到本地。方式二使用 from_pretrained / save_pretrained 工作流在联网机器上先用PreTrainedModel.from_pretrained下载模型与分词器 from transformers import AutoTokenizer, AutoModelForSeq2SeqLM tokenizer AutoTokenizer.from_pretrained(bigscience/T0_3B) model AutoModelForSeq2SeqLM.from_pretrained(bigscience/T0_3B)再用PreTrainedModel.save_pretrained将文件保存到指定目录 tokenizer.save_pretrained(./your/path/bigscience_t0) model.save_pretrained(./your/path/bigscience_t0)离线时用PreTrainedModel.from_pretrained从本地路径直接加载 tokenizer AutoTokenizer.from_pretrained(./your/path/bigscience_t0) model AutoModel.from_pretrained(./your/path/bigscience_t0)提示from_pretrained同时支持 Hub 仓库 ID如bigscience/T0_3B与本地目录路径正是这一双模式设计让在线下载、离线加载成为可能该能力由仓库中PreTrainedModel的底层加载逻辑统一提供可参考 modeling_utils.py 中对应的实现。方式三使用 huggingface_hub 库按文件下载先安装huggingface_hubpython -m pip install huggingface_hub使用hf_hub_download函数将指定文件下载到目标位置。例如下载 T0 模型的config.json from huggingface_hub import hf_hub_download hf_hub_download(repo_idbigscience/T0_3B, filenameconfig.json, cache_dir./your/path/bigscience_t0)hf_hub_download的cache_dir参数可以精确控制文件落盘位置便于后续批量拷贝到离线机器。离线加载配置文件的通用做法文件下载并缓存到本地后后续只需指定本地路径即可加载。例如加载配置 from transformers import AutoConfig config AutoConfig.from_pretrained(./your/path/bigscience_t0/config.json)小结安装优先使用虚拟环境 pip install transformersCPU 场景可一键pip install transformers[torch]需要最新功能用源码安装参与开发用可编辑安装conda 用户用conda install conda-forge::transformers。模型缓存默认位于~/.cache/huggingface/hub可通过HF_HUB_CACHE→HF_HOME→XDG_CACHE_HOME/huggingface的优先级顺序自定义。离线环境设置HF_HUB_OFFLINE1配合 Datasets 再加HF_DATASETS_OFFLINE1即可强制仅使用本地文件预先用save_pretrained或hf_hub_download备好模型文件即可在完全断网的机器上稳定运行。【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考