Laravel AI SDK - Knowledge of Laravel

简介

Laravel AI SDK 提供了统一且富有表现力的 API，用于与 OpenAI、Anthropic、Gemini 等 AI 提供商进行对话。使用 AI SDK，你可以通过一致且富有 Laravel 风格的接口来构建带有工具和结构化输出的智能代理、生成图像、进行语音合成与转录、创建向量嵌入等丰富的 AI 功能。

Laravel AI SDK 是在 Laravel 13 中新增的官方包。以 laravel/ai 形式提供，可通过统一 API 使用多个 AI 提供商。

提供商支持一览

功能	支持的提供商
文本生成	OpenAI, OpenAI Compatible, Anthropic, Gemini, Azure, Bedrock, Groq, xAI, DeepSeek, Mistral, Ollama, OpenRouter
图像生成	OpenAI, Gemini, xAI, Azure, Bedrock, OpenRouter
语音合成（TTS）	OpenAI, ElevenLabs, Gemini
语音识别（STT）	OpenAI, ElevenLabs, Mistral, Gemini
嵌入	OpenAI, Gemini, Azure, Bedrock, Cohere, Mistral, Jina, VoyageAI, Ollama, OpenRouter
重排序	Cohere, Jina, VoyageAI
文件	OpenAI, Anthropic, Gemini, Azure

安装

安装包

使用 Composer 安装 Laravel AI SDK。

composer require laravel/ai

发布配置文件与迁移

使用 vendor:publish Artisan 命令发布配置文件和迁移。

php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider"

执行迁移

执行数据库迁移。系统会创建 agent_conversations 和 agent_conversation_messages 表，用于保存对话历史。

php artisan migrate

配置

环境变量

在 .env 文件中设置所使用 AI 提供商的 API 密钥。

ANTHROPIC_API_KEY=
AZURE_OPENAI_API_KEY=
COHERE_API_KEY=
DEEPSEEK_API_KEY=
ELEVENLABS_API_KEY=
GEMINI_API_KEY=
GROQ_API_KEY=
MISTRAL_API_KEY=
OLLAMA_API_KEY=
OPENAI_API_KEY=
OPENROUTER_API_KEY=
JINA_API_KEY=
VOYAGEAI_API_KEY=
XAI_API_KEY=

用于文本、图像、语音、转录、嵌入的默认模型也可以在 config/ai.php 中配置。

自定义 Base URL

如果需要通过代理服务，可以为每个提供商配置自定义 URL。

'providers' => [
    'openai' => [
        'driver' => 'openai',
        'key' => env('OPENAI_API_KEY'),
        'url' => env('OPENAI_URL'),
    ],
    'anthropic' => [
        'driver' => 'anthropic',
        'key' => env('ANTHROPIC_API_KEY'),
        'url' => env('ANTHROPIC_BASE_URL'),
    ],
],

自定义 Base URL 支持 OpenAI、Anthropic、Gemini、Groq、Cohere、DeepSeek、xAI、OpenRouter。

OpenAI-Compatible 提供商

在使用 LM Studio、vLLM、Together、Fireworks、本地网关等兼容 OpenAI 的 API 时，可以使用 openai-compatible 驱动配置提供商。url 是必需的，如果指定了 key，会作为 Bearer 令牌发送。

'providers' => [
    'local' => [
        'driver' => 'openai-compatible',
        'url' => env('LOCAL_AI_URL'),
        'key' => env('LOCAL_AI_API_KEY'),
    ],
],

配置后即可像其他提供商一样使用提供商名称来指定。

agent()->prompt('What is Laravel?', provider: 'local', model: 'local-model');

如果设置了默认文本模型，则无需每次都指定模型。

'local' => [
    'driver' => 'openai-compatible',
    'url' => env('LOCAL_AI_URL'),
    'key' => env('LOCAL_AI_API_KEY'),
    'models' => [
        'text' => [
            'default' => env('LOCAL_AI_MODEL'),
        ],
    ],
],

OpenAI-Compatible 提供商支持文本生成、流式传输、工具、结构化输出以及图像附件。若端点需要额外的请求体字段，请使用提供商选项。

Lab 枚举

在代码中引用提供商时，使用 Lab 枚举。

use Laravel\Ai\Enums\Lab;

Lab::Anthropic;
Lab::OpenAI;
Lab::Gemini;

智能体（Agent）

智能体是 Laravel AI SDK 的基本构成要素。可以使用 make:agent 命令生成智能体类。

php artisan make:agent SalesCoach

# 生成带结构化输出的智能体
php artisan make:agent SalesCoach --structured

生成的智能体会放置在 app/Ai/Agents/ 目录下。下面是一个实现了所有主要接口的智能体示例。

<?php

namespace App\Ai\Agents;

use App\Ai\Tools\RetrievePreviousTranscripts;
use App\Models\History;
use App\Models\User;
use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\Conversational;
use Laravel\Ai\Contracts\HasStructuredOutput;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Messages\Message;
use Laravel\Ai\Promptable;
use Stringable;

class SalesCoach implements Agent, Conversational, HasTools, HasStructuredOutput
{
    use Promptable;

    public function __construct(public User $user) {}

    public function instructions(): Stringable|string
    {
        return 'You are a sales coach, analyzing transcripts and providing feedback and an overall sales strength score.';
    }

    public function messages(): iterable
    {
        return History::where('user_id', $this->user->id)
            ->latest()
            ->limit(50)
            ->get()
            ->reverse()
            ->map(function ($message) {
                return new Message($message->role, $message->content);
            })->all();
    }

    public function tools(): iterable
    {
        return [new RetrievePreviousTranscripts];
    }

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

Prompt

使用 prompt() 方法向智能体发送消息。

$response = (new SalesCoach)->prompt('Analyze this sales transcript...');
return (string) $response;

使用 make() 静态方法可以从容器解析依赖并生成实例。

$agent = SalesCoach::make(user: $user);

提供商、模型、超时可通过 prompt() 的参数覆盖。

$response = (new SalesCoach)->prompt(
    'Analyze this sales transcript...',
    provider: Lab::Anthropic,
    model: 'claude-haiku-4-5-20251001',
    timeout: 120,
);

对话上下文

实现 Conversational 接口并定义 messages() 方法后，即可将过去的对话历史传递给 AI。使用 RemembersConversations trait 可以自动将对话历史保存到数据库并读取。

use Laravel\Ai\Concerns\RemembersConversations;

class SalesCoach implements Agent, Conversational
{
    use Promptable, RemembersConversations;

