如何本地保存/加载HuggingFace表格识别模型及图像处理器

背景 #

在Python 3.10中尝试将HuggingFace的microsoft/table-transformer-structure-recognition模型及其图像处理器保存到本地磁盘，目的是后续在Docker容器中加载时，无需每次启动容器和Python服务都从HuggingFace拉取模型权重与配置。

目标 #

替换在线加载写法，改为从本地目录加载：

from transformers import pipeline

# 原在线加载写法
pipe = pipeline(
        task="object-detection",
        model="microsoft/table-transformer-structure-recognition",
)

# 期望的本地加载写法
pipe = pipeline(
        task="object-detection",
        model="./local_model_directory",
)

尝试1：通过pipeline保存/加载（失败） #

保存成功 #

使用pipe.save_pretrained保存模型，本地目录生成config.json和pytorch_model.bin两个文件：

pipe = pipeline(
        task="object-detection",
        model="microsoft/table-transformer-structure-recognition",
)

pipe.save_pretrained("./local_model_directory")

加载失败 #

用本地路径加载时触发报错：

OSError: ./local_model_directory does not appear to have a file named preprocessor_config.json.

尝试2：手动下载缺失文件（失败） #

从HuggingFace手动下载preprocessor_config.json和model.safetensors并添加到本地目录后，加载时出现新错误：

AttributeError: 'NoneType' object has no attribute 'get'

尝试3：手动保存模型和图像处理器（成功但有警告） #

不通过pipeline，直接加载模型和特征提取器再保存，本地目录生成config.json、preprocessor_config.json、pytorch_model.bin三个文件：

from transformers import AutoFeatureExtractor, AutoModelForObjectDetection

extractor = AutoFeatureExtractor.from_pretrained(
    "microsoft/table-transformer-structure-recognition"
)
model = AutoModelForObjectDetection.from_pretrained(
    "microsoft/table-transformer-structure-recognition"
)

extractor.save_pretrained("./local_model_directory")
model.save_pretrained("./local_model_directory")

此时用pipeline("object-detection", model="./local_model_directory")加载成功，但弹出警告：

python3.10/site-packages/transformers/models/detr/feature_extraction_detr.py:28: FutureWarning: The class DetrFeatureExtractor is deprecated and will be removed in version 5 of Transformers. Please use DetrImageProcessor instead.

完整解决方法 #

消除警告的正确保存方式 #

使用官方推荐的DetrImageProcessor替代已废弃的AutoFeatureExtractor，保存后加载无警告：

from transformers import DetrImageProcessor, AutoModelForObjectDetection

# 加载图像处理器和模型
processor = DetrImageProcessor.from_pretrained(
    "microsoft/table-transformer-structure-recognition"
)
model = AutoModelForObjectDetection.from_pretrained(
    "microsoft/table-transformer-structure-recognition"
)

# 保存到本地目录
processor.save_pretrained("./local_model_directory")
model.save_pretrained("./local_model_directory")

本地加载验证 #

使用以下代码加载本地模型，可正常运行且无警告：

from transformers import pipeline

pipe = pipeline(
    task="object-detection",
    model="./local_model_directory"
)

# 可添加测试代码验证模型功能
# 示例：result = pipe("test_table_image.jpg")

问题原因说明 #

1. pipe.save_pretrained仅保存模型权重和配置，不会自动保存图像处理器的配置文件（preprocessor_config.json），导致加载时缺失必要文件。
2. 手动下载文件时，可能因文件版本不匹配（如model.safetensors与本地pytorch_model.bin冲突）引发属性错误。
3. AutoFeatureExtractor已被官方标记为废弃，改用DetrImageProcessor是符合最新版本规范的写法，可消除警告。

内容的提问来源于stack exchange，提问作者Jay