基于 Agno 的视频分类实战用 Gemini 原生视频输入与结构化输出完成视频打标【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno导读视频分类Video Classification是数据标注流水线中的一项基础原语给整段视频片段clip打一个标签模型看完整段视频后输出一个全局结论相当于把图像分类的时间维折叠进来。本文基于 agno 仓库cookbook/data_labeling/_13_video_classification/目录中的完整示例讲解如何用 Agno Agent Google Gemini 实现视频的原生输入、闭集标签分类与置信度输出并深入源码说明Video媒体对象与 Gemini 视频接入的底层原理。读完本文你将能独立搭建一个可运行、可扩展的视频内容分类 Agent。理解视频分类这一标注原语视频分类要解决的核心问题是为一段视频输出一个片段级别的标签clip-level label。这与图像分类是同一个原始任务区别在于模型需要看完整个片段——包括连续帧、镜头切换与时间维度上的内容演变——再给出一个覆盖整段视频的单一结论。从 cookbook/data_labeling/_13_video_classification/README.md 的说明看这一原语适用于以下典型场景内容审核Content moderation对用户上传的短视频片段进行门禁式过滤先判定类别再决定是否放行素材预打标Pre-tagging按场景类型预先为素材库中的视频添加标签便于后续检索与推荐安防分流Routing根据事件类别对摄像头片段进行路由归类。如果业务需要的是带时间戳的类型化事件/场景提取例如第 3 秒到第 8 秒出现人物动作则应转向 cookbook/data_labeling/_14_video_extraction/README.md视频提取两者是互补关系分类回答这段视频是什么提取回答这段视频里发生了什么、发生在什么时候。运行环境与启动命令两个示例脚本都依赖 Gemini 模型对视频的原生理解能力因此需要准备环境变量GOOGLE_API_KEYGemini API 密钥安装 agno 及依赖脚本中用到agno、httpx、pydantic、rich等库示例视频通过公网 URL 实时下载无需本地准备素材。在仓库根目录下直接运行python cookbook/data_labeling/_13_video_classification/basic.py python cookbook/data_labeling/_13_video_classification/with_confidence.py运行时脚本会从https://agno-public.s3.amazonaws.com/demo/sample_seaview.mp4拉取视频字节交给 Agent 分类并通过rich.pretty.pprint打印 URL 与结构化分类结果。⚠️ 示例素材命名提示README 特别说明sample_seaview.mp4是个命名误导——这段视频实际是一段短小的实验室场景科学家通过显微镜观察样本并非海景。因此期望的输出标签更可能是indoor或people而不是nature。这一点在调试结果时非常重要避免因期望值与实际不符而误判模型能力。示例一单标签分类basic.pybasic.py 演示了最基础、最通用的视频分类流程全流程仅分三步定义输出 Schema → 创建 Agent → 传入视频运行。第一步用 Pydantic 定义闭集标签 Schemafrom typing import Literal from agno.agent import Agent, RunOutput from agno.media import Video from pydantic import BaseModel, Field from rich.pretty import pprint class Classification(BaseModel): scene_type: Literal[ nature, urban, indoor, people, vehicle, animal, other, ] Field(..., descriptionDominant scene type in the clip)关键设计点闭集标签Literal[...]把输出约束在 7 个候选值内nature/urban/indoor/people/vehicle/animal/other这正是分类与提取的本质区别——模型只能从预定义的封闭集合中挑选一个Field(..., description...)字段描述会随 Schema 一起注入提示词引导模型理解该字段语义片段中的主导场景类型output_schemaAgno Agent 的output_schema参数接受任意 PydanticBaseModel运行时会强制模型按该结构返回结构化输出。第二步创建 Agentagent Agent( modelgoogle:gemini-3.5-flash, instructionsYou classify short video clips by dominant scene type., output_schemaClassification, )三个参数各司其职model指定 Google Gemini 系列模型该 cookbook 的配套示例均使用google:gemini-3.5-flash支持原生视频输入instructions给出简短任务说明output_schema绑定上述结构化输出模型。第三步下载视频并运行if __name__ __main__: url https://agno-public.s3.amazonaws.com/demo/sample_seaview.mp4 video_bytes httpx.get(url).content run: RunOutput agent.run( Classify this clip., videos[Video(contentvideo_bytes, formatmp4)], ) pprint({url: url, result: run.content})这里展示了 Agno 媒体输入的标准姿势用httpx下载视频字节流构造Video(contentvideo_bytes, formatmp4)媒体对象通过agent.run(prompt, videos[...])将视频与文本提示一起送入模型从RunOutput.content取出结构化分类结果即Classification实例。示例二带置信度的分类with_confidence.pywith_confidence.py 在单标签基础上增加了一个置信度维度其工程动机在文件开头注释中写得很清楚让下游消费者可以把低置信度片段转交人工审核或更强的模型处理。扩展 Schema增加 confidence 字段class Classification(BaseModel): scene_type: Literal[ nature, urban, indoor, people, vehicle, animal, other, ] Field(..., descriptionDominant scene type in the clip) confidence: Literal[high, medium, low] Field( ..., descriptionConfidence in the label )confidence同样使用Literal[high, medium, low]约束为三档离散值便于下游做确定性路由而非解析自由文本。用指令约束置信度语义比基础版更精细的是 instructions 的写法它把三档置信度的判定标准写得非常具体instructions \ Classify the clip and report a confidence: - high - the dominant scene is unambiguous across the clip - medium - the dominant scene is identifiable but some shots break the pattern - low - the clip mixes several scene types and you had to pick 这四条规则实际上定义了一个可操作的置信度判定协议high主导场景在整段视频中无歧义medium主导场景可识别但部分镜头不符合该模式low视频混合了多种场景类型模型不得不硬选一个。这种把评估标准写进 instructions的做法比让模型自行发挥可靠得多也是本示例值得借鉴的实战模式。运行run: RunOutput agent.run( Classify this clip with confidence., videos[Video(contentvideo_bytes, formatmp4)], )仅提示词略有不同Classify this clip with confidence.其余流程与 basic 版完全一致。源码纵览Video 媒体对象的字段与校验理解Video对象是掌握 Agno 多媒体输入的关键。其实现位于 libs/agno/agno/media/media.py核心设计如下三种内容来源且三选一字段类型说明urlstr \| None视频的远程 URLfilepathPath \| str \| None本地视频文件路径contentbytes \| None原始视频字节统一规范化为 bytesvalidate_and_normalize_content校验器强制恰好提供一个内容来源全部为空或同时提供多个都会抛出ValueError。同时自动为对象生成iduuid4。媒体元数据format如mp4/mov/avi/webm、mime_type如video/mp4、duration秒、width/height像素、fps等字段用于描述视频本身。内容读取get_content_bytes()按content → url → media_reference → filepath的优先级返回字节若携带了media_reference媒体被卸载到对象存储时的引用则通过传入的MediaStorage句柄解析真实字节。此外还提供get_url()用于生成模型或浏览器可直接拉取的 URL。源码纵览Agent.run 如何接收视频视频输入是Agent.run的一等参数。在 libs/agno/agno/agent/agent.py 中run()的签名同时接收audio、images、videos、files四类媒体序列videos的类型为Optional[Sequence[Video]]随后统一派发到_run.run_dispatch(...)执行。在 Gemini 模型一侧libs/agno/agno/models/google/gemini.py消息中的videos会被逐个格式化后插入消息体若视频已上传为 Gemini File 对象content为GeminiFile则使用Part.from_uri(uri, mime_type)引用远端文件否则调用_format_video_for_message字节内容用Part.from_bytes(mime_typevideo/mp4, data...)直接内联本地文件路径则先上传到 Gemini API 再引用。值得注意的细节Google 官方建议单视频场景下把文本提示放在视频之后因此代码将视频 part 插入到消息 parts 的头部位置message_parts.insert(0, video_file)。从这条调用链可以看出Agno 对远程 URL、本地文件、字节流三种视频来源做了统一抽象上层业务代码只需构造Video对象底层自动完成上传与格式化。与视频提取_14_video_extraction的边界划分为方便决策将两个相邻目录的能力边界对比如下维度_13_video_classification本文_14_video_extraction输出粒度片段级单一标签闭集类型化对象事件、场景描述、带时间戳的动作典型 Schemascene_type: Literal[...]场景列表 /(action, start, end)结构化记录典型场景审核门禁、素材打标、安防路由视频归档索引、长视频章节生成、(video, labels)训练集构建是否需要时间信息不需要需要action_timestamps.py输出秒级起止时间规则可以概括为一句话只需要这段视频是什么就选分类需要里面发生了什么、何时发生就选提取。工程实践要点结合示例与源码总结几条可直接复用的实践建议用Literal强制闭集分类任务的标签必须是有限集合Literal让非法输出在 Schema 层面就无法产生配合output_schema做到结构即约束把置信度判定标准写进 instructions三档置信度的判定规则越明确模型输出越稳定下游路由人工审核 / 升级模型就越可靠利用Field(description...)传递字段语义描述文本会参与提示词构建帮助模型理解字段含义视频来源灵活远程 URL、本地路径、原始字节三种输入方式对应url/filepath/content三个字段cookbook 示例采用字节流方式httpx下载生产环境可改用文件路径或预先上传警惕素材命名与内容的错位sample_seaview.mp4实际是实验室场景跑通示例后应以视频真实内容而非文件名来校验输出。延伸阅读进阶示例本目录的完整脚本见 cookbook/data_labeling/_13_video_classification/basic.py 与 with_confidence.py相关原语需要时间戳级事件提取时参考 cookbook/data_labeling/_14_video_extraction/README.md 及其三个示例脚本basic.py、scene_descriptions.py、action_timestamps.py媒体对象实现libs/agno/agno/media/media.py 中的Video类与get_content_bytes/get_url运行入口libs/agno/agno/agent/agent.py 中run()的videos参数与调度逻辑Gemini 视频接入libs/agno/agno/models/google/gemini.py 中视频消息格式化与文件上传逻辑。【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 基于 Agno 的视频分类实战：用 Gemini 原生视频输入与结构化输出完成视频打标
基于 Agno 的视频分类实战用 Gemini 原生视频输入与结构化输出完成视频打标【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno导读视频分类Video Classification是数据标注流水线中的一项基础原语给整段视频片段clip打一个标签模型看完整段视频后输出一个全局结论相当于把图像分类的时间维折叠进来。本文基于 agno 仓库cookbook/data_labeling/_13_video_classification/目录中的完整示例讲解如何用 Agno Agent Google Gemini 实现视频的原生输入、闭集标签分类与置信度输出并深入源码说明Video媒体对象与 Gemini 视频接入的底层原理。读完本文你将能独立搭建一个可运行、可扩展的视频内容分类 Agent。理解视频分类这一标注原语视频分类要解决的核心问题是为一段视频输出一个片段级别的标签clip-level label。这与图像分类是同一个原始任务区别在于模型需要看完整个片段——包括连续帧、镜头切换与时间维度上的内容演变——再给出一个覆盖整段视频的单一结论。从 cookbook/data_labeling/_13_video_classification/README.md 的说明看这一原语适用于以下典型场景内容审核Content moderation对用户上传的短视频片段进行门禁式过滤先判定类别再决定是否放行素材预打标Pre-tagging按场景类型预先为素材库中的视频添加标签便于后续检索与推荐安防分流Routing根据事件类别对摄像头片段进行路由归类。如果业务需要的是带时间戳的类型化事件/场景提取例如第 3 秒到第 8 秒出现人物动作则应转向 cookbook/data_labeling/_14_video_extraction/README.md视频提取两者是互补关系分类回答这段视频是什么提取回答这段视频里发生了什么、发生在什么时候。运行环境与启动命令两个示例脚本都依赖 Gemini 模型对视频的原生理解能力因此需要准备环境变量GOOGLE_API_KEYGemini API 密钥安装 agno 及依赖脚本中用到agno、httpx、pydantic、rich等库示例视频通过公网 URL 实时下载无需本地准备素材。在仓库根目录下直接运行python cookbook/data_labeling/_13_video_classification/basic.py python cookbook/data_labeling/_13_video_classification/with_confidence.py运行时脚本会从https://agno-public.s3.amazonaws.com/demo/sample_seaview.mp4拉取视频字节交给 Agent 分类并通过rich.pretty.pprint打印 URL 与结构化分类结果。⚠️ 示例素材命名提示README 特别说明sample_seaview.mp4是个命名误导——这段视频实际是一段短小的实验室场景科学家通过显微镜观察样本并非海景。因此期望的输出标签更可能是indoor或people而不是nature。这一点在调试结果时非常重要避免因期望值与实际不符而误判模型能力。示例一单标签分类basic.pybasic.py 演示了最基础、最通用的视频分类流程全流程仅分三步定义输出 Schema → 创建 Agent → 传入视频运行。第一步用 Pydantic 定义闭集标签 Schemafrom typing import Literal from agno.agent import Agent, RunOutput from agno.media import Video from pydantic import BaseModel, Field from rich.pretty import pprint class Classification(BaseModel): scene_type: Literal[ nature, urban, indoor, people, vehicle, animal, other, ] Field(..., descriptionDominant scene type in the clip)关键设计点闭集标签Literal[...]把输出约束在 7 个候选值内nature/urban/indoor/people/vehicle/animal/other这正是分类与提取的本质区别——模型只能从预定义的封闭集合中挑选一个Field(..., description...)字段描述会随 Schema 一起注入提示词引导模型理解该字段语义片段中的主导场景类型output_schemaAgno Agent 的output_schema参数接受任意 PydanticBaseModel运行时会强制模型按该结构返回结构化输出。第二步创建 Agentagent Agent( modelgoogle:gemini-3.5-flash, instructionsYou classify short video clips by dominant scene type., output_schemaClassification, )三个参数各司其职model指定 Google Gemini 系列模型该 cookbook 的配套示例均使用google:gemini-3.5-flash支持原生视频输入instructions给出简短任务说明output_schema绑定上述结构化输出模型。第三步下载视频并运行if __name__ __main__: url https://agno-public.s3.amazonaws.com/demo/sample_seaview.mp4 video_bytes httpx.get(url).content run: RunOutput agent.run( Classify this clip., videos[Video(contentvideo_bytes, formatmp4)], ) pprint({url: url, result: run.content})这里展示了 Agno 媒体输入的标准姿势用httpx下载视频字节流构造Video(contentvideo_bytes, formatmp4)媒体对象通过agent.run(prompt, videos[...])将视频与文本提示一起送入模型从RunOutput.content取出结构化分类结果即Classification实例。示例二带置信度的分类with_confidence.pywith_confidence.py 在单标签基础上增加了一个置信度维度其工程动机在文件开头注释中写得很清楚让下游消费者可以把低置信度片段转交人工审核或更强的模型处理。扩展 Schema增加 confidence 字段class Classification(BaseModel): scene_type: Literal[ nature, urban, indoor, people, vehicle, animal, other, ] Field(..., descriptionDominant scene type in the clip) confidence: Literal[high, medium, low] Field( ..., descriptionConfidence in the label )confidence同样使用Literal[high, medium, low]约束为三档离散值便于下游做确定性路由而非解析自由文本。用指令约束置信度语义比基础版更精细的是 instructions 的写法它把三档置信度的判定标准写得非常具体instructions \ Classify the clip and report a confidence: - high - the dominant scene is unambiguous across the clip - medium - the dominant scene is identifiable but some shots break the pattern - low - the clip mixes several scene types and you had to pick 这四条规则实际上定义了一个可操作的置信度判定协议high主导场景在整段视频中无歧义medium主导场景可识别但部分镜头不符合该模式low视频混合了多种场景类型模型不得不硬选一个。这种把评估标准写进 instructions的做法比让模型自行发挥可靠得多也是本示例值得借鉴的实战模式。运行run: RunOutput agent.run( Classify this clip with confidence., videos[Video(contentvideo_bytes, formatmp4)], )仅提示词略有不同Classify this clip with confidence.其余流程与 basic 版完全一致。源码纵览Video 媒体对象的字段与校验理解Video对象是掌握 Agno 多媒体输入的关键。其实现位于 libs/agno/agno/media/media.py核心设计如下三种内容来源且三选一字段类型说明urlstr \| None视频的远程 URLfilepathPath \| str \| None本地视频文件路径contentbytes \| None原始视频字节统一规范化为 bytesvalidate_and_normalize_content校验器强制恰好提供一个内容来源全部为空或同时提供多个都会抛出ValueError。同时自动为对象生成iduuid4。媒体元数据format如mp4/mov/avi/webm、mime_type如video/mp4、duration秒、width/height像素、fps等字段用于描述视频本身。内容读取get_content_bytes()按content → url → media_reference → filepath的优先级返回字节若携带了media_reference媒体被卸载到对象存储时的引用则通过传入的MediaStorage句柄解析真实字节。此外还提供get_url()用于生成模型或浏览器可直接拉取的 URL。源码纵览Agent.run 如何接收视频视频输入是Agent.run的一等参数。在 libs/agno/agno/agent/agent.py 中run()的签名同时接收audio、images、videos、files四类媒体序列videos的类型为Optional[Sequence[Video]]随后统一派发到_run.run_dispatch(...)执行。在 Gemini 模型一侧libs/agno/agno/models/google/gemini.py消息中的videos会被逐个格式化后插入消息体若视频已上传为 Gemini File 对象content为GeminiFile则使用Part.from_uri(uri, mime_type)引用远端文件否则调用_format_video_for_message字节内容用Part.from_bytes(mime_typevideo/mp4, data...)直接内联本地文件路径则先上传到 Gemini API 再引用。值得注意的细节Google 官方建议单视频场景下把文本提示放在视频之后因此代码将视频 part 插入到消息 parts 的头部位置message_parts.insert(0, video_file)。从这条调用链可以看出Agno 对远程 URL、本地文件、字节流三种视频来源做了统一抽象上层业务代码只需构造Video对象底层自动完成上传与格式化。与视频提取_14_video_extraction的边界划分为方便决策将两个相邻目录的能力边界对比如下维度_13_video_classification本文_14_video_extraction输出粒度片段级单一标签闭集类型化对象事件、场景描述、带时间戳的动作典型 Schemascene_type: Literal[...]场景列表 /(action, start, end)结构化记录典型场景审核门禁、素材打标、安防路由视频归档索引、长视频章节生成、(video, labels)训练集构建是否需要时间信息不需要需要action_timestamps.py输出秒级起止时间规则可以概括为一句话只需要这段视频是什么就选分类需要里面发生了什么、何时发生就选提取。工程实践要点结合示例与源码总结几条可直接复用的实践建议用Literal强制闭集分类任务的标签必须是有限集合Literal让非法输出在 Schema 层面就无法产生配合output_schema做到结构即约束把置信度判定标准写进 instructions三档置信度的判定规则越明确模型输出越稳定下游路由人工审核 / 升级模型就越可靠利用Field(description...)传递字段语义描述文本会参与提示词构建帮助模型理解字段含义视频来源灵活远程 URL、本地路径、原始字节三种输入方式对应url/filepath/content三个字段cookbook 示例采用字节流方式httpx下载生产环境可改用文件路径或预先上传警惕素材命名与内容的错位sample_seaview.mp4实际是实验室场景跑通示例后应以视频真实内容而非文件名来校验输出。延伸阅读进阶示例本目录的完整脚本见 cookbook/data_labeling/_13_video_classification/basic.py 与 with_confidence.py相关原语需要时间戳级事件提取时参考 cookbook/data_labeling/_14_video_extraction/README.md 及其三个示例脚本basic.py、scene_descriptions.py、action_timestamps.py媒体对象实现libs/agno/agno/media/media.py 中的Video类与get_content_bytes/get_url运行入口libs/agno/agno/agent/agent.py 中run()的videos参数与调度逻辑Gemini 视频接入libs/agno/agno/models/google/gemini.py 中视频消息格式化与文件上传逻辑。【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考