Agent Structured Output/ 智能体结构化输出

结构化输出（Structured Output）让智能体不只是"说人话"，而是能产出机器可直接消费的JSON、表格、YAML等格式数据——这是智能体从"聊天助手"升级为"自动化流水线的一个可编程节点"的关键能力。没有它，Agent 的输出需要额外写正则/解析器来提取，脆弱且易出错。

智能体实现结构化输出有三种主流方案，可靠性和成本依次递减：

**1. 约束解码（Constrained Decoding）—— 最可靠**

在 LLM 生成每个 token 时，实时修改 logits 分布，将不合法的 token 概率置零（或极小），强制输出符合给定的 JSON Schema / Regex / Grammar。代表实现：llama.cpp 的 grammar、Outlines、Guidance。优点：100% 格式正确。缺点：部分推理引擎不支持，引入微小延迟。

**2. 工具调用即结构化（Tool-call as Structured Output）—— 最实用**

利用 Function Calling / Tool Use 的强制参数 schema 天然获得结构化输出。模型在训练时已学会填充 tool_call 的 arguments JSON 字段，格式正确率极高。OpenAI/Anthropic 的 tool_choice: "required" 可强制走工具路径。这是目前生产环境最主流的方案。

**3. 提示词引导 + 后处理（Prompt + Post-Parse）—— 最灵活**

在 system prompt 中要求模型输出 JSON，生成后用 json.loads / pydantic 解析，失败时重试。成本最低，但对弱模型不可靠。常用 Instructor / Marvin / LangChain OutputParser 封装重试逻辑。

• 测试一：Schema 符合率对比

• 操作：用同一段复杂 JSON Schema（含嵌套对象、数组、枚举、$ref），分别测试 (a) 纯 Prompt 引导 (b) Instructor 库 (c) Outlines 约束解码三种方式的输出格式通过率

• 工具：Instructor（https://github.com/jxnl/instructor）+ Outlines（https://github.com/dottxt-ai/outlines）

• 指标：100条测试的 JSON.parse 成功率、Schema.validate 通过率

• 测试二：复杂嵌套压力测试

• 操作：构建一个 5 层嵌套 + 20 个字段的 Schema（模拟真实 API 响应），测试各方案下输出完全合规的比例

• 工具：Pydantic v2 定义模型，用 model_json_schema() 生成 Schema

• 指标：嵌套层级 vs 成功率的衰减曲线、平均重试次数

• 测试三：Token 开销对比

• 操作：对同一 Schema，对比 tool-call 模式、Instructor、纯 Prompt 三种方案的平均输入/输出 token 消耗

• 工具：OpenAI token counter + LangSmith tracing

• 指标：总 token cost、结构化 overhead 占比

1. **别迷信 Prompt 约束**："Please output valid JSON" 对小模型（<7B）几乎无效。即使是 GPT-4，在复杂嵌套 Schema 下纯 Prompt 方案也有 5-15% 的格式错误率。生产环境至少用 Instructor 级别的封装，关键路径用 constrained decoding。

1. **嵌套过深导致幻觉键名**：当 Schema 超过 3 层嵌套、字段超过 15 个时，模型容易"发明"不在 Schema 中的键名，或遗漏必需字段。缓解方案：用 $ref 扁平化 Schema，或在 prompt 中预填一个合法的空骨架 JSON 让模型填充而非从头生成。

1. **结构化输出的 Token 膨胀不可忽视**：JSON 格式天然冗长（引号、花括号、逗号）。同样的语义信息，JSON 输出比纯文本多 30-50% token。如果 Agent 需要在循环中反复生成结构化输出，成本会快速攀升。建议：对高频调用用更紧凑的格式（如 CSV、自定义 DSL），仅在最终出口做结构转换。

• OpenAI 官方 Structured Outputs 指南: https://platform.openai.com/docs/guides/structured-outputs

• Instructor — 用 Pydantic 定义结构，自动处理重试/验证: https://github.com/jxnl/instructor

• Outlines — 最成熟的约束解码框架，支持 JSON Schema/Regex/Grammar: https://github.com/dottxt-ai/outlines

• BAML — 新一代结构化输出 DSL，编译到多种 LLM 后端: https://github.com/BoundaryML/baml