Transformers 安装实战指南从 uv 虚拟环境到 GPU 加速与离线模式配置【免费下载链接】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/transformersTransformers 是 Hugging Face 出品的大模型框架覆盖文本、视觉、音频与多模态模型的推理与训练。本文基于仓库官方安装文档 installation.md 与 setup.py 等仓库源码完整讲解如何在不同硬件环境CUDA、CPU、Intel XPU、NVIDIA Spark ARM64下安装 Transformers、如何验证安装、如何从源码或以可编辑模式安装以及如何配置模型缓存目录与离线运行环境。读完本文你可以独立完成一套干净、可复现、可离线运行的 Transformers 开发环境。一、环境前提Python 与 PyTorch 版本要求官方文档明确指出Transformers 与 PyTorch 配合工作已在Python 3.10 与 PyTorch 2.5上完成测试。这一说法与仓库构建配置一致——setup.py 中定义了支持的 Python 版本范围与 PyTorch 最低版本# setup.py SUPPORTED_PYTHON_VERSIONS (10, 14) # 3.10 to 3.14 ... torch2.5, python3.10.0,同时setup.py生成的python_requires为3.10.0。当前仓库中的开发版本号为5.16.0.dev0见 src/transformers/init.py。因此动手安装前请先确认Python 版本在 3.103.14 之间如果使用 NVIDIA GPU已按 PyTorch 官方指引 装好匹配的 CUDA 驱动。二、用 uv 创建虚拟环境官方推荐使用 [uv]一个基于 Rust 的高性能 Python 包与项目管理器来管理虚拟环境它能隔离不同项目的依赖、避免版本冲突。uv 可以作为 pip 的直接替代品——如果你偏好 pip只需把下文命令中的uv去掉即可。创建并激活一个虚拟环境uv venv .env source .env/bin/activate三、按硬件选择安装命令Transformers 的基础安装是transformersGPU 场景则通过 extras 语法transformers[torch]一并装上 PyTorch 与accelerate。[torch]这个 extra 的具体内容可以在 setup.py 中确认extras[torch] deps_list(torch, accelerate) # torch2.5, accelerate1.1.0文档给出了四种典型场景下面逐一说明。1. NVIDIA GPUCUDA先确认系统能检测到 NVIDIA GPUnvidia-smi然后安装带 torch extra 的 TransformersCUDA 版的 PyTorch 需要事先按 PyTorch 官方指引装好对应驱动uv pip install transformers[torch]等价的 pip 写法即 README.md 中展示的pip install transformers[torch]。2. NVIDIA SparkARM64 设备在运行 ARM64 的 NVIDIA Spark 设备如 RTX Spark 笔记本上PyTorch 需要 NVIDIA 官方的 ARM64 构建这些 wheel 不在默认 PyPI 索引或标准 PyTorch wheel 索引中必须从 NVIDIA PyPI 索引安装nvidia-smi # 先确认能检测到 NVIDIA GPU uv pip install torch --index-url https://pypi.nvidia.com uv pip install transformers注意这里的顺序先固定 PyTorch 来源再安装 Transformers避免依赖解析器从默认索引拉取不兼容的 ARM64 版本。3. 纯 CPUCPU 版本直接从 PyTorch 官方 CPU wheel 索引安装 torch再安装 Transformersuv pip install torch --index-url https://download.pytorch.org/whl/cpu uv pip install transformers4. Intel GPUXPU需要先按 Intel 官方指引安装 XPU 版 PyTorch 驱动然后用xpu-smi确认系统检测到了 Intel GPU再追加 XPU 索引 URL 安装xpu-smi uv pip install transformers[torch] --extra-index-url https://download.pytorch.org/whl/xpu四、验证安装是否成功安装完成后运行下面这条命令做冒烟测试。它会加载一个预训练情感分析模型对输入文本返回标签与置信度分数python -c from transformers import pipeline; print(pipeline(sentiment-analysis)(hugging face is the best)) # 期望输出形如 # [{label: POSITIVE, score: 0.9998704791069031}]这条命令同时验证了三件事transformers 包可正常导入、能访问 Hub 下载并缓存模型、pipeline推理链路完整。如果你看到类似输出即表示安装成功。五、从源码安装与可编辑安装源码安装拿到最新latest版本从源码安装装的是latest版本而非stable版本适合实验尚未进入稳定版的新特性、或修复尚未正式发布的 bug。代价是最新版本不一定稳定——遇到问题可以提交 GitHub Issue 帮助官方尽快修复。uv pip install githttps://github.com/huggingface/transformers安装后仍用第四节的情感分析命令验证。可编辑安装本地开发 Transformers 本身可编辑安装editable install把本地的 Transformers 代码目录直接链接进 Python 的导入路径而不是复制文件——修改源码后无需重装即可生效是参与 Transformers 本地开发的推荐方式git clone https://github.com/huggingface/transformers.git cd transformers uv pip install -e .注意本地 Transformers 文件夹必须一直保留删除后该安装即失效。后续同步上游最新改动cd ~/transformers/ git pull六、conda 安装方式如果你使用 conda 生态可以直接从 conda-forge 频道安装。在刚创建好的虚拟环境中执行conda install conda-forge::transformers七、配置缓存目录HF_HUB_CACHE 与优先级规则当你通过PreTrainedModel.from_pretrained加载预训练模型时模型会从 Hub 下载并缓存到本地。每次加载时都会检查缓存是否仍是最新版本一致则直接读本地不一致则下载并更新缓存。默认缓存目录由环境变量HF_HUB_CACHE决定通常为~/.cache/huggingface/hubWindows 上为C:\Users\username\.cache\huggingface\hub。这个默认值在源码中可以直接看到——当调用方没有显式传cache_dir时下载逻辑就回落到constants.HF_HUB_CACHE# src/transformers/utils/hub.py if cache_dir is None: cache_dir constants.HF_HUB_CACHE见 src/transformers/utils/hub.py。同文件中还定义了动态模块缓存路径HF_MODULES_CACHE默认落在HF_HOME/modules下见 hub.py。要把模型缓存到别的目录按以下优先级修改 shell 环境变量优先级从高到低HF_HUB_CACHE直接指定 Hub 缓存目录最精确HF_HOME指定整个 HF 数据主目录Hub 缓存固定为其子路径hubXDG_CACHE_HOME/huggingface仅在HF_HOME未设置时生效。八、离线模式防火墙环境下的完整方案在离线或防火墙环境中需要提前把模型文件下载并缓存好。官方给出了三种互补的手段。1. 预下载snapshot_download在有网机器上使用huggingface_hub的snapshot_download一次性拉取整个模型仓库from huggingface_hub import snapshot_download snapshot_download(repo_idmeta-llama/Llama-2-7b-hf, repo_typemodel)snapshot_download支持按 revision 下载、通过 CLI 下载、以及按文件模式过滤等更多选项。2. 环境变量禁网HF_HUB_OFFLINE1设置HF_HUB_OFFLINE1可以彻底禁止加载模型时的任何 HTTP 请求强制只走本地缓存HF_HUB_OFFLINE1 \ python examples/pytorch/language-modeling/run_clm.py --model_name_or_path meta-llama/Llama-2-7b-hf --dataset_name wikitext ...其中 run_clm.py 就是仓库中真实存在的语言模型训练示例脚本。3. 加载参数兜底local_files_onlyTrue另一种更细粒度的方式是只在特定加载调用上限定只读本地文件通过PreTrainedModel.from_pretrained的local_files_onlyTrue参数实现from transformers import LlamaForCausalLM model LlamaForCausalLM.from_pretrained(./path/to/local/directory, local_files_onlyTrue)从源码结构看local_files_only是下载链路上一贯透传的参数src/transformers/utils/hub.py 中它被声明在DownloadKwargs里并在调用hf_hub_download/snapshot_download时原样传递该文件中共有 18 处引用因此无论是单文件下载还是整仓快照离线约束都能生效。小结与延伸阅读本文完整覆盖了官方安装文档的六大板块uv 虚拟环境、四种硬件场景的安装命令、安装验证、源码/可编辑安装、conda 安装以及缓存目录与离线模式的配置。几个便于自查的要点版本底线Python 3.10、PyTorch 2.5extras 细节见 setup.py如torchextra 绑定accelerate1.1.0验证命令pipeline(sentiment-analysis)一行脚本即可确认环境完整可用缓存优先级HF_HUB_CACHEHF_HOMEXDG_CACHE_HOME /huggingface离线三件套snapshot_download预下载、HF_HUB_OFFLINE1禁网、local_files_onlyTrue局部兜底。如需进一步深入可以继续参考 README.md 中的快速上手示例与 docs/source/en/installation.md 的原始表述。【免费下载链接】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），仅供参考
