X-anylabeling如何手动加载（自定义）模型 ： 以Segment Anything 为例

提示：

文章目录

• 前言
• 1 手动下载模型至软件默认读取路径
• 2 加载自定义模型
• • 假设你已有模型（.pth），如何进行导出
  • 安装导出工具
  • 导出你的模型，
  • 在标注软件中加载模型
  • 打开软件，加载‘自定义’模型。并选择 上面提到的配置文件
• X-anylabeling 源码安装
• 过程中遇到的问题
• • GPU环境问题
  • opencv
  • 软件提示模型加载错误
  • 运行模型时程序闪退

前言

手动加载模型的需求，主要分为三种情况，

• 情况一 ：因各种网络原因无法加载，软件内置的模型加载方法无法使用
• 情况二 ：内置模型在你的应用场景效果不好，你已微调了这个模型（没有修改结构），想加载进去帮助标注
• 情况三 ：想添加软件暂不支持的自定义模型进入软件

前两种对应的解决方案

1. 手动下载模型文件至软件默认读取位置， 或者以自定义模型形式加入，或者让你的标注软件走你的代理
2. 以自定义模型形式加入

第三种需求，本文暂不涉及，后续会更新。

手动加载模型时因参数配置等情况可能出错，可执行文件版本的X-anylabeling在遇到问题时一般会直接闪退，无法提示错误原因或者Debug排查。这里我建议源码安装X-anylabeling（后简称**“标注软件”**），安装教程可见附录。

1 手动下载模型至软件默认读取路径

标注软件默认的模型下载、存放和读取根目录地址在

# ubntu
~/xanylabeling_data/models

# window
C:\Users\[你的用户名]\anylabeling_data\models

不同的模型存放在不同名字的文件夹中，手动下载的话需要确定文件夹名（及程序内定义的模型名）。如果你在软件中尝试过下载，通常这个模型文件夹是已经建立好了的，只是模型未能成功下载。

当然你也可以通过下述方法，手动查看模型文件夹名字，

首先，打开软件支持模型地址目录，找到你想要使用的模型。本次案例中以SAM ViT-base 模型为例，

打开模型对应的配置文件，name字段即模型在该软件中定义的名字，这也是你需要创建的文件夹名，display_name是在软件GUI中显示给用户的名字

type: segment_anything
name: segment_anything_vit_b-r20230810
display_name: Segment Anything (ViT-Base)
encoder_model_path: https://github.com/CVHub520/X-AnyLabeling/releases/download/v0.2.0/sam_vit_b_01ec64.encoder.onnx
decoder_model_path: https://github.com/CVHub520/X-AnyLabeling/releases/download/v0.2.0/sam_vit_b_01ec64.decoder.onnx
input_size: 1024
max_width: 1024
max_height: 682

待文件夹创造完成后，将两个模型文件下载进去（即图里的 encoder和decoder.onnx）

~/xanylabeling_data/models/segment_anything_vit_b-r20230810
|---- sam_vit_b_01ec64.encoder.onnx
|---- sam_vit_b_01ec64.decoder.onnx

即可完成手动下载文件，这个时候就可以在软件内使用该模型了。
这里面的注意事项就是路径不要输错， 程序版本-模型版本-文件都要做对应。

2 加载自定义模型

官方给这种方式的精确描述是Loading Adapted Custom Models

Adapted models are those that have already been integrated into X-AnyLabeling, so you don’t need to write any code. Refer to the Model List for more details.
已经适配的模型已经集成到 X-AnyLabeling 中，所以你不需要编写任何代码。详情请参见模型列表。软件支持模型地址目录

换句话说，只要你的网络结构和他的一样，就可以加载并辅助标注。

本案例中以Segment Anything模型为例，官方推荐使用
SAM论文仓库地址：的模型

https://github.com/facebookresearch/segment-anything.git

推荐工具仓库：进行模型导出

https://github.com/vietanhdev/samexporter.gi

假设你已有模型（.pth），如何进行导出

X-anylabeling要求模型导出为两个部分 一个 encoder 一个decoder，这样通常只有第一次加载图片时需要编码计算，后续在图上的操作只需要解码，会有不错的实时性提升。

安装导出工具

我建议源码安装，方便查看报错信息和调试
我还建议你新开一个虚拟环境去装这个工具，或者用你微调的sam模型的环境去做。不要使用X-anylabeling的虚拟环境，有不少难以兼容的依赖。

# 创建新环境略 python版本要求 3.10+
pip install torch==2.4.0 torchvision --index-url https://download.pytorch.org/whl/cpu
git clone https://github.com/vietanhdev/samexporter
cd samexporter
pip install -e .

导出你的模型，

可以参考我的脚本， export.sh

echo "Start to export encoder..."

python -m samexporter.export_encoder --checkpoint finetune_model/best_model_0813_6704.pth \
    --output output_models/best_model_0813_6704.encoder.onnx \
    --model-type vit_b \
    --quantize-out output_models/best_model_0813_6704.encoder.quant.onnx \
    --use-preprocess

echo "Export encoder finished"
echo "=========================="

echo "Start to export decoder..."

python -m samexporter.export_decoder --checkpoint finetune_model/best_model_0813_6704.pth \
    --output output_models/best_model_0813_6704.decoder.onnx \
    --model-type vit_b \
    --quantize-out output_models/best_model_0813_6704.decoder.quant.onnx \
    --return-single-mask

echo "Export encoder decoder"

以下是encoder导出和decoder导出的相关参数的解析。

