Laravel Scout - Knowledge of Laravel

简介

Laravel Scout 是一个基于驱动的简洁方案，用于给 Eloquent 模型添加全文检索能力。它通过模型观察者，自动同步 Eloquent 记录与搜索索引。 Scout 内置了 database 引擎，使用 MySQL / PostgreSQL 的全文索引和 LIKE 子句直接搜索数据库，无需外部服务。大规模生产环境中若需要拼写容错、分面搜索、地理搜索，则可以选择外部引擎。

支持的引擎一览

引擎	特点	适用场景
`database`	使用 MySQL / PostgreSQL 全文索引	大多数应用
`collection`	在 PHP 内过滤（含 SQLite 也可）	本地开发、测试
Meilisearch	开源，支持拼写容错，速度快	生产环境
Algolia	云端 SaaS，功能丰富	生产环境
Typesense	开源，支持向量检索	生产环境
Turbopuffer	全文、语义与混合检索	生产环境

安装

通过 Composer 安装。

composer require laravel/scout

安装后，使用 vendor:publish 命令发布配置文件，会生成 config/scout.php。

php artisan vendor:publish --provider="Laravel\Scout\ScoutServiceProvider"

最后在需要可搜索的模型上添加 Laravel\Scout\Searchable trait。该 trait 会注册模型观察者，实现与搜索驱动的自动同步。

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Searchable;

class Post extends Model
{
    use Searchable;
}

配置队列

使用 database 或 collection 之外的引擎时，强烈建议先配置好队列驱动。启动队列 worker 后，索引同步会在后台执行，Web 界面的响应速度将大幅提升。将 config/scout.php 中的 queue 设为 true。

'queue' => true,

也可以指定连接和队列名。

'queue' => [
    'connection' => 'redis',
    'queue' => 'scout'
],

配置好后启动专用的队列 worker。

php artisan queue:work redis --queue=scout

使用唯一任务

在写入密集的应用中，你可能希望避免同一模型记录的重复索引任务进入队列。在 config/scout.php 中注册 MakeSearchableUniquely 和 RemoveFromSearchUniquely 任务类，就能使用唯一化的索引任务。通常在服务提供者的 boot 方法中设置。

use Laravel\Scout\Jobs\MakeSearchableUniquely;
use Laravel\Scout\Jobs\RemoveFromSearchUniquely;
use Laravel\Scout\Scout;

Scout::makeSearchableUsing(MakeSearchableUniquely::class);
Scout::removeFromSearchUsing(RemoveFromSearchUniquely::class);

这些任务使用 Laravel 的唯一任务锁，防止已在队列中的同一模型记录被重复派发。

各驱动的准备工作

Algolia

使用 Algolia 驱动时，请在 config/scout.php 中配置 id 与 secret，并安装 Algolia PHP SDK。

composer require algolia/algoliasearch-client-php

在 .env 中配置凭证。

ALGOLIA_APP_ID=your-app-id
ALGOLIA_SECRET=your-secret-key

索引配置

Algolia 可以通过 config/scout.php 管理索引设置。

use App\Models\User;

'algolia' => [
    'id' => env('ALGOLIA_APP_ID', ''),
    'secret' => env('ALGOLIA_SECRET', ''),
    'index-settings' => [
        User::class => [
            'searchableAttributes' => ['id', 'name', 'email'],
            'attributesForFaceting' => ['filterOnly(email)'],
        ],
    ],
],

配置完毕后执行 scout:sync-index-settings 命令，让 Algolia 生效。

php artisan scout:sync-index-settings

Meilisearch

Meilisearch 是一款高性能的开源搜索引擎。本地开发中最简单的方法是使用 Laravel Sail 中的 Docker 服务。

# 使用 Laravel Sail
./vendor/bin/sail up -d meilisearch

不使用 Sail 时，可以直接用 Docker 启动。

docker run -it --rm \
    -p 7700:7700 \
    getmeili/meilisearch:latest \
    meilisearch --master-key="masterKey"

安装 Meilisearch PHP SDK。

composer require meilisearch/meilisearch-php http-interop/http-factory-guzzle

