tao-generate-referring-expressions

图像指代表达式流水线

根据带有 KITTI 格式边界框标签的图像，生成指代表达式和定位标注。单个 VLM（Gemini 或任何兼容 OpenAI 的端点）执行四个步骤：逐对象区域描述、整体图像说明、与边界框关联的分组定位表达式，以及可选的二次核验步骤。

用途

将 (image, KITTI labels) 对转换为统一的 annotations.jsonl，其中包含丰富且有依据的指代表达式。VLM 充当「教师」标注员：步骤 0-1 查看图像；步骤 2 将步骤 0 的输出分组为带有边界框列表的分组短语；步骤 3（可选）根据图像重新检查这些边界框，并修正不匹配之处。

流水线架构

Step 0: Region expression  ──┐
                              ├──▶  Step 2: Grounding expression  ──▶  [Step 3: Double check]
Step 1: Image caption  ──────┘                                                   (optional)

• 步骤 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。

说明

初始设置

当用户想运行此流水线时，请引导他们完成以下步骤：

1. 图像：询问 data.image_dir，即包含 .jpg、.jpeg 或 .png 图像的目录。

2. KITTI 标签：询问 data.kitti_label_dir，即每张图像对应一个 .txt 标签文件的目录。每行标签必须使用 KITTI 格式：<type> <truncated> <occluded> <alpha> <bbox_left> <bbox_top> <bbox_right> <bbox_bottom> ...。少于 8 个字段的行会被静默跳过。即使只运行 Step 1，也要设置此项，因为 Step 0 和 Step 2 需要它。

3. 从现有标注恢复：如果用户已有之前运行生成的统一 annotations.jsonl，请将 data.input_annotations_jsonl 设置为该文件，而不是从 data.image_dir 和 data.kitti_label_dir 开始。

4. 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 访问问题。

5. 工作流步骤：选择以下一项：

   • 完整流水线：["0", "1", "2", "3"]
   • 不生成描述：["0", "2", "3"]，其中 Step 2 会回退为仅使用图像上下文
   • 不进行验证：["0", "1", "2"]
   • 自定义子集：选择任意受支持的步骤子集

6. 输出格式：选择以下一项：

   • jsonl：仅使用统一架构
   • legacy：仅生成字节兼容的 .txt.stepN 文件
   • both：生成两种格式，且为下游工具的默认选项

运行流水线

流水线通过 auto_label CLI 在 TAO Toolkit 容器中运行：

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。

推荐的试点工作流

1. 使用全部四个步骤处理 5-10 张图像。
2. 检查 step_0_region_expr/annotations.jsonl：对象类型、颜色和区分性短语是否准确？
3. 检查 step_2_grounding_expr/annotations.jsonl：对象分组是否合理，边界框坐标是否与描述的分组相符？
4. 检查 step_3_double_check/annotations.jsonl：不匹配的边界框是否已移除或收紧？是否引入了新错误（较少见）？
5. 如果质量不够理想，请将 VLM 切换为更强大的模型（例如 gemini-2.5-pro 或更大型的 Qwen3-VL 端点），提高 media_resolution / max_output_tokens，然后使用 workflow.force_reprocess=true 重新运行。
6. 满意后，扩展到完整数据集。

配置

关键配置字段（完整参考见 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 初始化）

输入

有两种方式为流水线提供初始数据：

1. 图像目录 + KITTI 标签（默认）。设置 data.image_dir 和 data.kitti_label_dir。编排器会遍历图像目录，读取匹配的 <stem>.txt KITTI 文件，解析边界框（字段 0 + 4-7），通过 PIL 读取每张图像的 width / height，并将 seed_annotations.jsonl 写入 results_dir/。
2. 预置的 annotations 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:6.26.3-pyt
• API 访问权限：至少一个 VLM 端点（Gemini API key 或支持图像输入的 OpenAI 兼容端点）
• PIL / Pillow：初始化时读取图像尺寸所需（TAO 容器中已包含）