    public function instructions(): string
    {
        return 'You are a sales coach...';
    }
}

使用 forUser() 开始对话，然后使用返回的 conversationId 通过 continue() 继续对话。

$response = (new SalesCoach)->forUser($user)->prompt('Hello!');
$conversationId = $response->conversationId;

$response = (new SalesCoach)->continue($conversationId, as: $user)->prompt('Tell me more about that.');

结构化输出

实现 HasStructuredOutput 接口并通过 schema() 方法定义 JSON Schema，即可以结构化数据形式获取 AI 的响应。

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

$response = (new SalesCoach)->prompt('Analyze this...');
return $response['score'];

嵌套对象

public function schema(JsonSchema $schema): array
{
    return [
        'score' => $schema->integer()->required(),
        'metadata' => $schema->object(fn ($schema) => [
            'confidence' => $schema->string()->enum(['low', 'medium', 'high'])->required(),
            'language' => $schema->string()->required(),
        ])->required(),
    ];
}

对象数组

public function schema(JsonSchema $schema): array
{
    return [
        'feedback' => $schema->array()->items(
            $schema->object(fn ($schema) => [
                'comment' => $schema->string()->required(),
                'score' => $schema->integer()->required(),
            ])
        )->required(),
    ];
}

anyOf（多个 Schema 中选择）

当值可能匹配多个 Schema 中的任一个时，使用 anyOf 方法。

public function schema(JsonSchema $schema): array
{
    return [
        'content' => $schema->anyOf([
            $schema->object(fn ($schema) => [
                'type' => $schema->string()->enum(['article'])->required(),
                'title' => $schema->string()->required(),
            ]),
            $schema->object(fn ($schema) => [
                'type' => $schema->string()->enum(['image'])->required(),
                'url' => $schema->string()->required(),
            ]),
        ])->required(),
    ];
}

附件

通过 attachments 参数可以向智能体传递文档或图像。

use Laravel\Ai\Files;

$response = (new SalesCoach)->prompt(
    'Analyze the attached sales transcript...',
    attachments: [
        Files\Document::fromStorage('transcript.pdf'),
        Files\Document::fromPath('/home/laravel/transcript.md'),
        $request->file('transcript'),
    ]
);

图像附件的用法相同。

$response = (new ImageAnalyzer)->prompt('What is in this image?', attachments: [
    Files\Image::fromStorage('photo.jpg'),
    Files\Image::fromPath('/home/laravel/photo.jpg'),
    $request->file('photo'),
]);

流式传输

使用 stream() 方法可以按 chunk 返回响应。适合将较长的响应实时地发送到前端。

Route::get('/coach', function () {
    return (new SalesCoach)->stream('Analyze this sales transcript...');
});

通过 then() 回调可以在流式传输完成后执行处理。

use Laravel\Ai\Responses\StreamedAgentResponse;

Route::get('/coach', function () {
    return (new SalesCoach)
        ->stream('Analyze this sales transcript...')
        ->then(function (StreamedAgentResponse $response) {
            // $response->text, $response->events, $response->usage...
        });
});

也可以手动迭代流。

$stream = (new SalesCoach)->stream('Analyze this sales transcript...');

foreach ($stream as $event) {
    // ...
}

Vercel AI SDK 协议

在前端使用 Vercel AI SDK 时，调用 usingVercelDataProtocol()。

Route::get('/coach', function () {
    return (new SalesCoach)->stream('Analyze...')->usingVercelDataProtocol();
});

广播

可以将流事件发送到 Laravel Echo 等广播通道。

use Illuminate\Broadcasting\Channel;

$stream = (new SalesCoach)->stream('Analyze this sales transcript...');

foreach ($stream as $event) {
    $event->broadcast(new Channel('channel-name'));
}

使用 broadcastOnQueue() 可以通过队列进行广播。

(new SalesCoach)->broadcastOnQueue(
    'Analyze this sales transcript...',
    new Channel('channel-name'),
);

跳过巨大的事件

某些广播平台将 WebSocket 消息限制在约 10KB。当工具结果等数据量较大的流事件超过此上限时可能会广播失败。可以使用 WithoutBroadcasting 属性，将特定事件类型排除在广播之外。

<?php

namespace App\Ai\Agents;

use Laravel\Ai\Attributes\WithoutBroadcasting;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Promptable;
use Laravel\Ai\Streaming\Events\ToolCall;
use Laravel\Ai\Streaming\Events\ToolResult;

#[WithoutBroadcasting(ToolCall::class, ToolResult::class)]
class SearchAgent implements Agent, HasTools
{
    use Promptable;

    // ...
}

被排除的事件不会被广播，但仍会保存到 agent_conversation_messages 表中。因此前端可以在流结束后获取工具的全部数据。此机制对通过队列（broadcastOnQueue）和同步（broadcast / broadcastNow）方式均生效。

队列

使用 queue() 方法可以将提示放入队列进行异步处理。

use Laravel\Ai\Responses\AgentResponse;

Route::post('/coach', function (Request $request) {
    (new SalesCoach)
        ->queue($request->input('transcript'))
        ->then(function (AgentResponse $response) { /* ... */ })
        ->catch(function (Throwable $e) { /* ... */ });

    return back();
});

工具

使用工具可以让 AI 调用代码中的函数。可以通过 make:tool 命令生成工具类。

php artisan make:tool RandomNumberGenerator

<?php

namespace App\Ai\Tools;

use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Ai\Contracts\Tool;
use Laravel\Ai\Tools\Request;
use Stringable;

class RandomNumberGenerator implements Tool
{
    public function description(): Stringable|string
    {
        return 'This tool may be used to generate cryptographically secure random numbers.';
    }

    public function handle(Request $request): Stringable|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(),
        ];
    }
}

在智能体的 tools() 方法中注册工具。

public function tools(): iterable
{
    return [new RandomNumberGenerator];
}

相似度检索工具

可以轻松添加使用向量嵌入的相似度检索工具。

use App\Models\Document;
use Laravel\Ai\Tools\SimilaritySearch;

public function tools(): iterable
{
    return [
        SimilaritySearch::usingModel(Document::class, 'embedding'),
    ];
}

也可以指定选项。

SimilaritySearch::usingModel(
    model: Document::class,
    column: 'embedding',
    minSimilarity: 0.7,
    limit: 10,
    query: fn ($query) => $query->where('published', true),
),

也可以通过闭包定义自定义的检索逻辑。

new SimilaritySearch(using: function (string $query) {
    return Document::query()
        ->where('user_id', $this->user->id)
        ->whereVectorSimilarTo('embedding', $query)
        ->limit(10)
        ->get();
}),

可以通过 withDescription() 自定义工具的说明。

SimilaritySearch::usingModel(Document::class, 'embedding')
    ->withDescription('Search the knowledge base for relevant articles.'),

文件存储工具

使用 FileStorage 工具工厂可以让智能体访问 Laravel 文件系统磁盘。all 方法返回一套用于在指定磁盘上列出、读取、生成 URL、写入、删除和复制文件的工具。

use Laravel\Ai\Tools\FileStorage;

public function tools(): iterable
{
    return FileStorage::all('local');
}

若只希望允许只读访问，则使用 readOnly 方法。