在 .env 中配置驱动与主机。

SCOUT_DRIVER=meilisearch
MEILISEARCH_HOST=http://127.0.0.1:7700
MEILISEARCH_KEY=masterKey

升级 Scout 时请务必查阅 Meilisearch 本身的破坏性变更。

索引配置（Meilisearch）

在 Meilisearch 中，用于 where() 过滤的字段必须提前注册到 filterableAttributes，用于 orderBy() 排序的字段则注册到 sortableAttributes。

use App\Models\User;

'meilisearch' => [
    'host' => env('MEILISEARCH_HOST', 'http://localhost:7700'),
    'key' => env('MEILISEARCH_KEY', null),
    'index-settings' => [
        User::class => [
            'filterableAttributes' => ['id', 'name', 'email'],
            'sortableAttributes' => ['created_at'],
        ],
    ],
],

注意数值列的数据类型。Meilisearch 只会对类型正确的字段执行 >、< 之类的过滤操作。

public function toSearchableArray(): array
{
    return [
        'id' => (int) $this->id,
        'name' => $this->name,
        'price' => (float) $this->price,
    ];
}

设置完毕后执行 scout:sync-index-settings。

php artisan scout:sync-index-settings

语义检索与混合检索（Meilisearch）

要在 Meilisearch 中使用语义检索或混合检索，需在索引配置中指定 embedder，并在模型配置中指定嵌入信息。

'meilisearch' => [
    'index-settings' => [
        Article::class => [
            'embedders' => [
                'default' => [
                    'source' => 'userProvided',
                    'dimensions' => 1536,
                ],
            ],
        ],
    ],
    'model-settings' => [
        Article::class => [
            'embedding' => [
                'embedder' => 'default',
                'dimensions' => 1536,
            ],
        ],
    ],
],

模型的 toSearchableEmbedding 方法可返回由 Laravel AI SDK 进行嵌入的源文本，或已预先计算好的嵌入数组。设置完毕后请执行 scout:sync-index-settings。

Typesense

Typesense 是一款高性能的开源搜索引擎，支持关键字、语义、地理及向量检索。

composer require typesense/typesense-php

在 .env 中配置连接信息。

SCOUT_DRIVER=typesense
TYPESENSE_API_KEY=masterKey
TYPESENSE_HOST=localhost
TYPESENSE_PORT=8108
TYPESENSE_PATH=
TYPESENSE_PROTOCOL=http

使用 Typesense 时，toSearchableArray 需要把模型主键 cast 为字符串，把创建时间 cast 为 UNIX 时间戳。

public function toSearchableArray(): array
{
    return array_merge($this->toArray(), [
        'id' => (string) $this->id,
        'created_at' => $this->created_at->timestamp,
    ]);
}

语义检索与混合检索（Typesense）

要在 Typesense 中启用语义检索或混合检索，需要在模型的 Typesense 设置中定义 embedding 配置与向量字段。默认情况下，Scout 会使用 Laravel AI SDK 生成嵌入。

use App\Models\Article;

'model-settings' => [
    Article::class => [
        'collection-schema' => [
            'fields' => [
                ['name' => 'title', 'type' => 'string'],
                ['name' => 'embedding', 'type' => 'float[]', 'num_dim' => 1536],
            ],
        ],
        'search-parameters' => ['query_by' => 'title'],
        'embedding' => [
            'attribute' => 'embedding',
            'dimensions' => 1536,
        ],
    ],
],

模型的 toSearchableEmbedding 方法应返回由 Scout 进行嵌入的源文本，或已预先计算好的嵌入数组。

public function toSearchableEmbedding(): string|array
{
    return $this->title.' '.$this->body;
}

若使用 Typesense 的原生嵌入功能，则无需 Laravel AI SDK 也能生成嵌入。详情请参考 Typesense 官方文档。

Turbopuffer

Turbopuffer 是一款支持全文、语义与混合检索的搜索引擎。要使用 Turbopuffer 驱动，请设置 SCOUT_DRIVER 和 API 密钥。

SCOUT_DRIVER=turbopuffer
TURBOPUFFER_API_KEY=tpuf_...
TURBOPUFFER_REGION=gcp-us-central1

