用 Pydantic 约束 AI 输出：AgentScope 结构化输出实战笔记

用 Pydantic 约束 AI 输出AgentScope 结构化输出实战笔记【免费下载链接】agentscopeBuild and run agents you can see, understand and trust.项目地址: https://gitcode.com/GitHub_Trending/ag/agentscope读完本篇你会用 AgentScope 的structured_schema参数让模型直接吐出符合 Pydantic 校验的 dict省掉正则解析和格式修补。你将带走什么不再手动正则拆模型输出校验过的数据直接躺在res.structured_output里看懂「Schema 注入工具调用 校验重试」的机制出问题时知道去哪查掌握三个高频技巧Literal限枚举、Optional接缺失值、ge/le锁数值范围知道哪几类字段写法最容易翻车以及怎么改一次过 它到底怎么工作Schema 变工具调用给reply()传入 Pydantic 类后AgentScope 会把它编译成一个内置工具GenerateStructuredOutput工具的入参 schema 就是你的模型定义。回复收尾时模型必须调用该工具参数经model_validate校验不通过时错误信息原路返回模型带着报错重试直到通过。最终结果以 dict 形式挂在最终消息的structured_output属性上字段和类型跟你定义的一致。️ 最小可运行路径三步拿到校验过的 dict① 配置 DashScope 密钥export DASHSCOPE_API_KEYyour_dashscope_api_key密钥放进环境变量即可模型构造函数从os.environ读取不必写死在代码里。② 跑通示例核心就四步定义 Schema、建 Agent、带structured_schema回复、打印结果。from pydantic import BaseModel, Field from agentscope.agent import Agent from agentscope.message import UserMsg class PersonCard(BaseModel): name: str Field(descriptionFull name) age: int Field(descriptionAge in years, ge0, le120) agent Agent(nameFriday, system_promptYou are helpful., modelmodel) # ...model instance omitted... res await agent.reply( UserMsg(nameuser, contentIntroduce Albert Einstein), structured_schemaPersonCard, ) print(res.structured_output)真实输出示例节选{name: Albert Einstein, age: 76}拿到的是 dict不是 JSON 字符串age已是int可以直接入库。换个姿势用Literal 限枚举、Optional 接缺失值表单类抽取让模型从对话里挑一个固定选项别让它自创答案。class FruitPick(BaseModel): choice: Literal[apple, banana, orange] # only these 3 values note: Optional[str] None contact: Optional[EmailStr] None效果choice只能是三个值之一缺失的备注和邮箱自动落到None不会触发校验失败。工具结果转表先让 Agent 用搜索、读文件等工具收集信息最后用带嵌套字段的 Schema 收尾产出可直接渲染的表格数据Schema 里放什么字段表头就是什么省掉后处理。⚠️ 踩坑清单写 Schema 时最容易翻车的五处字段description写得含糊比如只写 the name → 模型会自由发挥。写上取值范围、格式示例约束才落得下去。全部字段设为必填 → 原文信息不全时校验直接报错、反复重试。缺省值多的字段改用Optional[...] None。拿到res.structured_output后又json.loads一遍 → 它已经是 dict 了二次解析只会报错。数值字段不加ge/le→ 模型可能给出 200 岁这种合法 int。范围约束交给Field(ge0, le120)。校验失败以为整轮白跑 → 实际上错误会回传给模型触发重试日志里看到ValidationError不必慌连续多次才需要回头改 Schema。 延伸资源src/agentscope/agent/_structured_output_tool.py内置校验工具源码重试与报错逻辑都在这tests/agent_structured_output_test.py端到端测试用例含默认值填充、校验失败分支examples/可运行的完整示例目录配合本文的最小路径对照着跑Schema 越具体输出越听话——挑一个你最常解析的字段现在就改成 Pydantic 模型跑一遍。【免费下载链接】agentscopeBuild and run agents you can see, understand and trust.项目地址: https://gitcode.com/GitHub_Trending/ag/agentscope创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考