Laravel AI SDK 正式發佈

Laravel AI SDK 今天正式發佈了。這個由 Taylor Otwell 開發數月的官方包，為 Laravel 應用提供了一套統一的 AI 交互接口，覆蓋文本對話、圖像生成、語音合成、語音轉錄、向量嵌入等場景，支持 OpenAI、Anthropic、Gemini、Groq、xAI 等主流服務商。

安裝方式和其他 Laravel 官方包一樣簡單：

composer require laravel/ai

文檔跟上了 Laravel 中文文檔 - AI SDK

Agent：核心交互單元

SDK 的核心概念是 Agent。每個 Agent 是一個 PHP 類，封裝了系統指令、對話上下文、工具和輸出格式。可以把它理解為一個專用助手——銷售教練、文檔分析器、客服機器人——配置一次，隨處調用。

通過 Artisan 命令創建：

php artisan make:agent SalesCoach

生成的類實現 Agent 接口，定義 instructions() 方法提供系統提示詞，然後調用 prompt() 發起對話：

$response = SalesCoach::make(user: $user)
    ->prompt('分析這段銷售錄音...');

return (string) $response;

prompt() 方法支持在調用時切換服務商和模型：

$response = (new SalesCoach)->prompt(
    '分析這段銷售錄音...',
    provider: 'anthropic',
    model: 'claude-haiku-4-5-20251001',
    timeout: 120,
);

如果不想創建專門的類，也可以用匿名 Agent 快速調用：

use function Laravel\Ai\{agent};

$response = agent(
    instructions: 'You are an expert at software development.',
)->prompt('Tell me about Laravel');

結構化輸出

Agent 可以返回結構化數據，而不僅僅是純文本。實現 HasStructuredOutput 接口，定義 schema() 方法即可：

public function schema(JsonSchema $schema): array
{
    return [
        'feedback' => $schema->string()->required(),
        'score' => $schema->integer()->min(1)->max(10)->required(),
    ];
}

調用後直接當數組用：

$response = (new SalesCoach)->prompt('分析這段錄音...');

return $response['score']; // 8

對話記憶

Agent 支持自動持久化對話歷史。使用 RemembersConversations trait 後，SDK 會自動將對話存入數據庫，後續可以通過 continue() 方法繼續之前的對話：

// 開始新對話
$response = (new SalesCoach)->forUser($user)->prompt('你好！');
$conversationId = $response->conversationId;

// 繼續對話
$response = (new SalesCoach)
    ->continue($conversationId, as: $user)
    ->prompt('接着剛才的話題...');

工具系統

Agent 可以使用工具來擴展能力。通過 make:tool 命令創建工具類，定義輸入 schema 和 handle() 方法：

class RandomNumberGenerator implements Tool
{
    public function description(): string
    {
        return '生成加密安全的隨機數。';
    }

    public function handle(Request $request): string
    {
        return (string) random_int($request['min'], $request['max']);
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'min' => $schema->integer()->min(0)->required(),
            'max' => $schema->integer()->required(),
        ];
    }
}

SDK 還內置了幾個服務商級別的工具：

• WebSearch — 讓 Agent 搜索網頁，支持 Anthropic、OpenAI、Gemini
• WebFetch — 讓 Agent 抓取網頁內容，支持 Anthropic、Gemini
• FileSearch — 在向量存儲中搜索文件，支持 OpenAI、Gemini
• SimilaritySearch — 基於 Eloquent 模型的向量相似度搜索，用於 RAG 場景

流式響應與廣播

對於需要實時輸出的場景，Agent 支持流式響應。返回值可以直接作為路由響應，自動發送 SSE：

Route::get('/coach', function () {
    return (new SalesCoach)->stream('分析這段錄音...');
});

流式事件還可以通過 Laravel Broadcasting 廣播到前端頻道，或者使用 Vercel AI SDK 協議與前端框架對接：

return (new SalesCoach)
    ->stream('分析這段錄音...')
    ->usingVercelDataProtocol();

隊列處理

耗時的 AI 請求可以推入隊列在後台處理：

(new SalesCoach)
    ->queue($request->input('transcript'))
    ->then(function (AgentResponse $response) {
        // 處理響應...
    })
    ->catch(function (Throwable $e) {
        // 處理異常...
    });

圖像生成