return FileStorage::readOnly('local');

这些方法返回 Illuminate\Support\Collection，因此可以进一步筛选要提供的工具。

use Laravel\Ai\Tools\Filesystem\DeleteFile;

return FileStorage::all('s3')
    ->reject(fn ($tool) => $tool instanceof DeleteFile);

MCP 工具

如果应用程序中使用了 Laravel MCP，可以将 Model Context Protocol 服务器公开的工具提供给智能体。使用 Laravel MCP 客户端可以连接远程或本地的 MCP 服务器，并将其工具直接传递给智能体。

要使用 MCP 工具，应用程序中需要已安装 Laravel MCP 包。

MCP 客户端的 tools 方法返回一个集合，因此可以使用 ... 展开运算符将其展开到智能体的 tools 数组中。

use App\Ai\Tools\RandomNumberGenerator;
use Laravel\Mcp\Client;

/**
 * Get the tools available to the agent.
 *
 * @return Tool[]
 */
public function tools(): iterable
{
    return [
        ...Client::web('https://mcp.example.com')
            ->withToken($token)
            ->tools(),

        new RandomNumberGenerator,
    ];
}

AI SDK 会自动包装各个 MCP 工具，使智能体像调用其他工具一样调用它们。也可以使用命名 MCP 客户端。

use Laravel\Mcp\Facades\Mcp;

public function tools(): iterable
{
    return [
        ...Mcp::client('github')->tools(),
    ];
}

或者，也可以连接本地 MCP 服务器。

use Laravel\Mcp\Client;

public function tools(): iterable
{
    return [
        ...Client::local('php', ['artisan', 'mcp:start'])->tools(),
    ];
}

关于创建 MCP 客户端及认证（如 Bearer 令牌或 OAuth）的更多信息，请参阅 MCP 客户端文档。

提供商工具

AI 提供商原生实现的特殊工具。

Web 检索

为智能体添加网络检索功能。支持 Anthropic、OpenAI、Gemini、OpenRouter。

use Laravel\Ai\Providers\Tools\WebSearch;

public function tools(): iterable
{
    return [new WebSearch];
}

可以选择性地指定检索结果数、允许的域名或位置信息。

(new WebSearch)->max(5)->allow(['laravel.com', 'php.net']),
(new WebSearch)->location(city: 'New York', region: 'NY', country: 'US');

Web 抓取

获取指定 URL 内容的工具。支持 Anthropic、Gemini。

use Laravel\Ai\Providers\Tools\WebFetch;

public function tools(): iterable
{
    return [new WebFetch];
}

(new WebFetch)->max(3)->allow(['docs.laravel.com']),

文件搜索

从向量存储中搜索文档的工具。支持 OpenAI、Gemini。

use Laravel\Ai\Providers\Tools\FileSearch;

public function tools(): iterable
{
    return [new FileSearch(stores: ['store_id'])];
}

// 指定多个存储
new FileSearch(stores: ['store_1', 'store_2']);

// 使用元数据过滤
new FileSearch(stores: ['store_id'], where: ['author' => 'Taylor Otwell', 'year' => 2026]);

也可以使用 FileSearchQuery 指定复杂过滤条件。

use Laravel\Ai\Providers\Tools\FileSearchQuery;

new FileSearch(stores: ['store_id'], where: fn (FileSearchQuery $query) =>
    $query->where('author', 'Taylor Otwell')
          ->whereNot('status', 'draft')
          ->whereIn('category', ['news', 'updates'])
);

子智能体

也可以从另一个智能体的 tools() 方法返回智能体。将智能体注册为工具后，父智能体可以将特定任务委派给子智能体，并将其结果整合到原始响应中。适合通用智能体访问具有专业指令、工具、模型配置或提供商设置的特化智能体。例如，客户支持智能体将有关退款政策的问题委派给退款专门智能体的示例。

<?php

namespace App\Ai\Agents;

use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Promptable;

class CustomerSupportAgent implements Agent, HasTools
{
    use Promptable;

    public function instructions(): string
    {
        return 'You help customers with account, order, and billing questions. Delegate refund policy questions to the refunds specialist.';
    }

    public function tools(): iterable
    {
        return [
            new RefundsAgent,
        ];
    }
}

若要自定义子智能体对父智能体的展示方式，可以在子智能体上实现 CanActAsTool 接口，并定义作为工具时使用的名称与说明。

<?php

namespace App\Ai\Agents;

use App\Ai\Tools\LookupOrder;
use Laravel\Ai\Attributes\Provider;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\CanActAsTool;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Enums\Lab;
use Laravel\Ai\Promptable;

#[Provider(Lab::Anthropic)]
class RefundsAgent implements Agent, CanActAsTool, HasTools
{
    use Promptable;

    public function instructions(): string
    {
        return 'You are a refunds specialist. Use order details and the refund policy to give concise eligibility guidance.';
    }

    public function name(): string
    {
        return 'refunds_specialist';
    }

    public function description(): string
    {
        return 'Determine whether an order is eligible for a refund and explain the next step.';
    }

    public function tools(): iterable
    {
        return [
            new LookupOrder,
        ];
    }
}

对于未实现 CanActAsTool 的子智能体，Laravel 会将类名用作工具名称，并自动生成通用的描述文本。每个子智能体的调用都是独立进行的，不会继承父智能体的对话历史。

中间件

可以为智能体添加中间件以拦截提示和响应。

php artisan make:agent-middleware LogPrompts

在智能体上实现 HasMiddleware 接口，并通过 middleware() 方法注册中间件。

<?php

namespace App\Ai\Agents;

use App\Ai\Middleware\LogPrompts;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasMiddleware;
use Laravel\Ai\Promptable;

class SalesCoach implements Agent, HasMiddleware
{
    use Promptable;

    public function middleware(): array
    {
        return [new LogPrompts];
    }
}

以下是中间件类的实现示例。

<?php

namespace App\Ai\Middleware;

use Closure;
use Laravel\Ai\Prompts\AgentPrompt;

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

使用 then() 可以添加响应后的处理。

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

匿名智能体

不定义类，也可以使用 agent() 助手函数创建匿名智能体。

use function Laravel\Ai\{agent};

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

也可以创建带结构化输出的匿名智能体。

use Illuminate\Contracts\JsonSchema\JsonSchema;

$response = agent(
    schema: fn (JsonSchema $schema) => ['number' => $schema->integer()->required()],
)->prompt('Generate a random number less than 100');

智能体配置（PHP 属性）

可以使用 PHP 属性以声明式方式定义智能体的默认配置。

属性	说明
`#[Provider]`	指定使用的提供商
`#[Model]`	指定使用的模型
`#[MaxSteps]`	工具调用的最大步骤数
`#[MaxTokens]`	最大 token 数
`#[Temperature]`	温度参数（0.0～1.0）
`#[TopP]`	核采样的概率（0.0～1.0）
`#[Timeout]`	超时（秒）
`#[UseCheapestModel]`	自动选择最便宜的模型
`#[UseSmartestModel]`	自动选择最高性能的模型

