agno 图像标注到向量数据库用 Agent 抽取结构化描述并构建可搜索媒体库的完整管线【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno导读本文以 agno cookbook 中的_09_image_extraction_to_vectordb示例为骨架完整讲解图像标注 → 向量化 → 检索的端到端管线一个 Agent 从图片 URL 中抽取结构化ImageDescription主体、场景、氛围、关键物体把结构化字段展平为可搜索文本再用GeminiEmbedder嵌入并写入 LanceDb最终支持用自然语言查询相似图片。读完本文你将掌握在 agno 中搭建可搜索媒体库 / 以文搜图 / 找相似类标注管线的完整实操方法与底层原理并看到该管线在真实环境中的测试验证结果。该示例位于 cookbook/data_labeling/_09_image_extraction_to_vectordb核心实现文件为 basic.py配套说明见 README.md。本文所有结论均依据仓库中的文档与源码。一、示例定位一条完整而非片段化的标注工作流在 agno 的 data_labeling 系列 cookbook 中_09_image_extraction_to_vectordb的价值恰恰在于它是完整的端到端管线而不是某一个环节的单独演示。README 明确指出basic.py把extract → embed → store → search四个步骤浓缩在一个文件里没有额外变体价值在于完整管线本身。管线的四个环节对每张图片 URL用一个 Agent 抽取结构化的ImageDescriptionsubject 主体、setting 场景、mood 氛围、key_objects 关键物体将结构化字段展平为单条可搜索文本用GeminiEmbedder对文本做嵌入存入 LanceDb用自然语言查询检索索引返回最相似的图片。值得强调的一点README 中专门提醒该检索作用于抽取出的文本描述而非图像本身的嵌入——两张图片匹配是因为它们的描述文本匹配。这决定了它适合的落地场景用自然语言查询搜索图库stock photo library按描述相似度对商品目录去重注意去重依据是抽取出的文本描述在用户上传的媒体上构建find more like this找相似功能。二、快速运行环境准备与执行命令运行该示例只需要两步来自 README.mdpip install lancedb python cookbook/data_labeling/_09_image_extraction_to_vectordb/basic.py运行前提与产物API Key需要GOOGLE_API_KEY环境变量。在源码层面GeminiEmbedder 在构建客户端时通过getenv(GOOGLE_API_KEY)读取该变量未设置时会记录错误日志GOOGLE_API_KEY not set。此外也可通过GOOGLE_GENAI_USE_VERTEXAItrue切换到 Vertex AI 方式此时读取GOOGLE_CLOUD_PROJECT与GOOGLE_CLOUD_LOCATION。数据目录运行会写入仓库根目录下的tmp/lancedb/。LanceDb 默认uri/tmp/lancedb示例显式传入uritmp/lancedb相对路径落在仓库根。可选依赖说明TEST_LOG 实测确认未安装tantivy也能正常运行——因为本例只使用SearchType.vector向量检索关键字检索引擎tantivy仅在 keyword/hybrid 检索时需要。三、核心代码逐段拆解basic.py3.1 结构化输出 SchemaImageDescription抽取 Agent 的输出不是自由文本而是一个 Pydantic 模型四个字段各带描述basic.pyclass ImageDescription(BaseModel): subject: str Field(..., descriptionThe main subject of the image) setting: str Field(..., descriptionWhere the image takes place) mood: str Field(..., descriptionOverall mood or tone) key_objects: List[str] Field( default_factorylist, descriptionUp to five notable objects )subject图片主体setting图片发生场景/地点mood整体氛围或基调key_objects最多五个值得注意的物体默认空列表。用 Pydantic 模型做output_schema是 agno 结构化输出的标准做法——模型必须按该 Schema 返回才能被后续步骤可靠地展平与入库。3.2 抽取 Agentextractor Agent( modelgoogle:gemini-3.5-flash, instructionsYou describe images as structured, search-friendly metadata., output_schemaImageDescription, )模型使用google:gemini-3.5-flash指令明确要求把图片描述成结构化、便于搜索的元数据——提示词与 Schema 双管齐下确保输出是搜索友好的元数据而非散文output_schemaImageDescription让每次run的.content直接是ImageDescription实例。3.3 向量数据库LanceDb GeminiEmbeddervector_db LanceDb( uritmp/lancedb, table_namedata_labeling_images, search_typeSearchType.vector, embedderGeminiEmbedder(idgemini-embedding-001), )对应 agno 的 LanceDb 实现关键点uriLanceDB 数据库位置示例用本地相对路径table_name表名data_labeling_images表已存在时打开不存在则后续创建search_type取自 agno.vectordb.search.SearchType可选vector向量检索本例所用、keyword关键字检索、hybrid混合检索embedder默认值为OpenAIEmbedder源码中未传时会回退并打印提示本例显式指定GeminiEmbedder(idgemini-embedding-001)其他可配置项源码可见便于按需扩展distance默认Distance.cosine余弦距离、nprobes检索探针数、reranker重排器、on_bad_vectors坏向量处理策略error/drop/fill/null与fill_value。GeminiEmbedder 的关键默认值模型idgemini-embedding-001task_typeRETRIEVAL_QUERYdimensions1536并支持通过request_params/client_params透传额外参数。嵌入请求通过 Google GenAI 客户端的models.embed_content完成google.pyoutput_dimensionality与task_type均会随请求发送。值得注意LanceDb 构造时会校验Embedder.dimensions必须已设置否则抛ValueErrorlance_db.py——GeminiEmbedder默认dimensions1536满足此约束。3.4 管线函数describe / to_searchable_text / index_images三个函数共同构成管线主体basic.pydef describe(url: str) - ImageDescription: return extractor.run(Describe this image., images[Image(urlurl)]).content def to_searchable_text(d: ImageDescription) - str: return ( fSubject: {d.subject}. Setting: {d.setting}. Mood: {d.mood}. fObjects: {, .join(d.key_objects)}. ) def index_images(urls: List[str]) - None: vector_db.create() docs: List[Document] [] for url in urls: description describe(url) docs.append( Document( nameurl, contentto_searchable_text(description), meta_data{url: url, subject: description.subject}, ) ) vector_db.insert(content_hashimage_batch_1, documentsdocs)describe把图片 URL 包装为agno.media.Image(urlurl)随提示词一起交给 Agent返回结构化描述to_searchable_text把四个字段拼接成单一可检索文本——这是把结构化输出变成可搜索文本的关键一步也是 README 强调检索作用于文本描述的直接体现index_images先vector_db.create()建表再对每张图抽取、构造Documentname用图片 URLcontent用展平文本meta_data附带 url 与 subject 便于检索后回看元信息最后以content_hashimage_batch_1为批次标识整体插入。Document对应 agno/knowledge/document/base.py 中的核心数据结构。3.5 主流程三张示例图 两条自然语言查询if __name__ __main__: urls [ https://agno-public.s3.amazonaws.com/images/krakow_mariacki.jpg, https://www.gstatic.com/webp/gallery/1.jpg, https://storage.googleapis.com/generativeai-downloads/images/generated_elephants_giraffes_zebras_sunset.jpg, ] index_images(urls) for query in [a historic city at night, wildlife on the savanna]: results vector_db.search(query, limit2) pprint({query: query, hits: [r.meta_data for r in results]})三张图片克拉科夫圣母圣殿城市夜景主题、gstatic 图库样例、大象/长颈鹿/斑马/鳄鱼汇聚水塘的野生动物场景vector_db.search(query, limit2)以自然语言查询向量索引返回前 2 条命中结果打印各命中的meta_data含 url 与 subject方便对照。四、实测验证TEST_LOG 的端到端结果仓库中的 TEST_LOG.md 记录了 2026-07-18 在gemini-3.5-flashgemini-embedding-001embedder、agno 2.7.4 环境下的实测结论可作为该管线的可信度佐证运行方式删除tmp/lancedb/后从干净状态跑完整管线抽取质量三张图全部成功产出结构规整的输出。例如克拉科夫图得到 subject St. Marys Basilica framed by the arches of the Cloth Hall圣玛丽大教堂与纺织会馆拱门同框、mood Magical and serene魔幻而宁静野生动物图得到 subject A diverse group of African wildlife, including elephants, giraffes, zebras, and a crocodile, gathered at a watering hole多种非洲野生动物汇聚水塘写入结果3 条文档成功插入检索正确性查询 a historic city at night 命中克拉科夫圣母圣殿查询 wildlife on the savanna 命中大象/长颈鹿/斑马场景——两条查询均返回语义正确的最相似图片性能参考单张图片抽取耗时约 2.7–4.8 秒该值依赖模型与网络仅作参考不作为普遍性能承诺环境边界未安装tantivy也能跑通再次印证向量检索不依赖关键字引擎。五、从源码看底层工作方式为什么这条管线成立结构化输出的可靠性output_schema 指令双约束使 Agent 的输出稳定落在ImageDescription上从而可以机械地展平为检索文本——这是后续一切的前提。嵌入与维度一致性GeminiEmbedder固定输出 1536 维dimensions默认值LanceDb 构造时校验embedder.dimensions已设置lance_db.py保证建表时向量维度与嵌入结果一致检索默认使用余弦距离Distance.cosine。文本检索而非图像检索整个流程中 LanceDb 存的是描述文本的嵌入查询时search(query)内部同样先对查询文本做嵌入再比对。因此召回质量取决于抽取出的描述质量——这也解释了为何指令要强调search-friendly metadata。可扩展配置如需混合检索可把search_type改为SearchType.hybrid此时需安装tantivy如需云上 LanceDB可传api_key或设置LANCEDB_API_KEY源码对db://开头的 Cloud URI 强制要求 API Key见 lance_db.py如需切换 Embedder直接替换embedder参数即可。六、延伸阅读同系列标注管线入口cookbook/data_labeling/README.md可对比文本、图像、音频、视频、文档等各模态的标注与抽取方案向量存储的其他后端示例cookbook/06_storageMySQL、Postgres、SQLite、Redis、Mongo 等LanceDb 源码实现在 libs/agno/agno/vectordb/lancedb/lance_db.pyEmbedder 抽象在 libs/agno/agno/knowledge/embedder/base.pyGeminiEmbedder在 libs/agno/agno/knowledge/embedder/google.py若需要构建 Agent 自身的知识检索RAG可参考 cookbook/07_knowledge 中的向量库接入方式。【免费下载链接】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 中的_09_image_extraction_to_vectordb示例为骨架完整讲解图像标注 → 向量化 → 检索的端到端管线一个 Agent 从图片 URL 中抽取结构化ImageDescription主体、场景、氛围、关键物体把结构化字段展平为可搜索文本再用GeminiEmbedder嵌入并写入 LanceDb最终支持用自然语言查询相似图片。读完本文你将掌握在 agno 中搭建可搜索媒体库 / 以文搜图 / 找相似类标注管线的完整实操方法与底层原理并看到该管线在真实环境中的测试验证结果。该示例位于 cookbook/data_labeling/_09_image_extraction_to_vectordb核心实现文件为 basic.py配套说明见 README.md。本文所有结论均依据仓库中的文档与源码。一、示例定位一条完整而非片段化的标注工作流在 agno 的 data_labeling 系列 cookbook 中_09_image_extraction_to_vectordb的价值恰恰在于它是完整的端到端管线而不是某一个环节的单独演示。README 明确指出basic.py把extract → embed → store → search四个步骤浓缩在一个文件里没有额外变体价值在于完整管线本身。管线的四个环节对每张图片 URL用一个 Agent 抽取结构化的ImageDescriptionsubject 主体、setting 场景、mood 氛围、key_objects 关键物体将结构化字段展平为单条可搜索文本用GeminiEmbedder对文本做嵌入存入 LanceDb用自然语言查询检索索引返回最相似的图片。值得强调的一点README 中专门提醒该检索作用于抽取出的文本描述而非图像本身的嵌入——两张图片匹配是因为它们的描述文本匹配。这决定了它适合的落地场景用自然语言查询搜索图库stock photo library按描述相似度对商品目录去重注意去重依据是抽取出的文本描述在用户上传的媒体上构建find more like this找相似功能。二、快速运行环境准备与执行命令运行该示例只需要两步来自 README.mdpip install lancedb python cookbook/data_labeling/_09_image_extraction_to_vectordb/basic.py运行前提与产物API Key需要GOOGLE_API_KEY环境变量。在源码层面GeminiEmbedder 在构建客户端时通过getenv(GOOGLE_API_KEY)读取该变量未设置时会记录错误日志GOOGLE_API_KEY not set。此外也可通过GOOGLE_GENAI_USE_VERTEXAItrue切换到 Vertex AI 方式此时读取GOOGLE_CLOUD_PROJECT与GOOGLE_CLOUD_LOCATION。数据目录运行会写入仓库根目录下的tmp/lancedb/。LanceDb 默认uri/tmp/lancedb示例显式传入uritmp/lancedb相对路径落在仓库根。可选依赖说明TEST_LOG 实测确认未安装tantivy也能正常运行——因为本例只使用SearchType.vector向量检索关键字检索引擎tantivy仅在 keyword/hybrid 检索时需要。三、核心代码逐段拆解basic.py3.1 结构化输出 SchemaImageDescription抽取 Agent 的输出不是自由文本而是一个 Pydantic 模型四个字段各带描述basic.pyclass ImageDescription(BaseModel): subject: str Field(..., descriptionThe main subject of the image) setting: str Field(..., descriptionWhere the image takes place) mood: str Field(..., descriptionOverall mood or tone) key_objects: List[str] Field( default_factorylist, descriptionUp to five notable objects )subject图片主体setting图片发生场景/地点mood整体氛围或基调key_objects最多五个值得注意的物体默认空列表。用 Pydantic 模型做output_schema是 agno 结构化输出的标准做法——模型必须按该 Schema 返回才能被后续步骤可靠地展平与入库。3.2 抽取 Agentextractor Agent( modelgoogle:gemini-3.5-flash, instructionsYou describe images as structured, search-friendly metadata., output_schemaImageDescription, )模型使用google:gemini-3.5-flash指令明确要求把图片描述成结构化、便于搜索的元数据——提示词与 Schema 双管齐下确保输出是搜索友好的元数据而非散文output_schemaImageDescription让每次run的.content直接是ImageDescription实例。3.3 向量数据库LanceDb GeminiEmbeddervector_db LanceDb( uritmp/lancedb, table_namedata_labeling_images, search_typeSearchType.vector, embedderGeminiEmbedder(idgemini-embedding-001), )对应 agno 的 LanceDb 实现关键点uriLanceDB 数据库位置示例用本地相对路径table_name表名data_labeling_images表已存在时打开不存在则后续创建search_type取自 agno.vectordb.search.SearchType可选vector向量检索本例所用、keyword关键字检索、hybrid混合检索embedder默认值为OpenAIEmbedder源码中未传时会回退并打印提示本例显式指定GeminiEmbedder(idgemini-embedding-001)其他可配置项源码可见便于按需扩展distance默认Distance.cosine余弦距离、nprobes检索探针数、reranker重排器、on_bad_vectors坏向量处理策略error/drop/fill/null与fill_value。GeminiEmbedder 的关键默认值模型idgemini-embedding-001task_typeRETRIEVAL_QUERYdimensions1536并支持通过request_params/client_params透传额外参数。嵌入请求通过 Google GenAI 客户端的models.embed_content完成google.pyoutput_dimensionality与task_type均会随请求发送。值得注意LanceDb 构造时会校验Embedder.dimensions必须已设置否则抛ValueErrorlance_db.py——GeminiEmbedder默认dimensions1536满足此约束。3.4 管线函数describe / to_searchable_text / index_images三个函数共同构成管线主体basic.pydef describe(url: str) - ImageDescription: return extractor.run(Describe this image., images[Image(urlurl)]).content def to_searchable_text(d: ImageDescription) - str: return ( fSubject: {d.subject}. Setting: {d.setting}. Mood: {d.mood}. fObjects: {, .join(d.key_objects)}. ) def index_images(urls: List[str]) - None: vector_db.create() docs: List[Document] [] for url in urls: description describe(url) docs.append( Document( nameurl, contentto_searchable_text(description), meta_data{url: url, subject: description.subject}, ) ) vector_db.insert(content_hashimage_batch_1, documentsdocs)describe把图片 URL 包装为agno.media.Image(urlurl)随提示词一起交给 Agent返回结构化描述to_searchable_text把四个字段拼接成单一可检索文本——这是把结构化输出变成可搜索文本的关键一步也是 README 强调检索作用于文本描述的直接体现index_images先vector_db.create()建表再对每张图抽取、构造Documentname用图片 URLcontent用展平文本meta_data附带 url 与 subject 便于检索后回看元信息最后以content_hashimage_batch_1为批次标识整体插入。Document对应 agno/knowledge/document/base.py 中的核心数据结构。3.5 主流程三张示例图 两条自然语言查询if __name__ __main__: urls [ https://agno-public.s3.amazonaws.com/images/krakow_mariacki.jpg, https://www.gstatic.com/webp/gallery/1.jpg, https://storage.googleapis.com/generativeai-downloads/images/generated_elephants_giraffes_zebras_sunset.jpg, ] index_images(urls) for query in [a historic city at night, wildlife on the savanna]: results vector_db.search(query, limit2) pprint({query: query, hits: [r.meta_data for r in results]})三张图片克拉科夫圣母圣殿城市夜景主题、gstatic 图库样例、大象/长颈鹿/斑马/鳄鱼汇聚水塘的野生动物场景vector_db.search(query, limit2)以自然语言查询向量索引返回前 2 条命中结果打印各命中的meta_data含 url 与 subject方便对照。四、实测验证TEST_LOG 的端到端结果仓库中的 TEST_LOG.md 记录了 2026-07-18 在gemini-3.5-flashgemini-embedding-001embedder、agno 2.7.4 环境下的实测结论可作为该管线的可信度佐证运行方式删除tmp/lancedb/后从干净状态跑完整管线抽取质量三张图全部成功产出结构规整的输出。例如克拉科夫图得到 subject St. Marys Basilica framed by the arches of the Cloth Hall圣玛丽大教堂与纺织会馆拱门同框、mood Magical and serene魔幻而宁静野生动物图得到 subject A diverse group of African wildlife, including elephants, giraffes, zebras, and a crocodile, gathered at a watering hole多种非洲野生动物汇聚水塘写入结果3 条文档成功插入检索正确性查询 a historic city at night 命中克拉科夫圣母圣殿查询 wildlife on the savanna 命中大象/长颈鹿/斑马场景——两条查询均返回语义正确的最相似图片性能参考单张图片抽取耗时约 2.7–4.8 秒该值依赖模型与网络仅作参考不作为普遍性能承诺环境边界未安装tantivy也能跑通再次印证向量检索不依赖关键字引擎。五、从源码看底层工作方式为什么这条管线成立结构化输出的可靠性output_schema 指令双约束使 Agent 的输出稳定落在ImageDescription上从而可以机械地展平为检索文本——这是后续一切的前提。嵌入与维度一致性GeminiEmbedder固定输出 1536 维dimensions默认值LanceDb 构造时校验embedder.dimensions已设置lance_db.py保证建表时向量维度与嵌入结果一致检索默认使用余弦距离Distance.cosine。文本检索而非图像检索整个流程中 LanceDb 存的是描述文本的嵌入查询时search(query)内部同样先对查询文本做嵌入再比对。因此召回质量取决于抽取出的描述质量——这也解释了为何指令要强调search-friendly metadata。可扩展配置如需混合检索可把search_type改为SearchType.hybrid此时需安装tantivy如需云上 LanceDB可传api_key或设置LANCEDB_API_KEY源码对db://开头的 Cloud URI 强制要求 API Key见 lance_db.py如需切换 Embedder直接替换embedder参数即可。六、延伸阅读同系列标注管线入口cookbook/data_labeling/README.md可对比文本、图像、音频、视频、文档等各模态的标注与抽取方案向量存储的其他后端示例cookbook/06_storageMySQL、Postgres、SQLite、Redis、Mongo 等LanceDb 源码实现在 libs/agno/agno/vectordb/lancedb/lance_db.pyEmbedder 抽象在 libs/agno/agno/knowledge/embedder/base.pyGeminiEmbedder在 libs/agno/agno/knowledge/embedder/google.py若需要构建 Agent 自身的知识检索RAG可参考 cookbook/07_knowledge 中的向量库接入方式。【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考