Image 類提供了簡潔的圖像生成接口，支持 OpenAI、Gemini 和 xAI：

use Laravel\Ai\Image;

$image = Image::of('廚房枱面上的甜甜圈')
    ->quality('high')
    ->landscape()
    ->generate();

$path = $image->store();

支持附加參考圖像進行風格遷移，也可以推入隊列異步生成。

音頻與轉錄

語音合成（TTS）和語音轉錄（STT）同樣被納入 SDK：

use Laravel\Ai\Audio;
use Laravel\Ai\Transcription;

// 文字轉語音
$audio = Audio::of('I love coding with Laravel.')
    ->female()
    ->instructions('用海盜的語氣説')
    ->generate();

// 語音轉文字
$transcript = Transcription::fromStorage('audio.mp3')
    ->diarize() // 按説話人分段
    ->generate();

TTS 支持 OpenAI 和 ElevenLabs，STT 同樣支持這兩個服務商。

Embeddings 與向量搜索

生成向量嵌入變得非常直觀。Laravel 的 Stringable 類新增了 toEmbeddings() 方法：

$embeddings = Str::of('Napa Valley has great wine.')->toEmbeddings();

配合 PostgreSQL 的 pgvector 擴展，可以在數據庫中直接進行向量相似度查詢：

$documents = Document::query()
    ->whereVectorSimilarTo('embedding', '納帕谷最好的酒莊')
    ->limit(10)
    ->get();

傳入字符串時，Laravel 會自動生成嵌入向量再進行查詢，不需要手動處理。Embedding 還支持緩存，避免重複調用 API。

Reranking

Reranking 可以對搜索結果按語義相關性重新排序，支持 Cohere 和 Jina：

$posts = Post::all()->rerank('body', 'Laravel 教程');

這個功能直接以 Collection 宏的形式提供，可以對 Eloquent 集合按指定字段做語義重排。

文件與向量存儲

SDK 提供了文件管理和向量存儲的完整方案。文件可以上傳到服務商存儲後反覆引用，向量存儲則用於 RAG 場景下的文件檢索：

use Laravel\Ai\Files\Document;
use Laravel\Ai\Stores;

// 上傳文件
$stored = Document::fromPath('/path/to/report.pdf')->put();

// 創建向量存儲並添加文件
$store = Stores::create('知識庫');
$store->add($stored);

Failover

調用時傳入服務商數組，SDK 會在主服務商不可用時自動切換到備用服務商：

$response = (new SalesCoach)->prompt(
    '分析這段錄音...',
    provider: ['openai', 'anthropic'],
);

Agent 配置

Agent 支持通過 PHP Attribute 配置參數，包括最大步數、最大 token 數、温度、超時時間等：

#[MaxSteps(10)]
#[MaxTokens(4096)]
#[Provider('anthropic')]
#[Temperature(0.7)]
#[Timeout(120)]
class SalesCoach implements Agent
{
    use Promptable;
}

UseCheapestModel 和 UseSmartestModel 兩個 Attribute 可以自動選擇服務商最便宜或最強的模型，不需要記具體的模型名。

中間件

Agent 支持中間件機制，可以在請求發送前後插入自定義邏輯，比如日誌記錄：

class LogPrompts
{
    public function handle(AgentPrompt $prompt, Closure $next)
    {
        Log::info('Prompting agent', ['prompt' => $prompt->prompt]);

        return $next($prompt)->then(function (AgentResponse $response) {
            Log::info('Agent responded', ['text' => $response->text]);
        });
    }
}

測試支持

SDK 為每個功能都提供了 fake() 方法和斷言 API，測試時不需要真實調用 AI 服務商：

SalesCoach::fake(['第一條響應', '第二條響應']);

// 執行業務邏輯...

SalesCoach::assertPrompted('分析這段...');
SalesCoach::assertNeverPrompted();

圖像、音頻、轉錄、Embeddings、Reranking、文件操作、向量存儲都有對應的 fake 和斷言方法。

服務商支持一覽

小結

Laravel AI SDK 把 AI 集成做成了 Laravel 開發者熟悉的樣子：Artisan 命令生成類、接口約束行為、trait 複用邏輯、隊列異步處理、fake 方法寫測試。如果你的 Laravel 項目需要接入 AI 能力，這個包值得嘗試。

🎉Laravel AI SDK 正式發佈