<?php

namespace App\Ai\Agents;

use Laravel\Ai\Attributes\MaxSteps;
use Laravel\Ai\Attributes\MaxTokens;
use Laravel\Ai\Attributes\Model;
use Laravel\Ai\Attributes\Provider;
use Laravel\Ai\Attributes\Temperature;
use Laravel\Ai\Attributes\Timeout;
use Laravel\Ai\Attributes\TopP;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Enums\Lab;
use Laravel\Ai\Promptable;

#[Provider(Lab::Anthropic)]
#[Model('claude-haiku-4-5-20251001')]
#[MaxSteps(10)]
#[MaxTokens(4096)]
#[Temperature(0.7)]
#[Timeout(120)]
#[TopP(0.9)]
class SalesCoach implements Agent
{
    use Promptable;
}

也提供了用于模型选择的快捷属性。

// 使用最便宜的模型
#[UseCheapestModel]
class SimpleSummarizer implements Agent
{
    use Promptable;
}

// 使用性能最高的模型
#[UseSmartestModel]
class ComplexReasoner implements Agent
{
    use Promptable;
}

提供商选项

实现 HasProviderOptions 接口可传递提供商特定的选项。

<?php

namespace App\Ai\Agents;

use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasProviderOptions;
use Laravel\Ai\Enums\Lab;
use Laravel\Ai\Promptable;

class SalesCoach implements Agent, HasProviderOptions
{
    use Promptable;

    public function providerOptions(Lab|string $provider): array
    {
        return match ($provider) {
            Lab::OpenAI => [
                'reasoning' => ['effort' => 'low'],
                'frequency_penalty' => 0.5,
                'presence_penalty' => 0.3,
            ],
            Lab::Anthropic => [
                'thinking' => ['budget_tokens' => 1024],
            ],
            default => [],
        };
    }
}

人工审批（Human Tool Approval）

使用工具审批需要一个能持久化对话历史的 Conversational 智能体。为了恢复被暂停的调用，RemembersConversations trait 提供了所需的持久化功能。

对于删除文件、汇款等敏感或不可撤销的操作，可以要求在执行前获得人工审批。若要将工具设为审批对象，请实现 Approvable 契约并使用 InteractsWithApprovals trait。审批对象工具默认需要审批。

<?php

namespace App\Ai\Tools;

use Illuminate\Contracts\JsonSchema\JsonSchema;
use Illuminate\Support\Facades\Storage;
use Laravel\Ai\Concerns\InteractsWithApprovals;
use Laravel\Ai\Contracts\Approvable;
use Laravel\Ai\Contracts\Tool;
use Laravel\Ai\Tools\Request;
use Stringable;

class DeleteFile implements Approvable, Tool
{
    use InteractsWithApprovals;

    /**
     * 获取工具用途的说明
     */
    public function description(): Stringable|string
    {
        return '从存储中删除文件。';
    }

    /**
     * 执行工具
     */
    public function handle(Request $request): Stringable|string
    {
        Storage::delete($request['path']);

        return "已删除：[{$request['path']}]";
    }

    /**
     * 获取工具的 schema 定义
     */
    public function schema(JsonSchema $schema): array
    {
        return [
            'path' => $schema->string()->required(),
        ];
    }
}

如果希望根据工具调用的参数动态判断是否需要审批，可以在工具中定义 needsApproval 方法。该方法可以返回布尔值，或包含审批理由的 Approval 实例。

use Laravel\Ai\Approvals\Approval;

/**
 * 判断对给定请求是否需要审批
 */
protected function needsApproval(Request $request): Approval|bool
{
    return str_starts_with($request['path'], 'temporary/')
        ? false
        : Approval::required('该文件将被永久删除。');
}

也可以在智能体的 tools 方法中返回工具时覆盖审批要求。

public function tools(): iterable
{
    return [
        (new SendNotification)->withoutApproval(),
        (new DeleteFile)->requireApproval('删除需要确认。'),
    ];
}

当调用需要审批的工具时，智能体会在执行前暂停。通过检查响应的 pendingApprovals，可以查看每次工具调用的 ID、工具名称、参数和审批理由。

$response = (new FileAssistant)
    ->forUser($user)
    ->prompt('删除旧的发票。');

if ($response->hasPendingApprovals()) {
    foreach ($response->pendingApprovals as $approval) {
        // $approval->id
        // $approval->tool
        // $approval->arguments
        // $approval->reason
    }
}

要恢复智能体，需要继续对话，并传入包含各待审批工具调用决定的 Decisions 实例。决定可以进行调用的批准、拒绝，或在执行前编辑参数。

use Laravel\Ai\Approvals\Decision;
use Laravel\Ai\Approvals\Decisions;

$response = (new FileAssistant)
    ->continue($conversationId, as: $user)
    ->prompt(Decisions::from([
        'call_abc' => Decision::approve(),
        'call_ghi' => Decision::reject('此发票必须保留。'),
    ]));

布尔值 true、false 可作为批准和拒绝的简写形式。所有待处理的工具调用都必须有决定。指定未知、缺失或已解决的工具调用 ID 会抛出 ApprovalMismatchException。对于没有显式决定的调用，可通过 approveRemaining 或 rejectRemaining 方法指定默认决定。

$decisions = Decisions::from([
    'call_abc' => true,
])->rejectRemaining('未获批准。');

$response = (new FileAssistant)
    ->continue($conversationId, as: $user)
    ->prompt($decisions);

以带结果的方式拒绝（如 Decision::reject('未获批准。')）时，结果会返回给模型继续响应。若不带结果拒绝，则在记录拒绝时生成循环停止。工具审批在 prompt、stream、queue、broadcast、broadcastNow、broadcastOnQueue 方法中都受支持。在流式传输和广播过程中，暂停以 tool_approval_request 事件表示。若使用 Vercel AI SDK 流协议，审批请求和结果会以协议原生的工具审批部件形式发送。对于队列化的智能体，结果响应会传递给 then 回调，Laravel 也会派发 ToolApprovalRequested 事件。在请求模型继续之前，Laravel 会保存已批准工具的执行结果。若之后生成失败，审批已然解决。请不要重发相同的审批决定，而是使用普通文本提示继续对话。

完整的审批流程

以下路由展示了完整的审批流程。GET 路由返回聊天界面，POST 路由接收来自聊天界面的新文本提示或审批决定。此示例假设应用程序的 User 模型使用了 HasConversations trait。

use App\Ai\Agents\FileAssistant;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Gate;
use Illuminate\Support\Facades\Route;
use Illuminate\Validation\Rule;
use Laravel\Ai\Approvals\Decision;
use Laravel\Ai\Approvals\Decisions;
use Laravel\Ai\Models\Conversation;

