：用 Gemini 原生視頻輸入與結(jié)構(gòu)化輸出完成視頻打標)
基于 Agno 的視頻分類實戰(zhàn)用 Gemini 原生視頻輸入與結(jié)構(gòu)化輸出完成視頻打標【免費下載鏈接】agnoBuild, run, and manage agent platforms.項目地址: https://gitcode.com/GitHub_Trending/ag/agno導(dǎo)讀視頻分類Video Classification是數(shù)據(jù)標注流水線中的一項基礎(chǔ)原語給整段視頻片段clip打一個標簽?zāi)Ｐ涂赐暾我曨l后輸出一個全局結(jié)論相當于把圖像分類的時間維折疊進來。本文基于 agno 倉庫cookbook/data_labeling/_13_video_classification/目錄中的完整示例講解如何用 Agno Agent Google Gemini 實現(xiàn)視頻的原生輸入、閉集標簽分類與置信度輸出并深入源碼說明Video媒體對象與 Gemini 視頻接入的底層原理。讀完本文你將能獨立搭建一個可運行、可擴展的視頻內(nèi)容分類 Agent。理解視頻分類這一標注原語視頻分類要解決的核心問題是為一段視頻輸出一個片段級別的標簽clip-level label。這與圖像分類是同一個原始任務(wù)區(qū)別在于模型需要看完整個片段——包括連續(xù)幀、鏡頭切換與時間維度上的內(nèi)容演變——再給出一個覆蓋整段視頻的單一結(jié)論。從 cookbook/data_labeling/_13_video_classification/README.md 的說明看這一原語適用于以下典型場景內(nèi)容審核Content moderation對用戶上傳的短視頻片段進行門禁式過濾先判定類別再決定是否放行素材預(yù)打標Pre-tagging按場景類型預(yù)先為素材庫中的視頻添加標簽便于后續(xù)檢索與推薦安防分流Routing根據(jù)事件類別對攝像頭片段進行路由歸類。如果業(yè)務(wù)需要的是帶時間戳的類型化事件/場景提取例如第 3 秒到第 8 秒出現(xiàn)人物動作則應(yīng)轉(zhuǎn)向 cookbook/data_labeling/_14_video_extraction/README.md視頻提取兩者是互補關(guān)系分類回答這段視頻是什么提取回答這段視頻里發(fā)生了什么、發(fā)生在什么時候。運行環(huán)境與啟動命令兩個示例腳本都依賴 Gemini 模型對視頻的原生理解能力因此需要準備環(huán)境變量GOOGLE_API_KEYGemini API 密鑰安裝 agno 及依賴腳本中用到agno、httpx、pydantic、rich等庫示例視頻通過公網(wǎng) 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拉取視頻字節(jié)交給 Agent 分類并通過rich.pretty.pprint打印 URL 與結(jié)構(gòu)化分類結(jié)果。?? 示例素材命名提示README 特別說明sample_seaview.mp4是個命名誤導(dǎo)——這段視頻實際是一段短小的實驗室場景科學(xué)家通過顯微鏡觀察樣本并非海景。因此期望的輸出標簽更可能是indoor或people而不是nature。這一點在調(diào)試結(jié)果時非常重要避免因期望值與實際不符而誤判模型能力。示例一單標簽分類basic.pybasic.py 演示了最基礎(chǔ)、最通用的視頻分類流程全流程僅分三步定義輸出 Schema → 創(chuàng)建 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)關(guān)鍵設(shè)計點閉集標簽Literal[...]把輸出約束在 7 個候選值內(nèi)nature/urban/indoor/people/vehicle/animal/other這正是分類與提取的本質(zhì)區(qū)別——模型只能從預(yù)定義的封閉集合中挑選一個Field(..., description...)字段描述會隨 Schema 一起注入提示詞引導(dǎo)模型理解該字段語義片段中的主導(dǎo)場景類型output_schemaAgno Agent 的output_schema參數(shù)接受任意 PydanticBaseModel運行時會強制模型按該結(jié)構(gòu)返回結(jié)構(gòu)化輸出。第二步創(chuàng)建 Agentagent Agent( modelgoogle:gemini-3.5-flash, instructionsYou classify short video clips by dominant scene type., output_schemaClassification, )三個參數(shù)各司其職model指定 Google Gemini 系列模型該 cookbook 的配套示例均使用google:gemini-3.5-flash支持原生視頻輸入instructions給出簡短任務(wù)說明output_schema綁定上述結(jié)構(gòu)化輸出模型。第三步下載視頻并運行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下載視頻字節(jié)流構(gòu)造Video(contentvideo_bytes, formatmp4)媒體對象通過agent.run(prompt, videos[...])將視頻與文本提示一起送入模型從RunOutput.content取出結(jié)構(gòu)化分類結(jié)果即Classification實例。示例二帶置信度的分類with_confidence.pywith_confidence.py 在單標簽基礎(chǔ)上增加了一個置信度維度其工程動機在文件開頭注釋中寫得很清楚讓下游消費者可以把低置信度片段轉(zhuǎn)交人工審核或更強的模型處理。擴展 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]約束為三檔離散值便于下游做確定性路由而非解析自由文本。用指令約束置信度語義比基礎(chǔ)版更精細的是 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 這四條規(guī)則實際上定義了一個可操作的置信度判定協(xié)議high主導(dǎo)場景在整段視頻中無歧義medium主導(dǎo)場景可識別但部分鏡頭不符合該模式low視頻混合了多種場景類型模型不得不硬選一個。這種把評估標準寫進 instructions的做法比讓模型自行發(fā)揮可靠得多也是本示例值得借鑒的實戰(zhàn)模式。運行run: RunOutput agent.run( Classify this clip with confidence., videos[Video(contentvideo_bytes, formatmp4)], )僅提示詞略有不同Classify this clip with confidence.其余流程與 basic 版完全一致。源碼縱覽Video 媒體對象的字段與校驗理解Video對象是掌握 Agno 多媒體輸入的關(guān)鍵。其實現(xiàn)位于 libs/agno/agno/media/media.py核心設(shè)計如下三種內(nèi)容來源且三選一字段類型說明urlstr \| None視頻的遠程 URLfilepathPath \| str \| None本地視頻文件路徑contentbytes \| None原始視頻字節(jié)統(tǒng)一規(guī)范化為 bytesvalidate_and_normalize_content校驗器強制恰好提供一個內(nèi)容來源全部為空或同時提供多個都會拋出ValueError。同時自動為對象生成iduuid4。媒體元數(shù)據(jù)format如mp4/mov/avi/webm、mime_type如video/mp4、duration秒、width/height像素、fps等字段用于描述視頻本身。內(nèi)容讀取get_content_bytes()按content → url → media_reference → filepath的優(yōu)先級返回字節(jié)若攜帶了media_reference媒體被卸載到對象存儲時的引用則通過傳入的MediaStorage句柄解析真實字節(jié)。此外還提供get_url()用于生成模型或瀏覽器可直接拉取的 URL。源碼縱覽Agent.run 如何接收視頻視頻輸入是Agent.run的一等參數(shù)。在 libs/agno/agno/agent/agent.py 中run()的簽名同時接收audio、images、videos、files四類媒體序列videos的類型為Optional[Sequence[Video]]隨后統(tǒng)一派發(fā)到_run.run_dispatch(...)執(zhí)行。在 Gemini 模型一側(cè)libs/agno/agno/models/google/gemini.py消息中的videos會被逐個格式化后插入消息體若視頻已上傳為 Gemini File 對象content為GeminiFile則使用Part.from_uri(uri, mime_type)引用遠端文件否則調(diào)用_format_video_for_message字節(jié)內(nèi)容用Part.from_bytes(mime_typevideo/mp4, data...)直接內(nèi)聯(lián)本地文件路徑則先上傳到 Gemini API 再引用。值得注意的細節(jié)Google 官方建議單視頻場景下把文本提示放在視頻之后因此代碼將視頻 part 插入到消息 parts 的頭部位置message_parts.insert(0, video_file)。從這條調(diào)用鏈可以看出Agno 對遠程 URL、本地文件、字節(jié)流三種視頻來源做了統(tǒng)一抽象上層業(yè)務(wù)代碼只需構(gòu)造Video對象底層自動完成上傳與格式化。與視頻提取_14_video_extraction的邊界劃分為方便決策將兩個相鄰目錄的能力邊界對比如下維度_13_video_classification本文_14_video_extraction輸出粒度片段級單一標簽閉集類型化對象事件、場景描述、帶時間戳的動作典型 Schemascene_type: Literal[...]場景列表 /(action, start, end)結(jié)構(gòu)化記錄典型場景審核門禁、素材打標、安防路由視頻歸檔索引、長視頻章節(jié)生成、(video, labels)訓(xùn)練集構(gòu)建是否需要時間信息不需要需要action_timestamps.py輸出秒級起止時間規(guī)則可以概括為一句話只需要這段視頻是什么就選分類需要里面發(fā)生了什么、何時發(fā)生就選提取。工程實踐要點結(jié)合示例與源碼總結(jié)幾條可直接復(fù)用的實踐建議用Literal強制閉集分類任務(wù)的標簽必須是有限集合Literal讓非法輸出在 Schema 層面就無法產(chǎn)生配合output_schema做到結(jié)構(gòu)即約束把置信度判定標準寫進 instructions三檔置信度的判定規(guī)則越明確模型輸出越穩(wěn)定下游路由人工審核 / 升級模型就越可靠利用Field(description...)傳遞字段語義描述文本會參與提示詞構(gòu)建幫助模型理解字段含義視頻來源靈活遠程 URL、本地路徑、原始字節(jié)三種輸入方式對應(yīng)url/filepath/content三個字段cookbook 示例采用字節(jié)流方式httpx下載生產(chǎn)環(huán)境可改用文件路徑或預(yù)先上傳警惕素材命名與內(nèi)容的錯位sample_seaview.mp4實際是實驗室場景跑通示例后應(yīng)以視頻真實內(nèi)容而非文件名來校驗輸出。延伸閱讀進階示例本目錄的完整腳本見 cookbook/data_labeling/_13_video_classification/basic.py 與 with_confidence.py相關(guān)原語需要時間戳級事件提取時參考 cookbook/data_labeling/_14_video_extraction/README.md 及其三個示例腳本basic.py、scene_descriptions.py、action_timestamps.py媒體對象實現(xiàn)libs/agno/agno/media/media.py 中的Video類與get_content_bytes/get_url運行入口libs/agno/agno/agent/agent.py 中run()的videos參數(shù)與調(diào)度邏輯Gemini 視頻接入libs/agno/agno/models/google/gemini.py 中視頻消息格式化與文件上傳邏輯。【免費下載鏈接】agnoBuild, run, and manage agent platforms.項目地址: https://gitcode.com/GitHub_Trending/ag/agno創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 基于 Agno 的視頻分類實戰(zhàn)：用 Gemini 原生視頻輸入與結(jié)構(gòu)化輸出完成視頻打標
基于 Agno 的視頻分類實戰(zhàn)用 Gemini 原生視頻輸入與結(jié)構(gòu)化輸出完成視頻打標【免費下載鏈接】agnoBuild, run, and manage agent platforms.項目地址: https://gitcode.com/GitHub_Trending/ag/agno導(dǎo)讀視頻分類Video Classification是數(shù)據(jù)標注流水線中的一項基礎(chǔ)原語給整段視頻片段clip打一個標簽?zāi)Ｐ涂赐暾我曨l后輸出一個全局結(jié)論相當于把圖像分類的時間維折疊進來。本文基于 agno 倉庫cookbook/data_labeling/_13_video_classification/目錄中的完整示例講解如何用 Agno Agent Google Gemini 實現(xiàn)視頻的原生輸入、閉集標簽分類與置信度輸出并深入源碼說明Video媒體對象與 Gemini 視頻接入的底層原理。讀完本文你將能獨立搭建一個可運行、可擴展的視頻內(nèi)容分類 Agent。理解視頻分類這一標注原語視頻分類要解決的核心問題是為一段視頻輸出一個片段級別的標簽clip-level label。這與圖像分類是同一個原始任務(wù)區(qū)別在于模型需要看完整個片段——包括連續(xù)幀、鏡頭切換與時間維度上的內(nèi)容演變——再給出一個覆蓋整段視頻的單一結(jié)論。從 cookbook/data_labeling/_13_video_classification/README.md 的說明看這一原語適用于以下典型場景內(nèi)容審核Content moderation對用戶上傳的短視頻片段進行門禁式過濾先判定類別再決定是否放行素材預(yù)打標Pre-tagging按場景類型預(yù)先為素材庫中的視頻添加標簽便于后續(xù)檢索與推薦安防分流Routing根據(jù)事件類別對攝像頭片段進行路由歸類。如果業(yè)務(wù)需要的是帶時間戳的類型化事件/場景提取例如第 3 秒到第 8 秒出現(xiàn)人物動作則應(yīng)轉(zhuǎn)向 cookbook/data_labeling/_14_video_extraction/README.md視頻提取兩者是互補關(guān)系分類回答這段視頻是什么提取回答這段視頻里發(fā)生了什么、發(fā)生在什么時候。運行環(huán)境與啟動命令兩個示例腳本都依賴 Gemini 模型對視頻的原生理解能力因此需要準備環(huán)境變量GOOGLE_API_KEYGemini API 密鑰安裝 agno 及依賴腳本中用到agno、httpx、pydantic、rich等庫示例視頻通過公網(wǎng) 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拉取視頻字節(jié)交給 Agent 分類并通過rich.pretty.pprint打印 URL 與結(jié)構(gòu)化分類結(jié)果。?? 示例素材命名提示README 特別說明sample_seaview.mp4是個命名誤導(dǎo)——這段視頻實際是一段短小的實驗室場景科學(xué)家通過顯微鏡觀察樣本并非海景。因此期望的輸出標簽更可能是indoor或people而不是nature。這一點在調(diào)試結(jié)果時非常重要避免因期望值與實際不符而誤判模型能力。示例一單標簽分類basic.pybasic.py 演示了最基礎(chǔ)、最通用的視頻分類流程全流程僅分三步定義輸出 Schema → 創(chuàng)建 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)關(guān)鍵設(shè)計點閉集標簽Literal[...]把輸出約束在 7 個候選值內(nèi)nature/urban/indoor/people/vehicle/animal/other這正是分類與提取的本質(zhì)區(qū)別——模型只能從預(yù)定義的封閉集合中挑選一個Field(..., description...)字段描述會隨 Schema 一起注入提示詞引導(dǎo)模型理解該字段語義片段中的主導(dǎo)場景類型output_schemaAgno Agent 的output_schema參數(shù)接受任意 PydanticBaseModel運行時會強制模型按該結(jié)構(gòu)返回結(jié)構(gòu)化輸出。第二步創(chuàng)建 Agentagent Agent( modelgoogle:gemini-3.5-flash, instructionsYou classify short video clips by dominant scene type., output_schemaClassification, )三個參數(shù)各司其職model指定 Google Gemini 系列模型該 cookbook 的配套示例均使用google:gemini-3.5-flash支持原生視頻輸入instructions給出簡短任務(wù)說明output_schema綁定上述結(jié)構(gòu)化輸出模型。第三步下載視頻并運行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下載視頻字節(jié)流構(gòu)造Video(contentvideo_bytes, formatmp4)媒體對象通過agent.run(prompt, videos[...])將視頻與文本提示一起送入模型從RunOutput.content取出結(jié)構(gòu)化分類結(jié)果即Classification實例。示例二帶置信度的分類with_confidence.pywith_confidence.py 在單標簽基礎(chǔ)上增加了一個置信度維度其工程動機在文件開頭注釋中寫得很清楚讓下游消費者可以把低置信度片段轉(zhuǎn)交人工審核或更強的模型處理。擴展 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]約束為三檔離散值便于下游做確定性路由而非解析自由文本。用指令約束置信度語義比基礎(chǔ)版更精細的是 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 這四條規(guī)則實際上定義了一個可操作的置信度判定協(xié)議high主導(dǎo)場景在整段視頻中無歧義medium主導(dǎo)場景可識別但部分鏡頭不符合該模式low視頻混合了多種場景類型模型不得不硬選一個。這種把評估標準寫進 instructions的做法比讓模型自行發(fā)揮可靠得多也是本示例值得借鑒的實戰(zhàn)模式。運行run: RunOutput agent.run( Classify this clip with confidence., videos[Video(contentvideo_bytes, formatmp4)], )僅提示詞略有不同Classify this clip with confidence.其余流程與 basic 版完全一致。源碼縱覽Video 媒體對象的字段與校驗理解Video對象是掌握 Agno 多媒體輸入的關(guān)鍵。其實現(xiàn)位于 libs/agno/agno/media/media.py核心設(shè)計如下三種內(nèi)容來源且三選一字段類型說明urlstr \| None視頻的遠程 URLfilepathPath \| str \| None本地視頻文件路徑contentbytes \| None原始視頻字節(jié)統(tǒng)一規(guī)范化為 bytesvalidate_and_normalize_content校驗器強制恰好提供一個內(nèi)容來源全部為空或同時提供多個都會拋出ValueError。同時自動為對象生成iduuid4。媒體元數(shù)據(jù)format如mp4/mov/avi/webm、mime_type如video/mp4、duration秒、width/height像素、fps等字段用于描述視頻本身。內(nèi)容讀取get_content_bytes()按content → url → media_reference → filepath的優(yōu)先級返回字節(jié)若攜帶了media_reference媒體被卸載到對象存儲時的引用則通過傳入的MediaStorage句柄解析真實字節(jié)。此外還提供get_url()用于生成模型或瀏覽器可直接拉取的 URL。源碼縱覽Agent.run 如何接收視頻視頻輸入是Agent.run的一等參數(shù)。在 libs/agno/agno/agent/agent.py 中run()的簽名同時接收audio、images、videos、files四類媒體序列videos的類型為Optional[Sequence[Video]]隨后統(tǒng)一派發(fā)到_run.run_dispatch(...)執(zhí)行。在 Gemini 模型一側(cè)libs/agno/agno/models/google/gemini.py消息中的videos會被逐個格式化后插入消息體若視頻已上傳為 Gemini File 對象content為GeminiFile則使用Part.from_uri(uri, mime_type)引用遠端文件否則調(diào)用_format_video_for_message字節(jié)內(nèi)容用Part.from_bytes(mime_typevideo/mp4, data...)直接內(nèi)聯(lián)本地文件路徑則先上傳到 Gemini API 再引用。值得注意的細節(jié)Google 官方建議單視頻場景下把文本提示放在視頻之后因此代碼將視頻 part 插入到消息 parts 的頭部位置message_parts.insert(0, video_file)。從這條調(diào)用鏈可以看出Agno 對遠程 URL、本地文件、字節(jié)流三種視頻來源做了統(tǒng)一抽象上層業(yè)務(wù)代碼只需構(gòu)造Video對象底層自動完成上傳與格式化。與視頻提取_14_video_extraction的邊界劃分為方便決策將兩個相鄰目錄的能力邊界對比如下維度_13_video_classification本文_14_video_extraction輸出粒度片段級單一標簽閉集類型化對象事件、場景描述、帶時間戳的動作典型 Schemascene_type: Literal[...]場景列表 /(action, start, end)結(jié)構(gòu)化記錄典型場景審核門禁、素材打標、安防路由視頻歸檔索引、長視頻章節(jié)生成、(video, labels)訓(xùn)練集構(gòu)建是否需要時間信息不需要需要action_timestamps.py輸出秒級起止時間規(guī)則可以概括為一句話只需要這段視頻是什么就選分類需要里面發(fā)生了什么、何時發(fā)生就選提取。工程實踐要點結(jié)合示例與源碼總結(jié)幾條可直接復(fù)用的實踐建議用Literal強制閉集分類任務(wù)的標簽必須是有限集合Literal讓非法輸出在 Schema 層面就無法產(chǎn)生配合output_schema做到結(jié)構(gòu)即約束把置信度判定標準寫進 instructions三檔置信度的判定規(guī)則越明確模型輸出越穩(wěn)定下游路由人工審核 / 升級模型就越可靠利用Field(description...)傳遞字段語義描述文本會參與提示詞構(gòu)建幫助模型理解字段含義視頻來源靈活遠程 URL、本地路徑、原始字節(jié)三種輸入方式對應(yīng)url/filepath/content三個字段cookbook 示例采用字節(jié)流方式httpx下載生產(chǎn)環(huán)境可改用文件路徑或預(yù)先上傳警惕素材命名與內(nèi)容的錯位sample_seaview.mp4實際是實驗室場景跑通示例后應(yīng)以視頻真實內(nèi)容而非文件名來校驗輸出。延伸閱讀進階示例本目錄的完整腳本見 cookbook/data_labeling/_13_video_classification/basic.py 與 with_confidence.py相關(guān)原語需要時間戳級事件提取時參考 cookbook/data_labeling/_14_video_extraction/README.md 及其三個示例腳本basic.py、scene_descriptions.py、action_timestamps.py媒體對象實現(xiàn)libs/agno/agno/media/media.py 中的Video類與get_content_bytes/get_url運行入口libs/agno/agno/agent/agent.py 中run()的videos參數(shù)與調(diào)度邏輯Gemini 視頻接入libs/agno/agno/models/google/gemini.py 中視頻消息格式化與文件上傳邏輯。【免費下載鏈接】agnoBuild, run, and manage agent platforms.項目地址: https://gitcode.com/GitHub_Trending/ag/agno創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考