
名称	tao-generate-referring-expressions
描述	“四步图像指代表达式流程：将图像与KITTI边界框标签转换为区域描述、场景标题、基于指代的表达式，并可选地通过VLM蒸馏进行验证。当用户希望从带有KITTI标签的图像生成指代表达式标注、构建区域描述、生成与边界框相关的分组短语、运行指代表达式的双重检查验证、自动标注交通/场景图像以用于指代数据集，或运行image_referring_expression流程时使用。触发词包括’referring expression’、‘region description’、‘KITTI labels’、‘spatial relationship annotation’、‘auto-label image referring expression’、‘image_referring_expression’。”
开源协议	Apache-2.0 compatibility: 需要docker + nvidia-container-toolkit + 至少一个VLM端点（Gemini API密钥或OpenAI兼容端点）。 metadata:
作者	NVIDIA Corporation
版本	“0.1.0” tags: - 图像 - 指代表达式 - kitti - 边界框 - 自动标注 - vlm allowed-tools: 读取 Bash 写入

图像指代表达式流程

独立安装？ 如果此会话未由TAO技能库插件初始化，请先运行tao-setup技能（主机预检、凭据、跨技能发现）。

使用带有KITTI格式边界框标签的图像生成指代表达式和接地标注。单个VLM（Gemini或任何OpenAI兼容端点）运行四个步骤：每对象区域描述、整体图像标题、与边界框相关的分组接地表达式，以及可选的双重检查验证步骤。

目的

将(图像, KITTI标签)对转换为统一的annotations.jsonl，包含丰富的、基于接地（grounded）的指代表达式。VLM充当“教师”标注器：步骤0-1看到图像；步骤2将步骤0的输出分组为带边界框列表的分组短语；步骤3（可选）重新检查这些边界框与图像，并纠正不匹配。

流程架构

步骤0: 区域表达式  ──┐
                      ├──▶  步骤2: 接地表达式  ──▶  [步骤3: 双重检查]
步骤1: 图像标题  ──────┘                                                   (可选)

步骤0 (region_expr) — VLM为每个KITTI边界框（bbox_2d, type, color, description）生成一个简短的区分性短语。
步骤1 (image_caption) — VLM生成一个整体的、不依赖于位置的场景标题。
步骤2 (grounding_expr) — VLM将步骤0的对象分组为分组短语，并为每组返回一个边界框列表，可选地使用步骤1的标题作为附加上下文。
步骤3 (double_check) — VLM重新检查每个步骤2的边界框与图像；不匹配的框被移除，稍有偏差的框被收紧。

步骤0和1在单一线程池内并行运行（它们仅依赖于种子记录）。每个步骤写出自己的step_<N>_*/annotations.jsonl，并在重新运行时跳过已处理的图像，除非设置了workflow.force_reprocess: true。

指令

初始设置

当用户希望运行此流程时，请执行以下步骤：

图像：询问data.image_dir，即包含.jpg, .jpeg或.png图像的目录。
KITTI标签：询问data.kitti_label_dir，即每个图像对应一个.txt标签文件的目录。每个标签行必须使用KITTI格式：<type> <truncated> <occluded> <alpha> <bbox_left> <bbox_top> <bbox_right> <bbox_bottom> ...。少于8个字段的行会被静默跳过。即使仅运行步骤1也需设置此项，因为步骤0和2需要它。
从现有标注恢复：如果用户已有先前运行生成统一的annotations.jsonl，则设置data.input_annotations_jsonl为该文件，而不是从data.image_dir和data.kitti_label_dir播种。
API访问：询问用户希望使用哪个VLM端点。提供以下五个选项并根据选择操作：
1. Gemini — 设置vlm.backend: "gemini"；需要GOOGLE_API_KEY（环境变量或vlm.gemini.api_key）。
2. NIM（例如https://inference-api.nvidia.com/v1）— 设置vlm.backend: "openai"；收集base_url, model_name和api_key。
3. TAO推理微服务（自托管，OpenAI兼容）。确认服务器是否已在运行：
  - 运行中 — 收集base_url, model_name和（可选）api_key；设置vlm.backend: "openai"。
  - 未运行 — 指导用户通过skills/applications/tao-run-inference-service技能启动本地TAO推理微服务，该服务提供OpenAI兼容API。在承诺提供特定模型之前，请检查skills/applications/tao-run-inference-service/references/service.yaml中的valid_network_arch_config_basenames。服务器启动后，收集base_url, model_name和（可选）api_key；设置vlm.backend: "openai"。