Route::get('/chat/{conversation}', function (Request $request, Conversation $conversation) {
    Gate::authorize('view', $conversation);

    return view('chat', [
        'conversation' => $conversation,
    ]);
})->middleware('auth');

Route::post('/chat/{conversation}', function (Request $request, Conversation $conversation) {
    Gate::authorize('view', $conversation);

    $validated = $request->validate([
        'message' => ['nullable', 'string', 'required_without:decisions', 'prohibited_with:decisions'],
        'decisions' => ['nullable', 'array', 'required_without:message', 'prohibited_with:message'],
        'decisions.*.action' => ['required_with:decisions', Rule::in(['approve', 'reject'])],
        'decisions.*.result' => ['nullable', 'string'],
    ]);

    $prompt = isset($validated['decisions'])
        ? Decisions::from($validated->collect('decisions')->map(
            fn (array $decision) => match ($decision['action']) {
                'approve' => Decision::approve(),
                'reject' => Decision::reject($decision['result'] ?? null),
            }
        )->all())
        : $validated['message'];

    $response = (new FileAssistant)
        ->continue($conversation->id, as: $request->user())
        ->prompt($prompt);

    return [
        'conversation_id' => $response->conversationId,
        'status' => $response->hasPendingApprovals() ? 'awaiting_approval' : 'complete',
        'message' => $response->text,
        'approvals' => $response->pendingApprovals,
    ];
})->middleware('auth');

若响应的状态为 awaiting_approval，聊天界面应显示待审批项，并以工具调用 ID 为键，将用户的选择发送到相同的端点。

{
    "decisions": {
        "call_abc": {
            "action": "approve"
        },
        "call_def": {
            "action": "reject",
            "result": "此发票必须保留。"
        }
    }
}

对于普通聊天消息，则改为发送 message 值。

{
    "message": "删除旧的发票。"
}

审批流程能在给予 AI 智能体强大操作权限的同时，在执行前插入人工检查。对于文件删除、支付处理、写入外部 API 等不可撤销的操作，请积极使用。

图像生成

使用 Image 类可以生成图像。OpenAI、Gemini、xAI 提供商均支持。

use Laravel\Ai\Image;

$image = Image::of('A donut sitting on the kitchen counter')->generate();
$rawContent = (string) $image;

可以指定质量、纵横比和超时。

$image = Image::of('A donut sitting on the kitchen counter')
    ->quality('high')
    ->landscape()
    ->timeout(120)
    ->generate();

也可以附加参考图像进行加工。

use Laravel\Ai\Files;

$image = Image::of('Update this photo to be in the style of an impressionist painting.')
    ->attachments([Files\Image::fromStorage('photo.jpg')])
    ->landscape()
    ->generate();

保存图像

$path = $image->store();
$path = $image->storeAs('image.jpg');
$path = $image->storePublicly();
$path = $image->storePubliclyAs('image.jpg');

通过队列生成图像

use Laravel\Ai\Responses\ImageResponse;

Image::of('A donut sitting on the kitchen counter')
    ->portrait()
    ->queue()
    ->then(function (ImageResponse $image) {
        $path = $image->store();
    });

语音合成（TTS）

使用 Audio 类可以将文本转换为语音。OpenAI、ElevenLabs 提供商均支持。

use Laravel\Ai\Audio;

$audio = Audio::of('I love coding with Laravel.')->generate();
$rawContent = (string) $audio;

也可以指定声音的性别、具体的语音 ID 或说话方式的指令。

$audio = Audio::of('I love coding with Laravel.')->female()->generate();
$audio = Audio::of('I love coding with Laravel.')->voice('voice-id-or-name')->generate();
$audio = Audio::of('I love coding with Laravel.')->female()->instructions('Said like a pirate')->generate();

保存音频

$path = $audio->store();
$path = $audio->storeAs('audio.mp3');
$path = $audio->storePublicly();
$path = $audio->storePubliclyAs('audio.mp3');

通过队列生成音频

use Laravel\Ai\Responses\AudioResponse;

Audio::of('I love coding with Laravel.')
    ->queue()
    ->then(function (AudioResponse $audio) {
        $path = $audio->store();
    });

转录（STT）

使用 Transcription 类可以将音频文件转换为文本。OpenAI、ElevenLabs、Mistral 提供商均支持。

use Laravel\Ai\Transcription;

$transcript = Transcription::fromPath('/home/laravel/audio.mp3')->generate();
$transcript = Transcription::fromStorage('audio.mp3')->generate();
$transcript = Transcription::fromUpload($request->file('audio'))->generate();

return (string) $transcript;

说话人分离（Diarization）

使用 diarize() 可以获取按说话人分离的转录内容。

$transcript = Transcription::fromStorage('audio.mp3')->diarize()->generate();

通过队列进行转录

use Laravel\Ai\Responses\TranscriptionResponse;

Transcription::fromStorage('audio.mp3')
    ->queue()
    ->then(function (TranscriptionResponse $transcript) { /* ... */ });

文本摘要（Text Summarization）

使用 Laravel Stringable 类提供的 summarize 方法可以总结文本。默认摘要不超过 3 句话，并使用所配置提供商中最便宜的文本模型。

use Illuminate\Support\Str;

$summary = Str::of($article)->summarize();

也可以指定摘要句数上限、提供商、模型和超时。Str 类也提供了静态方法版本。

use Laravel\Ai\Enums\Lab;

$summary = Str::of($article)->summarize(
    sentences: 4,
    provider: Lab::Anthropic,
    model: 'claude-sonnet-5',
    timeout: 30,
);

$summary = Str::summarize($article, sentences: 4);

嵌入（Embeddings）

可以将文本转换为向量表示，用于相似度检索等场景。

use Illuminate\Support\Str;

// 使用 Stringable 的方法
$embeddings = Str::of('Napa Valley has great wine.')->toEmbeddings();

use Laravel\Ai\Embeddings;

// 一次处理多个文本
$response = Embeddings::for(['Napa Valley has great wine.', 'Laravel is a PHP framework.'])->generate();
$response->embeddings; // [[0.123, 0.456, ...], [0.789, 0.012, ...]]

也可以指定提供商、模型和维度数。

$response = Embeddings::for(['Napa Valley has great wine.'])
    ->dimensions(1536)
    ->generate(Lab::OpenAI, 'text-embedding-3-small');

多模态嵌入（Multimodal Embeddings）

Embeddings::for 方法不仅接受字符串，也接受图像、音频、文档和视频输入，因此可以为非文本内容生成嵌入。Gemini 支持图像、音频、文档和视频的嵌入，VoyageAI 支持图像和视频的嵌入。

use Laravel\Ai\Embeddings;
use Laravel\Ai\Enums\Lab;
use Laravel\Ai\Files\Image;
use Laravel\Ai\Files\Video;

