长视频中查找特定主题时,可把视频交给 Gemini 4 Hydrogen,并在视频输入项设置 processing: "agentic",让模型按需检查时间线;长任务可启用后台执行并轮询结果。
适合的任务:长视频内容检索、定位主题相关片段、回答针对视频内容的问题。
不适合的任务:短视频的宽泛总结、要求整段视频每帧都参与的检查;官方建议这类任务优先考虑默认的静态处理。
适用的模型版本:文档“Agentic video understanding”章节列出 Gemini 4 Hydrogen。
适用的客户端、Agent 或 API:Google Gen AI SDK 的 Interactions API。
推荐的推理档位和参数:设视频输入项 processing 为 "agentic"。长视频或复杂任务可用 background=True;文档未给推理档位设置。
以下问题是官方示例中的原文:
What are the three main arguments presented?
官方示例将它用于一段本地 lecture 视频。下面保留该示例的 Python 请求结构与配置;本地文件路径需替换成实际视频路径。
import time
from google import genai
client = genai.Client()
# 上传长视频
video_file = client.files.upload(file="path/to/lecture.mp4")
while video_file.state.name == "PROCESSING":
time.sleep(2)
video_file = client.files.get(name=video_file.name)
# 使用 agentic 处理和后台执行
interaction = client.interactions.create(
model="gemini-4-hydrogen",
input=[
{
"type": "video",
"uri": video_file.uri,
"mime_type": video_file.mime_type,
"processing": "agentic"
},
{"type": "text", "text": "What are the three main arguments presented?"}
],
background=True,
)
while interaction.status == "in_progress":
time.sleep(5)
interaction = client.interactions.get(interaction.id)
print(interaction.output_text)这是官方代码示例,不是本次实测;文档没有提供该示例的模型回答。若改成查找特定事件,可把问题改成自己的定位问题,并要求返回时间戳。这个改写方向是本文建议,不是官方原文提示词。
准备较长的视频文件。示例使用本地 lecture.mp4,上传到 Files API。
轮询文件状态,等文件离开 PROCESSING 状态。
调用 client.interactions.create,模型设为 gemini-4-hydrogen,视频输入项设 processing="agentic",文本项放入问题。
对耗时较长的任务设置 background=True,按示例用 client.interactions.get(interaction.id) 轮询至状态不再是 in_progress。
读取 interaction.output_text。若要确认确实发生了动态导航,检查返回的 interaction.steps 是否含 processing_call 和 processing_result。
官方说明:默认视频处理是静态模式,按每秒 1 帧抽取;Agentic 模式按提示动态浏览时间线,按需读取转录文本或视频片段。
官方建议:Agentic 适合 5–10 分钟以上长视频、needle-in-a-haystack 检索,以及针对特定时刻或主题的问题;短视频或宽泛问题可能因额外推理和工具调用增加成本与延迟。
官方表格称长视频 Agentic 处理最多可减少 88% 的视频输入 token。该数字是文档给出的上限,不代表每个请求都能达到。
在“Agentic video understanding”章节的模型表中,Gemini 4 Hydrogen 被列为支持模型;页面后面的“Technical details about videos”段落列举支持 Agentic 的模型时没有列出 Hydrogen。本文按前述明确列出的模型表记录,同时保留这一处文档差异。
示例中的问题、模型名、配置及轮询逻辑均来自页面代码;没有记录或推断模型输出。
示例使用本地文件与 Files API。官方同时说明 YouTube URL 可作为视频输入,但该功能处于预览阶段;本例没有使用 YouTube URL。
Agentic 会执行多次检查;网络连接不稳定时,官方建议使用后台执行或 streaming。
页面给出的 token 节省幅度是上限,不应当作固定成本或质量保证。
Agentic 生成的 processing_call / processing_result 步骤可用于确认发生了视频导航;页面说明这些步骤不要求客户端回传响应。
来源页面:Google AI Studio「Video understanding」中“Agentic video understanding”与“Set the processing mode”章节。采集时选择 Python 示例;代码中的 path/to/lecture.mp4 是占位路径,需替换为可访问的视频文件。此处整理的是文档工作流,不是运行结果。
Gemini 4 Hydrogen