huggingface transformers调试问题--加载本地路径模型时pdb断点消失
问题描述
在 Hugging Face Transformers 动态加载的模块缓存文件中设置 pdb.set_trace() 断点后，断点“消失”或文件被还原为原始内容。
原因
这是 Hugging Face 的模块缓存机制导致的正常行为
1. Hugging Face 动态加载机制
我使用如下方式加载deepseek-ocr模型：
from transformers import AutoModel, AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained(pretrained_model_name_or_path="H:\code_space\study\deepseek-ocr\deepseek-ocr-hf", trust_remote_code=True)
model = AutoModel.from_pretrained(pretrained_model_name_or_path="H:\code_space\study\deepseek-ocr\deepseek-ocr-hf", trust_remote_code=True, use_safetensors=True)
如果模型目录包含 modeling_*.py 文件（如 modeling_deepseekocr.py），Hugging Face 会：
将该文件复制到缓存目录（如 ~/.cache/huggingface/modules/transformers_modules/…）
动态导入该缓存副本（而非你本地的原始文件）
2. 缓存文件是“只读快照”
- 每次 from_pretrained() 时，Hugging Face 会重新生成缓存文件（覆盖旧缓存）
- 因此，我在缓存文件中手动添加的 pdb.set_trace() 会被 原始文件内容覆盖
== 这就是看到“断点消失、文件回滚”的根本原因 ==。
正确调试方法
方法 1：直接修改原始模型文件（推荐）
不要修改缓存文件，而是修改本地模型目录中的 modeling_deepseekocr.py：
# 你的模型路径（不是缓存路径！）
H:\code_space\study\deepseek-ocr\deepseek-ocr-hf\modeling_deepseekocr.py
然后重新运行脚本，Hugging Face 会自动将修改同步到缓存。
⚠️ 注意：确保你加载的是本地路径，而非 hub 名称：
model = AutoModelForCausalLM.from_pretrained("H:/code_space/study/deepseek-ocr/deepseek-ocr-hf")
方法 2：禁用模块缓存（强制每次都加载原始文件）
设置环境变量，禁止 Hugging Face 缓存动态模块：
export HF_MODULES_CACHE="" # Linux/Mac
# 或
set HF_MODULES_CACHE= # Windows (CMD)
$env:HF_MODULES_CACHE = "" # Windows (PowerShell)
这样每次都会从原始路径加载，不会使用缓存。
方法 3：手动清除缓存后修改
- 删除缓存目录：
rm -rf C:\Users\pc\.cache\huggingface\modules\transformers_modules\deepseek-ocr-hf - 修改你本地的
modeling_deepseekocr.py（添加pdb） - 重新运行脚本 → Hugging Face 会用你修改后的版本生成新缓存
方法 4：使用 importlib.reload（高级）
如果在交互式环境（如 Jupyter）中调试：
import sys
import importlib
from pathlib import Path# 强制从本地路径加载
sys.path.insert(0, "H:/code_space/study/deepseek-ocr")
import modeling_deepseekocr
importlib.reload(modeling_deepseekocr)# 然后手动构建模型（不使用 AutoModel）
config = DeepseekOCRConfig.from_pretrained(...)
model = DeepseekOCRForCausalLM(config)
state_dict = torch.load(".../pytorch_model.bin")
model.load_state_dict(state_dict, strict=False)