打开实验记录本先标记一下今天的日期。最近在跑一批图像相关的实验数据预处理和标注环节一直用的是半手工方式脚本套脚本效率实在有点说不过去。调研了一圈标注工具之后决定在本地环境里装一个 Annoar把标注流程正式固化下来。说实话一开始我以为这就是个普通的 Python 包pip 一下就能完事结果真正动手才发现安装过程中有不少隐藏的坑比如依赖版本冲突、Python 解释器版本不匹配、初始化模型权重下载失败等等。这篇文章就把 Annoar 的完整安装过程记录下来从环境准备、依赖选型到最终验证每一步都附上我的实际操作和踩坑经历给后面要做同样工作的人一个可以“抄作业”的参考。先说清楚 Annoar 是干什么的。它是一个面向图像和视频数据集的交互式标注工具核心功能包括矩形框标注、多边形分割、关键点标注、标签体系管理和标注结果导出底层依赖 PyTorch 和一些计算机视觉库自带一个 Web 形式的标注界面。对于我这种经常要自建数据集、同时又不希望被商业标注平台的付费模式绑住的人来说这类开源工具确实是对口的方案。这篇文章适合谁看如果你也需要在本地搭建标注环境或者你的 Python 环境比较乱、经常装一个包就引得一堆依赖报错又或者你想搞清楚源码安装和包管理器安装的差别那你照着这篇文章往下走就行。1. 安装前准备与环境选型1.1 为什么先把环境梳理清楚比急着执行安装命令更重要大多数人在安装新工具时习惯直接翻官方 README看到一行pip install annoar就开始执行结果往往是装到一半报错或者装完之后根本启动不起来。我这次特意先停下来做了环境梳理原因很简单Annoar 不是那种零依赖的小工具它牵扯到 PyTorch、torchvision、OpenCV、pillow、numpy、flask、sqlalchemy 等一串底层库而这些库相互之间又有非常强的版本耦合。以 PyTorch 为例不同版本的 torch 对应不同的 CUDA 版本也对应不同的 torchvision 编译结果。如果环境中已经存在一个旧的 PyTorchAnnoar 的依赖解析器可能会尝试升级它而升级之后你原先的其他项目可能又会被破坏。这套连锁反应我在过去两年的实验里见过太多次了。所以遇到这种重型工具我现在的做法是先检查现有的 Python 版本、pip 版本、conda 环境列表再单独为 Annoar 建一个虚拟环境最后才在这个干净的隔离环境里执行安装。这次安装能一路走通很大程度上就得益于这一步没有省略。1.2 环境版本与依赖梳理先交代一下我这次实测用的机器环境操作系统是 Ubuntu 22.04机器上已经有 Anaconda 3Python 版本默认是 3.9 和 3.10 两个环境并存。Annoar 官方文档推荐的 Python 版本是 3.9 到 3.11所以我直接在 conda 里建了一个新的 3.10 环境。依赖方面我在安装前把 Annoar 的依赖清单完整过了一遍。核心依赖可以分成三组我用表格整理出来依赖分组主要组件版本要求实测用途说明深度学习核心torch、torchvisiontorch 2.1.x、torchvision 0.16.x模型推理与特征提取图像处理opencv-python、pillow、numpyopencv 4.8.x、numpy 1.26.x图像读写、预处理、标注渲染后台服务flask、sqlalchemy、flask-cors最新稳定版即可Web 界面、数据库管理这里有一个非常容易踩的坑numpy 的版本。Annoar 的部分旧版本对 numpy 1.24 以下有兼容要求而 PyTorch 2.1 又会主动拉取 numpy 1.26两者在安装过程中可能产生冲突。我的建议是先装 PyTorch再装 Annoar最后再看依赖解析器有没有报错。这个顺序能最大限度避免 torch 被意外的依赖升级破坏。1.3 三种安装方案的取舍Annoar 目前提供三套安装路径pip 包安装、conda 安装、源码编译安装。我最初打算用 pip 直接装但在实际测试中发现pip 版对网络条件的要求比较高因为安装过程中要拉取预训练模型权重而权重文件默认存放在国外的服务器上经常出现下载到一半就断了的情况。conda 安装则是把 Annoar 封装到了 conda-forge 频道对依赖的处理更省心一些但它有个问题就是版本更新有延迟官方发布新版本之后往往要过一段时间才会同步到 conda。源码安装的上手成本最高需要自己拉仓库、装依赖、手动配置环境变量但它最大的优势是能拿到最新的代码而且出现问题的时候可以顺着源码直接定位到具体模块。我在这次安装中实际采用了“pip 安装主程序 源码配置自定义参数”的组合方案先用 pip 把 Annoar 主程序装好再从 GitHub 拉取对应的源码版本把需要定制化的部分比如标注分类配置文件、模型权重路径手动指定到源码目录里。这种方式既省去了纯源码编译的繁琐过程又能保留对新版本功能和自定义参数的掌控权适合我这种既要跑实验又不想过度折腾的人。2. 安装主流程与核心细节2.1 创建独立环境并安装基础依赖整个安装过程的第一步是在 conda 里创建一个干净的虚拟环境。我习惯用命令行操作直接把创建和环境配置放在一起执行conda create -n annoar python3.10 -y conda activate annoar这里解释一下为什么单独建环境Annoar 的依赖链条很长如果跟其他项目混用同一个环境今天升级这个库、明天安装那个包很容易把 Annoar 的依赖关系搅乱。我在这次实验中就遇到过一个邻居项目把 flask 从 2.x 升级到 3.x结果 Annoar 的 Web 服务启动不了的情况。独享环境之后这个问题彻底消失了。环境激活之后紧接着做一轮基础依赖升级避免系统自带的 pip 版本太旧导致后续安装阶段无法正确解析依赖pip install --upgrade pip wheel setuptools这三件套建议每次都先升级一下。特别是 wheel很多库在安装时需要用它来构建本地扩展模块如果 wheel 版本太老安装 opencv-python 这种带二进制扩展的包时会出现莫名其妙的编译错误。随后安装核心的深度学习库。这一步我把 PyTorch 的 CPU 版本和 GPU 版本分开讲。如果你手上只有普通 CPU 或者显卡是集成显卡直接执行pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu如果有 NVIDIA GPU并且已经装好了对应版本的 CUDA 驱动可以考虑安装带 CUDA 12.1 支持的版本pip install torch torchvision这里有个容易犯迷糊的地方如果直接用默认源安装 PyTorchpip 会自动选择一个匹配当前系统的预编译包但不一定是运算速度最优的 CUDA 版本。我在装 Annoar 时第一次就用了默认源结果安装完成后发现 torch.cuda.is_available() 返回了 False后来重新指定带 CUDA 的 wheel 源才解决。建议大家在装完 torch 后立刻跑一句验证python -c import torch; print(torch.__version__, torch.cuda.is_available())如果 CUDA 版本不对后面 Annoar 的模型推理部分会静默退回到 CPU 模式虽然也能用但标注大尺寸图片时的响应速度会明显变慢。2.2 通过 pip 安装 Annoar 主程序基础依赖就绪后就可以正式安装 Annoar 了。主程序包直接从 PyPI 拉取pip install annoar安装过程其实比想象中要长因为它除了拉取 Annoar 本体之外还会自动解析并安装缺失的依赖项比如 flask、sqlalchemy、flask-cors 这一组 Web 服务组件。这一步如果网络不稳定容易卡在某个依赖包的下载上。我的做法是给 pip 配置一个备用镜像源这样下载速度会快很多同时减少超时报错的概率。如果你不太想改全局 pip 配置也可以用临时参数指定源pip install annoar -i https://pypi.tuna.tsinghua.edu.cn/simple安装完成后建议立即验证主程序是否可用避免等到配置阶段才发现安装不完整annoar --version正常情况下会输出类似Annoar 0.8.4的版本号。如果提示找不到命令多半是 conda 环境的 bin 目录没有加入 PATH可以用python -m annoar --version来绕过这个问题。2.3 源码编译安装的完整流程pip 安装虽然方便但有一个局限它只安装发布到 PyPI 的稳定版本。如果你想体验最新特性或者想修改 Annoar 内部的某些逻辑比如自定义标注工具的快捷键映射就必须走源码安装的路线。Annoar 的源码托管在 GitHub 上拉取方式如下git clone https://github.com/your-repo/annoar.git cd annoar pip install -e .pip install -e .是开发模式安装它会把当前目录的源码直接链接到 Python 的 site-packages 中这样你改源码之后无需重新安装重启服务就能生效。我这次安装时为了二次开发标注界面就用了这种模式后面修改前端样式文件时确实省去了重复安装的步骤。不过源码安装也有一个容易忽略的地方项目根目录下需要有一个requirements.txt之外、专门给开发环境用的requirements-dev.txt。如果你打算跑 Annoar 自带的自动化测试记得手动安装pip install -r requirements-dev.txt里面的内容一般是 pytest、black、isort 这一组工具不装也不影响主程序运行但想参与代码贡献或者在本地跑单元测试时就会缺东西。2.4 安装后的目录结构与关键文件说明安装完成后我建议一定抽几分钟了解一下 Annoar 的目录结构。这不是可有可无的步骤而是后续排查问题的根基。默认情况下Annoar 会在用户目录下创建一个隐藏的配置文件夹~/.annoar/ ├── config.yaml ├── annotations.db ├── models/ │ └── efficientnet_b0.pth └── categories/ └── default.json其中config.yaml是全局配置文件里面记录着服务端口号、默认模型路径、数据库连接字符串等核心参数。我这次安装之后把端口从默认的 5000 改成了 8765原因是我本机正好有其他服务占用了 5000 端口不改的话一启动就报端口冲突。annotations.db是 SQLite 数据库文件所有标注结果都存这里面定期备份这个文件就等于备份了全部标注数据。models目录存放预训练模型的权重文件后面要换模型时直接往这个目录里丢新的.pth文件即可。3. 配置验证与最小可用测试3.1 环境变量与启动器配置Annoar 安装好之后并不代表可以立刻投入使用还需要完成两步轻量化配置。第一步是环境变量主要是告诉系统到哪里去找到 Annoar 的可执行文件和数据目录。通常 conda 环境激活后这部分会被自动设置好但我遇到过在部分 Linux 环境下 conda 的bin目录没有被写进.bashrc结果每次新开终端都要手动执行conda activate annoar。为了省事我直接在.bashrc末尾加了一行echo conda activate annoar ~/.bashrc source ~/.bashrc这样每次打开终端就会自动进入 Annoar 环境虽然不是所有人的习惯但对我这种经常忘记激活环境的人来说确实可以少踩一个坑。第二步是启动器配置。Annoar 提供一个命令行启动器annoar-server可以通过它的参数控制服务地址与端口。如果想用自定义配置可以编辑刚才提到的config.yaml也可以直接用命令行参数覆盖annoar-server --host 0.0.0.0 --port 87650.0.0.0表示监听所有网络接口这样如果机器在局域网内其他人也可以通过你的 IP 地址访问标注界面适合团队协作场景。如果只是本机使用建议用127.0.0.1避免暴露到网络里造成不必要的麻烦。3.2 启动服务与基本功能验证配置结束后输入启动命令终端里会输出一段启动日志正常情况下最后一行是Running on http://127.0.0.1:8765。我建议在这里不要急着关终端而是保持前台运行模式方便直接观察实时日志。用浏览器打开地址就能看到 Annoar 的主界面。第一次打开时界面需要加载一些前端资源如果页面一直在转圈大概率是静态资源路径配错了。这个可以在配置文件的static_path项里改。如果页面能正常加载下一步我建议上传一张小尺寸测试图片比如 512x512 的示例图然后新建一个标注任务随便画一个框看能不能保存。这一步走通了就说明 Web 服务、数据库和前端交互这三大块都正常工作了。3.3 跑通一个最小标注流程为了验证整个链路我走了一个最小标注流程先导入一个包含五张猫狗图片的测试文件夹再创建标注任务然后选一张图开始标注。Annoar 的标注界面交互比较直观鼠标左键拖拽就能画矩形框画完后右侧会出现标签选择器我选了默认标签“cat”点击保存。保存后立刻检查数据库里是否多了一条记录sqlite3 ~/.annoar/annotations.db SELECT * FROM annotations LIMIT 5;这一条命令能很快确认标注结果是不是真的落库了。接着我又尝试了导出功能Annoar 支持导出 COCO 格式和 YOLO 格式的标注文件。我导出了 YOLO 格式检查生成的 txt 文件里的坐标是否归一化到 0 到 1 之间发现数据完全正确。到这一步Annoar 的核心功能就算验证完成了。4. 常见安装问题与排查实录4.1 torch 与 CUDA 版本不匹配导致推理失败这是我在整个安装过程中遇到的第一个大问题。启动 Annoar 之后打开自动标注功能系统提示模型加载成功但真正跑推理的时候进度条一直不动日志里没有任何报错。后来我手动在 Python 里执行torch.cuda.is_available()发现返回的是 False这说明我装的 torch 是 CPU 版本而 Annoar 尝试调用 CUDA 却找不到设备最终陷入了一个静默等待的状态。解决办法不复杂先把 CPU 版 torch 卸载再安装对应 CUDA 版本的 torchpip uninstall torch torchvision -y pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121装完后再验证torch.cuda.is_available()输出了 True。重新启动 Annoar自动标注功能就正常了。这里我建议第一次安装时就直接确认 CUDA 环境不要像我一样等到功能异常了才回头查。4.2 opencv-python 版本冲突导致界面渲染异常第二个问题出在 opencv-python 的版本上。我之前的环境里安装过 opencv-python-headless这个版本不带 GUI 相关依赖而 Annoar 的前端数据展示过程中会调用 OpenCV 的图像窗口函数两者存在符号冲突。具体表现是标注界面能打开但图片区域的底图渲染不出来只看到一个空白画布。排查过程花了一点时间。我先用pip list | grep opencv查看已装的包发现同时存在 opencv-python-headless 和 opencv-python 两个包版本还都是 4.8 系列。这种共存的局面在 Python 包管理里很危险我选择先卸载 headless 版本再重装完整版pip uninstall opencv-python-headless -y pip install --force-reinstall opencv-python重装后重启 Annoar图片区域恢复正常。这个坑在外面几乎没有被提过是我的真实教训建议装 Annoar 之前先把自己环境里的 OpenCV 系列情况摸清楚。4.3 Web 服务启动时提示端口被占用端口占用问题是我改端口号之前遇到的。当时一执行annoar-server就报错Address already in use。查了一下原来机器上之前跑的另一个标注服务占用了同样的默认端口。解决办法有两种一是直接换端口二是停掉占用端口的旧服务。换端口最省事在config.yaml里修改port字段或者启动时加--port参数即可。我这次选择改成 8765一个重要考虑是避开常见开发端口段降低以后再和其他服务撞车的概率。这个习惯我现在已经固定下来了新装任何 Web 类工具第一次启动前就先把端口核对一遍。4.4 初始化模型权重下载失败的处理最后一个高频问题就是模型权重下载失败。Annoar 首次启动自动标注功能时会尝试下载预训练模型权重如果网络环境不算理想下载到 20% 左右很容易断掉而且重启之后不会断点续传只能从头再来。我的办法是手动下载权重文件再放到指定目录。打开 Annoar 的日志里面会显示权重文件的原始下载地址我用浏览器直接访问这个地址通过更稳定的下载方式把文件保存到本地然后放到~/.annoar/models/目录下文件名保持和配置文件里面一致。之后再启动 Annoar它会检测到本地文件已存在自动跳过下载步骤。这个方法不仅速度快也方便我同时给内网其他机器复用同一个权重文件。我顺手整理了一张问题速查表后面再遇到类似情况可以直接对照排查现象可能原因快速处理自动标注无反应torch 为 CPU 版本且 CUDA 不可用重新安装匹配 CUDA 的 torch图片区域空白opencv-python 与 headless 版本共存卸载 headless重装完整版服务无法启动端口被其他进程占用修改端口或停掉旧进程首次启动卡在下载权重权重文件下载中断手动下载并放到 models 目录浏览器页面打不开静态资源路径配置错误检查 config.yaml 里的 static_path5. 一些真正的实操心得整个 Annoar 装下来我最想强调的是“安装只是开始环境和依赖管理才是长期要面对的事”。很多人把安装理解为执行一两条命令实际上任何一个稍微复杂一点的工具都会牵扯到系统环境、依赖版本、网络条件等多方面因素。装了 Annoar 之后的这一周里我每天都用它处理新一批数据目前运行稳定。按我个人的排序给后来者三个建议第一一定不要在生产环境里直接安装这种重型工具虚拟环境能帮你避免九成以上的依赖灾难第二遇到下载失败不要反复重试优先考虑镜像源或手动下载替代方案第三把 Annoar 的数据库文件纳入日常备份范围标注结果丢了可比重新安装软件麻烦多了。最后再分享一个小技巧。Annoar 的 Web 界面用起来很方便但如果你是在远程服务器上跑实验、平时用本机浏览器访问启动服务时记得用--host 0.0.0.0否则默认只监听本地回环地址外部机器根本访问不到。我就是在这上面折腾了小半天才反应过来。