Gemini API 边界框检测实战目标定位、坐标体系与可视化Agent Platform Gen AI SDK【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills导读本文围绕 Gemini API 技能 中的 bounding_box.md 参考文档展开讲解如何在 Gemini Enterprise Agent Platform原 Vertex AI上使用 Gemini 多模态模型对图片或视频中的物体进行边界框Bounding Box检测与定位。读完本文你将掌握结构化输出BoundingBox模式的定义与response_schema配置、[y_min, x_min, y_max, x_max]归一化坐标系的含义与换算方法以及如何把模型返回的坐标缩放回原始图像尺寸进行可视化。一、背景Gemini API 中的边界框检测能力边界框检测Bounding Box Detection是 Gemini 多模态理解能力的一项具体应用模型不仅能识别图片里有什么还能以矩形框的形式给出每个目标物在图像中的空间位置。该功能位于 Agent Platform 提供的 Gemini API 之上通过统一的 Google Gen AI SDKPython 包名为google-genai即可调用无需直接操作底层 REST 接口。在 SKILL.md 中该技能目录将Bounding Box Detection: Object detection and localization within images and video列为 Gemini API 的标准参考能力之一与文本生成、嵌入、媒体生成、Live API 等并列。模型返回的每个检测结果都包含label检测目标的类别标签如socksbox_2d二维边界框坐标。其典型应用场景包括商品识别与计数、工业质检、图片内容理解、视觉搜索预处理以及任何需要在图片/视频帧中定位目标的 AI 应用。二、核心坐标系统归一化[y_min, x_min, y_max, x_max]理解坐标系是正确使用边界框输出的前提。根据 bounding_box.md模型返回的坐标遵循以下约定格式[y_min, x_min, y_max, x_max]即依次为左上角 y 坐标、左上角 x 坐标、右下角 y 坐标、右下角 x 坐标归一化所有坐标都是0到1000之间的整数与输入图像的实际像素尺寸无关原点[0, 0]位于图像的左上角y 轴向下增长x 轴向右增长。因此任何从模型拿到的边界框都必须经过缩放回原图的步骤才能用于绘制或裁剪。例如模型返回box_2d [100, 200, 900, 800]意味着边界框从图像高度 10% 处开始、到 90% 处结束宽度方向从 20% 到 80%而不是像素坐标本身。注意归一化范围为 01000而非 01换算时按像素 归一化值 / 1000 * 原图尺寸处理详见下文可视化小节。三、Python 实现用response_schema强制结构化输出为了让模型输出可被程序直接消费的结构化结果官方推荐使用 Pydantic 定义一个BoundingBox类并将其作为GenerateContentConfig中的response_schema传入。这样模型返回的response.parsed就会被自动解析为类型安全的 Python 对象列表。完整代码如下继承自 bounding_box.mdfrom google import genai from google.genai.types import ( GenerateContentConfig, Part, ) from pydantic import BaseModel # Define the schema for the bounding box class BoundingBox(BaseModel): box_2d: list[int] label: str client genai.Client() config GenerateContentConfig( system_instruction Return bounding boxes as an array with labels. Never return masks. Limit to 25 objects. , response_mime_typeapplication/json, response_schemalist[BoundingBox], ) image_uri gs://cloud-samples-data/generative-ai/image/socks.jpg response client.models.generate_content( modelgemini-3.6-flash, contents[ Part.from_uri(file_uriimage_uri, mime_typeimage/jpeg), Detect the socks in the image and provide bounding boxes., ], configconfig, ) # Access the detected boxes for bbox in response.parsed: print(fLabel: {bbox.label}, Box: {bbox.box_2d})对关键点逐一说明response_mime_typeapplication/json要求模型以 JSON 形式返回内容这是结构化输出的基础开关。response_schemalist[BoundingBox]声明输出为一个BoundingBox对象列表BoundingBox.box_2d是包含 4 个整数的列表即归一化坐标BoundingBox.label是类别标签字符串。Pydantic 的BaseModel在这里承担了JSON Schema 定义 运行时校验的双重职责。system_instruction通过系统指令约束输出行为——只返回带标签的边界框数组、绝不返回掩码mask、单个响应最多 25 个目标避免模型返回额外的分割信息或无限枚举目标。response.parsedGen AI SDK 会根据response_schema自动把原始 JSON 解析为list[BoundingBox]使你可以直接通过属性访问bbox.label与bbox.box_2d无需手写 JSON 反序列化。3.1 结构化输出的通用机制边界框检测本质上是多模态输入 结构化输出的组合。这一机制在 structured_and_tools.md 中有更通用的描述使用标准 Python 类型注解或 Pydantic 模型即可强制模型输出满足指定 JSON Schema 的结果且response.text保证是符合 schema 的合法 JSON、response.parsed会返回解析后的类型化对象。边界框场景只是把 schema 从Recipe之类换成了BoundingBox其余配置方式完全一致。3.2 多模态输入图片来源的两种方式在上面的示例中图片通过Part.from_uri从 Google Cloud Storage 读取。同样地text_and_multimodal.md 展示了另一种常用方式——本地字节流with open(local_image.jpg, rb) as f: local_image types.Part.from_bytes(dataf.read(), mime_typeimage/jpeg)在边界框检测场景中两种方式可以混用例如同时传入一张 GCS 图片和一张本地图片做多图检测。视频场景同理可通过Part.from_uri传入视频 URI让模型对视频帧中的目标进行定位。四、坐标换算与可视化辅助函数拿到归一化坐标后若要将其绘制到原图上例如用 Pillow、OpenCV 画矩形框必须先按原图的实际宽高缩放。文档提供了如下辅助函数def scale_box(box_2d, width, height): y_min, x_min, y_max, x_max box_2d return [ int(y_min / 1000 * height), int(x_min / 1000 * width), int(y_max / 1000 * height), int(x_max / 1000 * width), ]用法要点width、height为原图像的像素宽高可通过 PillowImage.open(...).size或 OpenCVimg.shape获得注意坐标轴与宽高的对应关系y 分量y_min、y_max与height相乘x 分量x_min、x_max与width相乘顺序不能搞反返回的[y_min, x_min, y_max, x_max]是像素级整数坐标可直接交给cv2.rectangle(img, (x_min, y_min), (x_max, y_max), ...)或 Pillow 的ImageDraw.rectangle绘制。将上一节的主流程与该函数组合即可得到完整的检测 → 缩放 → 可视化流水线。五、运行前提环境与认证配置虽然 bounding_box.md 本身聚焦于代码但要让示例真正运行需要先完成 SKILL.md 中描述的认证与模型选型配置。5.1 依赖安装使用统一的 Gen AI SDK不要使用已废弃的google-cloud-aiplatform、google-generativeai等旧 SDKpip install google-genai5.2 认证方式二选一方式一Application Default CredentialsADC企业环境推荐export GOOGLE_CLOUD_PROJECTyour-project-id export GOOGLE_CLOUD_LOCATIONglobal export GOOGLE_GENAI_USE_ENTERPRISEtrue默认使用locationglobal访问全局端点系统会自动路由到有容量的区域如需固定区域可改为us-central1、europe-west4等。方式二Express ModeAPI Keyexport GOOGLE_API_KEYyour-api-key export GOOGLE_GENAI_USE_ENTERPRISEtrue配置完成后client genai.Client()无需传参即可自动拾取环境变量也可以在构造时显式指定genai.Client(enterpriseTrue, projectyour-project-id, locationglobal)。5.3 模型选择bounding_box.md 示例使用gemini-3.6-flash该模型在 SKILL.md 中被定位为快速、均衡、多模态100 万 token 上下文的主力模型适合检测类任务。其他候选模型包括面向复杂推理的gemini-3.1-pro-preview和高频轻量任务的gemini-3.5-flash-litegemini-2.x及更早版本已被标注为 legacy不应在新代码中使用。六、实战建议与注意事项数量上限通过system_instruction中的 Limit to 25 objects 显式约束检测数量避免模型枚举过多目标导致输出膨胀。只返回边界框不返回掩码Never return masks指令可防止模型在检测类任务中额外输出分割掩码显著减小响应体积并保持输出纯净。坐标务必缩放归一化坐标01000不能直接当作像素使用任何绘制、裁剪、IoU 计算前都必须先按原图尺寸还原。视频场景Part.from_uri同样支持视频 URI如video/mp4可将相同的response_schema机制用于视频帧目标定位。结构化输出的稳定性response_mime_typeapplication/json与response_schema必须成对使用二者共同保证response.parsed的类型安全这是边界框检测可靠落地的关键配置组合。七、延伸阅读Gemini API 技能总览与认证配置结构化输出与工具调用JSON Schema、Function Calling、Search Grounding文本与多模态输入GCS URI、本地字节流、视频输入媒体生成图像生成与编辑、视频生成高级特性上下文缓存、批处理预测、Thinking/推理等级【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考