排坑记录：transformers 报错 ModuleNotFoundError: Could not import module 'SegformerIm

原创

高老师

发布于 2026-09-17 12:07:07

880

排坑记录：transformers 报错 ModuleNotFoundError: Could not import module 'SegformerImageProcessor'

1. 问题背景

在 Linux 服务器（Debian 12 / 宝塔面板 Python 项目管理器）部署服装以图搜图服务时，执行服装语义分割与裁切接口 /api/search_upload?crop_garment=true 时，服务抛出 500 Internal Server Error：

File "/www/wwwroot/laurel-soutu/embedder.py", line 57, in _load_seg
    from transformers import SegformerImageProcessor, SegformerForSemanticSegmentation
File "/www/server/pyporject_evn/versions/3.12.8/lib/python3.12/site-packages/transformers/utils/import_utils.py", line 2648, in __getattr__
    raise ModuleNotFoundError(
ModuleNotFoundError: Could not import module 'SegformerImageProcessor'. Are this object's requirements defined correctly?
INFO: 192.168.205.80:57778 - "POST /api/search_upload?crop_garment=true&filter_category=false HTTP/1.1" 500 Internal Server Error

后续进一步引发：

OSError: PermissionError at /root/.cache/huggingface/token when downloading mattmdjaga/segformer_b0_clothes. Check cache directory permissions.

2. 核心原因剖析

该问题由两个链条问题引起：

链条一：缺少底层 C 扩展导致模块导入失败

transformers 内部使用动态延迟加载（Lazy Import）。
SegformerImageProcessor 会级联引入 torchvision。
torchvision 引入 Python 标准压缩模块 bz2 和 lzma。
宝塔源码编译 Python 3.12 时未装 libbz2-dev 和 liblzma-dev，导致标准库 _bz2.so 与 _lzma.so 缺失。

链条二：进程运行用户与缓存权限冲突（PermissionError）

Web 服务在宝塔下是以低权限的 www 用户身份运行的。
默认情况下 Hugging Face 会将模型缓存写入 /root/.cache/huggingface。
www 用户无权读写 /root 目录，在下载模型 token/文件时直接触发 PermissionError at /root/.cache/huggingface/token。

3. 完整解决方案

第一步：补齐底层 `_bz2` 与 `_lzma` 动态库

# 1. 安装系统依赖头文件
sudo apt-get update && sudo apt-get install -y libbz2-dev liblzma-dev build-essential

# 2. 下载同版本 Python 源码单编目标模块
curl -L -s https://mirrors.huaweicloud.com/python/3.12.8/Python-3.12.8.tgz -o /tmp/Python-3.12.8.tgz
tar -xzf /tmp/Python-3.12.8.tgz -C /tmp && cd /tmp/Python-3.12.8
./configure --prefix=/www/server/pyporject_evn/versions/3.12.8

# 3. 生成并链接动态库
make -j4 Modules/_bz2module.o Modules/_lzmamodule.o
gcc -shared -fPIC Modules/_bz2module.o -lbz2 -o /www/server/pyporject_evn/versions/3.12.8/lib/python3.12/lib-dynload/_bz2.cpython-312-x86_64-linux-gnu.so
gcc -shared -fPIC Modules/_lzmamodule.o -llzma -o /www/server/pyporject_evn/versions/3.12.8/lib/python3.12/lib-dynload/_lzma.cpython-312-x86_64-linux-gnu.so
rm -rf /tmp/Python-3.12.8*

第二步：解决 PermissionError 权限问题

将模型缓存目录统一指定到当前项目下的独立文件夹（如 hf_cache），并配置国内镜像源加速：

在 config.py 中预先设定环境变量：

import os
from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent
HF_CACHE_DIR = os.environ.get("HF_HOME", str(BASE_DIR / "hf_cache"))

os.environ.setdefault("HF_HOME", HF_CACHE_DIR)
os.environ.setdefault("TRANSFORMERS_CACHE", HF_CACHE_DIR)
os.environ.setdefault("HF_ENDPOINT", "https://hf-mirror.com")

服务器上设置目录所有者给 www 用户：

mkdir -p /www/wwwroot/laurel-soutu/hf_cache
chown -R www:www /www/wwwroot/laurel-soutu

第三步：保持依赖库版本兼容

若使用 transformers 5.x，对于部分未适配 meta tensor 的自定义模型（如 Marqo/marqo-fashionSigLIP），推荐锁定稳定版本：

pip install "transformers==4.49.0"

4. 验证测试

重启服务后，发送图片搜索测试：

POST /api/search_upload?crop_garment=true&filter_category=false

{
  "query_category": "上装",
  "garment_ratio": 0.2536,
  "filtered": false,
  "results": [...]
}

HTTP 状态码 200 OK，服装分割裁切与以图搜图全流程正常运行。

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

huggingface-transformers

排坑记录：transformers 报错 ModuleNotFoundError: Could not import module 'SegformerIm

排坑记录：transformers 报错 ModuleNotFoundError: Could not import module 'SegformerIm

排坑记录：transformers 报错 ModuleNotFoundError: Could not import module 'SegformerImageProcessor'

1. 问题背景

2. 核心原因剖析

链条一：缺少底层 C 扩展导致模块导入失败

链条二：进程运行用户与缓存权限冲突（PermissionError）

3. 完整解决方案

第一步：补齐底层 `_bz2` 与 `_lzma` 动态库

第二步：解决 PermissionError 权限问题

第三步：保持依赖库版本兼容

4. 验证测试

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐

排坑记录：transformers 报错 ModuleNotFoundError: Could not import module 'SegformerIm

排坑记录：transformers 报错 ModuleNotFoundError: Could not import module 'SegformerIm

排坑记录：transformers 报错 ModuleNotFoundError: Could not import module 'SegformerImageProcessor'

1. 问题背景

2. 核心原因剖析

链条一：缺少底层 C 扩展导致模块导入失败

链条二：进程运行用户与缓存权限冲突（PermissionError）

3. 完整解决方案

第一步：补齐底层 _bz2 与 _lzma 动态库

第二步：解决 PermissionError 权限问题

第三步：保持依赖库版本兼容

4. 验证测试

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐

第一步：补齐底层 `_bz2` 与 `_lzma` 动态库