agno 文本多标签分类实战用 output_schema 构建可复用的数据标注 Agent【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno导读本文基于 agno 仓库的 cookbook 数据标注系列系统讲解如何用 LLM Agent 完成文本多标签分类Text Multilabel Classification为同一段文本分配标签集合中任意子集。你将掌握三种由浅入深的标注方案——扁平标签空间的基础标注、带逐标签置信度的质量路由、以及两级层次化分类parent/child 标签并理解 agno 通过output_schema强制结构化输出的底层原理可直接用于餐饮评论打标、工单路由、新闻主题分类等真实标注任务。一、什么是文本多标签分类多标签分类的任务定义是把任意子集N 个标签中的若干个赋予一段文本。它与单标签分类的本质区别在于单标签要求输出封闭集合中的恰好一个标签而多标签分类中多个标签可以同时命中同一输入。例如一段餐厅点评可能同时提到食物、服务、价格、氛围等多个方面每个被提及的方面都是一个有效标签。在 agno 的示例中标签空间被建模为Literal联合类型输出结构则用 PydanticBaseModel描述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 )这里Literal[...]将标签限定为封闭集合List[Aspect]声明输出为标签列表可为空Field描述告知模型仅在文本真正涉及某方面时才打该标签。完整代码见 basic.py。何时使用多标签分类关联文档给出了三个典型场景餐厅评论打标按[food, service, value, atmosphere, cleanliness]标注点评涉及的方面客服工单路由按[bug, feature_request, billing, account]标注工单类型一个工单可能既是 bug 又涉及计费新闻文章主题标注按层次化主题分类如sports/football、tech/ai。与单标签的取舍如果任务恰好只允许一个标签生效应改用单标签方案见 cookbook/data_labeling/_01_text_classification/README.md。反之若多个标签可同时成立如同一篇新闻既属tech又属business就用本文的多标签方案。二、快速运行三个示例脚本的运行命令与依赖如下python 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前置条件需要配置GOOGLE_API_KEY环境变量因为三个示例默认使用google:gemini-3.5-flash模型。三个脚本均为自包含可执行文件if __name__ __main__直接运行即可在终端用rich.pretty.pprint打印{input: 文本, result: 结构化标签}形式的结果。三、方案一基础多标签标注flat label spacebasic.py演示了最简单、最通用的形态——从扁平标签空间输出标签集合。其核心是构造一个带output_schema的 agno Agentfrom agno.agent import Agent agent Agent( modelgoogle:gemini-3.5-flash, instructionsinstructions, output_schemaTagging, )Agent 构建三要素要素作用model指定 LLM此处为google:gemini-3.5-flashinstructions以自然语言约束标注行为是提示词的主载体output_schema提供 Pydantic 模型强制模型按该结构输出指令设计是多标签任务质量的关键。示例指令明确了两条规则只标注文本实际涉及的内容、正面或负面提及都算命中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. 运行时循环调用agent.run(text)返回的RunOutput对象中content即为解析后的结构化结果for text in samples: run: RunOutput agent.run(text) pprint({input: text, result: run.content})示例自带三条评测样本覆盖了多标签命中、负面提及、无明确方面等边界情形Pasta was excellent and our server was attentive. A bit pricey but worth it.Place was filthy. Floors sticky, bathroom unusable.Came for the vibes, stayed for the cocktails. The space is gorgeous.据仓库 TEST_LOG.md 记录agno 2.7.4 gemini-3.5-flash 实测三条样本分别输出[food, service, value]、[cleanliness]、[food, atmosphere]其中鸡尾酒被归入 food 方面全部返回合法Tagging对象说明List[Literal]约束下的结构解析稳定可靠。四、方案二带逐标签置信度confidence routingwith_confidence.py在方案一的基础上为每个标签附加一个置信度字段用于下游质量路由高置信度结果可直接进入训练集低置信度结果则转入人工审核或交给更强的模型复核。置信度的实现方式是嵌套 Pydantic 模型外层Tagging持有List[Tag]内层Tag同时携带标签值与置信度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]对应的指令把三个置信度等级的操作化定义写清楚这是让 LLM 输出一致且可解释的关键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 实测样本与结果据 TEST_LOG.mdPasta was excellent and the server brought refills without asking.→food/high、service/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值得注意第二个样本面对刻意模糊的输入模型选择了低置信度猜测而非返回空集。这正是置信度字段的价值——它把模型的不确定性显式暴露出来便于你在路由逻辑中设置阈值例如confidence low时转人工。五、方案三层次化多标签分类hierarchical taxonomyhierarchical.py面向标签空间大且天然嵌套的场景新闻主题、产品目录、客服分类树。其核心思路是父级类别用Literal封闭约束子级用自由文本str加Field示例引导。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]这种父级受限 子级开放的组合既保证了分类体系的规范性父级不会跑出 5 个预设类别又保留了灵活性子级无需预穷举。Field.description中的示例sports - football | basketball | tennis等实质上是给模型的 few-shot 提示。指令同样强调子级必须真实反映文章主题而非提及过的任意实体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. 实测结果据 TEST_LOG.mdThe Fed held rates steady as markets reacted to a surprise jobs report. Tech stocks led the rally, with AI chipmakers up 4 percent.→[business/markets, tech/ai, tech/hardware]同一篇短文命中多个父/子对体现多标签特性Manchester United fired their head coach after a third consecutive loss. The board is reportedly courting a replacement from Spain.→[sports/football]所有输出的 parent 均为合法Literal值child 为语义合理的子主题验证了两级结构的可行性。六、源码级原理解读output_schema 如何工作三个示例都依赖 agno 的output_schema机制实现结构化输出。从 libs/agno/agno/agent/agent.py 源码可以看到该机制的完整配置面# Provide a response model to get the response in the implied format. # You can use a Pydantic model or a JSON fitting the providers expected schema. output_schema: Optional[Union[Type[BaseModel], Dict[str, Any]]] None # Provide a secondary model to parse the response from the primary model parser_model: Optional[Model] None # If True, the response from the Model is converted into the output_schema # Otherwise, the response is returned as a JSON string parse_response: bool True # Use model enforced structured_outputs if supported (e.g. OpenAIChat) structured_outputs: Optional[bool] None关键点拆解output_schema接受一个 Pydantic 模型示例用法或 JSON Schema dict将模型的自由文本回复约束为目标结构parse_response: bool True是默认行为模型输出会被解析并转换回output_schema指定的 Pydantic 模型实例本系列三个示例的run.content拿到的都是Tagging对象若改为False则返回 JSON 字符串structured_outputs与parser_model是进阶选项前者在模型提供商支持时启用强制 JSON Schema 输出如 OpenAIChat后者在需要时引入第二个模型来解析主模型输出可在输出不稳定时作为兜底。运行结果的承载对象是RunOutput。在 libs/agno/agno/run/agent.py 中它被定义为一个 dataclass注释明确指出Response returned by Agent.run() or Workflow.run() functions其中content字段Optional[Any]在设置output_schema后即为解析得到的结构化对象dataclass class RunOutput: Response returned by Agent.run() or Workflow.run() functions run_id: Optional[str] None session_id: Optional[str] None ... content: Optional[Any] None content_type: str str除content外RunOutput还携带run_id、session_id、messages、metrics、tools等元数据方便你在批处理标注流程中记录每次标注的会话与统计信息。七、三种方案选型与工程实践建议综合关联文档与示例代码三种方案的选型建议如下方案输出结构适用场景代表文件基础多标签List[Literal]标签空间扁平、无需置信度/层级basic.py置信度路由List[{aspect, confidence}]需要将低置信度结果转人工审核或进训练集过滤with_confidence.py层次化分类List[{parent, child}]标签空间大且天然嵌套新闻、产品目录hierarchical.py工程实践要点均从本示例可推导验证指令是质量控制的核心三个示例的指令都明确了何时打标签、何时不打的判定边界only when the text actually addresses it、not every entity mentioned in passing以及多值语义positively or negatively - both count。标注任务中这类判定规则必须写进指令用Field携带标注规范无论是置信度含义还是子级示例Field(description...)都会随 schema 传给模型是比纯提示词更可靠的结构化引导用Literal封闭标签空间父级标签、置信度等级、扁平标签都用Literal限定从 schema 层面杜绝越界输出实测中所有标签都落在预设集合内置信度分级建议与下游联动high/medium/low三档可直接映射为直进训练集 / 抽查 / 人工复核三档路由策略模型与版本注意示例默认google:gemini-3.5-flashTEST_LOG 记录于 agno 2.7.4 环境若更换模型需重点回归验证结构解析稳定性。本文涉及的三个示例均位于 cookbook/data_labeling/_02_text_multilabel_classification/ 目录可对照 README.md 与 TEST_LOG.md 进行验证若需单标签版本可参考 cookbook/data_labeling/_01_text_classification/README.md。【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
