常见问题解答 (FAQ)
安装与运行相关问题
Q：启动时报错“仅完成部分的 ReadProcessMemory 或 WriteProcessMemory 请求”
可尝试重新打开一次。
Q: 启动时报错：ImportError: No module named expat; use SimpleXMLTreeBuilder instead
Conda 会自动更新系统库（如 expat）到最新版本，导致与预编译的 Python 模块不兼容。可尝试下载低版本 expat 解决，如：
conda install expat=2.5.0 -y
Q: 在 Fedora KDE 等环境下鼠标移动缓慢，响应延迟
在 Fedora KDE 桌面环境（包括 Wayland 和 X11）下，可能会遇到画布上鼠标指针移动缓慢、响应延迟的性能问题。
- 方法1：使用命令行参数强制使用 XCB 平台
python -m anylabeling --qt-platform xcb
- 方法2：设置环境变量
export QT_QPA_PLATFORM=xcb
python -m anylabeling
详情可参考#1145。
Q: 启动时报错：Failed to execute script 'app' due to unhandled exception: 'str' object does not support item assignment
删除用户目录下的配置文件后再重启。 可参考#996。
Q: 启动时报错：OPENSSL_Uplink(00007FFE6B47AC88,08): not OPENSSL_Applink
可参考#941。
Q: 程序运行时崩溃，出现 Qt5Core.dll 依赖库错误
可参考#907。
Q: 启动时报错：Gtk-WARNING **: 17:40:30.674: Could not load a pixbuf from icon theme
可参考#893。
Q: 启动时报错：AttributeError: 'NoneType' object has no attribute 'items'
可删除用户目录下的 .xanylabelingrc 文件再尝试重启。可参考#877。
Q: 启动时报错：Could not locate cublasLt64_12.dll. Please make sure it is in your library path!
Q: 启动时报错：qt.qpa.plugin: Could not load the Qt platform plugin "xcb" in "" even though it was found
Q: 启动时报错：qt.qpa.plugin: Could not find the Qt platform plugin "wayland" in "/usr/lib/qt/plugins/platforms/"
可参考#761。
Q：GPU 版本运行时闪退
可参考#500。
Q: QStandardPaths: wrong permissions on runtime directory /run/user/1000/, 0755 instead of 0700
添加 chmod 0700 /run/user/1000/ 到 .bashrc 文件中激活并重新启动应用即可。
Q: 启动软件时出现 AttributeError: module 'importlib.resources' has no attribute 'files'
请将 Python 版本升级至 3.11 及以上。
界面交互相关问题
Q: 如何快速绘制小目标物体？
可参考 #1000。
Q: 如何标注镂空目标用于图像分割任务？
可参考 #991。
Q: 如何快速进行多目标关键点标签与分组标注？
可参考 #982。
Q: 绘制矩形等目标框时，如何开启连续绘制模式？
可以打开电脑用户目录下的 .xanylabelingrc 配置文件，修改 auto_highlight_shape 和 auto_switch_to_edit_mode 为 False。 可参考 #887。
Q: 在高分辨率显示器上界面显示模糊
可参考#811。
Q: 标注完成后，没有弹出标签管理器自动分配标签名称？
取消勾选 Auto Use Last Label，可参考#805。
Q: 复制粘贴标注对象时出现重叠？(Duplicate Polygons vs Copy & Paste Objects)
X-AnyLabeling 提供两种用途不同的复制方式：
Ctrl+D用于在当前图片中快速复制对象。新对象默认会偏移 2 个像素，避免与原对象完全重叠。Ctrl+C和Ctrl+V主要用于跨图片复制对象。粘贴时会保留原坐标，因此在同一张图片中粘贴时会与原对象重叠。
系统剪贴板默认关闭，此时复制内容仅保存在应用内部，切换图片后仍可粘贴。若需将标注以 JSON 格式写入系统剪贴板，可启用 Edit > Use System Clipboard；启用后，每次复制都会覆盖系统剪贴板中的原有内容。
Q: 无法打开 .jpg、.png 等格式的图片？
可参考#823。
Q: 打不开超大分辨率图片，或打开大图时提示内存限制？
这通常不是图片文件本身体积过大，而是 Qt 在解码图片时命中了 QImageReader 的默认分配上限（默认约为 256 MB）。
你可以按需手动调整这个限制：
- 方式1：通过 GUI 设置
打开
Settings（Ctrl+0）>General，修改Qt Image Allocation Limit - 方式2：通过配置文件
编辑用户目录下的
.xanylabelingrc，设置qt_image_allocation_limit - 方式3：通过启动参数
使用
--qt-image-allocation-limit
示例：
qt_image_allocation_limit: 1024
xanylabeling --qt-image-allocation-limit 1024
说明：
null：保留 Qt 默认限制0：禁用该限制- 其他正整数：按 MB 指定新的上限，例如
512、1024
修改该设置后需要重启应用才能生效。若机器内存较小，不建议直接设置为 0。
模型相关问题
Q: 如何使用带 NMS 的 YOLO26 模型（自动标注时出现多个重叠框如何解决）？
YOLO26 默认导出为 end2end（NMS-free）模型，若希望使用带 NMS 的后处理以消除重叠框，可按以下方式操作：
- 从 PT 导出 ONNX 时，将参数设置为 end2end=false；
- end2end=false 时后处理与 YOLO11 一致，因此在自定义模型配置文件中需将 type 设为 yolo11，不要使用 type: yolo26。
详情可参考 #1280。
Q: 为什么使用预编译的 EXE 运行 Ultralytics（YOLO）训练会报错？
目前，通过 X-AnyLabeling 的预编译可执行文件（EXE）版本直接进行 Ultralytics/YOLO 模型训练暂不支持。主要原因包括：1）官方发布的 EXE 默认未打包 Ultralytics 训练环境；2）将应用打包成独立 EXE 后，Python 在子进程调用、动态脚本执行（例如 train_script.py）等方面存在固有的复杂性和限制，无法像在源码环境中一样正确生成并调用训练脚本。
在 Python 源码环境中运行 X-AnyLabeling 时，训练功能可正常使用。因此如需进行 YOLO 模型训练，请使用 Python 环境运行本软件。
详情可参考 #1100。
Q: 在 venv 环境中运行时出现 "Error loading tokenizer: No such file or directory (os error 2)"
这个问题的根源在于 Python 的资源加载机制。当我们用 importlib.resources.files() 获取包内资源时，它返回的实际上是一个 Traversable 对象。这个对象在不同环境下的行为会有差异：在某些情况下（比如通过 pip install -e . 可编辑模式安装时），直接把 Traversable 对象当作文件路径传给需要真实路径的函数（如 Tokenizer.from_file()）就会出现文件找不到的错误。
此问题已修复。资源加载方式已统一改为 read_text()，直接读取资源内容而不是依赖文件路径，从而确保在不同安装方式和运行环境下正常工作。如果仍遇到此问题，建议重新安装或更新 X-AnyLabeling。
Q: Error in model predict_shapes: ModelManager.new_auto_labeling_result[AutolabelingResult].emit(): argument 1 has unexpected type 'list'
通常是加载了损坏或无效的图像文件，或者当前图像格式不支持等原因所造成。
Q: Error in loading model: YOLOE model will be not be available.
可参考#997。
Q: Error in loading model: yoloe with error: [WinError, 1314] 客户端没有所需的特权。mobileclip_blt.pt
可参考#992。
Q: Error in loading custom model: Invalid config file format.
可参考#986。
Q: Error in predict_shapes: cannot access local variable 'p' where it is not associated with a value
可参考#983。
Q: Error in loading model :Could not download or initialize encoder data
可参考#961。
Q: 下载的模型默认保存在什么位置？
可参考#943。
Q: 模型预测的类别跟训练的类别对应不上
检查自定义模型配置文件（*.yaml）是不是格式没写对：
- 默认2个字符缩进；
- key 不能有空格； 可参考#923。
Q: Chatbot 中如何访问 'Google Gemini' 等需要外网访问的模型？
可在当前终端或者系统配置文件中设置代理协议，其中 ip 和 port 替换为自己的网络协议地址和端口号：
export http_proxy=http://ip:port
export https_proxy=http://ip:port
Q: 使用 Chatbot 时报错 "Using SOCKS proxy, but the 'socksio' package is not installed"
当系统环境变量中配置了 SOCKS 代理（如 ALL_PROXY=socks5://...）时，Chatbot 所依赖的 httpx 需要额外安装 socksio 才能支持 SOCKS 协议。手动安装即可解决：
pip install httpx[socks]
Q: ERROR | model_manager:predict_shapes:2031 - Error in predict_shapes: '<=' not supported between instances of 'int' and 'str'
请检查模型配置文件（*.yaml）是否正确，具体可参考此#902。
Q: Error in model prediction:openCV(4.7.0)xxx\opencv-python\opencv-python\opencv\modulesl\imgproc\src\resize.cpp:4065: error: (-215:Assertion failed) inv_scale_x >0 in function'cv::resize'
Q: 运行 yolo-pose 模型出现 Error in loading model: 'list' object has no attribute 'items'
未按照官方模板编写配置文件，可参考#880。
Q: Error in predict_shapes or Error in model prediction: list index out of range. Please check the model.
Q: Error with Error in loading model: exceptions must derive from BaseException
Q: Error in model prediction: ‘int’ object is not subscriptable. Please check the model.
如果是非官方内置的自定义模型，请检查模型的预处理、推理和后处理逻辑，参见 #828。
Q: 下载完的模型每次重新启动应用时都被自动删除重新下载
当前程序的处理逻辑是：当检测到本地已有缓存模型时，会先进行完整性校验；若校验失败或文件为空，则删除本地缓存并重新下载；若下载在达到最大尝试次数后仍失败，则停止本次加载并直接报错。该行为不会在单次加载流程中无限循环。
如果网络问题导致下载失败，请先检查网络环境，必要时配置代理或切换模型下载源（GitHub 或 ModelScope），相关设置参见《用户手册》的模型下载源配置。如果模型加载异常，请按照快速入门指南检查 CUDA、cuDNN、ONNX 和 ONNX Runtime 的版本兼容性。本地环境仍难以排查时，可使用 X-AnyLabeling-Server 部署 PyTorch 远程推理服务。
其他失败原因还包括模型路径中存在中文字符，参见 #600。
Q: AI模型推理时如何识别特定的类别？
当前仅支持部分模型设置此选项。具体地，以 yolo 系列模型为例，用户可通过在配置文件中添加 filter_classes，具体可参考此文档。
Q: in paint assert len(self.points) in [1, 2, 4] AssertionError.
可参考#491。
Q: 加载自定义模型报错？
Q: 运行完没有输出结果？
可参考#536。
Q: 使用 Grounding DINO 模型进行 GPU 推理时报错：
Error in predict_shapes: [ONNXRuntimeError] : 1 : FAIL : Non-zero status code returned while running Expand node. Name:'Expand_33526' Status Message: Expand_33526: left operand cannot broadcast on dim 2 LeftShape: {1,900,4}, RightShape: {1,900,256}
可参考#389。
Q: Missing config : num_masks
可参考#515。
Q: AttributeError: 'int' object has no attribute 'replace'
查看配置文件是否有定义纯数字标签。请注意在定义以纯数字命名的标签名称时，请务必将其加上单引号 ''
Q: Unsupported model IR version: 11, max supported IR version: 10
可参考以下解决方案：
import onnx
onnx_model = onnx.load("/path/to/your/onnx_model")
onnx_model.ir_version = 10 # 修改为合适的版本号
onnx.save(onnx_model, "/path/to/onnx_model")
Q: Your model ir_version is higher than the checker's.
onnx 版本过低，请更新：
pip install --upgrade onnx
Q: 如何在 MacOS 上使用 Segment-Anthing Video 功能？
可参考#865。
Q: 运行 GPU 版本时出现 FAIL : Failed to load library libonnxruntime_providers_cuda.so with error: libcudnn.so.9: cannot open shared object file: No such file or directory 错误
Q: 运行 GPU 版本时出现 ImportError: DLL load failed while importing onnx_cpp2py_export: 动态链接库(DLL)初始化例程失败 错误
onnx 和 onnxruntime 库版本不兼容，具体可参考#886
Q: 运行编译好的 GPU 版本时发现模型长时间处于加载状态
这通常是由于 onnx 和 onnxruntime-gpu 版本不匹配导致的。请参考ONNX Runtime 官方兼容性文档确保安装了匹配的 onnx 版本。
文件相关问题
Q: YOLO-Pose 导出的关键点ID均显示为0？
详情参见 #1270。
Q: 导出 Mask 图为空
请按照以下步骤依次检查下：
- 按下
ctrl+g查看当前任务的标注类别和标注类型，确保所有标注类型为polygon对象； - 检查导出配置文件的格式正确，且类别名称与上述步骤所示的标签类别名称相符；
- 升级到最新版本或通过源码运行获取更全面的日志信息。
详情可参考此#1153。
Q: 预编译版本加载视频文件没有成功解析处图片
可参考此#1136。
Q: 在 Labelme 中导入 X-AnyLabeling 的标签会提示 AssertionError 错误
可参考此#1007。
Q: 导出标签时发生错误：Error occurred while exporting annotations. 'xxx' is not in list
请按照以下步骤依次检查下：
- 按下
ctrl+g查看当前任务的标注类别； - 检查导出时上传的标签类别文件（
classes.txt）中定义的类别是否与标注类别名称一一对应； - 检查是否选择了错误的导出类型，例如标注的是矩形框，导出时却选择了分割或旋转框等选项；
Q: 加载图片目录时，出现 segmentation fault 段错误
可参考此#906。
Q: 上传标签文件时发生错误，出现 cannot identify image file xxx
请检查图片文件和标签文件是否分目录存放。参见 #911。
Q: 加载文件时，出现 a bytes-like object is required, not 'NoneType'，确保 xxx.json 是一个有效的标签文件
请检查 *.json 文件中，imagePath 字段值是否与图像文件名一致。具体可参考此#869。
Q: 导入的标签文件为空
请检查是否存在以下情况：
- 标注类型与导出类型不一致，例如标注对象为
rectangle，导出时却选择了Polygon。 - 导入的图像目录中存在多级嵌套的子目录，参见 #839。
Q: 导入和导出 yolo 关键点标签时闪退
请检查模型配置文件（*.yaml）是否正确，具体可参考此#898。
Q: 导入标签时出现 invalid literal for int() with base 10
可参考#782。
Q: Export mask error: "imageWidth"
可参考#477。
Q: operands could not be broadcast together with shapes (0,) (1,2)
可参考#492。
Q: 导出关键点标签时报错：int0 argument must be a string, a byteslike object or a number, not 'NoneType'
group_id字段缺失，请确保每个矩形框和关键点都有对应的群组编号。
Q: 'NoneType' object has no attribute 'shape'
检查文件路径是否包含中文字符。