SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场glmv-grounding

glmv-grounding

智能体与模型

查看项目

更新于 10-16 02:43

技能介绍

GLMV-Grounding Skill 用于提取和可视化 GLM-V 生成的 grounding（定位）结果。根据用户提示词的不同，模型输出中的定位坐标可能呈现为多种形式，包括 2D 边界框、目标检测 JSON、2D 点、3D 边界框以及目标跟踪 JSON。

坐标说明：GLM-V 输出的坐标中，x 和 y 是基于像素坐标 x_pixel、y_pixel 结合图像宽度 W 与高度 H 归一化后的相对坐标（范围 0-1000），即 x=round(x_pixel/W1000)，y=round(y_pixel/H1000)。像素坐标系原点位于图像左上角。若提示词未明确指定 grounding 格式（例如“找到 xxx 的位置”或“在 xxx 周围画框”），默认按 2D 边界框处理。

【何时使用】

  • 使用 GLM-V 在图像中定位目标：针对任意提示词描述的目标获取图像中的定位结果，输出格式可为 2D 边界框（默认）、2D 点、3D 边界框等。
  • 使用 GLM-V 在视频中跟踪目标：针对任意提示词描述的目标获取视频中的跟踪结果，输出格式如 {"0": [{"label": ..., "bbox_2d": ...}, ...], ...}。
  • 使用实用函数进行提取、转换和可视化：从自然文本中提取坐标、点和 JSON；归一化与反归一化坐标；可视化框、点、3D 框和视频跟踪结果。

【配置 API Key】 配置 ZHIPU_API_KEY 以调用 GLM-V API。 获取 API key：https://www.bigmodel.cn/usercenter/proj-mgmt/apikeys 配置命令： python scripts/config_setup.py setup --api-key YOUR_KEY

【安全与透明】

  • 主要 API key 环境变量：ZHIPU_API_KEY（必需）。
  • 超时环境变量：GLM_GROUNDING_TIMEOUT（可选，单位秒，默认 60）。
  • API 端点：在 CLI 实现中固定为智谱官方 Chat Completions 端点。
  • 不做动态 key 名称切换：该技能始终期望 ZHIPU_API_KEY。
  • URL/本地文件处理：技能可读取本地文件或获取用户提供的 URL 以进行处理/可视化；URL 输入限制为公开的 http/https 目标（拒绝 localhost/私有网络目标）。

【运行时依赖】 使用前安装依赖： pip install -r scripts/requirements.txt 主要包：requests、Pillow、opencv-python、numpy、matplotlib、decord 视频可视化的系统依赖：ffmpeg

【总体工作流】 输入（图像或视频 + Prompt）→ 运行 glm_grounding_cli.py 获取 grounding 结果（自然语言）→ 返回结果（grounding 结果、可视化图像或视频）。

【如何使用】 运行 glm_grounding_cli.py 获取 grounding 结果。

在图像中定位任意目标： python scripts/glm_grounding_cli.py --image-url "URL provided by user" --prompt "description of target for grounding"

在视频中跟踪任意目标： python scripts/glm_grounding_cli.py --video-url /path/to/image.jpg --prompt "description of target for tracking" --visualize --visualization-dir "./vis"

回复 grounding 结果：收到用户的 grounding 提示后，直接回复应包含 grounding 坐标的自然语言。坐标 x 和 y 为 [0, 1000] 区间内的相对值，计算公式为 x = round(x_pixel / W * 1000)，y = round(y_pixel / H * 1000)，其中 x_pixel、y_pixel 为以图像左上角 (0, 0) 为原点的像素坐标，W/H 为图像宽度/高度。