$response = Embeddings::for([
    'A vineyard at sunset.',
    Image::fromStorage('vineyard.jpg'),
    Video::fromPath('/home/laravel/tour.mp4'),
])->generate(Lab::Gemini);

多模态输入使用与附件相同的文件类。这些文件可以从本地路径、文件系统磁盘、远程 URL 或 Base64 编码内容创建。图像、文档和视频也可以从上传的文件创建，文档也可以从原始字符串内容创建。

use Laravel\Ai\Files\Audio;
use Laravel\Ai\Files\Document;
use Laravel\Ai\Files\Image;
use Laravel\Ai\Files\Video;

Image::fromPath('/home/laravel/photo.jpg');
Image::fromStorage('photo.jpg');
Image::fromUpload($request->file('photo'));

Audio::fromPath('/home/laravel/clip.mp3');
Audio::fromStorage('clip.mp3');
Audio::fromUpload($request->file('clip.mp3'));

Video::fromPath('/home/laravel/video.mp4');
Video::fromStorage('video.mp4');
Video::fromUpload($request->file('video'));

Document::fromUrl('https://example.com/report.pdf');
Document::fromString('Laravel is a PHP framework.', 'text/plain');
Document::fromUpload($request->file('report'));

VoyageAI 不允许在同一请求中混合使用远程 URL 媒体和 Base64 编码的媒体。本地、存储、上传的文件将作为 Base64 编码的内容发送，而文本输入可以与任一媒体源组合。请查阅各提供商的文档以了解可用的多模态模型和输入。

向量检索（pgvector）

以下是使用 PostgreSQL 和 pgvector 扩展进行向量检索的配置示例。

创建迁移

Schema::ensureVectorExtensionExists();

Schema::create('documents', function (Blueprint $table) {
    $table->id();
    $table->string('title');
    $table->text('content');
    $table->vector('embedding', dimensions: 1536);
    $table->timestamps();
});

// 添加 HNSW 索引
$table->vector('embedding', dimensions: 1536)->index();

设置模型

protected function casts(): array
{
    return ['embedding' => 'array'];
}

相似度检索查询

// 通过嵌入向量检索
$documents = Document::query()
    ->whereVectorSimilarTo('embedding', $queryEmbedding, minSimilarity: 0.4)
    ->limit(10)
    ->get();

// 传入字符串会自动生成嵌入
$documents = Document::query()
    ->whereVectorSimilarTo('embedding', 'best wineries in Napa Valley')
    ->limit(10)
    ->get();

也可以使用底层方法。

$documents = Document::query()
    ->select('*')
    ->selectVectorDistance('embedding', $queryEmbedding, as: 'distance')
    ->whereVectorDistanceLessThan('embedding', $queryEmbedding, maxDistance: 0.3)
    ->orderByVectorDistance('embedding', $queryEmbedding)
    ->limit(10)
    ->get();

嵌入的缓存

可以缓存相同文本的嵌入，避免重复生成。在 config/ai.php 中进行默认缓存配置。

'caching' => [
    'embeddings' => [
        'cache' => true,
        'store' => env('CACHE_STORE', 'database'),
    ],
],

也可以对每次请求分别控制缓存。

$response = Embeddings::for(['Napa Valley has great wine.'])->cache()->generate();
$response = Embeddings::for(['Napa Valley has great wine.'])->cache(seconds: 3600)->generate();

// Stringable 也可以
$embeddings = Str::of('Napa Valley has great wine.')->toEmbeddings(cache: true);
$embeddings = Str::of('Napa Valley has great wine.')->toEmbeddings(cache: 3600);

重排序

可以按与查询的相关度对检索结果进行重排。支持 Cohere、Jina 提供商。

use Laravel\Ai\Reranking;

$response = Reranking::of([
    'Django is a Python web framework.',
    'Laravel is a PHP web application framework.',
    'React is a JavaScript library for building user interfaces.',
])->rerank('PHP frameworks');

$response->first()->document; // "Laravel is a PHP web application framework."
$response->first()->score;    // 0.95
$response->first()->index;    // 1

通过 limit() 可以限制返回件数。

$response = Reranking::of($documents)->limit(5)->rerank('search query');

集合的重排序

可以直接对 Eloquent 集合进行重排。

// 单字段
$posts = Post::all()->rerank('body', 'Laravel tutorials');

// 多字段（以 JSON 发送）
$reranked = $posts->rerank(['title', 'body'], 'Laravel tutorials');

// 通过闭包生成自定义文本
$reranked = $posts->rerank(fn ($post) => $post->title.': '.$post->body, 'Laravel tutorials');

// 带选项
$reranked = $posts->rerank(
    by: 'content',
    query: 'Laravel tutorials',
    limit: 10,
    provider: Lab::Cohere,
);

文件管理

可以将文件上传到 AI 提供商，稍后再引用。

use Laravel\Ai\Files\Document;
use Laravel\Ai\Files\Image;

// 从路径
$response = Document::fromPath('/home/laravel/document.pdf')->put();
$response = Image::fromPath('/home/laravel/photo.jpg')->put();

// 从存储
$response = Document::fromStorage('document.pdf', disk: 'local')->put();
$response = Image::fromStorage('photo.jpg', disk: 'local')->put();

// 从 URL
$response = Document::fromUrl('https://example.com/document.pdf')->put();
$response = Image::fromUrl('https://example.com/photo.jpg')->put();

return $response->id;

也可以从字符串或表单上传处理。

$stored = Document::fromString('Hello, World!', 'text/plain')->put();
$stored = Document::fromUpload($request->file('document'))->put();

引用已保存的文件

可以使用已上传的文件 ID 将其附加到智能体。

use Laravel\Ai\Files;

$response = (new SalesCoach)->prompt(
    'Analyze the attached sales transcript...',
    attachments: [Files\Document::fromId('file-id')]
);

获取和删除文件

// 获取
$file = Document::fromId('file-id')->get();
$file->id;
$file->mimeType();

// 删除
Document::fromId('file-id')->delete();

指定提供商

$response = Document::fromPath('/home/laravel/document.pdf')->put(provider: Lab::Anthropic);

指定提供商特定选项

通过 withProviderOptions 方法可以传入提供商特定的上传选项。例如可以设置 OpenAI 的文件 purpose。

use Laravel\Ai\Files\Document;

$response = Document::fromPath('/home/laravel/knowledge.txt')
    ->withProviderOptions(['purpose' => 'assistants'])
    ->put();

若需要为不同的提供商指定不同选项，可以传入闭包。

use Laravel\Ai\Enums\Lab;
use Laravel\Ai\Files\Document;

$response = Document::fromPath('/home/laravel/training.jsonl')
    ->withProviderOptions(fn (Lab|string $provider) => match ($provider) {
        Lab::OpenAI => ['purpose' => 'fine-tune'],
        default => [],
    })
    ->put();

向量存储

使用向量存储可以将文档托管在提供商侧管理。

