TimeLens2-2B 是一款专为视频时间定位（temporal grounding）设计的轻量级视频多模态大模型：给定一段视频和一句文字查询，它会返回所有包含相关视觉证据的时间区间。本文分享一套经过实战验证的提示词工程（Prompt Engineering）技巧，帮助你让 TimeLens2-2B 每次都稳定输出[start, end]格式的 JSON 数组，而不是漏区间、乱格式或自由发挥。

为什么"稳定"这么难？

时间定位任务有两个天然难题：

• 多区间召回：同一事件（比如"男人打开冰箱"）在视频里可能重复出现多次，模型必须返回全部区间，一个都不能少；
• 格式一致性：下游代码需要直接json.loads解析结果，任何多余的解释文字都会导致解析失败。

TimeLens2-2B 基于 Qwen3-VL-2B-Instruct 构建，在 7 个时间定位基准上取得了44.5 的平均 mIoU，刷新了 2B 参数规模下的最高水平（详见 README.md）。但要发挥它的全部实力，提示词和推理参数这两处"细节"至关重要。

提示词模板：两个关键词决定成败

官方推荐的核心提示词非常短（摘自 README.md）：

prompt = ( f'Given the query: "{query}", return ALL time spans (in seconds) where the query is relevant.\n' "Output format MUST be a JSON array of [start, end] pairs.\n" )

别看它只有两行，每一处都有讲究：

1. 用 "ALL" 强调全量召回

return ALL time spans中的ALL直接对抗模型"只报一次"的惰性。实测中，去掉这个词后模型倾向于只返回第一个最显著的区间；加上后多段重复事件也能被完整列出。

2. 用 "MUST" 锁定输出格式

Output format MUST be a JSON array of [start, end] pairs这句把输出约束成唯一一种机器可解析的形态：

[[3.2, 7.8], [21.5, 24.1]]

配合in seconds明确单位，避免模型返回毫秒或时间戳格式，让下游解析代码保持极简。

3. 查询放在引号内

f'Given the query: "{query}"'用引号把用户查询包裹起来，避免查询内容与指令本身混淆，尤其是查询中包含冒号或引号等特殊字符时更稳定。

推理参数：把 temperature 压到 0.01

⚠️ 这是一个极易踩的坑：仓库自带的默认生成参数并不适合时间定位任务。

generation_config.json 中的默认值是temperature=0.7, top_k=20, top_p=0.8——这是通用对话的采样设置，会带来明显的随机性：同一视频跑两次，区间数量甚至起止时间都可能不同。

官方推理示例通过显式传参覆盖为近确定性解码：

model.generate( **inputs, temperature=0.01, top_p=0.001, top_k=1, repetition_penalty=1.0, max_new_tokens=4096, )

视频采样参数：fps 决定区间召回率

时间定位的召回质量还取决于模型"看到了多少帧"。官方示例中的视频参数：

{"type": "video", "video": ..., "fps": 2.0, "min_pixels": 32 * 32, "max_pixels": 480 * 480, "total_pixels": 128000 * 32 * 32}

• fps: 2.0：与 video_preprocessor_config.json 中预训练的默认帧率（fps: 2）保持一致。帧率过低（如 0.5）会漏掉短促动作区间；过高则可能触及max_frames: 768上限被截断。
• max_pixels: 480 * 480：控制单帧分辨率上限。分辨率太高会让长视频的 token 总量爆炸，反而挤占上下文。
• total_pixels：给整段视频设像素总预算，是长视频场景下保持稳定的关键保险丝。

常见翻车清单：4 个高频错误自查

1. 沿用了默认采样参数—— 没有覆盖temperature，结果带随机性，"时好时坏"。✅ 显式传入temperature=0.01, top_k=1。
2. 提示词里没写 "ALL"—— 只返回了第一个区间。✅ 保留return ALL time spans。
3. 没锁定 JSON 格式—— 输出混入 "The event happens at..." 之类自然语言。✅ 保留MUST be a JSON array of [start, end] pairs。
4. fps / 分辨率与预训练配置不匹配—— 长视频中后段区间缺失。✅ 按 video_preprocessor_config.json 的默认值（fps=2、max_frames=768）对齐。

另外，消息结构请交给processor.apply_chat_template自动拼装（模板见 chat_template.jinja），不要手写user标签，否则多模态占位符错位会直接破坏视频理解。

如何验证你的提示词"合格"了？

• ✅ 输出能被json.loads一次解析成功，无任何多余文字；
• ✅ 同一个视频 + 查询重复推理 3 次，区间数量与起止时间完全一致；
• ✅ 对多段重复事件的视频（如多次开合冰箱门），返回的区间数量与肉眼观察吻合。

把提示词模板、近确定性解码参数和官方视频采样配置这三件事对齐，TimeLens2-2B 的时间区间输出就能做到"给一段视频，拿一份稳定、可解析、全量召回的[start, end]清单"。完整可运行的推理代码请参考 README.md 的 Inference 章节，模型架构细节见 config.json。