基于 Agno 的圖像分類 Agent 實戰單標簽與多標簽結構化輸出【免費下載鏈接】agnoBuild, run, and manage agent platforms.項目地址: https://gitcode.com/GitHub_Trending/ag/agno本篇技術指南以 agno 倉庫中 cookbook/data_labeling/_06_image_classification 的示例與測試日志為骨架完整講解如何用 Agno Agent 對圖像做封閉標簽集分類basic.py輸出單一標簽multilabel.py輸出標簽子集。讀完本文你將掌握Image圖像輸入、Pydantic 結構化output_schema、RunOutput結果消費這一整套最小可復用的圖像分類管線并能直接套用到內容路由、媒體庫預打標、質量/NSFW 前置門禁等真實標注場景。一、示例與測試概覽該目錄下共包含兩個獨立示例與一份測試日志文件分類形態輸出模式basic.py單標簽分類Single-labelLiteral[...]單字段multilabel.py多標簽打標Multi-labelList[Literal[...]]標簽子集TEST_LOG.md測試記錄—根據測試日志兩個腳本于 2026-07-18 在 agno 2.7.4 環境下針對google:gemini-3.5-flash模型驗證全部通過PASS。整個示例的定位正如 README.md 所述輸入是圖像輸出是封閉集合中的一個或多個標簽與文本分類完全同構因此是圖像數據標注流水線中門檻最低、最易上手的第一個 primitive。二、核心原理圖像輸入 結構化輸出在深入兩個腳本之前先厘清支撐它們的三塊底層能力均可在 libs/agno/agno 源碼中得到印證。2.1Image圖像輸入類兩個腳本都通過from agno.media import Image引入圖像輸入。Image類定義于 libs/agno/agno/media/media.py其核心內容字段三選一且僅能選一字段類型說明urlOptional[str]遠程圖片地址如https://.../image.jpgfilepathOptional[Union[Path, str]]本地圖片路徑contentOptional[bytes]原始圖片字節統一規范為 bytes其余為元數據與輸入/輸出增強字段id跟蹤引用、format如 png/jpeg/webp、mime_type如 image/png、detail遵循 OpenAI vision 規范的 low/medium/high/auto 分辨率檔位、original_prompt/revised_prompt/alt_text輸出側字段以及media_reference媒體落盤到對象存儲后的引用。值得注意的實現細節Image的model_validatormedia.py#L213-L240會強制校驗url、filepath、content三者中恰好一個被提供——零個或超過一個都會拋出ValueError——并在未指定時自動生成id。這意味著Image(url...)與Image(filepath...)在 API 層面對調用方完全對稱本地文件與遠程 URL 可以無縫互換。此外get_content_bytes()等方法支持從 URL/文件惰性加載字節便于做 base64 傳輸或二次處理。2.2output_schema結構化輸出兩個腳本均以 PydanticBaseModel定義輸出模式并通過Agent(..., output_schema...)約束模型輸出。output_schema是 Agent 構造參數之一見 agent.py#L306類型為Optional[Union[Type[BaseModel], Dict[str, Any]]]即既可以傳 Pydantic 模型類也可以傳 dict schema。它的作用是把模型輸出嚴格解析為定義好的結構basic.py 期望得到含label字段的Classification對象multilabel.py 期望得到含tags列表的Tagging對象測試日志中每次運行都返回了validated通過校驗的結構化對象。2.3RunOutput結果載體agent.run(...)返回的RunOutput定義于 libs/agno/agno/run/agent.py其中content核心結果即按output_schema解析出的 Pydantic 對象此處為Classification/Tagging其他字段如run_id、session_id、messages、metrics、model、images、followups等用于追蹤一次運行的完整上下文。示例腳本中pprint({url: url, result: run.content})正是把輸入圖片 URL 結構化分類結果成對打印便于逐圖核對標注質量。三、單標簽分類basic.py 全解析basic.py 演示給一張圖片分配一個封閉集合中的標簽這一最基礎原語。3.1 輸出模式定義from typing import Literal from pydantic import BaseModel, Field class Classification(BaseModel): label: Literal[wildlife, landscape, sports, architecture, other] Field( ..., descriptionThe primary scene type of the image )Literal[wildlife, landscape, sports, architecture, other]定義了 5 個候選場景類型Field(..., description...)為模型補充語義提示。這是典型的**封閉標簽集closed-set**約束模型只能輸出這 5 個取值之一天然規避了自由文本分類的拼寫漂移問題。3.2 Agent 配置與運行from agno.agent import Agent, RunOutput from agno.media import Image agent Agent( modelgoogle:gemini-3.5-flash, instructionsYou classify images by scene type., output_schemaClassification, ) samples [ https://storage.googleapis.com/generativeai-downloads/images/generated_elephants_giraffes_zebras_sunset.jpg, https://www.gstatic.com/webp/gallery/1.jpg, https://www.gstatic.com/webp/gallery/2.jpg, https://agno-public.s3.amazonaws.com/images/krakow_mariacki.jpg, ] for url in samples: run: RunOutput agent.run(Classify this image., images[Image(urlurl)]) pprint({url: url, result: run.content})關鍵點images[Image(urlurl)]以列表形式傳入圖像可多圖Image(url...)直接消費遠程 URLagent.run(Classify this image., ...)消息文本 圖像共同構成多模態輸入示例圖片來自 Google 生成式 AI 示例資源、gstatic webp 畫廊以及 agno 公共 S3 桶均為穩定公共 URL無需本地數據即可復現。3.3 測試日志四張圖片全部命中預期按 TEST_LOG.md 記錄basic.py 對四張圖片的實測結果為輸入圖片預期/實際標簽elephants/giraffes/zebras sunsetGoogle 野生動物示例wildlifegstatic gallery/1.jpglandscapegstatic gallery/2.jpgsportskrakow_mariacki.jpgagno-public 克拉科夫教堂architecture四張圖片全部按預期分類每次運行均返回通過校驗的Classification對象單圖延遲 1.2–3.2 秒測試日志觀測值隨模型與網絡波動。這說明Literal約束在真實多模態輸入下表現穩定——尤其是other兜底標簽的存在為五種場景之外的圖片留出了出口避免模型被強制塞入錯誤類別。四、多標簽分類multilabel.py 全解析multilabel.py 演示給一張圖片分配 N 個標簽中的任意子集適用于場景打標與內容歸類。4.1 輸出模式與指令設計from typing import List, Literal from pydantic import BaseModel, Field SceneTag Literal[ outdoor, indoor, daytime, nighttime, people, vehicle, nature, architecture, ] class Tagging(BaseModel): tags: List[SceneTag] Field( ..., descriptionAll scene tags that apply; empty if none )與單標簽的關鍵差異輸出類型從Literal[...]變為List[Literal[...]]——允許多個標簽同時命中8 個候選標簽覆蓋了場景outdoor/indoor、時間daytime/nighttime、內容people/vehicle/nature/architecture四個維度形成正交的標簽空間tags字段描述明確All scene tags that apply; empty if none允許空列表為無標簽圖片留出合法輸出。指令部分同樣精心設計instructions \ Tag the image with every scene attribute that clearly applies. Include a tag only if it is unambiguously present in the image - skip tags that are inferred or implied. 只打圖中明確存在、無可爭議的標簽跳過推斷或暗示的標簽——這條指令直接決定多標簽結果的精確率precision寧可少打不可誤打與Any subset of N tags的語義嚴格對齊。4.2 Agent 配置與運行agent Agent( modelgoogle:gemini-3.5-flash, instructionsinstructions, output_schemaTagging, ) samples [ https://agno-public.s3.amazonaws.com/images/krakow_mariacki.jpg, https://storage.googleapis.com/generativeai-downloads/images/generated_elephants_giraffes_zebras_sunset.jpg, ] for url in samples: run: RunOutput agent.run(Tag this image., images[Image(urlurl)]) pprint({url: url, result: run.content})復用 basic.py 中的克拉科夫教堂與野生動物兩張圖片但把任務從分類切換為打標。4.3 測試日志標簽子集語義自洽按 TEST_LOG.md 記錄輸入圖片實際標簽子集krakow_mariacki.jpg[outdoor, nighttime, architecture]elephants/giraffes/zebras sunset[outdoor, daytime, nature]兩組標簽均與圖片內容一致且語義自洽克拉科夫教堂夜景命中了outdoor、nighttime、architecture而沒有誤打people或vehicle野生動物黃昏圖命中了outdoor、daytime、nature而未打architecture。每次運行均返回通過校驗的Tagging對象單圖延遲 2.8–5.6 秒測試日志觀測值。多標簽結果比單標簽消耗略高的推理時長符合候選空間更大、需要逐項判定的直覺。五、運行方式與環境要求按 README.md 說明從倉庫根目錄直接運行python cookbook/data_labeling/_06_image_classification/basic.py python cookbook/data_labeling/_06_image_classification/multilabel.py運行前提GOOGLE_API_KEY環境變量示例使用google:gemini-3.5-flash需配置有效的 Google Gemini API Key依賴agno示例測試于 2.7.4、pydantic、rich用于pprint美化輸出示例圖片使用穩定公共 URLGoogle 示例資源與 agno 公共 S3 桶無需預先下載圖片如網絡受限或需要處理自有數據將Image(urlurl)替換為Image(filepath本地路徑)即可——這正是Image類 url/filepath/content 三源互斥設計的實戰價值見 media.py#L213-L240 的強制校驗邏輯。六、應用場景與擴展方向README.md 明確列出該 primitivem 的典型落地場景路由用戶上傳圖片按內容類型wildlife/landscape/sports/architecture…分流到不同處理管線媒體庫入庫前預打標批量生成粗標簽供人工精修顯著降低全人工標注成本質量/NSFW 前置門禁在數據入庫前用封閉標簽做內容合規初篩。需要特別指出的邊界如果目標是從圖像中抽取結構化字段如顏色、品牌、圖中文字而非輸出標簽則應使用 cookbook/data_labeling/_07_image_extraction/ 的圖像抽取示例——這是 README 明確給出的路線選擇建議避免把分類與抽取兩類任務混為一談。七、小結通過_06_image_classification的兩個示例與測試日志可以歸納出一條可復用的 Agno 圖像分類范式定義封閉標簽集單標簽用Literal[...]多標簽用List[Literal[...]]配合Field描述約束語義配置多模態 Agentmodelgoogle:gemini-3.5-flash 明確的instructionsoutput_schema以Image(url...)或Image(filepath...)傳入圖像調用agent.run()從RunOutput.content消費結構化結果逐圖核對標注質量。測試日志驗證了該范式在 agno 2.7.4 gemini-3.5-flash 下的可用性單標簽四圖全中、多標簽語義自洽且輸出均通過 Pydantic 校驗。讀者可在此基礎上替換自有標簽集與圖片數據快速構建面向生產的數據標注 Agent。進一步學習完整的圖像數據標注系列位于 cookbook/data_labeling/其中_07_image_extraction提供圖像字段抽取、_17_llm_as_judge提供以 LLM 評判標注質量的能力可與本文的分類原語組合成更完整的標注流水線。【免費下載鏈接】agnoBuild, run, and manage agent platforms.項目地址: https://gitcode.com/GitHub_Trending/ag/agno創作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考 基于 Agno 的圖像分類 Agent 實戰：單標簽與多標簽結構化輸出
基于 Agno 的圖像分類 Agent 實戰單標簽與多標簽結構化輸出【免費下載鏈接】agnoBuild, run, and manage agent platforms.項目地址: https://gitcode.com/GitHub_Trending/ag/agno本篇技術指南以 agno 倉庫中 cookbook/data_labeling/_06_image_classification 的示例與測試日志為骨架完整講解如何用 Agno Agent 對圖像做封閉標簽集分類basic.py輸出單一標簽multilabel.py輸出標簽子集。讀完本文你將掌握Image圖像輸入、Pydantic 結構化output_schema、RunOutput結果消費這一整套最小可復用的圖像分類管線并能直接套用到內容路由、媒體庫預打標、質量/NSFW 前置門禁等真實標注場景。一、示例與測試概覽該目錄下共包含兩個獨立示例與一份測試日志文件分類形態輸出模式basic.py單標簽分類Single-labelLiteral[...]單字段multilabel.py多標簽打標Multi-labelList[Literal[...]]標簽子集TEST_LOG.md測試記錄—根據測試日志兩個腳本于 2026-07-18 在 agno 2.7.4 環境下針對google:gemini-3.5-flash模型驗證全部通過PASS。整個示例的定位正如 README.md 所述輸入是圖像輸出是封閉集合中的一個或多個標簽與文本分類完全同構因此是圖像數據標注流水線中門檻最低、最易上手的第一個 primitive。二、核心原理圖像輸入 結構化輸出在深入兩個腳本之前先厘清支撐它們的三塊底層能力均可在 libs/agno/agno 源碼中得到印證。2.1Image圖像輸入類兩個腳本都通過from agno.media import Image引入圖像輸入。Image類定義于 libs/agno/agno/media/media.py其核心內容字段三選一且僅能選一字段類型說明urlOptional[str]遠程圖片地址如https://.../image.jpgfilepathOptional[Union[Path, str]]本地圖片路徑contentOptional[bytes]原始圖片字節統一規范為 bytes其余為元數據與輸入/輸出增強字段id跟蹤引用、format如 png/jpeg/webp、mime_type如 image/png、detail遵循 OpenAI vision 規范的 low/medium/high/auto 分辨率檔位、original_prompt/revised_prompt/alt_text輸出側字段以及media_reference媒體落盤到對象存儲后的引用。值得注意的實現細節Image的model_validatormedia.py#L213-L240會強制校驗url、filepath、content三者中恰好一個被提供——零個或超過一個都會拋出ValueError——并在未指定時自動生成id。這意味著Image(url...)與Image(filepath...)在 API 層面對調用方完全對稱本地文件與遠程 URL 可以無縫互換。此外get_content_bytes()等方法支持從 URL/文件惰性加載字節便于做 base64 傳輸或二次處理。2.2output_schema結構化輸出兩個腳本均以 PydanticBaseModel定義輸出模式并通過Agent(..., output_schema...)約束模型輸出。output_schema是 Agent 構造參數之一見 agent.py#L306類型為Optional[Union[Type[BaseModel], Dict[str, Any]]]即既可以傳 Pydantic 模型類也可以傳 dict schema。它的作用是把模型輸出嚴格解析為定義好的結構basic.py 期望得到含label字段的Classification對象multilabel.py 期望得到含tags列表的Tagging對象測試日志中每次運行都返回了validated通過校驗的結構化對象。2.3RunOutput結果載體agent.run(...)返回的RunOutput定義于 libs/agno/agno/run/agent.py其中content核心結果即按output_schema解析出的 Pydantic 對象此處為Classification/Tagging其他字段如run_id、session_id、messages、metrics、model、images、followups等用于追蹤一次運行的完整上下文。示例腳本中pprint({url: url, result: run.content})正是把輸入圖片 URL 結構化分類結果成對打印便于逐圖核對標注質量。三、單標簽分類basic.py 全解析basic.py 演示給一張圖片分配一個封閉集合中的標簽這一最基礎原語。3.1 輸出模式定義from typing import Literal from pydantic import BaseModel, Field class Classification(BaseModel): label: Literal[wildlife, landscape, sports, architecture, other] Field( ..., descriptionThe primary scene type of the image )Literal[wildlife, landscape, sports, architecture, other]定義了 5 個候選場景類型Field(..., description...)為模型補充語義提示。這是典型的**封閉標簽集closed-set**約束模型只能輸出這 5 個取值之一天然規避了自由文本分類的拼寫漂移問題。3.2 Agent 配置與運行from agno.agent import Agent, RunOutput from agno.media import Image agent Agent( modelgoogle:gemini-3.5-flash, instructionsYou classify images by scene type., output_schemaClassification, ) samples [ https://storage.googleapis.com/generativeai-downloads/images/generated_elephants_giraffes_zebras_sunset.jpg, https://www.gstatic.com/webp/gallery/1.jpg, https://www.gstatic.com/webp/gallery/2.jpg, https://agno-public.s3.amazonaws.com/images/krakow_mariacki.jpg, ] for url in samples: run: RunOutput agent.run(Classify this image., images[Image(urlurl)]) pprint({url: url, result: run.content})關鍵點images[Image(urlurl)]以列表形式傳入圖像可多圖Image(url...)直接消費遠程 URLagent.run(Classify this image., ...)消息文本 圖像共同構成多模態輸入示例圖片來自 Google 生成式 AI 示例資源、gstatic webp 畫廊以及 agno 公共 S3 桶均為穩定公共 URL無需本地數據即可復現。3.3 測試日志四張圖片全部命中預期按 TEST_LOG.md 記錄basic.py 對四張圖片的實測結果為輸入圖片預期/實際標簽elephants/giraffes/zebras sunsetGoogle 野生動物示例wildlifegstatic gallery/1.jpglandscapegstatic gallery/2.jpgsportskrakow_mariacki.jpgagno-public 克拉科夫教堂architecture四張圖片全部按預期分類每次運行均返回通過校驗的Classification對象單圖延遲 1.2–3.2 秒測試日志觀測值隨模型與網絡波動。這說明Literal約束在真實多模態輸入下表現穩定——尤其是other兜底標簽的存在為五種場景之外的圖片留出了出口避免模型被強制塞入錯誤類別。四、多標簽分類multilabel.py 全解析multilabel.py 演示給一張圖片分配 N 個標簽中的任意子集適用于場景打標與內容歸類。4.1 輸出模式與指令設計from typing import List, Literal from pydantic import BaseModel, Field SceneTag Literal[ outdoor, indoor, daytime, nighttime, people, vehicle, nature, architecture, ] class Tagging(BaseModel): tags: List[SceneTag] Field( ..., descriptionAll scene tags that apply; empty if none )與單標簽的關鍵差異輸出類型從Literal[...]變為List[Literal[...]]——允許多個標簽同時命中8 個候選標簽覆蓋了場景outdoor/indoor、時間daytime/nighttime、內容people/vehicle/nature/architecture四個維度形成正交的標簽空間tags字段描述明確All scene tags that apply; empty if none允許空列表為無標簽圖片留出合法輸出。指令部分同樣精心設計instructions \ Tag the image with every scene attribute that clearly applies. Include a tag only if it is unambiguously present in the image - skip tags that are inferred or implied. 只打圖中明確存在、無可爭議的標簽跳過推斷或暗示的標簽——這條指令直接決定多標簽結果的精確率precision寧可少打不可誤打與Any subset of N tags的語義嚴格對齊。4.2 Agent 配置與運行agent Agent( modelgoogle:gemini-3.5-flash, instructionsinstructions, output_schemaTagging, ) samples [ https://agno-public.s3.amazonaws.com/images/krakow_mariacki.jpg, https://storage.googleapis.com/generativeai-downloads/images/generated_elephants_giraffes_zebras_sunset.jpg, ] for url in samples: run: RunOutput agent.run(Tag this image., images[Image(urlurl)]) pprint({url: url, result: run.content})復用 basic.py 中的克拉科夫教堂與野生動物兩張圖片但把任務從分類切換為打標。4.3 測試日志標簽子集語義自洽按 TEST_LOG.md 記錄輸入圖片實際標簽子集krakow_mariacki.jpg[outdoor, nighttime, architecture]elephants/giraffes/zebras sunset[outdoor, daytime, nature]兩組標簽均與圖片內容一致且語義自洽克拉科夫教堂夜景命中了outdoor、nighttime、architecture而沒有誤打people或vehicle野生動物黃昏圖命中了outdoor、daytime、nature而未打architecture。每次運行均返回通過校驗的Tagging對象單圖延遲 2.8–5.6 秒測試日志觀測值。多標簽結果比單標簽消耗略高的推理時長符合候選空間更大、需要逐項判定的直覺。五、運行方式與環境要求按 README.md 說明從倉庫根目錄直接運行python cookbook/data_labeling/_06_image_classification/basic.py python cookbook/data_labeling/_06_image_classification/multilabel.py運行前提GOOGLE_API_KEY環境變量示例使用google:gemini-3.5-flash需配置有效的 Google Gemini API Key依賴agno示例測試于 2.7.4、pydantic、rich用于pprint美化輸出示例圖片使用穩定公共 URLGoogle 示例資源與 agno 公共 S3 桶無需預先下載圖片如網絡受限或需要處理自有數據將Image(urlurl)替換為Image(filepath本地路徑)即可——這正是Image類 url/filepath/content 三源互斥設計的實戰價值見 media.py#L213-L240 的強制校驗邏輯。六、應用場景與擴展方向README.md 明確列出該 primitivem 的典型落地場景路由用戶上傳圖片按內容類型wildlife/landscape/sports/architecture…分流到不同處理管線媒體庫入庫前預打標批量生成粗標簽供人工精修顯著降低全人工標注成本質量/NSFW 前置門禁在數據入庫前用封閉標簽做內容合規初篩。需要特別指出的邊界如果目標是從圖像中抽取結構化字段如顏色、品牌、圖中文字而非輸出標簽則應使用 cookbook/data_labeling/_07_image_extraction/ 的圖像抽取示例——這是 README 明確給出的路線選擇建議避免把分類與抽取兩類任務混為一談。七、小結通過_06_image_classification的兩個示例與測試日志可以歸納出一條可復用的 Agno 圖像分類范式定義封閉標簽集單標簽用Literal[...]多標簽用List[Literal[...]]配合Field描述約束語義配置多模態 Agentmodelgoogle:gemini-3.5-flash 明確的instructionsoutput_schema以Image(url...)或Image(filepath...)傳入圖像調用agent.run()從RunOutput.content消費結構化結果逐圖核對標注質量。測試日志驗證了該范式在 agno 2.7.4 gemini-3.5-flash 下的可用性單標簽四圖全中、多標簽語義自洽且輸出均通過 Pydantic 校驗。讀者可在此基礎上替換自有標簽集與圖片數據快速構建面向生產的數據標注 Agent。進一步學習完整的圖像數據標注系列位于 cookbook/data_labeling/其中_07_image_extraction提供圖像字段抽取、_17_llm_as_judge提供以 LLM 評判標注質量的能力可與本文的分類原語組合成更完整的標注流水線。【免費下載鏈接】agnoBuild, run, and manage agent platforms.項目地址: https://gitcode.com/GitHub_Trending/ag/agno創作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考