use Laravel\Ai\Stores;

// 创建
$store = Stores::create('Knowledge Base');
$store = Stores::create(
    name: 'Knowledge Base',
    description: 'Documentation.',
    expiresWhenIdleFor: days(30),
);
return $store->id;

// 获取
$store = Stores::get('store_id');
$store->id;
$store->name;
$store->fileCounts;
$store->ready;

// 删除
Stores::delete('store_id');
$store->delete();

向存储添加文件

$store = Stores::get('store_id');

// 通过多种方式添加文件
$document = $store->add('file_id');
$document = $store->add(Document::fromId('file_id'));
$document = $store->add(Document::fromPath('/path/to/document.pdf'));
$document = $store->add(Document::fromStorage('manual.pdf'));
$document = $store->add($request->file('document'));

$document->id;
$document->fileId;

也可以附加元数据。

$store->add(
    Document::fromPath('/path/to/document.pdf'),
    metadata: [
        'author' => 'Taylor Otwell',
        'department' => 'Engineering',
        'year' => 2026,
    ]
);

从存储删除文件

$store->remove('file_id');

// 若同时删除文件本身
$store->remove('file_abc123', deleteFile: true);

故障转移

将多个提供商以数组形式指定后，第一个提供商失败时会自动回退到下一个提供商。

use App\Ai\Agents\SalesCoach;
use Laravel\Ai\Image;

// 智能体的故障转移
$response = (new SalesCoach)->prompt(
    'Analyze this sales transcript...',
    provider: [Lab::OpenAI, Lab::Anthropic],
);

// 图像生成的故障转移
$image = Image::of('A donut sitting on the kitchen counter')
    ->generate(provider: [Lab::Gemini, Lab::xAI]);

测试

Laravel AI SDK 提供了测试用的 fake 功能，可以在不调用实际 API 的情况下进行测试。

智能体的测试

use App\Ai\Agents\SalesCoach;
use Laravel\Ai\Prompts\AgentPrompt;

// 固定响应的 fake
SalesCoach::fake();
SalesCoach::fake(['First response', 'Second response']);

// 用闭包生成动态响应
SalesCoach::fake(function (AgentPrompt $prompt) {
    return 'Response for: '.$prompt->prompt;
});

// 断言
SalesCoach::assertPrompted('Analyze this...');
SalesCoach::assertPrompted(function (AgentPrompt $prompt) {
    return $prompt->contains('Analyze');
});
SalesCoach::assertNotPrompted('Missing prompt');
SalesCoach::assertNeverPrompted();

队列化的断言也已提供。

use Laravel\Ai\QueuedAgentPrompt;

SalesCoach::assertQueued('Analyze this...');
SalesCoach::assertQueued(function (QueuedAgentPrompt $prompt) {
    return $prompt->contains('Analyze');
});
SalesCoach::assertNotQueued('Missing prompt');
SalesCoach::assertNeverQueued();

使用 preventStrayPrompts() 可以在调用未在 fake 中定义的提示时抛出异常。

SalesCoach::fake()->preventStrayPrompts();

对返回结构化输出的智能体进行 fake 时，可以以数组形式指定响应。智能体将返回包含指定数据的结构化响应。

SalesCoach::fake([
    ['score' => 87],
]);

对于结构化输出智能体，如果未显式传入 fake 数据地调用 fake()，Laravel 会根据智能体定义的 schema 自动生成符合要求的 fake 数据。

匿名智能体的测试使用 AnonymousAgent::fake()。

use Laravel\Ai\AnonymousAgent;

AnonymousAgent::fake(['Test response']);

图像生成的测试

use Laravel\Ai\Image;
use Laravel\Ai\Prompts\ImagePrompt;

Image::fake();
Image::fake([base64_encode($firstImage), base64_encode($secondImage)]);
Image::fake(function (ImagePrompt $prompt) {
    return base64_encode('...');
});

Image::assertGenerated(function (ImagePrompt $prompt) {
    return $prompt->contains('sunset') && $prompt->isLandscape();
});
Image::assertNotGenerated('Missing prompt');
Image::assertNothingGenerated();

Image::assertQueued(fn (QueuedImagePrompt $prompt) => $prompt->contains('sunset'));
Image::assertNotQueued('Missing prompt');
Image::assertNothingQueued();

Image::fake()->preventStrayImages();

语音合成的测试

use Laravel\Ai\Audio;
use Laravel\Ai\Prompts\AudioPrompt;

Audio::fake();
Audio::fake([base64_encode($firstAudio), base64_encode($secondAudio)]);
Audio::fake(function (AudioPrompt $prompt) {
    return base64_encode('...');
});

Audio::assertGenerated(function (AudioPrompt $prompt) {
    return $prompt->contains('Hello') && $prompt->isFemale();
});
Audio::assertNotGenerated('Missing prompt');
Audio::assertNothingGenerated();

Audio::assertQueued(fn (QueuedAudioPrompt $prompt) => $prompt->contains('Hello'));
Audio::assertNotQueued('Missing prompt');
Audio::assertNothingQueued();

Audio::fake()->preventStrayAudio();

转录的测试

use Laravel\Ai\Transcription;
use Laravel\Ai\Prompts\TranscriptionPrompt;

Transcription::fake();
Transcription::fake(['First transcription text.', 'Second transcription text.']);
Transcription::fake(function (TranscriptionPrompt $prompt) {
    return 'Transcribed text...';
});

Transcription::assertGenerated(function (TranscriptionPrompt $prompt) {
    return $prompt->language === 'en' && $prompt->isDiarized();
});
Transcription::assertNotGenerated(fn (TranscriptionPrompt $prompt) => $prompt->language === 'fr');
Transcription::assertNothingGenerated();

Transcription::assertQueued(fn (QueuedTranscriptionPrompt $prompt) => $prompt->isDiarized());
Transcription::assertNotQueued(fn (QueuedTranscriptionPrompt $prompt) => $prompt->language === 'fr');
Transcription::assertNothingQueued();

Transcription::fake()->preventStrayTranscriptions();

嵌入的测试

use Laravel\Ai\Embeddings;
use Laravel\Ai\Prompts\EmbeddingsPrompt;

Embeddings::fake();
Embeddings::fake([[$firstEmbeddingVector], [$secondEmbeddingVector]]);
Embeddings::fake(function (EmbeddingsPrompt $prompt) {
    return array_map(
        fn () => Embeddings::fakeEmbedding($prompt->dimensions),
        $prompt->inputs
    );
});

Embeddings::assertGenerated(function (EmbeddingsPrompt $prompt) {
    return $prompt->contains('Laravel') && $prompt->dimensions === 1536;
});
Embeddings::assertNotGenerated(fn (EmbeddingsPrompt $prompt) => $prompt->contains('Other'));
Embeddings::assertNothingGenerated();

