Agno 文本多标签分类实战用结构化输出 Schema 实现任意子集标签、分层标签与置信度标注【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno导读多标签分类Multilabel Classification是数据标注与内容理解中的高频需求一段文本往往同时命中多个类别——一条餐厅评论可能既夸了菜品又夸了服务一篇新闻稿可能同时覆盖科技与商业话题。本文基于 agno 仓库cookbook/data_labeling/_02_text_multilabel_classification/目录下的三个完整示例讲解如何用 agno 的output_schema结构化输出机制让 LLM Agent 直接输出任意子集的标签集合并进一步扩展出带置信度的标签与**两级分层标签parent/child**两种生产级变体。读完本文你将掌握在 agno 中为 Agent 声明 Pydantic 输出模型、用Literal约束标签空间、用Field描述约束标签语义以及将结果接入下游路由或人工审核流程的完整方法。一、场景与适用边界什么时候该用多标签分类多标签分类解决的是多个标签可同时命中同一输入的问题。与单标签分类的二选一不同它允许模型输出任意子集包含空集、单元素与全量集合。在cookbook/data_labeling/_02_text_multilabel_classification/README.md中官方给出了三类典型场景餐厅评论标注标签空间为[food, service, value, atmosphere, cleanliness]一条评论可能同时涉及其中任意几个方面客服工单分类标签空间为[bug, feature_request, billing, account]一张工单可能既报告 bug 又涉及计费问题新闻文章主题标注使用两级分层标签空间如sports/football、tech/ai。目录 README 还明确划定了与单标签分类的边界如果恰好只有一个标签适用应改用_01_text_classification/目录下的单标签方案README 说明。多标签方案的价值在于它不需要为 N 个标签枚举 2^N 种组合而是把标签集合本身建模为结构化输出交由模型在一次生成中直接给出。二、核心机制output_schema 与结构化输出三个示例全部采用同一套核心机制——通过Agent的output_schema参数声明 Pydantic 模型让模型严格按照该结构返回结果agent Agent( modelgoogle:gemini-3.5-flash, instructionsinstructions, output_schemaTagging, )从源码看Agent.run()在运行时会把output_schema解析进RunContext并由 get_response_format() 决定底层如何约束模型输出若模型支持原生结构化输出model.supports_native_structured_outputs直接返回output_schema本身交给模型否则回退为{type: json_object}的 JSON 模式或借助模型对 JSON Schema 的支持做二次校验。也就是说无论底层走哪种路径最终返回给用户的对象都是经过校验的 Pydantic 模型实例。agent.run(text)的返回类型是RunOutput其content字段承载了结构化结果见 RunOutput 定义因此三个示例都用pprint({input: text, result: run.content})打印输入与结果。这种方案在数据标注场景的优势非常明显输出天然符合标签枚举约束非法标签会被 Schema 校验拦截无需事后正则清洗同时 Schema 本身就是标注数据的存储/训练格式可直接落库或导出。三、基础版 basic.py平坦标签空间下的任意子集标注basic.py 演示了最核心的写法标签空间是一个Literal输出模型用List[Literal]表达任意子集。3.1 Schema 设计from typing import List, Literal from pydantic import BaseModel, Field Aspect Literal[food, service, value, atmosphere, cleanliness] class Tagging(BaseModel): tags: List[Aspect] Field( ..., descriptionAll aspects the reviewer commented on; empty if none )这里有两个关键设计点Aspect Literal[...]把合法标签空间编译进类型系统模型输出的任何标签都会被 Pydantic 校验器约束在五个值之内Field(..., description...)的语义描述至关重要——empty if none明确告知模型没有任何方面被提及时应返回空列表而不是硬凑标签。这是让任意子集语义真正生效的指令基础。3.2 指令Instructions设计instructions \ Tag the review with every aspect the reviewer commented on. Include an aspect only when the text actually addresses it. An aspect can be mentioned positively or negatively - both count. 指令明确了两个判定规则只标注文本实际涉及到的方面防止过度标注以及正面/负面提及都算数如Place was filthy这种负面描述同样计为cleanliness。3.3 运行与测试日志结果运行方式需配置GOOGLE_API_KEYpython cookbook/data_labeling/_02_text_multilabel_classification/basic.py根据 TEST_LOG.md该示例在 agno 2.7.4 gemini-3.5-flash下测试状态为PASS三条评论全部返回了合法的Tagging对象输入文本输出 tags解读Pasta was excellent and our server was attentive. A bit pricey but worth it.[food, service, value]菜品、服务、性价比同时命中正体现任意子集Place was filthy. Floors sticky, bathroom unusable.[cleanliness]仅卫生一个标签负面提及被正确识别Came for the vibes, stayed for the cocktails. The space is gorgeous.[food, atmosphere]鸡尾酒被归入food标签标签空间的语义合并决策第二条与第三条分别验证了空集之外的最小标签集单标签以及标签语义归并能力——模型按 Schema 的描述把cocktails归入food这正是把领域知识写进Field描述的直接收益。四、进阶版 with_confidence.py为每个标签附加置信度with_confidence.py 在基础版之上把标签列表升级为带置信度的标签列表其动机在文件 docstring 中写得很清楚服务于下游路由——低置信度标签可被标记出来转人工审核高置信度标签则可直接进入训练集。4.1 嵌套 Schema标签与置信度组成复合结构class Tag(BaseModel): aspect: Aspect confidence: Literal[high, medium, low] Field( ..., descriptionConfidence that the review actually addresses this aspect ) class Tagging(BaseModel): tags: List[Tag]注意这里发生了结构升级tags的元素从字符串变成了复合对象Tag每个标签携带aspect取值仍受Aspect的Literal约束和confidencehigh/medium/low三档Literal。Pydantic 的嵌套模型天然支持这种层级agno 会把整个Tagging作为输出 Schema 传递。4.2 置信度语义的指令定义instructions \ Tag the review with every aspect the reviewer addresses. For each tag, report confidence: - high - explicit, unambiguous mention - medium - implicit or partial mention - low - inferred, hedged, or could be the reviewer just venting 置信度三档的判定标准被显式写入指令high为明确无歧义的提及medium为隐含或部分提及low为推断性、含糊的表述甚至可能只是吐槽。这组定义把主观的置信度转化成了可执行的标注规则也让下游的high → 直接入训练集 / low → 转人工路由策略有了统一依据。4.3 运行与测试日志结果python cookbook/data_labeling/_02_text_multilabel_classification/with_confidence.pyTEST_LOG 记录该示例同样PASS三条输入含一条故意含糊的输入的结果如下输入文本输出 tagsaspect/confidence解读Pasta was excellent and the server brought refills without asking.food/high、service/high明确提及全部 highNot sure Id come back. Something was off.atmosphere/low、food/low、service/low含糊输入模型给出三条低置信度猜测而非空列表——这是一种防御性标注行为可供人工审核决策Cocktails were $22. The room is loud. Food was fine.food/high、atmosphere/high、value/high价格、环境、菜品均为显式提及值得注意的行为差异面对含糊输入模型选择了输出多个 low 猜测而不是返回空列表。这既体现了置信度机制的价值低置信度标签恰好成为人工审核的信号也提示标注流程设计者应结合置信度字段定义自己的空集/猜测策略例如对全 low的结果强制人工复核。五、进阶版 hierarchical.py两级分层标签parent/childhierarchical.py 面向标签空间庞大且天然嵌套的场景新闻主题、商品目录、客服分类将输出结构扩展为父类目 子主题的二元组。5.1 父类目用 Literal 硬约束子主题用自由文本ParentTopic Literal[sports, politics, tech, business, health] class HierarchicalTag(BaseModel): parent: ParentTopic child: str Field( ..., description( Specific subtopic within the parent. Examples: sports - football | basketball | tennis; tech - ai | hardware | security; business - markets | startups | regulation. ), ) class Tagging(BaseModel): tags: List[HierarchicalTag]这个设计巧妙地平衡了约束强度与扩展性parent被Literal死死锁在 5 个预定义主题内从类型层面杜绝拼写错误或越界类目child是自由字符串通过Field的description给出每个父类目下的示例子主题如tech - ai | hardware | security引导模型输出与父类目语义一致的子主题同时不限制未来新增子主题。5.2 指令防止提及即标注的过度标注instructions \ Tag the news article with all parent/child pairs it covers. The child must be a meaningful subtopic of the parent, and should reflect what the article is actually about - not every entity mentioned in passing. 指令特意强调child 必须能反映文章真正谈论的主题而不是顺带提到的每个实体。这对新闻/内容标注场景尤为关键——新闻稿常大量出现机构名、人名与产品名若不加约束模型会退化成实体抽取而非主题分类。5.3 运行与测试日志结果python cookbook/data_labeling/_02_text_multilabel_classification/hierarchical.pyTEST_LOG 记录该示例PASS输入文本输出 tagsparent/child解读美联储议息 科技股领涨 AI 芯片上涨的新闻business/markets、tech/ai、tech/hardware一条新闻正确命中 3 组父子标签tech下出现两个不同子主题曼联解雇主教练的体育新闻sports/football父类目sports、子主题football完全符合预期TEST_LOG 特别确认所有输出的 parent 都是合法的Literal值child 均为合理的子主题。这验证了Literal硬约束 description引导组合的有效性。六、三个示例的对比与选型建议维度basic.pywith_confidence.pyhierarchical.py输出结构List[Literal]List[{aspect, confidence}]List[{parent, child}]标签空间平坦枚举5 个值平坦枚举 置信度三档父类目枚举 自由子主题核心用途基础多标签标注带路由/审核信号的标注大型嵌套标签体系额外机制Field描述空集语义置信度指令定义三档标准description示例化子主题测试状态agno 2.7.4 gemini-3.5-flashPASSPASSPASS选型建议标签集合平坦且数量少如 20 个直接用basic.py的List[Literal]需要把标注结果接入下游流水线训练集筛选 / 人工审核 / 路由升级为with_confidence.py的置信度结构用high/medium/low决定标签去向标签空间大且天然存在层级新闻主题、商品目录、客服多级分类采用hierarchical.py的 parent/child 结构父类目枚举化、子主题自由化。三者可自由组合——例如为分层标签的每个 child 再附加置信度字段构造List[{parent, child, confidence}]的复合结构这正是 Pydantic 嵌套模型与 agnooutput_schema的扩展边界所在。七、在 agno 中实现结构化标注的通用要点结合源码与三个示例可以总结出一套可复用的实现方法用Literal编译标签空间把合法取值写进类型定义获得 Pydantic 的静态校验同时让模型看到完整的合法值集合用Field(description...)承载语义规则基础版的empty if none、分层版的子主题示例都是靠 description 传递领域知识——get_response_format()最终把整个 Schema 交给模型description 会随 Schema 一起进入提示上下文用instructions定义判定标准什么算实际涉及、置信度三档如何区分、如何防止提及即标注这些主观规则应写在 instructions 而非硬编码进代码复用RunOutput.content获取结果agent.run(text)返回的RunOutput.content即校验后的结构化对象可直接pprint查看或序列化落库测试日志作为质量基准仓库中每个示例都配套了 TEST_LOG如 TEST_LOG.md记录了在特定 agno 版本与模型下的判定结果与典型输出可作为复现实验、回归对比的基线。三个示例的运行命令汇总均需在仓库根目录执行并配置GOOGLE_API_KEYpython cookbook/data_labeling/_02_text_multilabel_classification/basic.py python cookbook/data_labeling/_02_text_multilabel_classification/with_confidence.py python cookbook/data_labeling/_02_text_multilabel_classification/hierarchical.py八、总结文本多标签分类在 agno 中不是一个内置的黑盒算子而是一种**结构化输出 Schema 指令的组合模式**用 Pydantic 模型精确刻画标签结构平坦集合、带置信度、分层父子用output_schema交给 Agent 强制执行用instructions与Field.description注入判定语义。basic.py、with_confidence.py、hierarchical.py三个示例构成了从基础标注到生产级流水线的完整梯度其输出结构可直接对接训练集构建、人工审核路由与下游分类器是构建高质量文本标注管线的实用起点。【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考