TURBOPUFFER_REGION 可以省略，默认值为 gcp-us-central1。

database / collection 引擎

如果希望在不引入外部服务的情况下添加搜索功能，这两种就是最合适的选项。 database 引擎 使用 MySQL / PostgreSQL 的全文索引和 LIKE 子句。多数应用足够使用。

SCOUT_DRIVER=database

语义检索与混合检索

在启用了 pgvector 扩展的 PostgreSQL 上，database 引擎支持语义检索与混合检索。请在模型的数据表中添加可为 null 的向量列和全文索引。由于 Scout 会在模型保存后再存储嵌入，向量列必须允许为 null。

Schema::ensureVectorExtensionExists();

Schema::table('articles', function (Blueprint $table) {
    $table->vector('embedding', dimensions: 1536)->nullable();
    $table->vectorIndex('embedding');
    $table->fullText(['title', 'body']);
});

在模型上定义 toSearchableEmbedding 方法。该方法可返回由 Scout 进行嵌入的源文本，或已预先计算好的嵌入数组。嵌入默认保存在 embedding 列中，可通过 searchableEmbeddingColumn 方法修改。 collection 引擎 在 PHP 中过滤，因此可在 Laravel 支持的所有数据库（包括 SQLite）上运行。适合本地开发、测试或小数据集。

SCOUT_DRIVER=collection

数据库引擎不像外部引擎那样需要手动管理索引，它直接搜索数据库表。

Turbopuffer 配置

使用 Turbopuffer 时，需要在 config/scout.php 的 model-settings 中为每个模型定义可搜索属性和 schema。

'turbopuffer' => [
    'model-settings' => [
        Article::class => [
            'searchable-attributes' => [
                'title' => 3,
                'body' => 1,
            ],
            'schema' => [
                'title' => ['type' => 'string', 'full_text_search' => true],
                'body' => ['type' => 'string', 'full_text_search' => true],
                'status' => ['type' => 'string'],
            ],
        ],
    ],
],

searchable-attributes 中的数值是 BM25 的相对权重。在此示例中，标题的匹配对得分的贡献是正文的 3 倍。若要使用语义检索，请添加 embedding 配置和向量的 schema，并让模型的 toSearchableEmbedding 方法返回源文本或嵌入数组。

'embedding' => [
    'attribute' => 'embedding',
    'dimensions' => 1536,
],

'schema' => [
    'embedding' => ['type' => '[1536]f32', 'ann' => true],
],

若要使用 Turbopuffer 的原生嵌入，则无需 Laravel AI SDK 和 toSearchableEmbedding。将嵌入的源属性包含在 toSearchableArray 的返回值中，并按如下方式配置。

'embedding' => [
    'driver' => 'turbopuffer',
    'attribute' => 'embedding_text',
],

Searchable trait

自定义 toSearchableArray()

默认情况下，模型的 toArray() 全部数据都会写入搜索索引。要自定义同步到索引的数据，可以重写 toSearchableArray 方法。

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Searchable;

class Post extends Model
{
    use Searchable;

    /**
     * 获取要索引的数据数组。
     *
     * @return array<string, mixed>
     */
    public function toSearchableArray(): array
    {
        $array = $this->toArray();

        // 自定义数据...

        return $array;
    }
}

自定义索引名

默认情况下模型的表名（复数）会被用作索引名。可以通过重写 searchableAs 来自定义。

public function searchableAs(): string
{
    return 'posts_index';
}

database 引擎的搜索策略

在 database 引擎中，可以通过 PHP Attribute 为每列指定高效的搜索策略。

use Laravel\Scout\Attributes\SearchUsingFullText;
use Laravel\Scout\Attributes\SearchUsingPrefix;

#[SearchUsingPrefix(['id', 'email'])]
#[SearchUsingFullText(['bio'])]
public function toSearchableArray(): array
{
    return [
        'id' => $this->id,
        'name' => $this->name,
        'email' => $this->email,
        'bio' => $this->bio,
    ];
}

使用 SearchUsingFullText 之前，请确认目标字段已建立全文索引。

