用 agno 做文本结构化抽取基于 Pydantic 输出 Schema 与置信度标注的实战指南【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno导读本指南以 agno 仓库中 cookbook/data_labeling/_03_text_extraction 目录为线索系统讲解如何把电子邮件签名、会议记录等自由文本转化为由你掌控 Schema 的 Pydantic 对象——这也是当前生产环境中数据标注最常见的形态。读完本文你将掌握三类抽取能力扁平单条记录抽取、嵌套子对象列表抽取以及为每个字段附加置信度以支持下游人工复核路由并能在 basic.py、with_confidence.py、nested.py 三个示例基础上直接改造出可落地的抽取管线。文本抽取为什么它是生产环境最常用的标注形态在数据标注流水线中_03_text_extraction解决的问题是从自由文本中抽取带有类型的结构化数据。它的输出不是单个标签也不是字符级位置标注而是一个由你定义 Schema 的 Pydantic 对象——字段名、字段类型、可空性、字段描述全部由你控制。按照 README.md 的划分本目录覆盖三种标注形状示例脚本抽取形状典型用途basic.py文本 → 扁平类型化对象单条记录从邮件签名中抽取联系人信息with_confidence.py扁平对象 每字段置信度将低置信度字段路由到人工复核nested.py嵌套子对象列表从会议记录中抽取行动项适用场景非常直观从邮件签名抽取联系人信息、从会议记录抽取行动项、把非结构化的用户输入中的字段提升为数据库行。README 同时给出了场景边界——如果只需要单个标签应改用 cookbook/data_labeling/_01_text_classification如果需要实体的字符级位置则应查看 cookbook/data_labeling/_04_text_span_labeling。运行环境与前置条件三个示例脚本均使用同一模型与同一 agno 版本运行。根据 TEST_LOG.md 记录测试环境为gemini-3.5-flash模型 agno 2.7.4测试日期为 2026-07-18三个示例全部 PASS。运行方式以仓库根目录为基准python cookbook/data_labeling/_03_text_extraction/basic.py python cookbook/data_labeling/_03_text_extraction/with_confidence.py python cookbook/data_labeling/_03_text_extraction/nested.py运行前需在环境中配置GOOGLE_API_KEYREADME.md 中明确声明。三个脚本内部统一通过modelgoogle:gemini-3.5-flash指定模型若需切换其他 Google 模型或替换为 agno 支持的其他 provider只需修改Agent(model...)一处。基础篇用output_schema抽取扁平联系人记录定义抽取 Schema在 agno 中抽取结果的形状由你传入Agent的output_schema决定。从源码看agent.py 中output_schema的类型定义为Optional[Union[Type[BaseModel], Dict[str, Any]]]——既可以传一个 Pydantic 模型类也可以传一个 JSON dict。此外还有一组配套参数控制输出解析行为agent.pyparse_response: bool True——为 True 时将模型响应转换为output_schema对象否则返回 JSON 字符串structured_outputs: Optional[bool] None——若模型支持如 OpenAIChat使用模型强制的结构化输出use_json_mode: bool False——为 True 时将输出 Schema 的 JSON 描述注入系统消息而非直接传给模型。basic.py定义了名为Contact的 Pydantic 模型五个字段全部可空class Contact(BaseModel): name: Optional[str] Field(None, descriptionFull name as written) email: Optional[str] Field(None, descriptionEmail address) phone: Optional[str] Field(None, descriptionPhone number, raw format) company: Optional[str] Field(None, descriptionCompany or organization) title: Optional[str] Field(None, descriptionJob title)注意这里Field的description不是摆设——它会作为 Schema 元数据进入模型提示直接影响抽取质量。字段描述写得越精确例如Phone number, raw format强调保留原始格式模型越不容易自由发挥。用指令约束抽取行为抽取任务的成功率高度依赖指令设计。basic.py的指令只有三句话却覆盖了三个关键约束instructions \ Extract contact information from the input. Use exactly what the text shows - do not normalize or reformat. If a field is missing, leave it null. Do not guess. verbatim 原则照抄文本不做规范化或重新格式化缺省为 null字段缺失时留空不编造禁止猜测无把握的字段一律不填。运行 Agent 并读取结果basic.py构造了两个样本逐个agent.run(text)执行并用rich.pretty的pprint打印输入与结果if __name__ __main__: samples [ Hi - Sarah Johnson, VP of Marketing at Acme Corp. sarahacme.com / 1-555-0102., regards, Mike (engineeringstartup.io), ] for text in samples: run: RunOutput agent.run(text) pprint({input: text, result: run.content})agent.run()返回的是RunOutput对象。从 libs/agno/agno/run/agent.py 的RunOutput数据类定义看它是一个承载整次运行元数据的容器包含run_id、session_id、input、content、content_type、reasoning_content、messages、metrics、status、events等字段。抽取结果就放在run.content中当配置了output_schema时content是解析好的 Pydantic 对象实例。实测结果TEST_LOG.md 记录的实测结果为PASS样本 1完整签名五个字段全部逐字抽取成功——nameSarah Johnson、emailsarahacme.com、phone1-555-0102、companyAcme Corp.、titleVP of Marketing样本 2极简落款regards, Mike (engineeringstartup.io)只抽取了nameMike、emailengineeringstartup.iophone、company、title按指令留空为None。这个结果印证了指令的有效性模型严格遵守缺失字段留空、不猜测的约束而不是从残缺文本中硬凑一个看起来完整的记录——这正是抽取型标注与生成型任务的关键区别。进阶篇抽取嵌套子对象列表真实业务中抽取结果往往不是扁平结构而是一个文档 → 若干条同类子记录例如会议行动项、订单行项目、与会者列表、引用列表等。nested.py演示了这种形状顶层 Pydantic 模型内嵌一个子模型列表。Schema 设计class ActionItem(BaseModel): owner: str Field(..., descriptionPerson responsible, as named in the meeting) description: str Field(..., descriptionWhat they committed to do) due_date: Optional[str] Field(None, descriptionISO yyyy-mm-dd if mentioned) class Meeting(BaseModel): action_items: List[ActionItem]关键点owner和description是必填字段Field(...)并配有语义清晰的描述due_date可空描述中明确限定为ISO yyyy-mm-dd 格式且仅在文本中提到时填写顶层Meeting的字段action_items的类型是List[ActionItem]即列表内嵌对象。指令设计定义什么是行动项对列表抽取最大的风险是模型把不属于目标类别的内容也塞进来。nested.py的指令给出了非常精确的判定标准instructions \ Extract action items from the meeting transcript. An action item is a commitment a named person made during the meeting. Only include items that are clearly assigned to a specific person; ignore vague group asks. If a due date is not mentioned, leave it null. 指令明确了三点行动项必须是具名者做出的承诺只收录明确指派给具体人的事项忽略模糊的群体性请求未提及截止日期时留空。测试输入与实测结果nested.py使用了一段四行会议记录Mike: Ill send out the updated roadmap by Friday. Sarah: Great. And Ill set up the kickoff with the design team next week. Jess: We should probably get budget approval at some point. Mike: Yeah. Let me draft the budget memo by end of next week so we can send it to finance.TEST_LOG.md 记录的实测结果成功抽取3 条行动项owner 与承诺一一对应MikeSend out the updated roadmap、SarahSet up the kickoff with the design team、MikeDraft the budget memoJess 那句模糊的budget approval at some point 被正确排除——它没有明确的负责人和可执行承诺属于指令中要求忽略的vague group asks本轮运行中所有due_date均为None——因为原文只含相对日期by Friday、end of next week模型没有擅自把相对日期臆造为 ISO 日期。这段实测是理解嵌套抽取价值的最佳注脚列表的粒度由指令决定而不是由文本决定。模型能区分具名承诺与随口提议正是指令中判定标准起的作用。实战篇为每个字段附加置信度生产环境中的抽取结果往往需要分流高置信度字段直接入库低置信度字段路由到人工复核或更强模型。with_confidence.py演示了实现这一需求的经典模式——用共享的ConfidentField包装器包裹每个字段。包装器 Schemafrom typing import Literal, Optional class ConfidentField(BaseModel): value: Optional[str] None confidence: Literal[high, medium, low] Field( ..., descriptionConfidence in the extracted value ) class Contact(BaseModel): name: ConfidentField email: ConfidentField phone: ConfidentField company: ConfidentField title: ConfidentFieldConfidentField的confidence用Literal[high, medium, low]限定为三档枚举value可空。Contact的每个字段类型都是ConfidentField于是抽取结果自然变成值 置信度的二元组。置信度判定规则指令中把三档置信度的判定标准写得很具体保证模型输出口径一致instructions \ Extract contact information from the input. For each field: - value: what the text shows; null if the field is missing - confidence: high if explicit and unambiguous; medium if implied or partially formatted; low if guessed or ambiguous Use exactly what the text shows. Do not normalize or paraphrase. high文本中明确且无歧义medium隐含或格式不完整low猜测或存在歧义。实测结果置信度的语义验证TEST_LOG.md 记录的实测结果展示了置信度机制在两种极端输入下的表现样本 1完整签名五个字段全部返回confidencehigh值逐字一致样本 2ping mike on the eng teamname(mike, high)、title(eng team, medium)而email、phone、company均为(None, low)——即缺失字段以值为空 低置信度的形式显式表达。日志同时如实记录了本次运行中置信度判定的两个偏松之处namemike被标为high该称呼明显是昵称而非全名以及把eng team当作title抽取它是团队指代而非职务。这提醒我们置信度标定依赖模型的语义判断落地时需要用测试集持续校准判定规则必要时可把判定为 high 但下游复核有异议的案例反馈进指令中。源码级原理output_schema在 agno 中的实现位置三个示例都基于同一个机制Agent(..., output_schemaSomeModel)。理解它的底层行为有助于排查抽取质量问题参数定义libs/agno/agno/agent/agent.py 定义output_schema: Optional[Union[Type[BaseModel], Dict[str, Any]]] None并随parse_response、structured_outputs、use_json_mode、save_response_to_file等参数共同控制响应结构化的方式该参数在Agent.__init__agent.py 附近中被存入实例。结果容器RunOutput 是Agent.run()/Workflow.run()的统一返回类型content字段保存解析后的结构化结果同时携带run_id、session_id、metrics、messages、events等运行元数据方便后续追踪与观测。运行方法Agent.run()有多处重载定义见 agent.py分别对应不同输入形态示例中的agent.run(text)即字符串输入入口。一句话总结这套调用链指令instructions约束语义判定 →output_schema约束输出形状 →run()返回RunOutput→run.content携带解析好的 Pydantic 对象。三种模式对比与选型建议维度basic.pywith_confidence.pynested.py输出形状扁平单对象扁平对象每字段带置信度嵌套子对象列表字段可空Optional字段ConfidentField(value, confidence)必填/可空混合核心指令约束逐字抽取、缺失留空、不猜测三档置信度判定规则行动项判定标准、忽略模糊请求下游消费直接入库低置信度字段 → 人工复核拆分为多条业务记录实测状态PASSPASSPASS选型建议数据直接入库且信源质量高用basic.py的扁平模式需要人工复核兜底或分级路由用with_confidence.py的置信度包装器一份文本产出多条同类记录行动项、行项目、参会人用nested.py的嵌套列表需要字符级位置信息的标注参考 cookbook/data_labeling/_04_text_span_labeling只输出单个标签的分类任务参考 cookbook/data_labeling/_01_text_classification。小结文本结构化抽取是 agno 数据标注体系中最贴近生产的形态它以 Pydantic 模型定义输出形状以instructions定义语义判定边界以RunOutput.content返回可直接消费的结构化对象。_03_text_extraction目录的三个示例分别覆盖扁平单记录、嵌套列表和逐字段置信度三种真实需求且在gemini-3.5-flash agno 2.7.4 环境下全部通过实测——从抽取联系人信息到从会议记录拆出行动项再到低置信度字段路由人工复核一套调用链即可完整支撑。【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考