Embeddings::assertQueued(fn (QueuedEmbeddingsPrompt $prompt) => $prompt->contains('Laravel'));
Embeddings::assertNotQueued(fn (QueuedEmbeddingsPrompt $prompt) => $prompt->contains('Other'));
Embeddings::assertNothingQueued();

Embeddings::fake()->preventStrayEmbeddings();

重排序的测试

use Laravel\Ai\Reranking;
use Laravel\Ai\Prompts\RerankingPrompt;
use Laravel\Ai\Responses\Data\RankedDocument;

Reranking::fake();
Reranking::fake([[
    new RankedDocument(index: 0, document: 'First', score: 0.95),
    new RankedDocument(index: 1, document: 'Second', score: 0.80),
]]);

Reranking::assertReranked(function (RerankingPrompt $prompt) {
    return $prompt->contains('Laravel') && $prompt->limit === 5;
});
Reranking::assertNotReranked(fn (RerankingPrompt $prompt) => $prompt->contains('Django'));
Reranking::assertNothingReranked();

文件的测试

use Laravel\Ai\Files;
use Laravel\Ai\Contracts\Files\StorableFile;
use Laravel\Ai\Files\Document;

Files::fake();

Document::fromString('Hello, Laravel!', mimeType: 'text/plain')->as('hello.txt')->put();

Files::assertStored(fn (StorableFile $file) =>
    (string) $file === 'Hello, Laravel!' && $file->mimeType() === 'text/plain'
);
Files::assertNotStored(fn (StorableFile $file) => (string) $file === 'Hello, World!');
Files::assertNothingStored();

Files::assertDeleted('file-id');
Files::assertNotDeleted('file-id');
Files::assertNothingDeleted();

向量存储的测试

use Laravel\Ai\Stores;

Stores::fake(); // 文件操作也会被 fake

$store = Stores::create('Knowledge Base');

Stores::assertCreated('Knowledge Base');
Stores::assertCreated(fn (string $name, ?string $description) => $name === 'Knowledge Base');
Stores::assertNotCreated('Other Store');
Stores::assertNothingCreated();

Stores::assertDeleted('store_id');
Stores::assertNotDeleted('other_store_id');
Stores::assertNothingDeleted();

也可以对存储的文件操作进行断言。

$store = Stores::get('store_id');
$store->add('added_id');
$store->remove('removed_id');

$store->assertAdded('added_id');
$store->assertRemoved('removed_id');
$store->assertNotAdded('other_file_id');
$store->assertNotRemoved('other_file_id');

// 用闭包验证内容
$store->add(Document::fromString('Hello, World!', 'text/plain')->as('hello.txt'));
$store->assertAdded(fn (StorableFile $file) => $file->name() === 'hello.txt');
$store->assertAdded(fn (StorableFile $file) => $file->content() === 'Hello, World!');

事件

Laravel AI SDK 会派发以下事件。通过监听这些事件，可用于日志记录、监控等场景。

智能体相关

PromptingAgent — 提示发送前
AgentPrompted — 提示发送后
StreamingAgent — 开始流式传输时
AgentStreamed — 流式传输完成后
InvokingTool — 工具调用前
ToolInvoked — 工具调用后
ToolApprovalRequested — 请求工具审批时
ToolApprovalResolved — 工具审批解决后

图像 / 音频 / 转录相关

GeneratingImage — 图像生成前
ImageGenerated — 图像生成后
GeneratingAudio — 音频生成前
AudioGenerated — 音频生成后
GeneratingTranscription — 转录前
TranscriptionGenerated — 转录后

嵌入 / 重排序相关

GeneratingEmbeddings — 嵌入生成前
EmbeddingsGenerated — 嵌入生成后
Reranking — 重排序前
Reranked — 重排序后

文件 / 存储相关

StoringFile — 文件保存前
FileStored — 文件保存后
FileDeleted — 文件删除后
CreatingStore — 存储创建前
StoreCreated — 存储创建后
AddingFileToStore — 向存储添加文件前
FileAddedToStore — 向存储添加文件后
RemovingFileFromStore — 从存储删除文件前
FileRemovedFromStore — 从存储删除文件后

​简介

​提供商支持一览

​安装

​配置

​环境变量

​自定义 Base URL

​OpenAI-Compatible 提供商

​Lab 枚举

​智能体（Agent）

​Prompt

​对话上下文

​结构化输出

​嵌套对象

​对象数组

​anyOf（多个 Schema 中选择）

​附件

​流式传输

​Vercel AI SDK 协议

​广播

​跳过巨大的事件

​队列

​工具

​相似度检索工具

​文件存储工具

​MCP 工具

​提供商工具

​Web 检索

​Web 抓取

​文件搜索

​子智能体

​中间件

​匿名智能体

​智能体配置（PHP 属性）

​提供商选项

​人工审批（Human Tool Approval）

​完整的审批流程

​图像生成

​保存图像

​通过队列生成图像

​语音合成（TTS）

​保存音频

​通过队列生成音频

​转录（STT）

​说话人分离（Diarization）

​通过队列进行转录

​文本摘要（Text Summarization）

​嵌入（Embeddings）

​多模态嵌入（Multimodal Embeddings）

​向量检索（pgvector）

​嵌入的缓存

​重排序

​集合的重排序

​文件管理

​引用已保存的文件

​获取和删除文件

​指定提供商

​指定提供商特定选项

​向量存储

​向存储添加文件

​从存储删除文件

​故障转移

​测试

​智能体的测试

​图像生成的测试

​语音合成的测试

​转录的测试

​嵌入的测试

​重排序的测试

​文件的测试

​向量存储的测试

​事件

简介

提供商支持一览

安装

配置

环境变量

自定义 Base URL

OpenAI-Compatible 提供商

Lab 枚举

智能体（Agent）

Prompt

对话上下文

结构化输出

嵌套对象

对象数组

anyOf（多个 Schema 中选择）

附件

流式传输

Vercel AI SDK 协议

广播

跳过巨大的事件

队列

工具

相似度检索工具

文件存储工具

MCP 工具

提供商工具

Web 检索

Web 抓取

文件搜索

子智能体

中间件

匿名智能体

智能体配置（PHP 属性）

提供商选项

人工审批（Human Tool Approval）

完整的审批流程

图像生成

保存图像

通过队列生成图像

语音合成（TTS）

保存音频

通过队列生成音频

转录（STT）

说话人分离（Diarization）

通过队列进行转录

文本摘要（Text Summarization）

嵌入（Embeddings）

多模态嵌入（Multimodal Embeddings）

向量检索（pgvector）

嵌入的缓存

重排序

集合的重排序

文件管理

引用已保存的文件

获取和删除文件

指定提供商

指定提供商特定选项

向量存储

向存储添加文件

从存储删除文件

故障转移

测试

智能体的测试

图像生成的测试

语音合成的测试

转录的测试

嵌入的测试

重排序的测试

文件的测试

向量存储的测试

事件