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：手动清除缓存后修改

1. 删除缓存目录：

   rm -rf C:\Users\pc\.cache\huggingface\modules\transformers_modules\deepseek-ocr-hf

2. 修改你本地的 modeling_deepseekocr.py（添加 pdb）

3. 重新运行脚本 → 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)