X-AnyLabeling 快速入门指南

1. 安装部署
- 1.1 前置条件
- 1.2 安装
- 1.3 GUI 安装包
1. 使用方法
1. 打包编译

1. 安装部署

X-AnyLabeling 提供了多种安装方式，包括 pip 安装、源码安装和图形界面安装包。您可以根据自己的需求选择合适的方式。

1.1 前置条件

在安装 X-AnyLabeling 之前，请确保满足以下前置条件：

Python 环境： 推荐使用 Python 3.12 版本（3.11 及以上版本也兼容）。
虚拟环境： 建议使用 Miniconda 或 venv 创建独立的虚拟环境，以避免依赖冲突。
CUDA（可选）： 如果需要 GPU 加速，需确保本地安装了与所用 ONNX Runtime 版本兼容的 CUDA 和 cuDNN。

您可以根据需要选择相应的 CUDA 版本创建环境：

数据来源:

以下命令演示了如何使用 Miniconda 或 venv 创建不同环境：

复制代码

# 1. Miniconda 创建环境（CPU 版本）
conda create --name x-anylabeling-cpu python=3.12 -y
conda activate x-anylabeling-cpu

# 2. Miniconda 创建环境（CUDA 11.x 版本）
conda create --name x-anylabeling-cu11 python=3.12 -y
conda activate x-anylabeling-cu11

# 3. Miniconda 创建环境（CUDA 12.x 版本）
conda create --name x-anylabeling-cu12 python=3.12 -y
conda activate x-anylabeling-cu12

# 4. venv 创建环境（CPU 版本）
python3.12 -m venv venv-cpu
source venv-cpu/bin/activate  # Linux/macOS
# venv-cpu\Scripts\activate     # Windows

# 5. venv 创建环境（CUDA 12.x 版本）
python3.12 -m venv venv-cu12
source venv-cu12/bin/activate  # Linux
# venv-cu12\Scripts\activate     # Windows

# 6. venv 创建环境（CUDA 11.x 版本）
python3.12 -m venv venv-cu11
source venv-cu11/bin/activate  # Linux
# venv-cu11\Scripts\activate     # Windows

除了上述方法，也可以使用 uv 工具来创建虚拟环境。首先安装 uv，然后使用以下命令创建并激活环境：

复制代码

# 1. 安装 uv
# Linux/macOS/WSL2
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# 2. 创建并激活 CPU 环境
uv venv --python 3.12 .venv-cpu
source .venv-cpu/bin/activate      # Linux/macOS/WSL2
# .venv-cpu\Scripts\activate       # Windows

# 3. 创建并激活 CUDA 12.x 环境
uv venv --python 3.12 .venv-cu12
source .venv-cu12/bin/activate     # Linux
# .venv-cu12\Scripts\activate      # Windows

# 4. 创建并激活 CUDA 11.x 环境
uv venv --python 3.12 .venv-cu11
source .venv-cu11/bin/activate     # Linux
# .venv-cu11\Scripts\activate      # Windows

1.2 安装

您可以通过 pip 直接安装 X-AnyLabeling 的最新 Beta 预发布版本。推荐使用 uv 来加速安装：

复制代码

# 1. 安装 uv
pip install -U uv

# 2. 安装 CPU 版本（官方包）
uv pip install --pre "x-anylabeling-cvhub[cpu]"

# 3. 安装 GPU 版本（默认 CUDA 12.x）
uv pip install --pre "x-anylabeling-cvhub[gpu]"

# 4. 安装特定 CUDA 11.x 版本
uv pip install --pre "x-anylabeling-cvhub[gpu-cu11]"

安装完成后，您可以使用以下命令验证安装是否成功：

复制代码

# 检查系统和版本信息
xanylabeling checks

# 显示帮助信息
xanylabeling help

# 显示版本号
xanylabeling version

# 显示配置文件路径
xanylabeling config

验证无误后，即可运行 X-AnyLabeling 应用：

复制代码

xanylabeling

如果您想查看所有可用的命令行选项，可以使用 xanylabeling --help。完整的参数说明如下表所示：

数据来源: ,

1.3 GUI 安装包

