模型下载失败主因是网络不通或Hugging Face认证缺失；微调OOM因默认加载float32权重，推理应优先用device_map="auto"；混合精度报错需检查数据类型并合理配置fp16/bf16。

模型下载失败：from_pretrained 卡住或报 ConnectionError

网络不通或 Hugging Face Hub 认证缺失是主因，不是代码写错了。国内直接调用 from_pretrained 默认走官方 CDN，没代理基本会卡在“Resolving model”阶段，甚至抛出 requests.exceptions.ConnectionError 或 OSError: Can't load config。

• 优先用离线方式：先手动下载模型文件夹（含 config.json、pytorch_model.bin 等），再传本地路径给 from_pretrained，比如 from_pretrained("./bert-base-chinese")
• 若必须在线拉取，加 cache_dir 参数指定缓存位置，并确保环境变量 HUGGINGFACE_HUB_CACHE 一致，避免多用户冲突
• 需要私有模型时，必须提前运行 huggingface-cli login 并配置 token，否则 from_pretrained 会静默失败（尤其 transformers>=4.30）

微调时报 RuntimeError: expected scalar type Float but found Half

混合精度训练（fp16=True）和模型/数据类型不匹配的典型症状。不是模型本身有问题，而是 Trainer 自动启用了 amp，但输入数据没转成 float32，或某些层权重被意外 cast 成了 float16。

• 检查数据预处理：确保 tokenized_dataset 中的 input_ids 是 torch.long，而 labels 是 torch.float32（分类任务）或 torch.long（序列标注），别用 .half() 手动降精度
• 禁用自动混合精度：在 TrainingArguments 中设 fp16=False，先跑通 baseline；确认无误后再开 fp16=True 并配 bf16=True（A100+）或 fp16_full_eval=True
• 自定义 Trainer 时，注意重写的 compute_loss 返回值必须是 torch.Tensor 标量，且 dtype 与模型输出一致

加载后显存爆掉：模型能载入但一 forward 就 OOM

不是模型太大，而是默认加载了完整精度（float32）权重 + 梯度 + 优化器状态。哪怕只是推理，from_pretrained 也会把整个 pytorch_model.bin 解压进显存，没做任何量化或分片。

macOS UI 自动化技能包 —— 用 Python 控制你的 Mac

让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限

下载

• 推理场景优先用 device_map="auto"（transformers>=4.30），它会自动把层分配到 CPU / GPU / disk，配合 offload_folder 可大幅降低 VRAM 占用
• 微调时别盲目加 gradient_checkpointing=True —— 它省显存但增计算，且某些模型（如 ChatGLM）需额外 patch 才兼容
• 小显存设备（bnb_4bit_quant_type="nf4"，bitsandbytes 的 4-bit 加载虽快，但首次 forward 会触发隐式 dequant，反而更吃显存

Trainer 微调结果指标异常：loss 不降、acc 不涨

大概率是数据格式或标签对齐问题，而不是模型能力不足。Hugging Face 的 Trainer 对输入结构非常敏感，错一个字段名或维度就 silently 错训。

立即学习“Python免费学习笔记（深入）”；

• 确认 Dataset 的 __getitem__ 返回字典里含 "input_ids"、"attention_mask"，分类任务还要有 "labels"（不是 "label"），且 labels shape 是 (batch_size,) 而非 (batch_size, 1)
• 检查 tokenizer 是否用了对应模型的专用 tokenizer（比如 bert-base-chinese 必须配 BertTokenizer.from_pretrained("bert-base-chinese")），混用会导致 input_ids 全是 [UNK]
• 验证集 metrics 为 0？可能是 compute_metrics 函数里用了 np.argmax(logits, axis=1)，但 logits 是 (seq_len, num_labels) 形状（如序列标注），得先 logits.view(-1, num_labels)

最麻烦的是模型内部的 label smoothing 或 dropout 随机性——调试时记得固定 seed 和 data_collator 的 shuffle 行为，否则每次跑结果都不一样，根本没法归因。