有条件地允许搜索

若只想在特定条件下让模型可被搜索，可以定义 shouldBeSearchable 方法。

/**
 * 判断该模型是否应可被搜索。
 */
public function shouldBeSearchable(): bool
{
    return $this->isPublished();
}

shouldBeSearchable 对 database 引擎无效。要在 database 引擎上实现类似效果，请使用where 子句。

索引管理

本节命令主要针对 Algolia、Meilisearch、Typesense 等外部引擎。database 引擎无需管理索引。

导入已有记录

在已有项目中引入 Scout 时，可以使用 scout:import 命令把已有记录导入索引。

php artisan scout:import "App\Models\Post"

也可以通过队列在后台导入。

php artisan scout:queue-import "App\Models\Post" --chunk=500

清空索引

要从索引中删除某模型的全部记录，可以使用 scout:flush。

php artisan scout:flush "App\Models\Post"

暂停索引同步

想在一段 Eloquent 操作期间临时停止与索引的同步，使用 withoutSyncingToSearch。

use App\Models\Order;

Order::withoutSyncingToSearch(function () {
    // 内部的模型操作都不会同步到搜索索引
});

手动添加 / 删除记录

可以基于查询把一批模型加入索引。

// 加入查询结果
Order::where('price', '>', 100)->searchable();

// 通过关联加入
$user->orders()->searchable();

从索引中移除记录使用 unsearchable。

Order::where('price', '>', 100)->unsearchable();

模型 delete 时会自动从索引中删除。

搜索

search 方法用来搜索模型。再链上 get 就可以得到 Eloquent 模型集合。

use App\Models\Order;

$orders = Order::search('Star Trek')->get();

在控制器或路由中直接返回时会自动转 JSON。

use Illuminate\Http\Request;

Route::get('/search', function (Request $request) {
    return Order::search($request->search)->get();
});

如需拿到原始搜索结果，使用 raw 方法。

$orders = Order::search('Star Trek')->raw();

语义检索

在配置了嵌入的 database、Meilisearch、Typesense、Turbopuffer 引擎中，可以基于查询的语义来搜索记录。在搜索查询上链式调用 semantic 方法即可。当由 Scout 生成嵌入时，语义检索与混合检索需要 Laravel AI SDK。如果使用 Typesense 的原生嵌入、Turbopuffer 的原生嵌入或预先计算好的查询向量，则不需要 Laravel AI SDK。

$articles = Article::search('如何在没有电力的情况下保持房屋舒适')
    ->semantic()
    ->get();

在支持的引擎中，还可以指定最低相似度阈值。

$articles = Article::search('可再生能源储能')
    ->semantic(minSimilarity: 0.6)
    ->get();

要将全文检索与语义检索结合使用，可以使用 hybrid 方法，并通过参数指定文本检索与语义检索的相对权重。

$articles = Article::search('可再生能源储能')
    ->hybrid(textWeight: 1, semanticWeight: 2)
    ->get();

分页

paginate 方法用来对搜索结果做分页，用法与普通 Eloquent 查询一致。

$orders = Order::search('Star Trek')->paginate();

// 指定每页条数
$orders = Order::search('Star Trek')->paginate(15);

在 database 引擎下也可以使用 simplePaginate，因为它不计算总数，对大数据集更高效。

$orders = Order::search('Star Trek')->simplePaginate(15);

Blade 模板中的展示示例：

<div class="container">
    @foreach ($orders as $order)
        {{ $order->price }}
    @endforeach
</div>

{{ $orders->links() }}

过滤与排序

where 方法可以给搜索查询添加过滤条件。

use App\Models\Order;

// 相等过滤
$orders = Order::search('Star Trek')->where('user_id', 1)->get();

// 在数组内任一匹配
$orders = Order::search('Star Trek')->whereIn('status', ['open', 'paid'])->get();

// 不在数组内
$orders = Order::search('Star Trek')->whereNotIn('status', ['closed'])->get();

使用 Meilisearch 时，在使用 where 前必须配置可过滤字段。

query 方法用来自定义 Eloquent 查询。

use Illuminate\Database\Eloquent\Builder;