除了通过源码或 pip 安装，您还可以下载 X-AnyLabeling 的图形界面安装包来使用。该安装包提供了开箱即用的体验，无需手动安装依赖项。

下载地址：
使用方法： 下载对应平台的安装包后，解压即可直接运行 X-AnyLabeling。相比源码运行，GUI 安装包更加简单方便。

不过，GUI 安装包也有一些限制：

故障排查困难： 如果软件崩溃或出现错误，由于缺少源码调试信息，排查问题可能较为困难。
功能滞后： GUI 版本的功能更新可能滞后于源码版本，可能会缺少最新的功能或存在兼容性问题。
GPU 加速限制： 当前的 GPU 推理加速功能需要用户自行从源码编译，GUI 安装包可能无法直接提供。

因此，建议根据具体需求选择合适的安装方式：如果需要最新功能和更好的性能，推荐使用源码安装；如果追求简便易用，GUI 安装包也是一个不错的选择。

2. 使用方法

X-AnyLabeling 提供了丰富的功能和直观的图形界面来帮助您进行数据标注和模型推理。

以下是一些基本使用方法：

启动应用： 在安装完成并激活虚拟环境后，直接运行 xanylabeling 命令即可启动 X-AnyLabeling GUI。
界面布局： X-AnyLabeling 的界面布局清晰，主要包括顶部菜单栏、左侧工具栏、中间图像显示区和右侧属性/标签面板等区域。

数据来源: ,

加载图像： 通过菜单栏的 File -> Open Directory 打开包含图像的文件夹，或使用 File -> Open File 打开单张图像。
标注工具： 左侧工具栏提供了多种标注工具，如矩形框、多边形、圆形、画笔、橡皮擦等。选择工具后，在图像上绘制标注框或区域即可。
标签管理： 右侧的 Labels 面板用于管理标注标签。您可以选择现有标签或新建标签，并为其指定颜色等属性。
标注操作： 使用快捷键可以快速执行常见操作，例如：上一张图像 （A键）、下一张图像 （D键）、矩形框 （R键）、多边形（P键）等。具体的快捷键可以在界面状态栏查看。
模型推理： X-AnyLabeling 支持多种 AI 模型进行自动标注和推理。在界面左侧点击 AI 图标即可启用自动标注模式，并选择要使用的模型。目前支持的模型包括 Segment Anything (SAM) 系列模型（如 ViT-Base、ViT-Large 等）以及 YOLO 等目标检测模型。

数据来源:

标注导出： 完成标注后，您可以将标注结果导出为多种格式，如 VOC 、YOLO 、COCO 等。通过菜单栏的 Export -> Export to VOC/YOLO/COCO 即可选择导出格式并指定保存路径。

更多详细的使用说明和功能介绍，请参考 X-AnyLabeling 用户手册。

3. 打包编译

如果您需要将 X-AnyLabeling 打包成可执行文件或针对特定平台进行编译，可以按照以下步骤进行：

修改设备配置： 在编译前，请确保修改 anylabeling/app_info.py 文件中的 __preferred_device__ 参数，选择相应的 GPU 或 CPU 版本进行构建。例如，如果要编译 GPU 版本，将其设置为 "cuda"；如果编译 CPU 版本，设置为 "cpu"。
验证 GPU 环境： 如果编译 GPU 版本，需要提前激活对应的 CUDA 环境，并确保已正确安装 onnxruntime-gpu 库。您可以使用 pip list | grep onnxruntime-gpu 命令检查其安装情况。
修改打包配置： 根据目标平台和 CUDA 版本，修改相应的打包配置文件：
- Windows-GPU： 手动编辑 packaging/pyinstaller/specs/x-anylabeling-win-gpu.spec 文件中的 datas 列表，将本地 onnxruntime-gpu 动态库相关的 *.dll 文件添加到列表中。
- Linux-GPU： 手动编辑 packaging/pyinstaller/specs/x-anylabeling-linux-gpu.spec 文件中的 datas 列表，将本地 onnxruntime-gpu 动态库相关的 *.so 文件添加到列表中。同时，请确保下载与您 CUDA 版本匹配的 onnxruntime-gpu 包，并根据官方文档的兼容性信息进行配置。
执行编译命令： 在项目根目录下执行以下命令进行打包编译：
- Windows-CPU： bash scripts/build_executable.sh win-cpu
- Windows-GPU： bash scripts/build_executable.sh win-gpu
- Linux-CPU： bash scripts/build_executable.sh linux-cpu
- Linux-GPU： bash scripts/build_executable.sh linux-gpu
- macOS： bash scripts/build_executable.sh macos

