Laravel 12 原生 AI 开发工具包深度解析
Laravel 框架一直致力于提升开发效率，提供优雅的语法处理各类任务。在 Laravel 12 中，官方推出了原生的 Laravel AI SDK，为构建智能化应用提供了一站式解决方案。无需再为接入 OpenAI、Anthropic 或 Gemini 等不同厂商而分别引入第三方库，也无需手动维护对话上下文。
SDK 核心概述
该工具包提供了一套统一且表达力强的 API，支持对接主流大模型供应商（如 OpenAI、Anthropic、Gemini、Mistral 等）。开发者无需编写原生的 HTTP 请求或学习各厂商不同的 SDK 用法，即可实现以下功能：
- 构建智能体（聊天机器人、虚拟助手）。
- 处理结构化数据输出（JSON）。
- 图像生成与视觉分析。
- 语音合成与识别（TTS/STT）。
- 文本嵌入与重排序。
环境准备与安装
通过 Composer 即可快速安装此官方扩展包：
composer require laravel/ai安装完成后，发布配置文件并执行数据库迁移。迁移会自动创建 ai_dialogues 和 ai_dialogue_records 数据表，用于持久化聊天记录。
php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider"
php artisan migrate相关凭证配置位于 config/ai.php 或 .env 环境变量中，填入对应的 API Key 即可启用服务。
核心机制：智能体
在本 SDK 中，最基础的抽象单元是 Agent（智能体）。它是一个封装了提示词、工具及上下文的 PHP 类。使用 Artisan 命令可快速创建：
php artisan make:agent MarketingExpert该命令会在指定目录生成类文件，允许你定义其行为逻辑和角色设定。重构后的示例代码如下：
namespace App\Ai\Agents;
use App\Models\User;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Promptable;
class MarketingExpert implements Agent
{
use Promptable;
public function __construct(public User $authUser) {}
/**
* 定义智能体的核心行为准则
*/
public function instructions(): string
{
return '你是一位资深的营销顾问。请评估用户的策略并提供优化建议。';
}
}调用时，只需实例化该类并触发 prompt 方法：
use App\Ai\Agents\MarketingExpert;
$feedback = (new MarketingExpert($authUser))->prompt('如何提高广告转化率？');
echo $feedback;内置高级特性
1. 自动对话记忆
上下文管理一直是聊天机器人的痛点。SDK 提供了 RemembersConversations 特性，可自动从数据库读取历史消息并追加新记录。
use Laravel\Ai\Concerns\RemembersConversations;
class CustomerSupportBot implements Agent, Conversational
{
use Promptable, RemembersConversations;
// ...
}
// 调用方式
$reply = (new CustomerSupportBot)->forUser($authUser)->prompt('我的退款进度如何？');2. 结构化数据输出
当需要大模型返回可供代码直接处理的数组而非纯文本时，可实现 HasStructuredOutput 接口。通过流式构造器定义数据模式，SDK 将保证返回合规的 JSON。
public function schema(JsonSchema $schema): array
{
return [
'emotion' => $schema->string()->enum(['happy', 'angry']),
'confidence' => $schema->integer()->min(0)->max(100),
];
}3. 多模态与附件支持
若需解析图片或文档，可直接在 prompt 方法中传入附件。SDK 会处理底层复杂的文件上传逻辑。
use Laravel\Ai\Files;
$analysis = (new DocumentParser)->prompt(
'请提取此图表中的关键指标',
attachments: [
Files\Image::fromPath('/storage/reports/chart.png')
]
);4. 响应流式输出
为了提升交互体验，通常需要逐字输出模型生成的文本。SDK 提供了 stream() 方法，与 Server-Sent Events (SSE) 配合极佳。
Route::get('/stream-chat', function () {
return (new MarketingExpert)->stream('简述内容营销的趋势。');
});