在 macOS 上设置 Hugging Face Transformers

整合了网上找到的几个安装教程后发现都不是很全，最后整合一下解决方案发出来，其中新增了故障排查部分，以便帮助你解决在配置过程中可能遇到的问题。以下内容没有原创，只是整合。

在 macOS 上设置 Hugging Face Transformers

Hugging Face Transformers 是一个强大的自然语言处理（NLP）库，使开发者能够使用最先进的预训练模型来执行文本生成、翻译、情感分析等任务。如果你正在使用 macOS，本指南将一步步引导你完成环境设置，并包含常见问题的解决方案。

第 1 步：安装 Xcode 命令行工具

在安装其他组件之前，首先需要安装 Xcode 命令行工具。这些工具包含了 macOS 开发所需的基本组件，包括 Homebrew 依赖的编译器和库。

在终端中运行以下命令：

xcode-select --install

如果收到提示：

xcode-select: note: Command line tools are already installed. Use "Software Update" in System Settings or the softwareupdate command line interface to install updates.

说明系统已安装命令行工具，可直接进入下一步。

第 2 步：安装 Homebrew

Homebrew 是 macOS 的包管理器，它可以简化开发工具的安装。

运行以下命令安装 Homebrew：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安装完成后，更新 Homebrew 以确保所有软件包都是最新版本：

brew update brew upgrade

第 3 步：安装 Pyenv 和 Pyenv-Virtualenv

Pyenv 可帮助你在系统上管理多个 Python 版本，而 Pyenv-Virtualenv 用于创建不同项目的独立 Python 环境。

使用 Homebrew 安装这两个工具：

brew install pyenv pyenv-virtualenv

初始化 Pyenv：
为确保 Pyenv 在 Zsh（macOS 默认 Shell）中正常工作，将以下内容添加到 ~/.zshrc 文件中（如果该文件不存在，请先创建：touch ~/.zshrc）：

eval "$(pyenv init -)" if which pyenv-virtualenv-init > /dev/null; then eval "$(pyenv virtualenv-init -)"; fi

保存后，执行以下命令使更改生效：

source ~/.zshrc

第 4 步：安装 Python

首先，查看可用的 Python 版本列表：

pyenv install -l

选择一个版本进行安装（例如 3.12.0）：

pyenv install 3.12.0

设置该版本为全局默认 Python 版本：

pyenv global 3.12.0

验证安装是否成功：

python --version

第 5 步：创建并激活虚拟环境

为隔离项目依赖，使用 Pyenv 创建虚拟环境：

pyenv virtualenv 3.12.0 myproject pyenv local myproject

这将在当前目录下创建并激活名为 myproject 的虚拟环境，终端提示符会显示 (myproject)。

若需日后删除该虚拟环境，可以运行：

pyenv virtualenv-delete myproject

第 6 步：安装 Hugging Face Transformers 及依赖项

在虚拟环境激活状态下，首先安装 Hugging Face Transformers：

pip install transformers

对于大多数 NLP 任务，还需要安装一个后端，如 PyTorch 或 TensorFlow。推荐使用 PyTorch。

标准 PyTorch 安装

pip install torch torchvision

针对 Apple Silicon（M1、M2 等）的优化安装

如果你使用的是 Apple Silicon Mac，请运行：

pip install torch torchvision --extra-index-url https://download.pytorch.org/whl/torch_stable.html

注意：如果误装了非 Apple Silicon 优化版的 PyTorch，请先卸载：

pip uninstall torch torchvision -y

再执行上述安装命令。

第 7 步：验证安装

运行以下命令，检查是否正确安装了 Hugging Face Transformers：

python -c "import transformers; print(transformers.__version__)"

如果没有错误，并成功打印出版本号，则说明环境配置成功！

故障排查

如果在配置过程中遇到问题，可以参考以下解决方案：

• python 命令找不到或版本错误：

  • 检查是否在 ~/.zshrc 中正确初始化了 Pyenv。

  • 运行 echo $PATH，确认路径中包含 $HOME/.pyenv/shims。

  • 执行 pyenv rehash 更新 shims 文件。

  • 使用 pyenv versions 确认当前激活的虚拟环境是否正确。

• .zshrc 文件不存在：

  • 如果提示 source: no such file or directory: ~/.zshrc，请先创建该文件：

    touch ~/.zshrc

    然后将初始化 Pyenv 的命令添加进去并执行 source ~/.zshrc。

• PyTorch 安装错误：

  • 如果误装了标准版 PyTorch（不适用于 Apple Silicon），请先卸载：

    pip uninstall torch torchvision -y

    然后安装优化版本：

    pip install torch torchvision --extra-index-url https://download.pytorch.org/whl/torch_stable.html

作者声明本文无利益相关，欢迎值友理性交流，和谐讨论～