解决权限问题（Windows）： 如果在 Windows 上执行上述脚本时遇到权限问题，可在确保完成上述准备步骤后，直接使用 pyinstaller 命令手动编译：

复制代码

# 编译 CPU 版本
pyinstaller --noconfirm packaging/pyinstaller/specs/x-anylabeling-win-cpu.spec

# 编译 GPU 版本
pyinstaller --noconfirm packaging/pyinstaller/specs/x-anylabeling-win-gpu.spec

通过以上步骤，您可以将 X-AnyLabeling 打包成适用于不同平台的可执行文件。编译完成后，生成的可执行文件通常位于 dist 目录下。

需要注意的是，打包编译过程可能会因为依赖关系或平台差异遇到问题。如果遇到困难，请参考官方文档或社区支持获取帮助。

参考资料

1

Installation -- AnyLabeling

https://anylabeling.nrl.ai/docs/installation[2]

X-AnyLabeling 开启 ultralytics GPU训练模式

https://www.e-com-net.com/article/1990929045709185024.htm[3]

使用AnyLabeling标注图片

https://blog.csdn.net/xulibo5828/article/details/154707998[4]

X-AnyLabeling 自动数据标注保姆级教程：从安装到格式转换 ...

https://blog.csdn.net/qq_42910179/article/details/155908309

1. 软件定位

X-AnyLabeling 是一个支持多种视觉标注与推理能力的工具，支持：

图像标注
标签格式转换
目标检测 / 分割 / 追踪
OCR、关键点、视觉提示定位等扩展功能

2. 安装方式总览

2.1 三种主要安装方式

安装方式	特点	是否推荐
Pip 安装	简单快速，适合直接体验	适合入门
Git 克隆安装	功能最完整，支持高级功能和二次开发	推荐
GUI 安装包	解压即用，最方便	适合普通用户

2.2 结论

想稳定使用 + 功能完整 ：选 Git 克隆
想快速体验 ：选 Pip
不想配置环境 ：选 GUI 安装包

3. 高级功能说明

以下高级功能 仅适用于 Git 克隆方式：

远程推理服务
视频目标追踪
目标候选框生成
交互式检测分割
智能检测分割
一键训练平台
全模态视觉推理

记忆点：凡是"高级功能"，优先想到源码安装。

4.2 虚拟环境方案

支持三种方式：

A. Miniconda

适合已有 Conda 使用习惯的用户。

CPU 环境

复制代码

conda create --name x-anylabeling-cpu python=3.12 -y conda activate x-anylabeling-cpu

CUDA 11.x

复制代码

conda create --name x-anylabeling-cu11 python=3.12 -y conda activate x-anylabeling-cu11

CUDA 12.x

复制代码

conda create --name x-anylabeling-cu12 python=3.12 -y conda activate x-anylabeling-cu12

B. venv

适合使用 Python 内置环境管理的用户。

CPU

复制代码

python3.12 -m venv venv-cpu source venv-cpu/bin/activate # Windows: venv-cpu\Scripts\activate

CUDA 12.x

复制代码

python3.12 -m venv venv-cu12 source venv-cu12/bin/activate # Windows: venv-cu12\Scripts\activate

CUDA 11.x

复制代码

python3.12 -m venv venv-cu11 source venv-cu11/bin/activate # Windows: venv-cu11\Scripts\activate

C. uv

特点：会自动下载所需 Python 版本，体验更现代。

安装 uv

复制代码

# Linux / macOS / WSL2 curl -LsSf https://astral.sh/uv/install.sh | sh # Windows（PowerShell） powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

创建环境

