告别手写正则解析：Laravel AI 结构化输出（Structured Output）实战教程

使用Laravel AI（laravel/ai）的结构化输出功能，你可以让 AI 直接返回符合 JSON Schema 的数组或对象，彻底告别正则匹配、字符串截取这些脆弱的解析方式。本文用最短路径带你跑通：创建 Agent → 定义 Schema → 取出结构化数据，全程不到 10 分钟。

为什么你需要结构化输出？

调用 AI 做意图识别、信息抽取时，常见的"老办法"是这样的：

让 AI 返回固定格式的文本，然后用preg_match一点点抠出字段……

这种方式问题很多：AI 偶尔多一个空格、换行、中英文标点混用，正则就可能全线崩溃，你只能不断修补。

而Structured Output的思路完全不同：

Laravel AI 将 OpenAI、Anthropic、Gemini、Bedrock、DeepSeek 等十几个 Provider 的结构化输出统一成了同一套 API——你写一份 Schema，所有供应商通用。

准备工作

先安装 Laravel AI 包并配置至少一个 Provider 的 API Key（以 OpenAI 为例，配置位于config/ai.php）：

composer require laravel/ai

// config/ai.php 'providers' => [ 'openai' => [ 'key' => env('OPENAI_KEY'), ], ],

完整配置参考仓库内的 config/ai.php。

第一步：一键生成结构化 Agent

Laravel AI 内置了make:agent命令，加上--structured参数（或缩写-s）即可生成带结构化输出的 Agent 骨架（命令定义见 src/Console/Commands/MakeAgentCommand.php）：

php artisan make:agent SummarizeAgent --structured

命令会在app/Ai/Agents下创建类文件，其模板来自 stubs/structured-agent.stub。生成的类实现了Agent与HasStructuredOutput两个接口，核心就是一个schema()方法：

use Illuminate\Contracts\JsonSchema\JsonSchema; use Laravel\Ai\Contracts\Agent; use Laravel\Ai\Contracts\HasStructuredOutput; use Laravel\Ai\Promptable; class SummarizeAgent implements Agent, HasStructuredOutput { use Promptable; public function instructions(): string { return '你是文章摘要助手，请提取标题、摘要和关键词。'; } public function schema(JsonSchema $schema): array { return [ 'title' => $schema->string()->required(), 'summary' => $schema->string()->required(), 'keywords' => $schema->array()->items($schema->string())->required(), ]; } }

HasStructuredOutput接口只有一个方法（源码见 src/Contracts/HasStructuredOutput.php）：

public function schema(JsonSchema $schema): array;

$schema是 Laravel 提供的 JsonSchema 类型工厂，string()、array()、number()、object()、boolean()等方法链式声明字段类型，.required()标记必填。你不再需要在 Prompt 里写"请严格按TITLE: xxx的格式输出"——格式由 Schema 声明式地交给 AI 执行。

💡 官方测试里的一个真实示例是"元素符号抽取"，schema()里只有一行'symbol' => $schema->string()->required()，非常简洁，见 tests/Fixtures/Agents/StructuredAgent.php。

第二步：调用 Agent 并取回结构化数据

Agent 创建完成后，调用它只需要一行：

$response = (new SummarizeAgent)->prompt( '请总结这篇文章：' . $article );

只要 Agent 实现了HasStructuredOutput，SDK 的文本生成流程会自动检测并调用schema()（判定逻辑在 src/Providers/Concerns/GeneratesText.php），把解析结果包装成StructuredAgentResponse。这个响应对数据结构做了全面"数组化"（源码见 src/Responses/StructuredAgentResponse.php）：

// 像数组一样按字段取 $summary = $response['summary']; // 或者直接整个转成数组 / JSON $data = $response->toArray(); $json = $response->toJson();

没有任何json_decode外层文本，没有正则，$response['title']直接就是干净的字符串。

底层发生了什么？

1. 请求阶段：SDK 把schema()返回的定义转成标准 JSON Schema，传给 Provider。支持原生结构化输出的供应商（如 Anthropic）会走专用通道，见 src/Gateway/Anthropic/Concerns/BuildsTextRequests.php。
2. 响应阶段：Gateway 解析 AI 返回，各 Provider 通过共享的DecodesStructuredOutput特性统一解码为 PHP 数组（源码见 src/Gateway/Concerns/DecodesStructuredOutput.php）。
3. 封装阶段：结果注入StructuredAgentResponse，供你按字段访问。

进阶技巧

1. 用#[Strict]开启严格模式

给 Agent 类加上Strict属性（定义见 src/Attributes/Strict.php），SDK 会在 Schema 上声明additionalProperties: false，AI 输出的字段一个都不能多、一个都不能少：

#[Strict] class SummarizeAgent implements Agent, HasStructuredOutput { // ... }

ObjectSchema也会递归地给所有嵌套对象关闭额外属性（逻辑见 src/ObjectSchema.php）。

2. 指定模型与 Provider

通过属性快速绑定：

#[Model('gpt-4o')] #[Provider('openai')]

属性定义位于 src/Attributes/Model.php 与 src/Attributes/Provider.php，更多可选属性（Temperature、MaxTokens、Timeout等）都在 src/Attributes/ 目录下。

3. 匿名 Agent 也能结构化输出

不想写类？可以直接用StructuredAnonymousAgent内联定义（源码见 src/StructuredAnonymousAgent.php），适合在 Controller 里快速原型验证。

4. 查看原始响应做调试

$response->raw是底层 HTTP 响应对象，排查 Provider 层面的问题时非常有用——测试代码中的用法可参考 tests/Feature/Providers/Anthropic/RawResponseTest.php。

常见问题 FAQ

Q：哪些 Provider 支持结构化输出？A：SDK 覆盖了 OpenAI、Anthropic、Gemini、Bedrock、Cohere、DeepSeek、Groq、Mistral、Ollama、OpenRouter、XAI 等主流供应商，Gateway 目录下的ParsesTextResponses均集成了结构化解码，目录见 src/Gateway/。

Q：结构化输出会影响工具调用（Tools）吗？A：不会。结构化输出与HasTools接口正交，Agent 可以同时声明工具和 Schema，SDK 的多步循环（TextGenerationLoop）会一并处理。

Q：流式响应支持吗？A：支持。stream()同样会识别HasStructuredOutput，逻辑在 src/Providers/Concerns/StreamsText.php。

Q：Schema 里能定义嵌套对象和数组吗？A：可以。类型工厂支持object()、array()->items(...)等嵌套结构，且additionalProperties会被递归禁用，见 src/ObjectSchema.php。

小结

• 用php artisan make:agent 名称 --structured生成骨架
• 在schema()中用类型工厂声明字段，Schema 即契约
• 调用prompt()后，$response['字段名']直接取值，零解析代码
• 加#[Strict]可获得最严格的输出约束

从"正则 + 字符串"到"Schema + 数组"，这就是 Laravel AI 结构化输出带给你的确定性。

延伸阅读

• 接口定义：src/Contracts/HasStructuredOutput.php
• 响应封装：src/Responses/StructuredAgentResponse.php
• 命令实现：src/Console/Commands/MakeAgentCommand.php
• 官方文档：docs/official.md