基于 agno 的文本分类标注实战output_schema 驱动的单标签情感标注全流程【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno导读本文以 agno 数据标注系列的第一课_01_text_classification为核心完整讲解如何用Agent output_schema实现输入一段文本、输出一个封闭集合标签这一最基础的标注原语并给出三个逐级升级的实战脚本基础标签、置信度分级、标注理由溯源及其对应的真实测试日志。读者学完后即可动手搭建自己的情感 / 意图 / 话题分类标注管道。一、为什么文本分类是数据标注的第一原语在 agno 仓库的cookbook/data_labeling/系列中文本分类Text Classification被定义为最简单、最基础的标注原语输入是一个字符串输出是一个封闭集合closed set中的标签。它不做多标签选择不做实体抽取只回答一个问题这段话属于哪一类从 cookbook/data_labeling/_01_text_classification/README.md 可以看到这个模块的适用场景非常明确——当输出必须是固定、穷举的标签集合之一时任务类型标签集合示例情感分析Sentimentpositive / negative / neutral意图识别Intentrefund / complaint / question / praise话题分类Topicsports / politics / tech / health质量分桶Quality bucketgood / mediocre / poor同时该 README 也划清了与相邻模块的边界如果一段文本可以同时命中多个标签应使用_02_text_multilabel_classification/如果输出的是结构化的实体或字段则使用_03_text_extraction/。二、三种标注脚本从单标签到可审计标注_01_text_classification目录下包含三个逐级增强的脚本对应的测试日志 TEST_LOG.md 记录于 2026-07-18在gemini-3.5-flash模型、agno 2.7.4 版本下全部 PASSbasic.py文本 → 单一标签最简原语with_confidence.py在标签基础上增加自报置信度high / medium / low用于把低置信度样本路由给人工或更强的模型with_rationale.py在标签基础上增加一段自由文本理由rationale用于可审计性与训练数据构建2.1 basic.py最简的 text → label 映射核心代码完全依赖 Pydantic 的Literal类型来约束输出这正是 agnooutput_schema的典型用法from typing import Literal from agno.agent import Agent, RunOutput from pydantic import BaseModel, Field class Classification(BaseModel): label: Literal[positive, negative, neutral] Field( ..., descriptionThe assigned sentiment label ) agent Agent( modelgoogle:gemini-3.5-flash, instructionsYou classify product reviews by sentiment., output_schemaClassification, ) if __name__ __main__: samples [ I love this product, fantastic quality and fast shipping., Broken on arrival, total waste of money., It works as described, nothing special., ] for text in samples: run: RunOutput agent.run(text) pprint({input: text, result: run.content})测试日志给出了三条样本的全部真实结果均符合预期I love this product, fantastic quality and fast shipping. →positiveBroken on arrival, total waste of money. →negativeIt works as described, nothing special. →neutral2.2 with_confidence.py给每个预测打上置信度同样的任务但输出模型额外增加confidence字段。它的工程价值在脚本 docstring 中写得很清楚当下游消费方需要把低置信度标签路由到人工队列或更强的模型时使用。class Classification(BaseModel): label: Literal[positive, negative, neutral] Field( ..., descriptionThe assigned sentiment label ) confidence: Literal[high, medium, low] Field( ..., descriptionSelf-reported confidence in the label ) instructions \ Classify the sentiment of the input text. Report a confidence level: - high - the sentiment is clear and unambiguous - medium - the sentiment is mostly clear but with some hedging or mixed signals - low - the text is sarcastic, ambiguous, or off-topic 注意这里的指令设计非常讲究它不仅要求模型输出置信度还定义了三个档位的语义边界——high 对应清晰无歧义、medium 对应存在犹豫或混合信号、low 对应讽刺、歧义或离题。没有这层定义模型的置信度就只是一串无意义的自夸。测试日志中的三条样本很好地验证了置信度机制能捕捉文本歧义Best purchase of my life, life-changing! →positive / highIts fine I guess. →neutral / medium存在 hedgingI guessYeah right, this thing is amazing.反讽→negative / low最后一条尤为关键模型不仅识别出反讽、把看似褒义的 amazing 判为 negative还诚实地给出 low 置信度——这正是把样本送入人工队列的信号。2.3 with_rationale.py让每个标签都有据可查第三个脚本在标签之外增加自由文本rationale字段指令要求模型引用或转述驱动决策的关键词class Classification(BaseModel): label: Literal[positive, negative, neutral] Field( ..., descriptionThe assigned sentiment label ) rationale: str Field( ..., descriptionOne sentence explaining why this label was chosen ) instructions \ Classify the sentiment of the input text. Quote or paraphrase the specific words that drove your decision in the rationale. 从测试日志看两条样本不仅标签正确rationale 也精准锚定了决策证据Shipping was fast but the product itself fell apart in a week. →negative理由转述了 the product quickly fell apart within a weekBetter than expected, will buy again. →positive理由直接引用了 Better than expected 与 will buy againrationale 的工程价值体现在两处脚本 docstring 原文一是可审计性——标注结果为什么如此可以被追溯复核二是训练数据构建——reasoning trace 本身就是训练语料的一部分可作为后续微调时的监督信号。三、运行方式与环境要求README 给出了三个脚本的统一运行命令全部从仓库根目录执行python cookbook/data_labeling/_01_text_classification/basic.py python cookbook/data_labeling/_01_text_classification/with_confidence.py python cookbook/data_labeling/_01_text_classification/with_rationale.py三个脚本都使用modelgoogle:gemini-3.5-flash因此运行前必须配置GOOGLE_API_KEY环境变量。如希望切换模型直接替换model参数即可agno 支持provider:model的字符串形式引用模型。四、底层原理output_schema 如何约束模型输出三个脚本的共性在于都通过output_schemaClassification把 Pydantic 模型传给 Agent。从源码 libs/agno/agno/agent/agent.py 可以看到相关参数定义output_schema接受 Pydantic 模型类或 JSON dict用于以指定格式获得响应parse_response默认True若为 True模型响应会被解析成output_schema对应的对象否则以 JSON 字符串返回structured_outputs模型支持时如 OpenAIChat可启用模型强制的结构化输出use_json_mode为 True 时不把 Pydantic schema 直接传给模型而是将 JSON 描述追加到 system message 中。也就是说Literal[positive, negative, neutral]这类类型约束会被编译成模型可遵循的 schema从根本上杜绝模型输出标签集合之外的非法值——这正是封闭集合标注在工程上的可靠保障。运行返回的对象是RunOutput定义见 libs/agno/agno/run/agent.py其中content字段承载模型最终输出。由于设置了output_schemarun.content即为填充后的Classification实例可直接访问.label、.confidence、.rationale等字段便于接入下游落库或人工审核流程。五、落地建议把标注脚本升级为标注管道基于以上三个脚本可以推断出在实际标注工程中的三条升级路径可与 agno 的会话与存储能力组合使用置信度驱动的分流读取run.content.confidence将 low 置信度样本写入人工审核队列如数据库表high / medium 直接入库作为标注结果从而降低人工成本理由驱动的质检利用rationale做规则化校验——例如若 label 为 positive 但 rationale 中出现 broke、fell apart 等负面词则触发重新标注形成廉价的自动质检层标注即训练数据将(text, label, rationale)三元组落盘为训练集rationale 可作为思维链监督信号后续用于微调更轻量的分类模型。三个脚本的完整代码与说明位于 cookbook/data_labeling/_01_text_classification/其中README.md给出使用场景矩阵与相邻模块跳转指引TEST_LOG.md记录全部验证结论可供复现时对照参考。【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考