GLMV-Grounding 技能

提取并可视化 GLM-V 生成的 grounding 结果。根据用户提示的不同，模型输出中的 grounding 坐标可能以多种形式呈现，包括：2D 边界框（bounding box）、目标检测 JSON（Objects Detection JSON）、2D 关键点（points）、3D 边界框（3D bounding box）以及目标跟踪 JSON（target-tracking JSON）。

注意：GLM-V 输出的坐标为归一化相对坐标，其计算方式为：使用图像宽度 W 和高度 H 将像素坐标 x_pixel 和 y_pixel 归一化至范围 [0, 1000]，即：
x = round(x_pixel / W * 1000)，y = round(y_pixel / H * 1000)。
像素坐标系原点位于图像左上角。

注意：若用户提示未明确指定 grounding 格式（例如仅表述为“找到 xxx 的位置”或“在 xxx 周围画一个框”），则默认按2D 边界框处理。

适用场景

• 使用 GLM-V 在图像中定位目标：对任意由提示语描述的目标，在图像中获取 grounding 结果，支持输出格式包括 2D 边界框（默认）、2D 关键点、3D 边界框等。
• 使用 GLM-V 在视频中跟踪目标：对任意由提示语描述的目标，在视频中获取跟踪结果，输出格式形如：{"0": [{"label": ..., "bbox_2d": ...}, ...], ...}。
• 使用工具函数进行提取、转换与可视化：从自然语言文本中提取坐标、关键点及 JSON 数据；执行坐标的归一化与反归一化；可视化边界框、关键点、3D 边界框及视频跟踪结果。

配置 API Key

需配置环境变量 ZHIPU_API_KEY 才可调用 GLM-V API。

1. 获取您的 API 密钥：https://www.bigmodel.cn/usercenter/proj-mgmt/apikeys
2. 通过以下命令完成配置：

python scripts/config_setup.py setup --api-key YOUR_KEY

安全性与透明性

• 主 API 密钥环境变量：ZHIPU_API_KEY（必需）。
• 超时环境变量：GLM_GROUNDING_TIMEOUT（可选，默认值为 60 秒）。
• API 端点：CLI 实现中固定使用智谱官方 Chat Completions 接口地址。
• 不支持动态密钥名称切换：该技能始终期望使用 ZHIPU_API_KEY 环境变量。
• URL / 本地文件处理：该技能支持读取本地文件或拉取用户提供的 URL 进行处理与可视化；URL 输入仅限公网 http/https 地址（拒绝 localhost 或私有网络地址）。

运行时依赖

使用前请先安装依赖：

pip install -r scripts/requirements.txt

本技能主要使用的 Python 包：

• requests
• Pillow
• opencv-python
• numpy
• matplotlib
• decord

视频可视化所需的系统级依赖：

• ffmpeg

通用工作流

	输入（图像或视频 + 提示语）
		|
		▼
	运行 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 = \text{round}(x_{\text{pixel}} / W \times 1000) \\ y = \text{round}(y_{\text{pixel}} / H \times 1000) $$

其中 $x_{\text{pixel}}, y_{\text{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 列表，每个对象包含类别标签及一个含 9 个参数的 3D 边界框（注：实际为 9 个字段，含中心坐标、尺寸、欧拉角共 9 维）
• 目标检测 JSON：[{'label': 'category', 'bbox_2d': [x1, y1, x2, y2]}, ...]，提取结果为 JSON 列表，每个对象包含类别标签及一个 2D 边界框
• 视频目标跟踪 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": True,
#         "grounding_result": [[100, 200, 300, 400], [500, 600, 700, 800]],
#         "visualizations_result": (
#             {"visualized_image": "./vis/image_vis.jpg"}
#         ),
#         "raw_result": "1. Person 1: box [100, 200, 300, 400]\n2. Person 2: box [500, 600, 700, 800]. The box format is [x1, y1, x2, y2], where (x1, y1) is the top-left corner and (x2, y2) is the bottom-right corner.",
#         "error": None,
#         "source": source,
#     }

工具函数速查表

常见错误

• 坐标值超过 1000：若提取出的坐标值大于 1000，可能是因提示语影响导致模型输出了未归一化的像素坐标。此时应提取用户请求中的目标短语（例如“戴圣诞帽的人”），重新向模型发起查询，并在提示语中**明确要求输出坐标为基于图像尺寸归一化至 [0, 1000] 的相对值**（例如：“请在图像中框出所有戴圣诞帽的人，并告知其坐标。确保输出坐标是基于图像尺寸归一化至 [0, 1000] 的相对值。”）。