使用 Agno 构建文本分类数据标注流水线从固定标签到置信度与推理依据【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno文本分类Text Classification是数据标注领域最基础的原子能力输入一段文本输出一个来自封闭标签集合的标签。本文以 Agno 仓库cookbook/data_labeling/_01_text_classification/目录下的三个可运行示例为核心讲解如何用Agentoutput_schema结构化输出实现文本 → 单标签的分类标注并逐步扩展出置信度字段用于低置信样本转人工或转强模型与推理依据字段用于审计与训练数据沉淀最后结合源码揭示其底层工作机理。读完本文你将掌握一套可直接复制运行的情感/意图/主题分类标注脚本并理解如何把它们接入更复杂的多标签分类与结构化抽取流程。什么是文本 → 单标签分类单标签文本分类是数据标注流水线中最简单的原语输入是一个字符串输出是封闭集合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判断是否应该使用本文方案的关键在于输出是否恰好是固定、穷举标签集合中的一个。如果多个标签可以同时命中如一条餐厅评论同时涉及 food 和 service应当改用cookbook/data_labeling/_02_text_multilabel_classification/如果输出是带字段的结构化数据实体、字段、嵌套对象则应当使用cookbook/data_labeling/_03_text_extraction/。从仓库整体布局看cookbook/data_labeling/README.md明确指出应当从本目录的basic.py开始学习目录中其他所有 cookbook 都镜像了它的结构——每个子目录包含一个端到端可运行的basic.py外加在任务上有意义task-meaningful的变体。因此本文不仅是单标签分类的指南也是理解整个 data_labeling 系列28 个子目录、75 个单文件示例的入门钥匙。目录结构与三个示例文件cookbook/data_labeling/_01_text_classification/ ├── README.md ├── basic.py # 文本 → 单个标签最小可读示例 ├── with_confidence.py # 在标签之外追加自报置信度字段 ├── with_rationale.py # 在标签之外追加一句话推理依据 └── TEST_LOG.md # 按 cookbook 惯例维护的运行日志basic.py— 文本 → 单标签。最小、最直白的标注原语。with_confidence.py— 为每次预测追加自报置信度high/medium/low。当需要把低置信度样本路由给人工或更强模型时使用。with_rationale.py— 追加一段简短推理依据字符串解释为什么选择该标签。适合审计追踪与作为训练数据沉淀。三个文件共享同一套技术栈agno.agent中的Agent与RunOutput、pydantic的BaseModel/Field、typing.Literal定义封闭标签、rich.pretty的pprint打印结果。下面逐一展开。basic.py文本 → 单个标签完整源码位于 basic.py核心只有三步。第一步用Literal定义封闭标签集合。typing.Literal是 Python 3.8 提供的类型把允许取值限定为显式枚举的字符串from typing import Literal from pydantic import BaseModel, Field class Classification(BaseModel): label: Literal[positive, negative, neutral] Field( ..., descriptionThe assigned sentiment label )这里label字段的类型被锁定为positive/negative/neutral三者之一Pydantic 会在解析输出时强制校验——模型如果输出集合之外的标签结构化解析会直接失败从机制上杜绝了模型自由发挥标签的可能。这正是封闭集合这一约束在代码层面的落地。第二步创建 Agent绑定模型、指令与输出 Schema。from agno.agent import Agent, RunOutput agent Agent( modelgoogle:gemini-3.5-flash, instructionsYou classify product reviews by sentiment., output_schemaClassification, )关键参数是output_schemaClassification它声明了模型必须返回符合Classification结构的 JSON 对象而非自由文本。instructions则描述了任务语义按情感分类产品评论。示例默认使用google:gemini-3.5-flashGemini 3.5 Flash原生多模态这一点与整个 data_labeling cookbook 系列保持一致——cookbook/data_labeling/README.md的环境变量表中注明GOOGLE_API_KEY是该系列每个 cookbook 的默认凭证。第三步批量运行并打印结果。from rich.pretty import pprint 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})对每条样本调用agent.run(text)得到RunOutput其中的content即解析后的Classification对象含label字段。pprint将输入与结果以字典形式结构化打印方便直接观察标注输出。预期的运行结果来自 TEST_LOG.md2026-07-18 针对gemini-3.5-flash、agno 2.7.4 实测 PASSI love this product, fantastic quality and fast shipping.→positiveBroken on arrival, total waste of money.→negativeIt works as described, nothing special.→neutral三条样本恰好覆盖正、负、中三种情感验证了单标签分类的最小闭环。with_confidence.py追加自报置信度支持低置信样本路由在生产标注流水线中纯标签往往不够——你需要知道哪些标注可信从而把拿不准的样本转给人工或更强的模型。with_confidence.py在label之外追加了一个confidence字段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 )置信度同样是封闭枚举high/medium/low并通过instructions向模型给出可操作的判定标准而非空泛的请给出置信度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。该示例的测试样本刻意覆盖了这三档samples [ Best purchase of my life, life-changing!, Its fine I guess., Yeah right, this thing is amazing., ]TEST_LOG.md 记录的实测结果为第一句 →positive/high第二句带保留语气→neutral/medium第三句讽刺→negative/low。可见模型确实依据指令标准区分了歧义程度。落地价值有了confidence字段下游消费者就能实现确定性路由——confidence low的样本进入人工审核队列或转发给更强模型复审而high/medium样本可以直接入库。这种按置信度分流模式是真实标注系统中最常见的质量兜底手段之一。with_rationale.py追加推理依据服务审计与训练数据沉淀仅凭一个标签事后很难追溯模型为什么这么标。with_rationale.py在label之外追加自由文本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不再是模型的自说自话而是可校验的决策痕迹。该示例的两个测试样本samples [ Shipping was fast but the product itself fell apart in a week., Better than expected, will buy again., ]TEST_LOG.md 实测第一句 →negativerationale 引用了产品在一周内散架第二句 →positiverationale 引用了Better than expected和will buy again。两个标签正确且理由均落到决定性短语上。落地价值rationale有两大用途——其一可审计性人工审核员可以只读理由快速判断标注质量无需重读全文其二训练数据沉淀reasoning trace 本身就是产物可以直接作为后续模型微调或少样本提示的输入素材。运行方式与环境变量在 agno 仓库根目录下依次执行即可。三个脚本独立可跑无需额外依赖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前置条件需要设置GOOGLE_API_KEY环境变量示例默认使用 Gemini 3.5 Flash。若尚未配置演示环境可先执行仓库根目录的./scripts/demo_setup.sh创建并激活 demo 虚拟环境source .venvs/demo/bin/activate再运行上述命令。本目录三个脚本均只依赖模型推理无额外 Python 包或外部服务依赖。源码级原理output_schema 与 RunOutput 如何工作示例中两个 API 值得从源码层面理解其机制。output_schema的结构化输出强制。Agent的output_schema参数本示例传入 Pydantic 模型Classification驱动了从提示词到响应解析的全链路。在 libs/agno/agno/agent/_messages.py 中可以找到对应逻辑当output_schema存在且模型不支持原生结构化输出时系统会向系统消息追加 JSON 输出提示get_json_output_prompt要求模型按 schema 输出 JSON模型返回后Agno 再按Classification的 Pydantic 定义解析并强校验。因此示例代码中的类型约束Literal封闭标签、必填字段在运行时同样生效——解析失败会报错而不是静默放行。RunOutput是agent.run()的统一返回容器。agent.run(text)返回的RunOutput定义于 libs/agno/agno/run/agent.py其 docstring 明确写着Response returned by Agent.run() or Workflow.run() functions。它携带run_id、session_id、content结构化解析后的结果对象、metrics、messages、tools等字段。示例中访问的run.content即解析后的Classification实例label、confidence、rationale等字段均可直接取用而run_id/session_id等元数据可用于后续的记录、追踪与重放——这正是数据标注流水线需要的可追溯性基础。与相邻标注原语的关系。当标注需求升级时本文方案是其他原语的地基多个标签同时命中 →cookbook/data_labeling/_02_text_multilabel_classification/平面标签空间任意子集、逐标签置信度、层级化父子标签输出为结构化对象实体、字段、嵌套结构→cookbook/data_labeling/_03_text_extraction/生产环境最常见的标注形态需要实体字符/Token 位置 →cookbook/data_labeling/_04_text_span_labeling/。向上游看cookbook/data_labeling/_17_llm_as_judge/、_18_quality_review/、_19_inter_annotator_agreement/等组合模式都建立在分类/抽取这类基础原语之上。理解本文的basic.py等于掌握了整个 data_labeling 系列的通用骨架。小结basic.py用Literal封闭标签集合 output_schema强制结构化输出实现了最简的文本 → 单标签分类标注with_confidence.py追加confidence字段与可执行的判定指令支撑低置信样本路由到人工或更强模型with_rationale.py追加rationale字段并要求引用关键证据服务于审计追踪与训练数据沉淀底层机制上output_schema驱动提示词注入 返回结果 Pydantic 强校验RunOutput统一承载运行结果与追踪元数据二者共同保证了标注输出的结构性与可追溯性。如果你要构建真实标注流水线推荐从这三个脚本出发先用basic.py验证任务可行性再按需叠加confidence质量路由与rationale审计与训练素材最后依据输出形态切换到多标签或结构化抽取目录继续复用同一套 Agent output_schema模式。【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 使用 Agno 构建文本分类数据标注流水线：从固定标签到置信度与推理依据
使用 Agno 构建文本分类数据标注流水线从固定标签到置信度与推理依据【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno文本分类Text Classification是数据标注领域最基础的原子能力输入一段文本输出一个来自封闭标签集合的标签。本文以 Agno 仓库cookbook/data_labeling/_01_text_classification/目录下的三个可运行示例为核心讲解如何用Agentoutput_schema结构化输出实现文本 → 单标签的分类标注并逐步扩展出置信度字段用于低置信样本转人工或转强模型与推理依据字段用于审计与训练数据沉淀最后结合源码揭示其底层工作机理。读完本文你将掌握一套可直接复制运行的情感/意图/主题分类标注脚本并理解如何把它们接入更复杂的多标签分类与结构化抽取流程。什么是文本 → 单标签分类单标签文本分类是数据标注流水线中最简单的原语输入是一个字符串输出是封闭集合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判断是否应该使用本文方案的关键在于输出是否恰好是固定、穷举标签集合中的一个。如果多个标签可以同时命中如一条餐厅评论同时涉及 food 和 service应当改用cookbook/data_labeling/_02_text_multilabel_classification/如果输出是带字段的结构化数据实体、字段、嵌套对象则应当使用cookbook/data_labeling/_03_text_extraction/。从仓库整体布局看cookbook/data_labeling/README.md明确指出应当从本目录的basic.py开始学习目录中其他所有 cookbook 都镜像了它的结构——每个子目录包含一个端到端可运行的basic.py外加在任务上有意义task-meaningful的变体。因此本文不仅是单标签分类的指南也是理解整个 data_labeling 系列28 个子目录、75 个单文件示例的入门钥匙。目录结构与三个示例文件cookbook/data_labeling/_01_text_classification/ ├── README.md ├── basic.py # 文本 → 单个标签最小可读示例 ├── with_confidence.py # 在标签之外追加自报置信度字段 ├── with_rationale.py # 在标签之外追加一句话推理依据 └── TEST_LOG.md # 按 cookbook 惯例维护的运行日志basic.py— 文本 → 单标签。最小、最直白的标注原语。with_confidence.py— 为每次预测追加自报置信度high/medium/low。当需要把低置信度样本路由给人工或更强模型时使用。with_rationale.py— 追加一段简短推理依据字符串解释为什么选择该标签。适合审计追踪与作为训练数据沉淀。三个文件共享同一套技术栈agno.agent中的Agent与RunOutput、pydantic的BaseModel/Field、typing.Literal定义封闭标签、rich.pretty的pprint打印结果。下面逐一展开。basic.py文本 → 单个标签完整源码位于 basic.py核心只有三步。第一步用Literal定义封闭标签集合。typing.Literal是 Python 3.8 提供的类型把允许取值限定为显式枚举的字符串from typing import Literal from pydantic import BaseModel, Field class Classification(BaseModel): label: Literal[positive, negative, neutral] Field( ..., descriptionThe assigned sentiment label )这里label字段的类型被锁定为positive/negative/neutral三者之一Pydantic 会在解析输出时强制校验——模型如果输出集合之外的标签结构化解析会直接失败从机制上杜绝了模型自由发挥标签的可能。这正是封闭集合这一约束在代码层面的落地。第二步创建 Agent绑定模型、指令与输出 Schema。from agno.agent import Agent, RunOutput agent Agent( modelgoogle:gemini-3.5-flash, instructionsYou classify product reviews by sentiment., output_schemaClassification, )关键参数是output_schemaClassification它声明了模型必须返回符合Classification结构的 JSON 对象而非自由文本。instructions则描述了任务语义按情感分类产品评论。示例默认使用google:gemini-3.5-flashGemini 3.5 Flash原生多模态这一点与整个 data_labeling cookbook 系列保持一致——cookbook/data_labeling/README.md的环境变量表中注明GOOGLE_API_KEY是该系列每个 cookbook 的默认凭证。第三步批量运行并打印结果。from rich.pretty import pprint 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})对每条样本调用agent.run(text)得到RunOutput其中的content即解析后的Classification对象含label字段。pprint将输入与结果以字典形式结构化打印方便直接观察标注输出。预期的运行结果来自 TEST_LOG.md2026-07-18 针对gemini-3.5-flash、agno 2.7.4 实测 PASSI love this product, fantastic quality and fast shipping.→positiveBroken on arrival, total waste of money.→negativeIt works as described, nothing special.→neutral三条样本恰好覆盖正、负、中三种情感验证了单标签分类的最小闭环。with_confidence.py追加自报置信度支持低置信样本路由在生产标注流水线中纯标签往往不够——你需要知道哪些标注可信从而把拿不准的样本转给人工或更强的模型。with_confidence.py在label之外追加了一个confidence字段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 )置信度同样是封闭枚举high/medium/low并通过instructions向模型给出可操作的判定标准而非空泛的请给出置信度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。该示例的测试样本刻意覆盖了这三档samples [ Best purchase of my life, life-changing!, Its fine I guess., Yeah right, this thing is amazing., ]TEST_LOG.md 记录的实测结果为第一句 →positive/high第二句带保留语气→neutral/medium第三句讽刺→negative/low。可见模型确实依据指令标准区分了歧义程度。落地价值有了confidence字段下游消费者就能实现确定性路由——confidence low的样本进入人工审核队列或转发给更强模型复审而high/medium样本可以直接入库。这种按置信度分流模式是真实标注系统中最常见的质量兜底手段之一。with_rationale.py追加推理依据服务审计与训练数据沉淀仅凭一个标签事后很难追溯模型为什么这么标。with_rationale.py在label之外追加自由文本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不再是模型的自说自话而是可校验的决策痕迹。该示例的两个测试样本samples [ Shipping was fast but the product itself fell apart in a week., Better than expected, will buy again., ]TEST_LOG.md 实测第一句 →negativerationale 引用了产品在一周内散架第二句 →positiverationale 引用了Better than expected和will buy again。两个标签正确且理由均落到决定性短语上。落地价值rationale有两大用途——其一可审计性人工审核员可以只读理由快速判断标注质量无需重读全文其二训练数据沉淀reasoning trace 本身就是产物可以直接作为后续模型微调或少样本提示的输入素材。运行方式与环境变量在 agno 仓库根目录下依次执行即可。三个脚本独立可跑无需额外依赖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前置条件需要设置GOOGLE_API_KEY环境变量示例默认使用 Gemini 3.5 Flash。若尚未配置演示环境可先执行仓库根目录的./scripts/demo_setup.sh创建并激活 demo 虚拟环境source .venvs/demo/bin/activate再运行上述命令。本目录三个脚本均只依赖模型推理无额外 Python 包或外部服务依赖。源码级原理output_schema 与 RunOutput 如何工作示例中两个 API 值得从源码层面理解其机制。output_schema的结构化输出强制。Agent的output_schema参数本示例传入 Pydantic 模型Classification驱动了从提示词到响应解析的全链路。在 libs/agno/agno/agent/_messages.py 中可以找到对应逻辑当output_schema存在且模型不支持原生结构化输出时系统会向系统消息追加 JSON 输出提示get_json_output_prompt要求模型按 schema 输出 JSON模型返回后Agno 再按Classification的 Pydantic 定义解析并强校验。因此示例代码中的类型约束Literal封闭标签、必填字段在运行时同样生效——解析失败会报错而不是静默放行。RunOutput是agent.run()的统一返回容器。agent.run(text)返回的RunOutput定义于 libs/agno/agno/run/agent.py其 docstring 明确写着Response returned by Agent.run() or Workflow.run() functions。它携带run_id、session_id、content结构化解析后的结果对象、metrics、messages、tools等字段。示例中访问的run.content即解析后的Classification实例label、confidence、rationale等字段均可直接取用而run_id/session_id等元数据可用于后续的记录、追踪与重放——这正是数据标注流水线需要的可追溯性基础。与相邻标注原语的关系。当标注需求升级时本文方案是其他原语的地基多个标签同时命中 →cookbook/data_labeling/_02_text_multilabel_classification/平面标签空间任意子集、逐标签置信度、层级化父子标签输出为结构化对象实体、字段、嵌套结构→cookbook/data_labeling/_03_text_extraction/生产环境最常见的标注形态需要实体字符/Token 位置 →cookbook/data_labeling/_04_text_span_labeling/。向上游看cookbook/data_labeling/_17_llm_as_judge/、_18_quality_review/、_19_inter_annotator_agreement/等组合模式都建立在分类/抽取这类基础原语之上。理解本文的basic.py等于掌握了整个 data_labeling 系列的通用骨架。小结basic.py用Literal封闭标签集合 output_schema强制结构化输出实现了最简的文本 → 单标签分类标注with_confidence.py追加confidence字段与可执行的判定指令支撑低置信样本路由到人工或更强模型with_rationale.py追加rationale字段并要求引用关键证据服务于审计追踪与训练数据沉淀底层机制上output_schema驱动提示词注入 返回结果 Pydantic 强校验RunOutput统一承载运行结果与追踪元数据二者共同保证了标注输出的结构性与可追溯性。如果你要构建真实标注流水线推荐从这三个脚本出发先用basic.py验证任务可行性再按需叠加confidence质量路由与rationale审计与训练素材最后依据输出形态切换到多标签或结构化抽取目录继续复用同一套 Agent output_schema模式。【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考