复制代码

 CPU uv venv --python 3.12 .venv-cpu source .venv-cpu/bin/activate # Windows: .venv-cpu\Scripts\activate # CUDA 12.x uv venv --python 3.12 .venv-cu12 source .venv-cu12/bin/activate # Windows: .venv-cu12\Scripts\activate # CUDA 11.x uv venv --python 3.12 .venv-cu11 source .venv-cu11/bin/activate # Windows: .venv-cu11\Scripts\activate

记忆点：官方推荐安装依赖时优先使用 uv pip。

5. 安装方法详解

5.1 Pip 安装（Beta 预发布版）

先安装 uv：

复制代码

pip install -U uv

CPU

复制代码

uv pip install --pre "x-anylabeling-cvhub[cpu]"

GPU（默认 CUDA 12.x）

复制代码

uv pip install --pre "x-anylabeling-cvhub[gpu]"

GPU（CUDA 11.x）

复制代码

uv pip install --pre "x-anylabeling-cvhub[gpu-cu11]"

特点

安装快
适合体验
版本偏向 Beta 预发布

5.2 Git 克隆安装（推荐）

步骤 1：克隆仓库

复制代码

git clone https://github.com/CVHub520/X-AnyLabeling.git cd X-AnyLabeling

步骤 2：安装依赖

复制代码

pip install -U uv

CPU

复制代码

uv pip install -e ".[cpu]"

GPU（默认 CUDA 12.x）

复制代码

uv pip install -e ".[gpu]"

GPU（CUDA 11.x）

复制代码

uv pip install -e ".[gpu-cu11]"

开发依赖

复制代码

uv pip install -e ".[cpu,dev]"

注意

如果切换到新的工程目录，需要在新目录下重新执行安装命令，否则环境仍然引用旧源码目录。

5.3 GUI 安装包

下载地址：GitHub Releases

优点

解压即用
无需了解底层配置

缺点

出错时不易排查
功能可能落后于源码版
GPU 加速通常仍需源码编译

适用人群

普通体验用户
不想折腾环境配置的用户

准备工作：什么是"虚拟环境"？

在安装软件前，我们需要建一个"隔离的房间"（虚拟环境），避免这个软件的配置把你电脑上其他的 Python 软件弄坏。

官方推荐用 uv 这个超快的新工具来建房间。

第 1 步：安装 uv（建房工具）

打开你电脑的终端（Windows 打开 PowerShell，Mac 打开 Terminal），复制粘贴并回车：

Windows: powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
Mac/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh

第 2 步：创建并进入"房间"

假设你只有普通的电脑 CPU（没有高级的 N 卡），敲这两行：

复制代码

1. 创建一个装有 Python 3.12 的房间，起名叫 .venv-cpu

uv venv --python 3.12 .venv-cpu

2. 进入房间 (Windows 系统)

.venv-cpu\Scripts\activate

或者 (Mac/Linux 系统)

source .venv-cpu/bin/activate

(注意：如果你有带 CUDA 12.x 的 Nvidia 显卡，把上面名字里的 cpu 换成 cu12 即可)

进入"房间"后，我们开始把 X-AnyLabeling 搬进来。

1. 把源码下载到本地

复制代码

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

cd X-AnyLabeling

2. 安装软件及依赖

如果是普通电脑（CPU）：

复制代码

更新 uv

pip install -U uv

安装 X-AnyLabeling (注意最后有个点和中括号)

uv pip install -e ".[cpu]"

(如果你是 GPU 用户，把 [cpu] 换成 [gpu])

3. 见证奇迹：启动软件！

安装完成后，直接在终端输入：

复制代码

xanylabeling

如果弹出了软件界面，恭喜你，闯关成功！🎉

💡 常用命令速查备忘录

把下面这些命令当作你的"作弊代码"，以后遇到问题随时查：

我想干什么？	我该敲什么代码？
检查系统和版本信息 (报错时常用)	`xanylabeling checks`
查看软件版本号	`xanylabeling version`
遇到困难，想看帮助说明	`xanylabeling help`
转换标签格式 (比如转成 YOLO 格式)	`xanylabeling convert`
重置软件所有设置 (软件卡死或配置乱了)	`xanylabeling --reset-config`

