企业官网建设流程全解析

Laravel AI SDK 是 Laravel 官方推出的 AI 开发工具包，它把 OpenAI、Anthropic、Gemini 等十多家 AI 提供商封装成一套统一、简洁的 API。你只需写一份代码，就能完成文本对话、图像生成、语音合成与转写、向量嵌入，甚至构建能"动手干活"的 AI Agent——切换提供商时几乎不用改业务逻辑。

如果你正在用 Laravel 做项目，又头疼各家 AI 接口写法各不相同，这篇文章会带你用最少的代码跑通第一条 AI 对话，并理清它的核心概念。

为什么需要一套"统一 API"

不同 AI 提供商的接口风格差异很大：请求参数、鉴权方式、响应结构各不相同。如果直接调用，每新增一家就要重写一遍逻辑，切换模型时更是牵一发动全身。

Laravel AI SDK 解决的正是这个问题：

• 🧩一套接口，多家后端：文本、图像、音频、向量等操作走同一套语法。
• 🤖Agent 优先：内置 Agent（智能体）与 Tool（工具）模型，让 AI 能调用你的函数完成任务。
• 🔄平滑切换与故障转移：可以配置多个提供商，一家失败自动切到下一家。
• 🧪友好的测试与假数据支持：开发期可用 Fake 桩，不消耗真实 API 额度。
• 🎛️贴合 Laravel 习惯：配置、门面、控制台命令、迁移，都遵循 Laravel 生态惯例。

3 步快速安装 Laravel AI SDK

Laravel AI SDK 要求PHP 8.3+与Laravel 12/13。

第 1 步：安装官方包

composer require laravel/ai

第 2 步：配置提供商密钥

在.env中填入你要用的 API Key，例如：

OPENAI_API_KEY=sk-xxxx ANTHROPIC_API_KEY=sk-ant-xxxx GEMINI_API_KEY=xxxx

各驱动的名称、密钥与环境变量，都在配置文件 config/ai.php 中集中定义，默认文本提供商为openai：

'default' => 'openai', 'providers' => [ 'anthropic' => [ 'driver' => 'anthropic', 'key' => env('ANTHROPIC_API_KEY'), ], // ... 其他提供商 ],

第 3 步：跑通第一句话

安装完成后，用内置的命令行聊天命令即可立刻验证（见 src/Console/Commands/ChatCommand.php）：

php artisan agent:chat

用几行代码连接你的第一个 AI 提供商

SDK 提供了一个全局助手函数agent()（定义在 functions.php），它能快速创建一个"即席"Agent，再调用prompt()发起对话：

use function Laravel\Ai\agent; $response = agent('You are a helpful assistant.') ->prompt('用一句话介绍一下 Laravel 框架'); echo $response->text;

prompt()方法由Promptable特性提供（源码见 src/Promptable.php），除了直接拿文本，还能拿到消息历史、用量统计、执行步骤等结构化信息。

切换提供商：只改两个参数

想换成 Anthropic 或 Gemini？只要在调用时指定provider与model即可，业务代码无需重写：

$response = agent() ->prompt('写一首关于大海的小诗', provider: 'anthropic');

这一套"多实例 + 门面"的调度逻辑由 src/AiManager.php 统一管理，Ai门面（src/Ai.php）就是它的外壳。

支持十多家 AI 提供商，自由切换

SDK 内置了覆盖文本、图像、音频、向量等多类能力的驱动。常见的包括：

各驱动实现放在 src/Providers/ 目录，底层请求适配层在 src/Gateway/ 目录。

故障转移：一家挂了自动切下一家

你既可以指定单一提供商，也可以传入一个候选列表。当某家提供商返回可恢复的错误（如限流、过载）时，SDK 会自动尝试下一家，并触发AgentFailedOver事件，保证对话尽量不中断——这对生产环境非常友好。

构建能"动手"的 AI Agent：工具调用

光会聊天还不够。真正的亮点是Agent + Tool：AI 可以调用你写的 PHP 函数来查数据、发邮件、操作文件，从而完成真实任务。

创建一个工具类只需一条脚手架命令（见 src/Console/Commands/MakeToolCommand.php）：

php artisan make:tool Weather

生成的骨架见 stubs/tool.stub，核心是三个方法：description()说明用途、schema()声明参数、handle()执行逻辑。仓库里的示例工具 workbench/app/Tools/Weather.php 展示了完整写法。

然后把工具挂到 Agent 上即可。参考 workbench/app/Agents/Assistant.php：

class Assistant implements Agent, HasTools { use Promptable; public function instructions(): string { return '你是一个乐于助人的助手，请优先使用可用工具，而不是凭记忆回答。'; } public function tools(): array { return [new Weather]; } }

之后 AI 会自己判断"用户问天气 → 该调用 Weather 工具"，多步执行完成后给出最终答复。

结构化输出：让 AI 返回可直接解析的数据

当需要把 AI 结果存入数据库或传给前端时，自由文本不够用。SDK 支持结构化输出：你声明一个 Schema，AI 就会按格式返回。

php artisan make:assistant --structured

对应脚手架见 stubs/structured-agent.stub。Agent 实现HasStructuredOutput接口并在schema()中描述字段，调用后即可从响应中直接取到强类型数据，省去写解析逻辑。

此外，SDK 还内置了开箱即用的 Agent，例如摘要助手 src/Agents/SummarizeAgent.php，通过#[UseCheapestModel]属性自动选用最划算的模型——这类属性（#[Model]、#[Provider]、#[Temperature]等）定义在 src/Attributes/，让配置意图直接写在类上，一目了然。

图像、语音、向量：不止会聊天

同一套 API 还能覆盖多模态场景：

• 🎨图像生成：指定图像提供商即可产出图片。
• 🎙️语音合成 / 转写：文字转语音、语音转文字各走统一入口。
• 📐向量嵌入与重排：为 RAG（检索增强）应用提供向量与排序能力。
• 📁文件与存储：内置文件上传、文档解析、知识库存储等能力（见 src/Files/ 与 src/Store.php）。

不同能力的默认提供商也可在 config/ai.php 中分别指定，例如图像默认走gemini、转写默认走openai，各取所长。

内置脚手架与生态，开箱即用

除了make:agent/make:tool，SDK 还内置了 Agent 中间件脚手架（php artisan make:agent-middleware，命令见 src/Console/Commands/MakeAgentMiddlewareCommand.php）、数据库会话迁移（database/migrations/2026_01_11_000001_create_agent_conversations_table.php）以及会话记忆能力（RemembersConversations，让 Agent 记住历史对话）。

它还支持MCP（Model Context Protocol）工具、技能（Skills）加载，以及面向前端的流式输出协议，方便把实时回答推送到页面。

适合谁？如何上手

• Laravel 开发者：想给现有项目快速接入 AI，又不想被各家 SDK 绑定。
• 独立开发者：用 Agent + Tool 快速搭出能执行真实任务的智能助手。
• 多模型用户：希望按成本、速度、能力在不同提供商之间灵活切换。

建议的上手路径：

1. 按前文 3 步安装并配置好一个提供商密钥；
2. 用agent()->prompt()跑通第一条对话；
3. 用make:tool加一个工具，体验 Agent 的自动调用；
4. 需要强类型数据时，再加结构化输出。

小结

Laravel AI SDK 的价值在于"统一"：一套简洁 API 连接十多家 AI 提供商，既能聊天问答，也能生成图像与语音、构建能执行任务的 Agent，并在切换模型与故障转移上省心省力。对 Laravel 开发者来说，它是把 AI 能力真正落到业务代码里的一条快速通道。