4. vLLM（自托管，OpenAI兼容）。确认服务器是否已在运行：
  - 运行中 — 收集base_url, model_name和（可选）api_key；设置vlm.backend: "openai"。
  - 未运行 — 按照references/vllm_server.md安装并启动vLLM服务器，然后收集base_url, model_name和（可选）api_key；设置vlm.backend: "openai"。
5. 自定义（任何其他OpenAI兼容端点）— 设置vlm.backend: "openai"；收集base_url, model_name和（可选）api_key。
如果用户没有端点且不想设置，则停止并首先帮助解决API访问问题。
工作流步骤：选择以下之一：
- 完整流程：["0", "1", "2", "3"]
- 无标题生成：["0", "2", "3"]，此时步骤2使用仅图像上下文
- 无验证：["0", "1", "2"]
- 自定义子集：任何支持的步骤子集
输出格式：选择以下之一：
- jsonl：仅统一模式
- legacy：仅字节兼容的.txt.stepN文件
- both：同时写入两种格式，是下游工具链的默认设置

运行流程

流程在TAO工具包容器内通过auto_label CLI运行：

auto_label generate -e /path/to/spec.yaml \
    results_dir=/results \
    image_referring_expression.data.image_dir=/data/images \
    image_referring_expression.data.kitti_label_dir=/data/labels \
    image_referring_expression.vlm.gemini.api_key=$GOOGLE_API_KEY

生成默认规范：auto_label default_specs results_dir=/results module_name=auto_label，然后设置autolabel_type: "image_referring_expression"。所有字段均支持命令行上的Hydra点表示法覆盖。

有关完整的YAML结构、所有参数、模型/端点设置和错误模式，请参阅references/configuration.md。

配置

关键配置字段（完整参考见references/configuration.md）：

字段	默认值	描述
`workflow.steps`	`["0","1","2","3"]`	要执行的步骤（`0`=region_expr, `1`=image_caption, `2`=grounding_expr, `3`=double_check）
`workflow.max_workers`	`4`	每步的并行线程数（注意API速率限制）
`workflow.force_reprocess`	`false`	忽略缓存的每步输出并从头重新处理
`workflow.output_format`	`"jsonl"`（默认规范中设置为`"both"`）	`"jsonl"`, `"legacy"`或`"both"`
`vlm.backend`	`"gemini"`	`"gemini"`或`"openai"`（OpenAI兼容端点）
`data.image_dir`	必需	输入图像目录（`.jpg` / `.jpeg` / `.png`）
`data.kitti_label_dir`	必需（除非恢复）	KITTI格式`.txt`标签文件目录
`data.input_annotations_jsonl`	`""`	可选的预播种`annotations.jsonl`（跳过KITTI播种）

输入

播种流程的两种方式：

图像目录 + KITTI标签（默认）。设置data.image_dir和data.kitti_label_dir。编排器遍历图像目录，读取匹配的<stem>.txtKITTI文件，解析边界框（字段0和4-7），通过PIL读取每个图像的width/height，并将seed_annotations.jsonl写入results_dir/。
预播种的注释JSONL（恢复/预计算区域）。设置data.input_annotations_jsonl为每行一个{"image_id", "image_path", "width", "height", "kitti_bboxes": [...]}对象的文件。

输出

所有输出均写入results_dir/：

seed_annotations.jsonl — 初始每图像记录（除非提供了input_annotations_jsonl）。
step_0_region_expr/annotations.jsonl — 添加regions[]（每个包含bbox/bbox_2d, type, color, description）。
step_1_image_caption/annotations.jsonl — 添加caption（字符串）。
step_2_grounding_expr/annotations.jsonl — 添加expressions[]（每个{text, instances: [{bbox: [x1,y1,x2,y2]}]}）。
step_3_double_check/annotations.jsonl — 与步骤2形状相同，但边界框被移除/更新。
results_dir/annotations.jsonl — 最后一个完成步骤输出的副本。
当workflow.output_format为"legacy"或"both"时，每个步骤还会为原始2d-data-engine工具链编写字节兼容的step_<N>_*/labels/<stem>.txt.stepN文件。

先决条件

容器：nvcr.io/nvidia/tao/tao-toolkit:7.1.0-pyt
API访问：至少一个VLM端点（Gemini API密钥或支持图像输入的OpenAI兼容端点）
PIL / Pillow：在播种期间读取图像尺寸所需（TAO容器中已存在）

图像指代表达式生成Skill tao-generate-referring-expressions

图像指代表达式流程

目的

流程架构

指令

初始设置

运行流程

推荐的试点工作流

配置

输入

输出

先决条件