除另有说明外，grounding 结果应使用以下 Python 数据格式：

  • 2D 边界框：[[x1, y1, x2, y2], ...]，提取结果为框的列表，每个框含 4 个坐标值。
  • 2D 点：[[x, y], ...]，提取结果为点的列表，每个点含 2 个坐标值。
  • 2D 多边形：[[x1, y1], [x2, y2], ...]，提取结果为多边形坐标列表，每个顶点含 2 个坐标值。
  • 3D 边界框：[{"bbox_3d":[x_center, y_center, z_center, x_size, y_size, z_size, roll, pitch, yaw],"label":"category"}, ...]，提取结果为 JSON 列表，每个对象含一个类别标签和一个含 8 个坐标值的 3D 框。
  • 目标检测 JSON：[{'label': 'category', 'bbox_2d': [x1, y1, x2, y2]}, ...]，提取结果为 JSON 列表，每个对象含一个类别标签和一个框。
  • 视频目标跟踪 JSON：{0: [{'label': 'car-1', 'bbox_2d': [1,2,3,4]}, {'label': 'car-2', 'bbox_2d': [2,3,4,5]}], 1: [{'label': 'car-2', 'bbox_2d': [4,5,6,7]}, {'label': 'person-1', 'bbox_2d': [10,20,30,40]}]}，提取结果为 JSON 对象，键为视频帧索引，值为 JSON 对象列表，每个对象含一个类别标签和一个 2D 框。

【Python 示例】

1. 用户 grounding 请求与回复

image=https://example.com/image.jpg prompt="Please box all people wearing Santa hats in the image and tell me their coordinates. Use red boxes, line thickness 3, and label format 'SantaHat-i'."

2. 获取 grounding 结果

python scripts/glm_grounding_cli.py --image-url $image --prompt $prompt --visualize --visualization-dir "./vis"

返回示例包含 ok、grounding_result、visualizations_result、raw_result、error、source 等字段。

【实用函数速查】

  • parse_coordinates_from_response(response_str, coords_type='bbox', init_context_window=2000, max_context_window=-1)：从模型响应中解析并提取所有坐标结果（支持 2D bbox、point、polygon）。
  • parse_3d_boxes_from_response(response_str, max_context_window=-1)：从模型响应中解析并提取所有 3D 框和标签（严格与宽松匹配）。
  • parse_detection_from_response(response_str, max_context_window=-1)：从模型响应中解析并提取所有 2D 检测结果（目标检测 JSON 格式）。
  • parse_mot_from_response(response_str, max_context_window=-1)：从模型响应中解析并提取所有视频目标跟踪结果（视频目标跟踪 JSON 格式）。
  • visualize_boxes(img_path=None, img_bytes=None, boxes=[], labels=None, renormalize=False, save_path=None, return_b64=False, save_optimized=True, **kwargs)：在图像上绘制带标签、自定义颜色和线宽的 2D 框。
  • visualize_points(img_path=None, img_bytes=None, points=[], labels=None, renormalize=False, diameters=None, save_path=None, return_b64=False, save_optimized=True, distinct_colors=False, colors=None)：在图像上绘制带标签、自定义大小和颜色的点。
  • visualize_3d_boxes_glmv_simple(image_path, cam_params, bbox_3d_list, image_bytes=None, coord_format='xyzwhlpyr', save_path=None, save_optimized=False, return_b64=False, **kwargs)：使用相机内参在图像上绘制投影后的 3D 框（支持旋转和多种坐标格式）。
  • visualize_mot(video_path=None, video_bytes=None, mot_js=None, renormalize=False, save_path=None, return_b64=False, distinct_colors=True, **kwargs)：在视频每一帧上绘制带标签的视频目标跟踪框。

【常见错误】 坐标值超过 1000：若提取到的坐标值大于 1000，模型可能因提示词影响产生了未归一化的坐标。可从用户请求中提取目标短语（例如“people wearing Santa hats”），然后再次查询模型，并明确要求输出基于图像尺寸归一化到 0-1000 的相对坐标（例如：“Please box all people wearing Santa hats in the image and tell me their coordinates. Ensure the output coordinates are relative values normalized to 0-1000 based on image size.”）。