用 Agno 实现图片结构化提取：从视觉输入到类型化 Pydantic 对象

用 Agno 实现图片结构化提取从视觉输入到类型化 Pydantic 对象【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno导读本文围绕 agno 开源仓库中 cookbook/data_labeling/_07_image_extraction/ 这一数据标注工作流讲解如何把图片输入转化为由你自定义 Schema 约束的类型化对象——包括场景属性描述、逐字段置信度标注以及招牌/小票/商品标签上的 OCR 字段抽取。读完本文你将掌握 agnoAgent的多模态输入方式、output_schema的类型化输出机制以及如何将图片提取这一原始能力应用到商品自动编目、表单预填、媒体档案元数据生成等实际标注管线中。一、什么是图片提取Image Extraction图片提取是 agno 数据标注系列工作流cookbook/data_labeling/中图像Image模态下的核心原语之一。它的核心模式是Image → typed Pydantic object图片 → 类型化 Pydantic 对象与文本提取_03_text_extraction/共享完全相同的输出形态——输入换成图片输出依然是受 Pydantic 模型约束的结构化数据。典型输出内容包括描述性属性主对象subject、场景设定setting、时间段time_of_day、主色调dominant_colors、显著物体notable_objectsOCR 字段招牌上的主文字、次级文字、配色方案等文字密集字段结构化元数据可按需组合的任意嵌套字段。该工作流位于 cookbook/data_labeling/_07_image_extraction/包含三个可直接运行的单文件示例basic.py、with_confidence.py、ocr_fields.py。每个文件都是端到端的完整脚本符合整个 data_labeling 目录每个子目录一个basic.py加若干任务变体的组织约定。与其他图像原语的分工图片提取不是唯一图像标注手段选择它之前先明确边界见目录 README只需要一个标签→ 用_06_image_classification/单标签或多标签分类需要像素区域/坐标→ 用_08_image_bounding_boxes/归一化(x, y, w, h)检测框需要可检索的结构化描述→ 先提取再入向量库用_09_image_extraction_to_vectordb/打通全链路。二、典型使用场景从原文档与仓库示例看图片提取适合以下三类高价值场景商品照片自动编目Auto-cataloging从产品图中抽取颜色、款式、类型等字段直接落入商品数据库例如basic.py的SceneSchema 所演示的属性集合。从照片预填表单字段Pre-filling form fields对小票receipt、名片business card拍照后由模型读取文字并映射进表单模板例如ocr_fields.py的SignReadingSchema。为媒体档案生成可搜索元数据Searchable metadata为图片库批量生成结构化描述后送入向量检索完整流水线见_09_image_extraction_to_vectordb/——它正是提取 → 嵌入 → 存储 → 检索的经典媒体库标注流程。三、运行环境与依赖环境准备从仓库根目录创建并激活 demo 虚拟环境见 cookbook/data_labeling/README.md./scripts/demo_setup.sh source .venvs/demo/bin/activate运行三个示例python cookbook/data_labeling/_07_image_extraction/basic.py python cookbook/data_labeling/_07_image_extraction/with_confidence.py python cookbook/data_labeling/_07_image_extraction/ocr_fields.py关键环境变量GOOGLE_API_KEY必填本目录默认使用google:gemini-3.5-flash模型它本身是多模态模型可直接接收图片输入。运行前请先通过export GOOGLE_API_KEY...配置。三个脚本内置的示例图片分别来自 agno 公共 S3 桶与 Google 示例资源README 明确说明可按需替换成你自己的图片 URL 或本地路径本地路径见下文Image类的filepath字段。四、基础用法提取类型化场景属性basic.pybasic.py 演示最小可运行的图片提取流程核心分三步定义 Schema → 配置 Agent → 传入图片执行。1. 定义输出 Schemafrom typing import List, Literal, Optional from pydantic import BaseModel, Field class Scene(BaseModel): subject: str Field(..., descriptionThe main subject of the image) setting: Literal[indoor, outdoor, studio, unknown] time_of_day: Optional[Literal[day, night, dawn_or_dusk]] None dominant_colors: List[str] Field( default_factorylist, descriptionTwo to four named colors ) notable_objects: List[str] Field( default_factorylist, descriptionUp to five named objects in the scene )Schema 设计的几个关键点Literal枚举字段如setting、time_of_day把模型输出限制在封闭集合内天然防止越界值也便于下游直接做枚举映射或过滤Optional字段允许模型在无法从图片确定时输出null配合指令约束实现优雅降级Field(..., description...)描述会随 Schema 一起传递给模型是引导提取质量的重要手段——例如Two to four named colors、Up to five named objects直接规定了数量范围。2. 配置 Agentfrom agno.agent import Agent, RunOutput instructions \ Describe the image as a structured Scene. Be concrete and observational. If a field is not determinable from the image, leave it null or empty. agent Agent( modelgoogle:gemini-3.5-flash, instructionsinstructions, output_schemaScene, )要点output_schema参数接受Type[BaseModel]或Dict[str, Any]见 libs/agno/agno/agent/agent.pyAgent 会把模型的非结构化输出强制规整为指定的 Pydantic 对象实现类型化输出指令instructions与 Schema 描述协同Schema 定义是什么指令定义怎么判断——例如不确定就置空这一行为完全由指令驱动。3. 传入图片并执行from agno.media import Image url https://agno-public.s3.amazonaws.com/images/krakow_mariacki.jpg run: RunOutput agent.run(Extract the scene attributes., images[Image(urlurl)]) pprint({url: url, result: run.content})Image是 agno 统一的图片载体类定义于 libs/agno/agno/media/media.py三种内容来源三选一同时提供多个会触发校验错误字段含义示例url远程图片地址Image(urlhttps://...jpg)filepath本地图片路径Image(filepath./photo.jpg)content原始图片字节自动归一化为 bytesImage(contentimg_bytes)此外还支持detail图片理解精细度如low/high、id追踪引用、format/mime_type、metadata等元数据字段。运行时通过agent.run(..., images[Image(...)])把图片列表传入任务提示词Extract the scene attributes.则说明要对图片做什么。返回的RunOutput.content即为填充好的Scene实例。五、进阶变体一逐字段置信度标注with_confidence.py当输入图片质量参差不齐低分辨率、运动模糊、部分遮挡时单一的结构化输出不足以支撑下游决策——你还需要知道每个字段的可信程度以便把不确定字段送入人工复核。with_confidence.py 用两层 Pydantic 模型解决这个问题Confidence Literal[high, medium, low] class ConfidentStr(BaseModel): value: Optional[str] None confidence: Confidence class ConfidentList(BaseModel): values: List[str] Field(default_factorylist) confidence: Confidence class Scene(BaseModel): subject: ConfidentStr setting: ConfidentStr time_of_day: ConfidentStr dominant_colors: ConfidentList notable_objects: ConfidentList核心设计把每个字段从裸值包装成值 置信度复合对象ConfidentStr对应单值字段ConfidentList对应列表字段。指令中给出了明确的置信度判定标准- high - clearly determinable from the image - medium - inferred but well-supported - low - guessed or partially obscured Be conservative. If you cannot see a field, mark its value null and confidence low.保守原则是关键看不到的字段值置null、置信度标low而不是强行猜测。这种值 置信度的输出形态让下游可以按置信度分级处理——例如low字段自动路由到人工复核队列与 data_labeling 系列中_18_quality_reviewlabeler → reviewer → adjudicator的人机协作理念一脉相承。运行示例使用 Google 示例图片https://www.gstatic.com/webp/gallery/1.jpg。六、进阶变体二OCR 字段抽取ocr_fields.py当图片中的核心信息是文字本身招牌、菜单、小票、名片时ocr_fields.py 展示了如何让模型读图并映射进类型化 Schemaclass SignReading(BaseModel): primary_text: Optional[str] Field( None, descriptionThe main word or phrase shown on the sign ) secondary_text: List[str] Field( default_factorylist, descriptionAny additional words shown, in reading order, ) color_scheme: Optional[str] Field( None, descriptionDominant colors used on the sign, comma separated )对应的指令对忠实读取提出了严格要求Read the text on the sign in the image. Return what is literally written - do not translate, expand, or paraphrase. If the sign is partly obscured, include what is legible and leave the rest null.这里的关键约束是禁止翻译、扩写或改写——OCR 场景要求返回字面上写了什么而不是模型理解的大意。secondary_text要求按阅读顺序in reading order返回附加文字primary_text可空以容纳部分遮挡的情况。运行示例使用https://agno-public.s3.us-east-1.amazonaws.com/images/agno-intro.png。这个变体可直接推广到小票金额/日期/商户名抽取、名片姓名/职位/联系方式抽取、菜单条目结构化等 OCR 标注任务。七、模式总结与下一步三个示例共同构成了图片提取的完整方法论变体文件输出形态解决的核心问题基础提取basic.py纯属性Scene图片 → 结构化描述置信度提取with_confidence.py值 置信度high/medium/low低质输入下的不确定字段标记OCR 字段ocr_fields.py文字字段SignReading图片文字的忠实读取与结构化贯穿始终的三个设计原则Schema 即契约用 Pydantic 的Literal/Optional/Field(description)精确约束输出空间让模型行为可预期指令补足判断规则Schema 定义结构instructions 定义如何判断两者缺一不可确定性优先不确定就置空/标 low而不是编造保证标注数据的可审计性。若你需要把提取结果真正用于检索直接衔接_09_image_extraction_to_vectordb/先由 Agent 提取结构化ImageDescription拍平为可检索字符串用GeminiEmbedder嵌入存入 LanceDb需先pip install lancedb即可实现按自然语言查询的媒体库搜索。至此图片提取从一个单步能力扩展为完整的媒体归档与检索流水线。参考文件索引工作流入口cookbook/data_labeling/_07_image_extraction/README.md示例代码basic.py、with_confidence.py、ocr_fields.py系列总览cookbook/data_labeling/README.md关联工作流_06_image_classification/、_08_image_bounding_boxes/、_09_image_extraction_to_vectordb/底层实现Image 图片载体类、output_schema参数定义【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考