tao-generate-image-grounding

图像定位流程

将 (image, caption) 对转换为每张图像的定位标注：清理后的标题、带字符跨度的指代表达式，以及每个表达式对应的像素空间边界框。单个 VLM（Gemini 或任何兼容 OpenAI 的端点）负责处理这两个步骤。

用途

生成用于指代表达式和定位模型的短语定位训练数据。VLM 充当“教师”标注器：步骤 0 在查看图像的同时从标题中提取指代表达式；步骤 1 为每张图像中的每个表达式返回一组边界框。

流程架构

Step 0: Expression extraction  → VLM cleans caption, extracts referring expressions + char spans
Step 1: Phrase grounding       → VLM returns pixel bboxes + scores per expression

可通过 workflow.steps 单独选择各个步骤。每个步骤都会将每个样本的检查点写入 step_<N>_*/.ckpt/<sample_id>.json，并在重新运行时跳过已处理的记录。设置 workflow.force_reprocess: true 可忽略检查点并从头重新处理。

说明

初始设置

当用户想要运行此流程时，按以下步骤操作：

1. 输入 JSONL：询问 JSONL 路径。每行必须是一个类似 {"image_path": "...", "caption": "..."} 的对象。image_path 可以是绝对路径或相对路径。

2. 图像根目录：如果任何 image_path 值是相对路径，请将 data.image_root 设置为这些路径所依据的目录。

3. 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 skill，该 skill 会启动一个本地 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 访问权限问题。

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

   • 完整流程：["0", "1"]
   • 仅提取表达式：["0"]
   • 仅进行定位：["1"]，这需要已有的步骤 0 输出，路径为 results_dir/step_0_expression_extraction/annotations.jsonl

5. 继续运行还是全新运行：默认情况下，工作流会复用检查点并跳过已完成的记录。若要重新处理所有内容，请设置 image_grounding.workflow.force_reprocess=true。

运行流程

该流程通过 auto_label CLI 在 TAO Toolkit 容器内运行：

auto_label generate -e /path/to/spec.yaml \
    results_dir=/results \
    image_grounding.data.input_jsonl=/data/captions.jsonl \
    image_grounding.data.image_root=/data/images \
    image_grounding.vlm.gemini.api_key=$GOOGLE_API_KEY

生成默认配置：auto_label default_specs results_dir=/results module_name=auto_label，然后设置 autolabel_type: "image_grounding"。所有字段都支持在命令行中使用 Hydra 点号格式进行覆盖。

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

推荐的试运行流程

1. 使用两个步骤处理 5-10 张图像
2. 检查 step_0_expression_extraction/annotations.jsonl——cleaned_caption 和 expressions[] 是否准确？是否捕获了正确的名词短语？
3. 检查 step_1_grounding/annotations.jsonl——expressions[].instances[] 中的边界框是否正确？置信度分数是否合理？
4. 如果质量不够理想，请将 VLM 切换为更强大的模型（例如 gemini-2.5-pro），或提高 media_resolution/max_output_tokens，然后使用 force_reprocess=true 重新运行。
5. 满意后，再扩展到完整数据集。

配置

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

字段	默认值	说明
workflow.steps	["0","1"]	要执行的流水线步骤（"0" = 表达式，"1" = 定位）
workflow.max_workers	4	每个步骤的并行线程数（注意 API 速率限制）
workflow.force_reprocess	false	忽略每个样本的检查点，从头重新处理
vlm.backend	"gemini"	"gemini" 或 "openai"（兼容 OpenAI 的端点）
data.input_jsonl	必填	输入 JSONL 文件路径，每行包含 image_path 和 caption
data.image_root	""	可选前缀，用于解析相对路径的 image_path 条目

输入

data.input_jsonl 指定的单个 JSONL 文件。每行一个 JSON 对象：

字段	必填	说明
image_path	是	绝对路径，或相对于 data.image_root 解析的路径
caption	是	图像的自由文本描述
image_id	否	稳定标识符；若缺失，则根据文件名自动生成
width、height	否	图像的像素尺寸；若缺失，则默认为 1920×1080，用于边界框范围限制

输出

所有输出都写入 results_dir/：

• step_0_expression_extraction/annotations.jsonl — 按记录输出，并添加 cleaned_caption 和 expressions[]（每项包含 text、expression_id、char_span、noun_chunk，以及空的 instances[]）。
• step_1_grounding/annotations.jsonl — 相同记录，其中已填入 expressions[].instances[]（每个实例包含像素坐标空间中的 bbox: [x1,y1,x2,y2]、范围为 [0.0, 1.0] 的 score，以及 bbox_id）。
• results_dir/annotations.jsonl — 为方便使用，复制最后一个步骤的输出。
• step_<N>_*/.ckpt/<sample_id>.json — 用于恢复运行的每个样本检查点。

前提条件

• 容器：nvcr.io/nvidia/tao/tao-toolkit:6.26.3-pyt
• API 访问权限：至少一个 VLM 端点（Gemini API 密钥或支持图像输入的 OpenAI 兼容端点）