🚧 小白避坑指南（划重点）

高级功能暂不碰 ：文档里提到的"视频目标追踪"、"远程推理服务"、"打包编译 (第3部分)"，初学阶段完全不需要看，直接跳过，等以后变成老手了再说。
避免冲突 ：如果你以前装过旧版的 anylabeling，记得先卸载它：pip uninstall anylabeling -y。
切换目录会报错 ：如果你把刚才下载的 X-AnyLabeling 文件夹移动到了别的地方，你需要重新在新的文件夹里执行一次安装命令（uv pip install -e ".[cpu]"）。
Fedora 系统鼠标卡顿 ：如果你刚好在用 Fedora Linux，启动时加上这句：xanylabeling --qt-platform xcb。

进阶玩法：常用启动"快捷键"（命令行参数）

官方文档里有一个长长的"选项描述"表格，看起来很吓人。其实，这就像是你打开游戏时加的启动参数。我帮你挑出了小白最容易用到的几个，教你如何组合使用：

如果你平时只是直接敲 xanylabeling 启动软件，下次可以试试加上这些"魔法小尾巴"：

🛡️ 防手滑神器（自动保存）：

xanylabeling --autosave

强烈推荐！开启后会自动保存你的标注数据，再也不怕突然断电或手滑关掉软件导致白干了。
📂 直接打开目标文件夹：

xanylabeling /你的文件夹路径/

启动软件的同时，直接加载这个文件夹里的所有图片，省去了在软件里点"文件 -> 打开目录"的步骤。
💾 指定标签存放在哪：

xanylabeling --output /你想保存的路径/

默认情况下，标注生成的 .json 文件会和原图片混在一起。用这个命令可以把它们统一存放到你指定的地方，保持图片文件夹清爽。
🎞️ 视频标注小助手（保留上一帧）：

xanylabeling --keep-prev

如果你在连续标注视频的每一帧（比如画面里有个人在走路），开启这个功能，软件会自动把上一张图的框"复制"到下一张图，你只需要微调就行，极大提升效率！

高能防坑区：想用 GPU（显卡）加速？注意这些！

文档中特别提到了 Important（重要） 和 Warning（警告） 两个板块，全都是针对 N 卡（NVIDIA 显卡）用户的。

如果你觉得用 CPU 跑 AI 自动标注太慢，想用 GPU 加速，你需要面对一个非常严格的"相亲匹配"过程：

版本必须门当户对：你的显卡驱动（CUDA 版本）和底层推理库（ONNX Runtime）必须完美兼容。
死磕版本号（针对 CUDA 11.x 用户）：官方严正警告，依赖库的版本必须刚好卡在这个区间：
- onnx 必须在 1.15.0 到 1.16.0 之间。
- onnxruntime-gpu 必须在 1.15.0 到 1.18.x 之间。

💡 建议： 如果你对配置环境变量、查显卡驱动版本一头雾水，请先安心使用 CPU 版本。等熟练了基础操作，再考虑折腾显卡加速。

文档的后半部分涉及了一些高阶操作，这里告诉你它们是干嘛的，然后你可以放心地假装没看见：

可选步骤：刷新翻译与资源文件 (generate_languages.py)
- 这是啥？ 这是给参与软件开发、帮软件做各国语言翻译的人用的。
- 小白对策： 不管它。
可选步骤：设置环境变量 (PYTHONPATH)
- 这是啥？ 告诉电脑你的软件源码放在哪，防止电脑找不到文件。如果你严格按照上一篇笔记里的步骤在虚拟环境里安装了，这一步基本不需要做。
第 3 部分：打包编译 (build_executable.sh / pyinstaller)
- 这是啥？ 把你电脑上的这堆 Python 代码，打包变成一个双击就能运行的 .exe (Windows) 或 .app (Mac) 安装包，发给别人用。

6. 安装后验证

常用验证命令

复制代码

xanylabeling checks xanylabeling help xanylabeling version xanylabeling config

启动程序

复制代码

xanylabeling

查看全部命令行选项

