Q: 启动时报错：仅完成部分的ReadProcessMemory或 WriteProcessMemory请求。
可尝试重新打开一次。
Q: 启动时报错：ImportError: No module named expat; use SimpleXMLTreeBuilder instead
Conda 会自动更新系统库（如 expat）到最新版本，导致与预编译的 Python 模块不兼容。可尝试下载低版本 expat 解决，如：
conda install expat=2.5.0 -yQ: 在 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!`
方案1：OnnxRunTime 库与 CUDA 版本不兼容，可参考#844； 方案2：针对于没有全局安装 CUDA、CUDNN 的方法，可参考#1014。
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.9 及以上。
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+D 就能快速复制，而且新旧标注框会自动错开，不会重叠。
第二种是传统的剪贴板复制粘贴，也就是 Ctrl+C 加 Ctrl+V 的组合。这个功能的设计初衷是用来跨图片复制标注的。比如你标注了第一张图片里某个位置的物体，想把这个标注直接复制到第二张、...、第n张图片的相同位置上。所以这个功能在粘贴时会严格按照原来的坐标位置来放置标注框，不会做任何偏移。这也是为什么如果你在同一张图片上用 Ctrl+C 和 Ctrl+V，会发现新旧标注框完全重叠在一起，看起来像是"多个标注框对应同一个对象"——其实这就是它的设计行为，并不是 bug。
另外还有个系统剪贴板的设置需要注意。默认情况下，这个功能是关闭的，也就是配置文件里的 system_clipboard 是 false。这时候你用 Ctrl+C 复制的标注数据会存在软件内部的一个变量里，不会影响系统剪贴板的其他内容。这样设计的好处是，即使你切换到其他图片，之前复制的标注内容还在，随时可以粘贴。有些用户可能会觉得"快捷键有概率无法正常触发复制，导致粘贴时依旧沿用上一次的复制结果"，其实这正是这个机制的体现。
如果你想启用系统剪贴板，可以在菜单里找到 Edit -> Use System Clipboard。启用后，复制的标注数据会以 JSON 格式存到系统剪贴板里，你甚至可以在记事本里看到和编辑这些数据。但要注意，这样一来每次复制都会覆盖系统剪贴板的内容。
所以总结一下使用建议：如果你只是在当前图片里复制标注框，建议用 Ctrl+D，它会自动帮你错开位置，避免重叠。如果你需要把标注复制到其他图片上，或者就是想让标注框精确地粘贴在原位置，那就用 Ctrl+C 和 Ctrl+V。
Q: 应用启动时，首次点击无效？
此问题暂时无解。
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: 1024xanylabeling --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()）就会出现文件找不到的错误。
我们将会在 v3.3.4+ 版本中修复了此问题，统一将资源加载方式改为 read_text() 方法，直接读取资源内容而不是依赖文件路径，这样就能确保在任何安装方式和运行环境下都能正常工作。如果你遇到此问题，建议更新到合适的版本。
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: Chatbot 中如何访问 'Google Gemini' 等需要外网访问的模型？
可在当前终端或者系统配置文件中设置代理协议，其中 ip 和 port 替换为自己的网络协议地址和端口号：
export http_proxy=http://ip:port
export https_proxy=http://ip:portQ: 使用 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.
可参考以下解决方案：
- 检查标签名称是否为纯数字，若是，请务必将其加上单引号；
- 检查配置文件中 type 字段是否正确定义，可参考#837、#878；
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}
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 onnxQ: 如何在 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'
检查文件路径是否包含中文字符。