$orders = Order::search('Star Trek')
    ->query(fn (Builder $query) => $query->with('invoices'))
    ->get();

Eager Loading

Scout 会先从搜索引擎获得 ID 列表，再用 Eloquent 取回模型。要避免 N+1 问题，可以在 query 方法内使用 with() 提前加载。

use App\Models\Order;
use Illuminate\Database\Eloquent\Builder;

$orders = Order::search('Star Trek')
    ->query(fn (Builder $query) => $query->with(['invoices', 'user']))
    ->get();

批量导入时若也需要 Eager Load 关联，可以定义 makeAllSearchableUsing。

use Illuminate\Database\Eloquent\Builder;

protected function makeAllSearchableUsing(Builder $query): Builder
{
    return $query->with('author');
}

makeAllSearchableUsing 在通过队列进行批量导入时可能不生效。队列任务处理模型集合时不会恢复关联。

软删除

如果被索引的模型使用了软删除，并希望在搜索时也能搜到已删除的模型，请把 config/scout.php 的 soft_delete 设为 true。

'soft_delete' => true,

启用后可以通过 withTrashed 或 onlyTrashed 搜索已删除记录。

// 包含已删除
$orders = Order::search('Star Trek')->withTrashed()->get();

// 仅搜索已删除
$orders = Order::search('Star Trek')->onlyTrashed()->get();

自定义引擎

若内置引擎不能满足需求，可以自行实现自定义引擎。自定义引擎需继承 Laravel\Scout\Engines\Engine 抽象类，并实现下面 8 个方法。

use Laravel\Scout\Builder;

abstract public function update($models);
abstract public function delete($models);
abstract public function search(Builder $builder);
abstract public function paginate(Builder $builder, $perPage, $page);
abstract public function mapIds($results);
abstract public function map(Builder $builder, $results, $model);
abstract public function getTotalCount($results);
abstract public function flush($model);

实现时可参考 Laravel\Scout\Engines\AlgoliaEngine 类。创建的自定义引擎需要在 App\Providers\AppServiceProvider 的 boot 方法中注册。

use App\ScoutExtensions\MySqlSearchEngine;
use Laravel\Scout\EngineManager;

public function boot(): void
{
    resolve(EngineManager::class)->extend('mysql', function () {
        return new MySqlSearchEngine;
    });
}

注册后在 config/scout.php 中作为驱动使用。

'driver' => 'mysql',

Eloquent ORM

了解 Eloquent 模型的基础用法。

Eloquent 关联

了解关联定义与 Eager Loading。

队列

Scout 可以配合队列在后台异步同步索引。

​简介

​支持的引擎一览

​安装

​配置队列

​使用唯一任务

​各驱动的准备工作

​Algolia

​索引配置

​Meilisearch

​索引配置（Meilisearch）

​语义检索与混合检索（Meilisearch）

​Typesense

​语义检索与混合检索（Typesense）

​Turbopuffer

​database / collection 引擎

​语义检索与混合检索

​Turbopuffer 配置

​Searchable trait

​自定义 toSearchableArray()

​自定义索引名

​database 引擎的搜索策略

​有条件地允许搜索

​索引管理

​导入已有记录

​清空索引

​暂停索引同步

​手动添加 / 删除记录

​搜索

​语义检索

​分页

​过滤与排序

​Eager Loading

​软删除

​自定义引擎

​相关页面

Eloquent ORM

Eloquent 关联

队列

简介

支持的引擎一览

安装

配置队列

使用唯一任务

各驱动的准备工作

Algolia

索引配置

Meilisearch

索引配置（Meilisearch）

语义检索与混合检索（Meilisearch）

Typesense

语义检索与混合检索（Typesense）

Turbopuffer

database / collection 引擎

语义检索与混合检索

Turbopuffer 配置

Searchable trait

自定义 toSearchableArray()

自定义索引名

database 引擎的搜索策略

有条件地允许搜索

索引管理

导入已有记录

清空索引

暂停索引同步

手动添加 / 删除记录

搜索

语义检索

分页

过滤与排序

Eager Loading

软删除

自定义引擎

相关页面