#安装与环境

#环境要求

• Python 3.10+（推荐 3.11 / 3.12）
• pip（或 uv / conda）
• 磁盘：Hub 缓存会增长，预留数 GB
• GPU 可选：分类与 tiny 生成可在 CPU 上跑；完整微调建议有 CUDA / MPS

张量与 torch.device 细节见本站 PyTorch 教程。

#创建虚拟环境

python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

#安装 PyTorch

先装与本机匹配的 PyTorch，再装 Transformers，避免 pip 拉到错误 CUDA 轮子：

# CPU 示例；GPU 请到 https://pytorch.org 复制命令
pip install torch

import torch
print(torch.__version__, torch.cuda.is_available())

#安装 Transformers 生态

官方推荐的一组：

pip install -U transformers datasets evaluate accelerate

按需补充：

pip install huggingface_hub   # hf CLI、登录、push
pip install peft              # LoRA，微调章用
pip install sentencepiece     # 部分 Tokenizer
pip install soundfile         # Whisper 等音频

验证：

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

#登录 Hub：hf auth login

huggingface_hub 提供 hf CLI。下载公开 ungated 模型不必登录；上传、私有仓、部分数据集需要 Token。

hf auth login

浏览器授权或粘贴 Access Token（写权限仅在 push_to_hub 时需要）。查看身份：

hf auth whoami

也可用环境变量（CI / 脚本，勿提交 Git）：

# bash
export HF_TOKEN="hf_..."

$env:HF_TOKEN = "hf_..."

旧命令 huggingface-cli login 仍可能可用，新文档以 hf auth login 为准。

#GPU 与加载参数

有一张消费级 GPU 时，加载大模型常用：

from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen2.5-0.5B-Instruct",
    device_map="auto",
    dtype="auto",
)

没有 GPU 也能学完本课：用 DistilBERT / DistilGPT2 / Whisper-tiny，把 device_map 去掉或设为 cpu。7B 全参微调不是入门作业。

#缓存与国内网络

默认缓存目录是 ~/.cache/huggingface（可用 HF_HOME 改）。重复 from_pretrained 会走本地。

大陆访问 Hub 不稳定时，可自查社区镜像或代理，并设置文档中的端点变量（以你使用的镜像说明为准）。不要把 Token 写进笔记本后公开分享。

#建议项目结构

my-hf-lab/
├── .venv/
├── .gitignore          # 忽略 .venv、.env、*.pt
├── requirements.txt
├── classify.py
└── outputs/            # Trainer 的 output_dir

requirements.txt 最小集：torch、transformers、datasets、evaluate、accelerate。

#常见问题

hf 不是内部或外部命令？
pip install huggingface_hub 后重新激活 venv。

下载一直卡住？
检查网络；先换本课的 ungated 小模型；设置 HF_HUB_ENABLE_HF_TRANSFER=1 有时能加速。

CUDA out of memory？
减小 per_device_train_batch_size、改用 LoRA，或换 0.5B / DistilBERT。本地闲聊也可改走 Ollama。

Windows 上登录要 Git？
可加 --no-add-to-git-credential，或先安装 Git for Windows。

#下一步

• 快速上手
• Pipeline 推理