Laravel AI 生产级应用架构：智能体编排、流式响应与检索增强生成实战
Laravel 官方将人工智能能力解耦为三个独立模块，分别服务于业务功能集成、本地开发辅助以及外部协议交互。掌握这三者的协作边界，是构建高可用 AI 驱动型应用的基础。
核心组件定位
- AI SDK：面向产品端的运行时库，提供统一的接口封装智能体（Agents）、工具调用、结构化输出、多模态处理及向量检索。
- Boost：开发期依赖包，通过 MCP 服务器与项目专属指南，使 Cursor 或 Claude Code 等编辑器能够感知路由、数据库结构与配置。
- MCP 插件：用于将现有 Laravel 应用转化为标准的 MCP Server，对外暴露受权限保护的工具、资源与提示词模板。
环境初始化与依赖配置
引入核心包
bash
composer require laravel/ai
发布配置与数据表
bash
php artisan vendor:publish --provider="Laravel\\Ai\\AiServiceProvider"
php artisan migrate
执行后会自动创建 agent_conversations 与 agent_conversation_messages 两张表，用于持久化对话上下文。
密钥管理
在 .env 中定义各厂商的凭证：
OPENAI_API_KEY=sk-xxx
ANTHROPIC_API_KEY=sk-ant-xxx
GEMINI_API_KEY=AIza...
OLLAMA_API_KEY=
所有键值均映射至 config/ai.php。若需代理转发或部署私有模型网关，可自定义端点：
'providers' => [
'custom_llm' => [
'driver' => 'openai',
'key' => env('CUSTOM_KEY'),
'url' => env('LLM_GATEWAY_URL', 'https://proxy.internal/v1'),
],
],
框架原生支持 OpenAI、Anthropic、Groq 及 OpenRouter 等厂商的路由覆盖。
智能体（Agent）类设计
SDK 采用面向对象范式组织指令、上下文与输出约束。建议通过命令行脚手架快速生成基类：
bash
php artisan make:agent ReviewAnalyst --structured
实现指令集与方法规范：
<?php
namespace App\Ai\Agents;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Promptable;
class ReviewAnalyst implements Agent
{
use Promptable;
public function getInstructions(): string
{
return '你是一名资深内容审核专员，负责评估用户提交文本的合规性与情感倾向，并返回标准 JSON 结构。';
}
}
在实际请求中注入该实例并发起调用：
use App\Ai\Agents\ReviewAnalyst;
use Illuminate\Routing\Route;
Route::post('/evaluate', function () {
$pipeline = new ReviewAnalyst();
$result = $pipeline->prompt('评估以下评论：产品包装破损严重...');
return response()->json([
'status_code' => (int) $result,
'raw_output' => (string) $result
]);
});
开启结构化输出可大幅降低大模型响应波动，适用于字段校验严格的场景。
异步任务调度与实时推送
对于耗时较长的推理任务，推荐采用队列模式避免阻塞主进程：
use App\Ai\Agents\ReviewAnalyst;
use Laravel\Ai\Responses\AgentResponse;
use Illuminate\Http\Request;
use Throwable;
Route::post('/async-eval', function (Request $request) {
$transcript = $request->input('text');
return (new ReviewAnalyst)
->queue($transcript)
->then(function (AgentResponse $payload) {
// 处理成功回调，写入日志或更新状态机
})
->catch(function (Throwable $error) {
// 记录异常信息并降级至人工审核
});
});
若前端需要打字机效果或 SSE 实时渲染，可切换为流式 API：
use Laravel\Ai\Responses\StreamedAgentResponse;
Route::get('/live-feedback', function () {
$engine = new ReviewAnalyst();
return $engine
->stream('开始分析文档段落...')
->then(fn (StreamedAgentResponse $stream) => [
'tokens' => $stream->text,
'metrics' => $stream->usage,
'raw_events' => $stream->events
]);
});
扩展工具链与安全沙箱
Agent 可通过注册 Tool 实例获得外部系统操作能力。框架内置了网络检索与文件检索组件：
use Laravel\Ai\Providers\Tools\WebSearch;
use Laravel\Ai\Providers\Tools\WebFetch;
use Laravel\Ai\Providers\Tools\FileSearch;
class ReviewAnalyst implements Agent
{
use Promptable;
public function tools(): iterable
{
return [
new WebSearch(limit: 5),
new WebFetch(timeout: 30),
new FileSearch(
stores: ['docs_v2', 'legacy_kb'],
filter_meta: ['category' => 'technical']
),
];
}
public function getInstructions(): string { /* ... */ }
}
FileSearch 底层对接 Provider 的向量存储，支持多索引并联与元数据过滤，是实现垂直领域知识库检索的标准方案。
检索增强生成（RAG）落地路径
当前版本提供两种主流架构策略：
策略一：基于关系型数据库的自托管向量查询
利用 PostgreSQL 的 pgvector 扩展将 Embedding 直接存入业务表：
Schema::ensureVectorExtensionExists();
Schema::create('knowledge_base', function ($table) {
$table->id();
$table->string('slug');
$table->longText('body');
$table->vector('dense_vector', dimensions: 1536);
$table->timestamps();
});
// 添加 HNSW 索引以加速余弦相似度匹配
$table->vector('dense_vector', dimensions: 1536)->index();
查询时需结合语义分词器提取特征，再通过原生 SQL 进行 Top-K 召回。
策略二：托管式向量云 + 客户端检索
使用 Provider 提供的 Vector Store 服务上传非结构化文档。Agent 内部自动完成 Chunking 与向量化，调用时仅需传递 FileSearch 即可触发跨文档联合推理。
多模态处理与信息重排序
框架提供高层 Facade 简化媒体流交互：
图像生成与编辑
use Laravel\Ai\Image;
use Laravel\Ai\Files;
$render = Image::of('极简主义风格的咖啡杯设计图')
->quality('hd')
->orientation('wide')
->timeout(90)
->generate();
// 风格迁移示例
$remix = Image::of('转换为赛博朋克霓虹色调')
->attachments([Files::Image::fromStorage('base_art.png')])
->generate();
音频合成与语音转写
use Laravel\Ai\Audio;
use Laravel\Ai\Transcription;
$speech = Audio::of('欢迎使用下一代智能工作台')->generate();
$text = Transcription::fromStorage('meeting_recording.wav')->generate();
结果重排序（Reranking） 在检索管道末尾插入重排序节点可显著提升相关性：
use Laravel\Ai\Reranking;
$candidates = [
'Django 是 Python 全栈框架',
'Laravel 专注于 PHP 企业级开发',
'Vue.js 仅处理前端视图层'
];
$ranked = Reranking::of($candidates)->rerank('PHP Web 解决方案');
echo $ranked->first()->document; // 优先返回最相关项
不同特性的厂商覆盖率存在差异，建议在生产环境中统一抽象适配层。
多云容灾与流量降级
面对限流（Rate Limit）或服务宕机，框架支持声明式故障转移：
$response = (new ReviewAnalyst)->prompt(
query: '分析用户投诉工单...',
fallback_chain: ['openai', 'anthropic', 'gemini']
);
SDK 会按优先级依次尝试，失败则自动跃迁至下一节点，开发者无需编写额外的重试中间件或健康检查逻辑。
Boost：本地代码库上下文注入
Boost 作为 --dev 依赖安装后可无缝接入现代 IDE：
bash
composer require laravel/boost --dev
php artisan boost:install
安装过程会根据目标编辑器自动生成规则文件。当调用补全或重构指令时，Boost 会启动后台 MCP 进程扫描路由定义、Eloquent 模型定义、环境变量映射及 Artisan 命令签名。这使得代码建议严格对齐项目规范，彻底消除"幻觉式"拼凑代码。
MCP Server：对外暴露受控业务动作
若需允许外部 AI Client 安全调用内部逻辑，可采用 MVC 架构配合 MCP 协议注册端点：
- 定义
Tool类，明确输入校验 Schema 与执行 Handler。 - 挂载受鉴权保护的 HTTP 路由，通常结合 Sanctum 或 OAuth2 签发短期 Token。
- 提供
Resource接口只读导出报表，使用Prompt模板固化常用工作流。
典型应用场景包括：客服机器人自动创建工单、数据分析 Agent 查询脱敏指标、自动化运维脚本触发等。通过显式声明边界，可杜绝大模型直连数据库带来的越权风险。