复制代码

xanylabeling --help

7. 常用命令速查

7.1 核心命令

命令	作用
`xanylabeling`	启动程序
`xanylabeling checks`	检查系统和版本信息
`xanylabeling help`	查看帮助
`xanylabeling version`	查看版本号
`xanylabeling config`	查看配置文件路径

7.2 转换命令

复制代码

xanylabeling convert xanylabeling convert <task>

例：

复制代码

xanylabeling convert xlabel2yolo

用途：

列出支持的格式转换任务
查看具体任务帮助
批量进行标签格式转换

8. 命令行参数重点记忆

参数	作用
`filename`	指定图像或标签文件；如果给目录则加载全部文件
`--help, -h`	显示帮助信息
`--reset-config`	重置 Qt 配置
`--logger-level`	设置日志级别
`--output, -O, -o`	指定输出文件或目录
`--config`	指定配置文件或 YAML 配置字符串
`--work-dir`	指定工作目录
`--nodata`	不在 JSON 中保存图像数据
`--autosave`	自动保存标注
`--nosortlabels`	禁用标签排序
`--flags`	传入标志列表或标志文件
`--labelflags`	标签专用标志配置
`--labels`	标签列表或标签文件
`--validatelabel`	设置标签验证方式
`--keep-prev`	保留上一帧标注
`--no-auto-update-check`	禁止启动自动更新检查

高频参数记忆：--autosave、--output、--config、--keep-prev

9. GPU 加速注意事项

若要启用 GPU 推理，需要确保：

本地 CUDA 版本匹配
cuDNN 版本匹配
ONNX Runtime 版本兼容

CUDA 11.x 特别要求

onnx >= 1.15.0, < 1.16.1
onnxruntime-gpu >= 1.15.0, < 1.19.0

核心记忆：GPU 问题大多出在 CUDA / cuDNN / onnxruntime 版本不匹配。

10. 可选操作

10.1 刷新翻译与资源文件

适用于修改界面文案、多语言维护。

复制代码

python scripts/generate_languages.py python scripts/compile_languages.py

作用

重新生成 .ts
编译 .qm
重建 Qt 资源

10.2 设置环境变量

Linux / macOS

复制代码

export PYTHONPATH=/path/to/X-AnyLabeling

Windows

复制代码

set PYTHONPATH=C:\path\to\X-AnyLabeling

10.3 卸载旧版本避免冲突

复制代码

pip uninstall anylabeling -y

这是为了避免与第三方包或旧版本冲突。

10.4 Fedora KDE 性能问题

如果鼠标移动缓慢或界面响应延迟，可尝试：

复制代码

xanylabeling --qt-platform xcb

11. 打包编译笔记

11.1 这部分适合谁？

仅适用于：

需要定制软件
需要自己编译发布
有特殊部署场景

普通使用者可跳过。

11.2 编译前注意事项

必做检查

修改 anylabeling/app_info.py 中的 __preferred_device__
如果编译 GPU 版，先激活对应 GPU 环境
执行以下命令确认 GPU 依赖正常：

复制代码

pip list | grep onnxruntime-gpu

平台特殊要求

Windows GPU

需要修改：

packaging/pyinstaller/specs/x-anylabeling-win-gpu.spec

并在 datas 中加入本地 onnxruntime-gpu 相关 .dll

Linux GPU

需要修改：

packaging/pyinstaller/specs/x-anylabeling-linux-gpu.spec

并在 datas 中加入本地 onnxruntime-gpu 相关 .so

11.3 编译命令

复制代码

# Windows-CPU bash scripts/build_executable.sh win-cpu # Windows-GPU bash scripts/build_executable.sh win-gpu # Linux-CPU bash scripts/build_executable.sh linux-cpu # Linux-GPU bash scripts/build_executable.sh linux-gpu # macOS bash scripts/build_executable.sh macos

Windows 遇到权限问题

可直接执行：

复制代码

pyinstaller --noconfirm packaging/pyinstaller/specs/x-anylabeling-win-cpu.spec pyinstaller --noconfirm packaging/pyinstaller/specs/x-anylabeling-win-gpu.spec