使用 agno Agent 为图片生成物体检测边界框Bounding Box数据标注与坐标约定实战【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno导读本文基于 agno 数据标注 Cookbook 中的cookbook/data_labeling/_08_image_bounding_boxes目录系统讲解如何用多模态 Agent 检测图片中的物体并输出(x, y, width, height)归一化边界框覆盖单目标检测、带置信度评分、多目标多类别检测三种形态。读者读完将掌握 agno 的Image媒体输入、Pydanticoutput_schema结构化输出、归一化坐标约定以及如何将这一能力用于训练集预标注、商品图裁剪建议与粗粒度空间统计等真实场景。一、核心思路用文本补丁替代专用检测头物体检测传统上依赖专门训练的目标检测模型如 YOLO、Faster R-CNN。而 agno 提供了一条完全不同的路径让原生多模态的大语言模型直接看图说话把检测结果以结构化 JSON 形式输出。本目录的三份示例正是这一思路的最小可运行实现全部位于 cookbook/data_labeling/_08_image_bounding_boxes/basic.py— 检测单个标注目标输出一个边界框with_confidence.py— 在基本版之上为每个框附加置信度high / medium / lowmulti_object.py— 检测同一张图中多个类别、多个目标输出一个框列表。三个文件共享同一套骨架定义 Pydantic 输出模型 → 编写检测指令 → 创建 Agent → 用agent.run(..., images[Image(...)])驱动。它们都属于 cookbook/data_labeling/ 数据标注系列中图像模态下的区域检测工作流该系列共 28 个主题、75 个可单文件运行示例。适用边界这一原语输出的是矩形边界框而非像素级掩码。若需要逐像素精度的分割结果应选用专门的分割模型若只关心图中是否存在 X而不需要坐标则应改用多标签分类方案见 cookbook/data_labeling/_06_image_classification/。二、坐标约定归一化天然分辨率无关所有示例输出的坐标均归一化到图像尺寸这是整个检测方案的核心约定字段含义取值范围x左上角 x 坐标[0, 1]y左上角 y 坐标[0, 1]width框的宽度[0, 1]height框的高度[0, 1]实际换算很简单将归一化坐标乘以图片的实际宽高即得到像素坐标例如像素框左上角为(x * img_width, y * img_height)框宽为width * img_width。这套约定让同一套输出 schema 可以无缝适配任意分辨率的输入图无需针对不同尺寸的图片调整输出逻辑。三、单目标检测basic.py 逐行拆解basic.py 演示最简形态——在图中定位主体并返回一个紧致边界框。第一步定义输出模型。借助 Pydantic 在 schema 层强制约束数值范围from pydantic import BaseModel, Field class BoundingBox(BaseModel): label: str Field(..., descriptionWhat the box contains) x: float Field(..., ge0.0, le1.0, descriptionTop-left x in [0, 1]) y: float Field(..., ge0.0, le1.0, descriptionTop-left y in [0, 1]) width: float Field(..., ge0.0, le1.0, descriptionWidth in [0, 1]) height: float Field(..., ge0.0, le1.0, descriptionHeight in [0, 1])注意ge0.0, le1.0这是坐标约定在类型层的落地任何越界输出都会被 Pydantic 校验拦截。第二步编写检测指令。指令明确两个关键点——坐标语义与紧致框质量要求instructions \ Locate the main subject of the image and return its bounding box in normalized coordinates. Coordinates are relative to the full image: - x, y: top-left corner, each in [0, 1] - width, height: size, each in [0, 1] The box should be tight: include the subject and exclude as much background as possible without clipping the subject. 第三步创建 Agent 并运行。output_schemaBoundingBox让 Agent 把模型响应解析为 Pydantic 对象images[Image(urlurl)]注入多模态输入from agno.agent import Agent, RunOutput from agno.media import Image from rich.pretty import pprint agent Agent( modelgoogle:gemini-3.5-flash, instructionsinstructions, output_schemaBoundingBox, ) if __name__ __main__: url https://www.gstatic.com/webp/gallery/2.jpg run: RunOutput agent.run( Locate the main subject of this image., images[Image(urlurl)] ) pprint({url: url, result: run.content})运行结果中run.content即为校验过的BoundingBox实例含label、x、y、width、height。四、带置信度with_confidence.py 与下游阈值化with_confidence.py 在基本 schema 上增加一个confidence字段其类型为字面量三档from typing import Literal class BoundingBox(BaseModel): label: str Field(..., descriptionWhat the box contains) x: float Field(..., ge0.0, le1.0, descriptionTop-left x in [0, 1]) y: float Field(..., ge0.0, le1.0, descriptionTop-left y in [0, 1]) width: float Field(..., ge0.0, le1.0, descriptionWidth in [0, 1]) height: float Field(..., ge0.0, le1.0, descriptionHeight in [0, 1]) confidence: Literal[high, medium, low] Field( ..., descriptionConfidence in the box and label )指令中必须把三档置信度的判定标准写清楚模型才能稳定对齐high— 目标清晰可见框紧致且准确medium— 目标可辨认但部分被遮挡框为近似位置low— 目标几乎不可见或位置基本靠猜。这一设计的价值在于下游消费方可以按置信度分流例如low的框直接路由给人工审核human-in-the-loophigh的框直接进入训练集medium的框按业务容忍度决定去留。五、多目标多类别multi_object.py 与框列表multi_object.py 处理一张图中有多个目标、多个类别的场景schema 升级为外层容器 内部框列表from typing import List class BoundingBox(BaseModel): label: str Field(..., descriptionObject class for this box) x: float Field(..., ge0.0, le1.0) y: float Field(..., ge0.0, le1.0) width: float Field(..., ge0.0, le1.0) height: float Field(..., ge0.0, le1.0) class Detection(BaseModel): boxes: List[BoundingBox] Field( default_factorylist, descriptionAll detected objects in the image )对应的指令同时约束召回哪些对象和如何去重避免无意义的背景框Detect every distinct object in the image. For each one, return a label and a tight bounding box in normalized coordinates (top-left x and y, width, height - all in [0, 1]). Skip background elements (sky, road surface) unless they are the subject. Skip duplicates: if two objects are nearly identical and overlapping, report a single box.示例使用的输入图为一张大象、长颈鹿、斑马在日落中的场景图generated_elephants_giraffes_zebras_sunset.jpg运行后run.content是一个包含boxes列表的Detection对象每个元素对应一个(label, x, y, width, height)。default_factorylist保证了即使图中没有检测到任何目标输出也始终是合法的空列表而非报错——这对下游批量处理的健壮性很重要。六、底层机制output_schema 与 Image 媒体输入三个示例的运作依赖于 agno 两个底层能力其实现可以在仓库源码中验证1.output_schema驱动的结构化输出。Agent 的output_schema参数接收一个 Pydantic 模型类见 libs/agno/agno/agent/agent.py。与之配套的关键开关包括parse_responseTrue默认将模型响应解析为 output_schema 实例否则返回 JSON 字符串、structured_outputs当模型支持时启用 provider 强制的结构化输出如 OpenAIChat、use_json_mode将 output schema 的 JSON 描述注入系统消息而不是直接传 schema。默认情况下模型可能以 provider 内置的结构化输出function calling / constrained decoding保证 JSON 形状再由 Pydantic 完成字段级校验。2.Image媒体类。图片通过 libs/agno/agno/media/media.py 中的ImagePydantic 模型传入其内容来源三选一且互斥url远程地址、filepath本地路径、content原始字节。校验器在构造阶段就会强制有且仅有一个内容来源否则抛出ValueError同时支持id、format、mime_type等元数据字段。这意味着示例中的Image(url...)可以平滑替换为Image(filepathlocal.jpg)或Image(contentbytes)用本地图片或程序内字节流驱动检测详见_06_image_classificationREADME 中关于可替换为本地路径的说明。七、运行环境与依赖示例要求GOOGLE_API_KEY环境变量Gemini 系列模型默认用于整个 data_labeling Cookbook原生多模态。从仓库根目录按 cookbook/data_labeling/README.md 的说明创建并激活 demo 虚拟环境后逐个运行python cookbook/data_labeling/_08_image_bounding_boxes/basic.py python cookbook/data_labeling/_08_image_bounding_boxes/with_confidence.py python cookbook/data_labeling/_08_image_bounding_boxes/multi_object.py也可先用./scripts/demo_setup.sh完成环境初始化激活后为.venvs/demo。若想更换检测目标直接替换Image(...)中的 URL 或改用本地文件路径即可schema 与指令无需任何改动。八、适用场景与选型建议推荐使用边界框原语的场景训练集预标注先由 Agent 生成初版框人工在框上做修正human-in-the-loop大幅降低从零标注的成本配合with_confidence.py的置信度分流低置信样本自动进入人工队列商品图裁剪建议自动定位商品主体输出紧致框为缩略图、主图裁剪提供候选区域粗粒度空间统计例如统计人数、车辆数、缺陷数量不需要像素级精度只关心在哪、有几个。需要换方案的场景需要像素级掩码→ 使用专门的分割模型边界框原语不适用只需要判断图中是否含有 X而不需要坐标→ 使用 cookbook/data_labeling/_06_image_classification/ 的多标签分类。从源码结构看这套Pydantic schema 指令 多模态 Agent的组合还可以继续叠加 data_labeling 系列中的组合模式如 _17_llm_as_judge、_18_quality_review对检测结果做质量评审或在_26_scale_out的异步并发框架下扩展到十万级图片的批量标注流水线。【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考