python -m samexporter.export_encoder \
    --checkpoint finetune_model/best_model_0813_6704.pth \ # 指定要导出的模型检查点文件路径
    --output output_models/best_model_0813_6704.encoder.onnx \ # 指定导出后的 ONNX 模型文件路径，没有这个文件夹的话会报错，请手动创建
    --model-type vit_b \ # 指定模型类型（例如 vit_b, vit_l 请参考SAM官方工程）
    --quantize-out output_models/best_model_0813_6704.encoder.quant.onnx \ # 指定量化后模型的输出路径
    --use-preprocess # 使用预处理步骤

python -m samexporter.export_decoder \
    --checkpoint finetune_model/best_model_0813_6704.pth \ # 指定要导出的模型检查点文件路径
    --output output_models/best_model_0813_6704.decoder.onnx \ # 指定导出后的 ONNX 模型文件路径
    --model-type vit_b \ # 指定模型类型（例如 vit_b）
    --quantize-out output_models/best_model_0813_6704.decoder.quant.onnx \ # 指定量化后模型的输出路径
    --return-single-mask # 返回单一的掩码，如果希望返回多个掩码则不要加这一行

在标注软件中加载模型

把你导出的 encoder decoder 和对应的模型配置文件（.yaml） 放在程序模型目录中

# ubntu
~/xanylabeling_data/models

# window
C:\Users\[你的用户名]\anylabeling_data\models

例如我的模型放在在这个目录下的一个新建文件夹custom_model中

~/xanylabeling_data/models/custom_model
|---- best_model_0813_6704.encoder.onnx
|---- best_model_0813_6704.decoder.onnx
|---- segment_anything_vit_b.yaml    #配置文件

提示：虽然你可以把模型放在任何位置。但是我强烈建议你按本文档操作： 将这三个文件放在软件模型存放地址下的同级目录，避免出现一些路径中转义字符的错误。如果你用的是可执行文件的软件版本，模型加载错误时进程闪退，不会给你任何提示，让你摸不着头脑。

修改 segment_anything_vit_b.yaml 文件，将编码器encoder_model_path 解码器 decoder_model_path地址重新指向 模型位置。display_name改成自己喜欢的 其余的不要动。

type: segment_anything
name: segment_anything_vit_b_quant-r20230520
display_name: Segment Anything (ViT-Base Quant Custom)
encoder_model_path: best_model_0813_6704.encoder.quant.onnx
decoder_model_path: best_model_0813_6704.decoder.quant.onnx
input_size: 1024
max_width: 1024
max_height: 682

这是官方文档翻译的字段解释

打开软件，加载‘自定义’模型。并选择 上面提到的配置文件

应该到这就大功告成了，如果出现闪退一般是模型有问题，
即模型路径是对的，但模型文件有问题，请排查你导出时是否存在问题。
更多信息，你可看官方教程

X-anylabeling 源码安装

官方教程， 本案例中需要配一个 ubuntu GPU Cuda 11.1 可二次开发的环境
克隆工程

git clone https://github.com/CVHub520/X-AnyLabeling.git -b v2.4.0

环境配置， 建议不要修改python版本，否则pyqt可能存在不兼容

conda create --name xany python=3.9 -y
conda activate xany

安装依赖

# Install ONNX Runtime CPU
pip install onnxruntime

# Install ONNX Runtime GPU , 官方文档中建议至少版本为1.16.0
pip install onnxruntime-gpu==1.16.0

cd X-AnyLabeling/

# 安装GPU 开发版环境
pip install -r requirements-gpu-dev.txt

#生成资源
pyrcc5 -o anylabeling/resources/resources.py anylabeling/resources/resources.qrc

设置相关路径

sudo gedit ~/.bashrc

# 打开 ~/.bashrc 后写入环境变量，改成你文件夹路径
export PYTHONPATH=/path/to/X-AnyLabeling

# 写完后更新
source ~/.bashrc

启动程序

python anylabeling/app.py

过程中遇到的问题

GPU环境问题

[W:onnxruntime:Default, onnxruntime_pybind_state.cc:541 CreateExecutionProviderInstance] Failed to create CUDAExecutionProvider. Please reference https://onnxruntime.ai/docs/reference/execution-providers/CUDA-ExecutionProvider.html#requirements to ensure all dependencies are met.

# or

[E:onnxruntime:Default, provider_bridge_ort.cc:1480 TryGetProviderInfo_CUDA] /onnxruntime_src/onnxruntime/core/session/provider_bridge_ort.cc:1193 onnxruntime::Provider& onnxruntime::ProviderLibrary::Get() [ONNXRuntimeError] : 1 : FAIL : Failed to load library libonnxruntime_providers_cuda.so with error: libcudnn.so.8: 无法打开共享对象文件: 没有那个文件或目录

前者，onnxruntime-gpu环境有误，可以参考，

https://blog.csdn.net/qq_40541102/article/details/130086491

后者，缺cudnn库

opencv

cv2.error: OpenCV(4.10.0) /io/opencv/modules/highgui/src/window.cpp:1301: error: (-2:Unspecified error) The function is not implemented. Rebuild the library with Windows, GTK+ 2.x or Cocoa support. If you are on Ubuntu or Debian, install libgtk2.0-dev and pkg-config, then re-run cmake or configure script in function 'cvShowImage'

https://blog.csdn.net/beautifulback/article/details/125504940

软件提示模型加载错误

X-anylabling提示

Error in loading model: exceptions must derive from BaseException

在我这是模型路径有问题，产生了这个报错。yaml文件中修改为正确的模型路径后成功

运行模型时程序闪退

我的模型地址写错了 写成了两个decoder，所以不会提示模型不存在，但是加载和运行肯定会报错