Scout

未匹配的标注
本文档最新版为 12.x,旧版本可能放弃维护,推荐阅读最新版!

Laravel Scout

简介

Laravel Scout 提供了一种基于驱动的简单方案,为 Eloquent 模型 添加全文搜索功能。Scout 使用模型观察器,自动保持搜索索引与 Eloquent 记录同步。

Scout 内置的 database 引擎使用 MySQL / PostgreSQL 全文索引和 LIKE 子句直接搜索现有数据库,无需外部服务。对于大多数应用来说,这已经足够。有关 Laravel 中所有搜索选项的概览,请参阅 搜索文档。

当你需要容错、分面筛选、向量搜索或大规模地理搜索等功能时,Scout 还提供 Algolia、Meilisearch、Typesense 和 Turbopuffer 驱动。另外还有用于本地开发的「collection」驱动,你也可以编写 自定义引擎。

安装

首先,通过 Composer 包管理器安装 Scout:

composer require laravel/scout

安装 Scout 后,应使用 vendor:publish Artisan 命令发布 Scout 配置文件。该命令会将 scout.php 配置文件发布到应用的 config 目录:

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 以外的引擎时,强烈建议在使用该库之前配置 队列驱动。运行队列工作进程后,Scout 就可以将所有同步模型信息到搜索索引的操作放入队列,从而显著缩短应用 Web 界面的响应时间。

配置队列驱动后,将 config/scout.php 配置文件中的 queue 选项设为 true:

'queue' => true,

即使将 queue 选项设为 false,也要注意 Algolia 和 Meilisearch 等部分 Scout 驱动始终异步索引记录。也就是说,即使索引操作已在 Laravel 应用中完成,搜索引擎本身也可能不会立即反映新增或更新的记录。

要指定 Scout 作业使用的连接和队列,可以将 queue 配置选项定义为数组:

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

当然,如果自定义了 Scout 作业使用的连接和队列,应运行队列工作进程来处理该连接和队列上的作业:

php artisan queue:work redis --queue=scout

唯一作业

在写入频繁的应用中,你可能希望防止 Scout 为相同的模型记录重复排队作业。可以注册 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 配置文件中配置 Algolia 的 id 和 secret 凭证。配置好凭证后,还需要通过 Composer 包管理器安装 Algolia PHP SDK:

composer require algolia/algoliasearch-client-php

Meilisearch

Meilisearch 是一个快速的开源搜索引擎,支持全文、语义和混合搜索。如果不确定如何在本地安装 Meilisearch,可以使用 Laravel 官方支持的 Docker 开发环境 Laravel Sail。在生产环境中,你可以 自行托管 Meilisearch 或使用 Meilisearch Cloud。

使用 Meilisearch 驱动时,需要通过 Composer 包管理器安装 Meilisearch PHP SDK:

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

然后,在应用的 .env 文件中设置 SCOUT_DRIVER 环境变量以及 Meilisearch 的 host 和 key 凭证:

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

有关 Meilisearch 的更多信息,请参阅 Meilisearch 文档。

Typesense

Typesense 是一个速度极快的开源搜索引擎,支持关键词搜索、语义搜索、地理搜索和向量搜索。

你可以 自行托管 Typesense 或使用 Typesense Cloud。

要在 Scout 中使用 Typesense,请通过 Composer 包管理器安装 Typesense PHP SDK:

composer require typesense/typesense-php

然后,在应用的 .env 文件中设置 SCOUT_DRIVER 环境变量以及 Typesense 主机和 API 密钥凭证:

SCOUT_DRIVER=typesense
TYPESENSE_API_KEY=masterKey
TYPESENSE_HOST=localhost

如果使用 Laravel Sail,你可能需要调整 TYPESENSE_HOST 环境变量以匹配 Docker 容器名称。你也可以选择指定安装实例的端口、路径和协议:

TYPESENSE_PORT=8108
TYPESENSE_PATH=
TYPESENSE_PROTOCOL=http

Typesense 集合的其他设置和模式定义可在应用的 config/scout.php 配置文件中找到。有关 Typesense 的更多信息,请参阅 Typesense 文档。

Turbopuffer

Turbopuffer 是一个支持全文、语义和混合搜索的搜索引擎。要使用 Turbopuffer 驱动,请设置 SCOUT_DRIVER 环境变量并提供 Turbopuffer API 密钥:

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

TURBOPUFFER_REGION 环境变量是可选的,默认为 gcp-us-central1。

配置

配置可搜索数据

默认情况下,给定模型的完整 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;
    }
}

配置模型搜索引擎

搜索时,Scout 通常使用应用的 scout 配置文件中指定的默认搜索引擎。不过,可以通过重写模型的 searchableUsing 方法来更改特定模型使用的搜索引擎:

<?php

namespace App\Models;

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

class User extends Model
{
    use Searchable;

    /**
     * 获取用于索引模型的引擎。
     */
    public function searchableUsing(): Engine
    {
        return Scout::engine('meilisearch');
    }
}

数据库 / 集合引擎

数据库引擎

[!WARNING]
数据库引擎目前支持 MySQL 和 PostgreSQL,两者都支持快速的列全文索引。

database 引擎使用 MySQL / PostgreSQL 全文索引和 LIKE 子句直接搜索现有数据库。对于许多应用来说,这是添加搜索功能最简单、最实用的方式,无需外部服务或额外基础设施。

要使用数据库引擎,请将 SCOUT_DRIVER 环境变量设为 database:

SCOUT_DRIVER=database

配置完成后,即可 定义可搜索数据,并开始对模型 执行搜索查询。与第三方引擎不同,数据库引擎无需单独的索引步骤,它会直接搜索数据库表。

语义与混合搜索

使用带有 pgvector 扩展的 PostgreSQL 时,数据库引擎支持语义搜索和混合搜索。首先,为模型表添加一个可为空的向量列和一个全文索引。由于 Scout 在模型持久化后才存储嵌入向量,该向量列必须允许为空:

Schema::ensureVectorExtensionExists();

Schema::table('articles', function (Blueprint $table) {
    // ...

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

接下来,在模型上定义 toSearchableEmbedding 方法。该方法可以返回 Scout 应生成嵌入向量的源文本,也可以返回预先计算的嵌入向量数组。Scout 默认将嵌入向量存储在 embedding 列中;要使用其他列,请在模型上定义 searchableEmbeddingColumn 方法。

自定义数据库搜索策略

默认情况下,数据库引擎会对每个 配置为可搜索 的模型属性执行 LIKE 查询。不过,你可以为特定列指定更高效的搜索策略。SearchUsingFullText 属性使用数据库中该列的全文索引,而 SearchUsingPrefix 仅匹配字符串开头(example%),而不是搜索整个字符串(%example%)。

要定义此行为,请为模型的 toSearchableArray 方法添加 PHP 属性。未指定属性的列将继续使用默认的 LIKE 策略:

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

/**
 * 获取模型的可索引数据数组。
 *
 * @return array<string, mixed>
 */
#[SearchUsingPrefix(['id', 'email'])]
#[SearchUsingFullText(['bio'])]
public function toSearchableArray(): array
{
    return [
        'id' => $this->id,
        'name' => $this->name,
        'email' => $this->email,
        'bio' => $this->bio,
    ];
}

[!WARNING]
指定列使用全文查询约束之前,请确保该列已创建 全文索引。

PostgreSQL 全文搜索

使用 PostgreSQL 时,Scout 可以搜索存储的 tsvector 列,以实现带索引和权重的全文搜索。首先,在迁移中使用 searchable 方法添加生成的 search_vector 列及其 GIN 索引:

use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

Schema::table('posts', function (Blueprint $table) {
    $table->searchable(['title' => 'A', 'body' => 'D']);
});

列权重从 A(最高)到 D(最低)。你也可以传入不带权重的列名列表,例如 ['title', 'body'],为每列分配默认权重 D。源列发生变化时,PostgreSQL 会自动更新生成的列。

接下来,将 SearchUsingFullText 属性应用于模型的 toSearchableArray 方法,并将 vector 选项设为 true:

use Laravel\Scout\Attributes\SearchUsingFullText;

/**
 * 获取模型的可索引数据数组。
 *
 * @return array<string, mixed>
 */
#[SearchUsingFullText(['search_vector'], ['vector' => true])]
public function toSearchableArray(): array
{
    return ['search_vector' => null];
}

只需提供列名,Scout 会直接搜索存储的值。请仅返回向量列,以免为其他属性添加 LIKE 子句,导致 PostgreSQL 无法使用 GIN 索引。

searchable 方法还接受文本搜索配置、三元组索引列和自定义向量列名:

$table->searchable(
    columns: ['title' => 'A', 'body' => 'D'],
    language: 'english',
    trigram: ['title'],
    tsvector: 'search_vector',
);

要在回滚迁移时删除生成的列及其索引,请使用 dropSearchable 方法,并传入相同的三元组列和向量列名:

Schema::table('posts', function (Blueprint $table) {
    $table->dropSearchable(trigram: ['title'], tsvector: 'search_vector');
});

PostgreSQL 搜索选项

可以通过 SearchUsingFullText 属性的第二个参数自定义 PostgreSQL 全文搜索:

选项 说明 默认值
vector 全文列是否为存储的 tsvector 列。 false
language 文本搜索配置,例如 english 或 public.english_unaccent。 english
mode 查询语法:plain、phrase、websearch 或 raw。 plain
rank 排名函数:ts_rank 或 ts_rank_cd。 ts_rank
trigram 用于拼写容错匹配的列名或列名数组。 无
trigram_mode 三元组匹配是用作回退(fallback),还是与全文匹配混合(blend)。 fallback

plain 模式搜索所有查询词,而 phrase 按顺序匹配词语。websearch 模式支持网页搜索语法,例如带引号的短语和排除词;raw 则接受 PostgreSQL tsquery 语法。搜索存储的向量列时,language 必须与生成该列时使用的文本搜索配置一致。

要启用拼写容错,请在迁移和属性选项中都指定三元组列:

#[SearchUsingFullText(['search_vector'], ['vector' => true, 'trigram' => ['title']])]
public function toSearchableArray(): array
{
    return ['search_vector' => null];
}

默认情况下,Scout 仅在首次搜索没有结果时才使用三元组匹配重试。将 trigram_mode 设为 blend,即可将三元组匹配与全文匹配一并纳入结果,并将三元组相似度计入相关性排名。

[!WARNING]
三元组匹配要求 pg_trgm 扩展在连接的搜索路径中可用。提供三元组列时,searchable 迁移方法会创建该扩展,因此运行迁移的数据库用户必须有权创建扩展。

你可以使用 options 方法,为单次搜索覆盖 mode、language、rank、trigram 和 trigram_mode 选项:

$posts = Post::search('"laravel scout"')->options(['mode' => 'websearch'])->get();

集合引擎

「collection」引擎适用于快速原型、极小的数据集(数百条记录)或运行测试。它从数据库中检索所有可能的记录,并使用 Laravel 的 Str::is 辅助函数在 PHP 中筛选,因此不需要任何索引或特定数据库功能。对于非简单场景,应改用 数据库引擎。

要使用集合引擎,只需将 SCOUT_DRIVER 环境变量设为 collection,或者在应用的 scout 配置文件中直接指定 collection 驱动:

SCOUT_DRIVER=collection

将集合驱动设为首选驱动后,即可开始对模型 执行搜索查询。使用集合引擎时,无需进行搜索引擎索引,例如填充 Algolia、Meilisearch 或 Typesense 索引所需的索引操作。

与数据库引擎的区别

数据库引擎使用全文索引和 LIKE 子句高效查找匹配记录,而集合引擎会取出所有记录并在 PHP 中筛选。集合引擎具有最好的可移植性,因为它适用于 Laravel 支持的所有关系数据库(包括 SQLite 和 SQL Server);但其效率明显低于数据库引擎,不应在大型数据集上使用。

第三方引擎配置

以下配置选项仅与 Algolia、Meilisearch 或 Typesense 等第三方搜索引擎有关。如果使用 数据库引擎,可以跳过本节。

配置模型索引

使用第三方引擎时,每个 Eloquent 模型都与一个搜索「索引」同步,该索引包含模型的所有可搜索记录。默认情况下,每个模型都会保存到与其常规模型「表」名称相同的索引中,通常是模型名称的复数形式;你也可以通过重写模型的 searchableAs 方法自定义索引:

<?php

namespace App\Models;

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

class Post extends Model
{
    use Searchable;

    /**
     * 获取与模型关联的索引名称。
     */
    public function searchableAs(): string
    {
        return 'posts_index';
    }
}

[!NOTE]
使用数据库引擎时,searchableAs 方法没有效果,因为数据库引擎始终直接搜索模型的数据库表。

配置模型 ID

默认情况下,Scout 使用模型主键作为存储在搜索索引中的唯一 ID / 键。使用第三方引擎时,如果需要自定义此行为,可以重写模型的 getScoutKey 和 getScoutKeyName 方法:

<?php

namespace App\Models;

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

class User extends Model
{
    use Searchable;

    /**
     * 获取用于索引模型的值。
     */
    public function getScoutKey(): mixed
    {
        return $this->email;
    }

    /**
     * 获取用于索引模型的键名。
     */
    public function getScoutKeyName(): mixed
    {
        return 'email';
    }
}

[!NOTE]
使用数据库引擎时,getScoutKey 和 getScoutKeyName 方法没有效果,因为数据库引擎始终使用模型主键。

Algolia

索引设置

有时,你可能需要为 Algolia 索引配置额外设置。虽然可以通过 Algolia 界面管理这些设置,但直接在应用的 config/scout.php 配置文件中管理索引配置的期望状态有时更加高效。

这种方式允许你通过应用的自动化部署流水线部署这些设置,避免手动配置,并确保多个环境保持一致。你可以配置可筛选属性、排名、分面或 其他受支持的设置。

首先,在应用的 config/scout.php 配置文件中为每个索引添加设置:

use App\Models\User;
use App\Models\Flight;

'algolia' => [
    'id' => env('ALGOLIA_APP_ID', ''),
    'secret' => env('ALGOLIA_SECRET', ''),
    'index-settings' => [
        User::class => [
            'searchableAttributes' => ['id', 'name', 'email'],
            'attributesForFaceting'=> ['filterOnly(email)'],
            // 其他设置字段……
        ],
        Flight::class => [
            'searchableAttributes'=> ['id', 'destination'],
        ],
    ],
],

如果某个索引对应的模型支持软删除,且包含在 index-settings 数组中,Scout 会自动为该索引支持基于软删除模型的分面。如果不需要为可软删除模型的索引定义其他分面属性,可以在 index-settings 数组中为该模型添加一个空条目:

'index-settings' => [
    Flight::class => []
],

配置应用的索引设置后,必须调用 scout:sync-index-settings Artisan 命令。此命令会将当前配置的索引设置告知 Algolia。为了方便,你可以将此命令加入部署流程:

php artisan scout:sync-index-settings

识别用户

Scout 允许在使用 Algolia 时自动识别用户。将已认证用户与搜索操作关联,有助于在 Algolia 控制面板中查看搜索分析数据。可以在应用的 .env 文件中将 SCOUT_IDENTIFY 环境变量设为 true 来启用用户识别:

SCOUT_IDENTIFY=true

启用此功能还会将请求的 IP 地址和已认证用户的主标识符传递给 Algolia,从而将这些数据与该用户发起的所有搜索请求关联。

Meilisearch

索引设置

Meilisearch 要求预先定义索引搜索设置,例如可筛选属性、可排序属性和 其他支持的设置字段。

可筛选属性是调用 Scout 的 where 方法时计划用于筛选的属性,而可排序属性是调用 Scout 的 orderBy 方法时计划用于排序的属性。要定义索引设置,请调整应用 scout 配置文件中 meilisearch 配置项的 index-settings 部分:

use App\Models\User;
use App\Models\Flight;

'meilisearch' => [
    'host' => env('MEILISEARCH_HOST', 'http://localhost:7700'),
    'key' => env('MEILISEARCH_KEY', null),
    'index-settings' => [
        User::class => [
            'filterableAttributes'=> ['id', 'name', 'email'],
            'sortableAttributes' => ['created_at'],
            // 其他设置字段……
        ],
        Flight::class => [
            'filterableAttributes'=> ['id', 'destination'],
            'sortableAttributes' => ['updated_at'],
        ],
    ],
],

如果某个索引对应的模型支持软删除,且包含在 index-settings 数组中,Scout 会自动为该索引支持按软删除模型筛选。如果不需要为可软删除模型的索引定义其他可筛选或可排序属性,可以在 index-settings 数组中为该模型添加一个空条目:

'index-settings' => [
    Flight::class => []
],

配置应用的索引设置后,必须调用 scout:sync-index-settings Artisan 命令。此命令会将当前配置的索引设置告知 Meilisearch。为了方便,你可以将此命令加入部署流程:

php artisan scout:sync-index-settings

语义与混合搜索

要使用 Meilisearch 进行语义或混合搜索,请在索引设置中配置嵌入器,并为每个可搜索模型配置嵌入设置:

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

模型的 toSearchableEmbedding 方法可以返回源文本,由 Scout 使用 Laravel AI SDK 生成嵌入向量,也可以返回预先计算的嵌入向量数组。更新配置后,运行 scout:sync-index-settings 命令。

你也可以将嵌入的 driver 设为 meilisearch,使用 Meilisearch 原生嵌入。在此模式下,Meilisearch 使用配置的嵌入器生成文档和查询的嵌入向量,因此不需要 dimensions 选项和 toSearchableEmbedding 方法:

'meilisearch' => [
    'index-settings' => [
        Article::class => [
            'embedders' => [
                'default' => [
                    'source' => 'openAi',
                    'apiKey' => env('OPENAI_API_KEY'),
                    'model' => 'text-embedding-3-small',
                    'documentTemplate' => 'An article titled {{ doc.title }}: {{ doc.body }}',
                ],
            ],
        ],
    ],
    'model-settings' => [
        Article::class => [
            'embedding' => [
                'embedder' => 'default',
                'driver' => 'meilisearch',
            ],
        ],
    ],
],

使用原生嵌入时,Scout 不会生成向量或将向量添加到索引文档。你仍可通过 vector 搜索选项提供预先计算的查询向量。与其他索引设置一样,更新嵌入器配置后请运行 scout:sync-index-settings 命令。

有关可用嵌入器来源及其选项的更多信息,请参阅 Meilisearch 混合搜索文档。

可搜索数据类型

Meilisearch 只会对类型正确的数据执行筛选操作(>、< 等)。自定义可搜索数据时,应确保将数值转换为正确的类型:

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

Typesense

准备可搜索数据

使用 Typesense 时,可搜索模型必须定义 toSearchableArray 方法,将模型主键转换为字符串,并将创建日期转换为 UNIX 时间戳:

/**
 * 获取模型的可索引数据数组。
 *
 * @return array<string, mixed>
 */
public function toSearchableArray(): array
{
    return array_merge($this->toArray(),[
        'id' => (string) $this->id,
        'created_at' => $this->created_at->timestamp,
    ]);
}

还应在应用的 config/scout.php 文件中定义 Typesense 集合模式。集合模式描述了可通过 Typesense 搜索的各字段的数据类型。有关所有可用模式选项,请参阅 Typesense 文档。

如果需要修改已定义的 Typesense 集合模式,可以运行 scout:flush 和 scout:import,这会删除所有现有索引数据并重新创建模式;也可以使用 Typesense API 修改集合模式,而不删除任何索引数据。

如果可搜索模型支持软删除,应在应用的 config/scout.php 配置文件中,为该模型对应的 Typesense 模式定义 __soft_deleted 字段:

User::class => [
    'collection-schema' => [
        'fields' => [
            // ...
            [
                'name' => '__soft_deleted',
                'type' => 'int32',
                'optional' => true,
            ],
        ],
    ],
],

嵌入向量

要启用语义和混合搜索,请在模型的 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 允许你在执行搜索操作时通过 options 方法动态修改 搜索参数:

use App\Models\Todo;

Todo::search('Groceries')->options([
    'query_by' => 'title, description'
])->get();

Turbopuffer

Turbopuffer 要求为每个模型定义模式和可搜索属性。请在 scout 配置文件的 turbopuffer 配置中,通过 model-settings 数组定义它们:

use App\Models\Article;

'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 权重。在上面的示例中,文章标题中的匹配贡献的分数是正文中匹配的三倍。

要启用语义和混合搜索,请在模型配置中添加 embedding 设置和向量模式:

'turbopuffer' => [
    // ...
    'model-settings' => [
        Article::class => [
            'searchable-attributes' => [
                'title' => 3,
                'body' => 1,
            ],
            'embedding' => [
                'attribute' => 'embedding',
                'dimensions' => 1536,
            ],
            'schema' => [
                'title' => ['type' => 'string', 'full_text_search' => true],
                'body' => ['type' => 'string', 'full_text_search' => true],
                'embedding' => ['type' => '[1536]f32', 'ann' => true],
            ],
        ],
    ],
],

模型的 toSearchableEmbedding 方法应返回 Scout 要生成嵌入向量的源文本,或预先计算的嵌入向量数组。Scout 使用 Laravel AI SDK 根据源文本生成嵌入向量。

你也可以使用 Turbopuffer 原生嵌入,而无需安装 Laravel AI SDK 或定义 toSearchableEmbedding 方法。将嵌入驱动设为 turbopuffer,并在可搜索的源属性上配置 embed 模式:

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

'schema' => [
    // ...
    'embedding_text' => [
        'type' => 'string',
        'embed' => [
            'model' => 'voyage/voyage-4',
            'dimensions' => 1024,
            'attribute' => 'embedding',
        ],
    ],
],

源属性必须包含在模型的 toSearchableArray 输出中。

第三方引擎索引

[!NOTE]
本节介绍的索引功能主要适用于 Algolia、Meilisearch、Typesense 或 Turbopuffer 等第三方引擎。数据库引擎直接搜索数据库表,因此不需要手动管理索引。

批量导入

如果在现有项目中安装 Scout,可能已有需要导入索引的数据库记录。Scout 提供 scout:import Artisan 命令,可将所有现有记录导入搜索索引:

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

可以使用 scout:queue-import 命令通过 队列作业 导入所有现有记录:

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

可以使用 flush 命令从搜索索引中移除某个模型的所有记录:

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

修改导入查询

如果要修改批量导入时用于检索所有模型的查询,可以在模型上定义 makeAllSearchableUsing 方法。这个方法适合添加导入模型前可能需要的关系预加载:

use Illuminate\Database\Eloquent\Builder;

/**
 * 修改将所有模型设为可搜索时用于检索模型的查询。
 */
protected function makeAllSearchableUsing(Builder $query): Builder
{
    return $query->with('author');
}

[!WARNING]
使用队列批量导入模型时,makeAllSearchableUsing 方法可能不适用。作业处理模型集合时,不会恢复 关系。

添加记录

为模型添加 Laravel\Scout\Searchable trait 后,只需 save 或 create 模型实例,它就会自动添加到搜索索引。如果已将 Scout 配置为 使用队列,此操作将在后台由队列工作进程执行:

use App\Models\Order;

$order = new Order;

// ...

$order->save();

通过查询添加记录

如果要通过 Eloquent 查询将模型集合添加到搜索索引,可以在 Eloquent 查询后链式调用 searchable 方法。searchable 方法会将查询结果 分块,并将记录添加到搜索索引。同样,如果已配置 Scout 使用队列,所有块都会由队列工作进程在后台导入:

use App\Models\Order;

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

你也可以在 Eloquent 关系实例上调用 searchable 方法:

$user->orders()->searchable();

或者,如果内存中已有 Eloquent 模型集合,可以在集合实例上调用 searchable 方法,将模型实例添加到对应索引:

$orders->searchable();

[!NOTE]
searchable 方法可以视为「upsert」操作。也就是说,如果模型记录已在索引中,就会更新该记录;如果不存在,则会将其添加到索引中。

更新记录

要更新可搜索模型,只需更新模型实例的属性,并将模型 save 到数据库。Scout 会自动将更改保存到搜索索引:

use App\Models\Order;

$order = Order::find(1);

// 更新订单……

$order->save();

你也可以在 Eloquent 查询实例上调用 searchable 方法来更新模型集合。如果模型不存在于搜索索引中,则会创建相应记录:

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

如果要更新关系中所有模型的搜索索引记录,可以在关系实例上调用 searchable 方法:

$user->orders()->searchable();

或者,如果内存中已有 Eloquent 模型集合,可以在集合实例上调用 searchable 方法,更新模型实例在对应索引中的记录:

$orders->searchable();

导入前修改记录

有时,可能需要在模型集合变为可搜索之前对其进行准备。例如,你可能希望预加载某个关系,以便高效地将关系数据添加到搜索索引。为此,请在相应模型上定义 makeSearchableUsing 方法:

use Illuminate\Database\Eloquent\Collection;

/**
 * 修改正在设为可搜索的模型集合。
 */
public function makeSearchableUsing(Collection $models): Collection
{
    return $models->load('author');
}

有条件地更新搜索索引

默认情况下,无论修改了哪些属性,Scout 都会重新索引更新后的模型。如果要自定义此行为,可以在模型上定义 searchIndexShouldBeUpdated 方法:

/**
 * 确定是否应更新搜索索引。
 */
public function searchIndexShouldBeUpdated(): bool
{
    return $this->wasRecentlyCreated || $this->wasChanged(['title', 'body']);
}

移除记录

要从索引中移除记录,只需从数据库中 delete 模型。即使模型使用了 软删除,也可以这样做:

use App\Models\Order;

$order = Order::find(1);

$order->delete();

如果不想在删除记录之前检索模型,可以在 Eloquent 查询实例上使用 unsearchable 方法:

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

如果要移除关系中所有模型的搜索索引记录,可以在关系实例上调用 unsearchable 方法:

$user->orders()->unsearchable();

或者,如果内存中已有 Eloquent 模型集合,可以在集合实例上调用 unsearchable 方法,从对应索引中移除这些模型实例:

$orders->unsearchable();

要从对应索引中移除模型的所有记录,可以调用 removeAllFromSearch 方法:

Order::removeAllFromSearch();

暂停索引

有时,你可能需要对模型执行一批 Eloquent 操作,而不将模型数据同步到搜索索引。可以使用 withoutSyncingToSearch 方法。该方法接受一个立即执行的闭包,闭包中的模型操作不会同步到模型的索引:

use App\Models\Order;

Order::withoutSyncingToSearch(function () {
    // 执行模型操作……
});

有条件的可搜索模型实例

有时,你可能只希望模型在满足特定条件时才可搜索。例如,假设 App\Models\Post 模型有「草稿」和「已发布」两种状态,你可能只希望允许搜索「已发布」的文章。为此,可以在模型上定义 shouldBeSearchable 方法:

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

shouldBeSearchable 方法仅在通过 save 和 create 方法、查询或关系操作模型时生效。直接使用 searchable 方法使模型或集合可搜索,会覆盖 shouldBeSearchable 方法的结果。

[!WARNING]
shouldBeSearchable 方法不适用于 Scout 的「database」引擎,因为所有可搜索数据始终存储在数据库中。使用数据库引擎时,要实现类似行为,应改用 where 子句。

搜索

可以使用 search 方法开始搜索模型。该方法接受一个用于搜索模型的字符串。然后,应在搜索查询后链式调用 get 方法,以获取符合给定搜索查询的 Eloquent 模型:

use App\Models\Order;

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

由于 Scout 搜索返回 Eloquent 模型集合,你甚至可以直接从路由或控制器返回结果,它们会自动转换为 JSON:

use App\Models\Order;
use Illuminate\Http\Request;

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

如果要在搜索结果转换为 Eloquent 模型之前获取原始结果,可以使用 raw 方法:

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

语义搜索

数据库、Meilisearch、Typesense 和 Turbopuffer 引擎支持语义搜索,即根据查询的含义匹配记录。当 Scout 生成嵌入向量时,语义搜索和混合搜索需要 Laravel AI SDK。Typesense 原生嵌入、Turbopuffer 原生嵌入 和预先计算的查询向量则不需要 Laravel AI SDK。

为选定引擎配置嵌入后,在搜索查询上调用 semantic 方法:

$articles = Article::search('staying cool in the summer')
    ->semantic()
    ->get();

当选定引擎支持时,你可以提供最低相似度阈值:

$articles = Article::search('renewable energy storage')
    ->semantic(minSimilarity: 0.6)
    ->get();

要结合全文搜索和语义搜索,请使用 hybrid 方法。其前两个参数控制文本结果和语义结果的相对权重:

$articles = Article::search('renewable energy storage')
    ->hybrid(textWeight: 1, semanticWeight: 2)
    ->get();

自定义索引

使用第三方引擎搜索时,搜索查询通常针对模型的 searchableAs 方法指定的索引执行。不过,可以使用 within 方法指定要搜索的自定义索引:

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

Where 子句

Scout 允许为搜索查询添加「where」子句。例如,基本的相等性检查可用于按所有者 ID 限定搜索查询范围:

use App\Models\Order;

$orders = Order::search('Star Trek')->where('user_id', 1)->get();

你也可以使用 =、!=、<、>、>=、<= 比较运算符构建更高级的查询:

Order::search('Star Trek')
  ->where('status', '=', 'completed')
  ->where('is_refunded', '!=', true)
  ->where('total_price', '>', 100)
  ->where('shipping_cost', '<', 20)
  ->where('discount_percent', '>=', 10)
  ->where('item_count', '<=', 5)
  ->get();

此外,可以使用 whereIn 方法验证给定列的值是否包含在给定数组中:

$orders = Order::search('Star Trek')->whereIn(
    'status', ['open', 'paid']
)->get();

whereNotIn 方法验证给定列的值是否不包含在给定数组中:

$orders = Order::search('Star Trek')->whereNotIn(
    'status', ['closed']
)->get();

[!WARNING]
如果应用使用 Meilisearch,必须先配置应用的 可筛选属性,然后才能使用 Scout 的「where」子句。

自定义 Eloquent 结果查询

Scout 从应用的搜索引擎检索到匹配的 Eloquent 模型列表后,会使用 Eloquent 根据主键检索所有匹配的模型。你可以调用 query 方法自定义此查询。query 方法接受一个闭包,该闭包会接收 Eloquent 查询构建器实例作为参数:

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

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

使用第三方引擎时,此回调在相关模型已从搜索引擎中检索出来之后调用,因此不应用它来「筛选」结果,而应使用 Scout where 子句。不过,使用数据库引擎时,query 方法的约束会直接应用于数据库查询,因此也可以用它进行筛选。

分页

除了获取模型集合外,还可以使用 paginate 方法对搜索结果分页。与 对普通 Eloquent 查询分页 一样,该方法会返回一个 Illuminate\Pagination\LengthAwarePaginator 实例:

use App\Models\Order;

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

可以将数量作为第一个参数传给 paginate 方法,指定每页获取的模型数量:

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

使用数据库引擎时,还可以使用 simplePaginate 方法。与获取匹配记录总数以显示页码的 paginate 不同,simplePaginate 只判断当前页之后是否还有更多结果。因此,对于只需要「上一页」和「下一页」链接的大型数据集,它更高效:

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

获取结果后,可以使用 Blade 显示结果并渲染分页链接,就像对普通 Eloquent 查询分页一样:

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

{{ $orders->links() }}

当然,如果想以 JSON 格式获取分页结果,可以直接从路由或控制器返回分页器实例:

use App\Models\Order;
use Illuminate\Http\Request;

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

[!WARNING]
由于搜索引擎不了解 Eloquent 模型的全局作用域定义,因此在使用 Scout 分页的应用中不应使用全局作用域。或者,你应该在通过 Scout 搜索时重新应用全局作用域的约束。

软删除

如果索引中的模型使用 软删除,且需要搜索软删除的模型,请将 config/scout.php 配置文件的 soft_delete 选项设为 true:

'soft_delete' => true,

当此配置选项为 true 时,Scout 不会从搜索索引中移除软删除的模型,而是在索引记录上设置一个隐藏的 __soft_deleted 属性。然后,你可以在搜索时使用 withTrashed 或 onlyTrashed 方法检索软删除的记录:

use App\Models\Order;

// 检索结果时包含已删除的记录……
$orders = Order::search('Star Trek')->withTrashed()->get();

// 检索结果时仅包含已删除的记录……
$orders = Order::search('Star Trek')->onlyTrashed()->get();

[!NOTE]
使用 forceDelete 永久删除软删除的模型时,Scout 会自动将其从搜索索引中移除。

自定义引擎搜索

如果需要对引擎的搜索行为进行高级自定义,可以将闭包作为第二个参数传递给 search 方法。例如,可以使用此回调在搜索查询传给 Algolia 之前,将地理位置数据添加到搜索选项中:

use Algolia\AlgoliaSearch\SearchIndex;
use App\Models\Order;

Order::search(
    'Star Trek',
    function (SearchIndex $algolia, string $query, array $options) {
        $options['body']['query']['bool']['filter']['geo_distance'] = [
            'distance' => '1000km',
            'location' => ['lat' => 36, 'lon' => 111],
        ];

        return $algolia->search($query, $options);
    }
)->get();

自定义引擎

编写引擎

如果 Scout 内置的搜索引擎不符合你的需求,可以编写自己的自定义引擎并将其注册到 Scout。引擎应继承 Laravel\Scout\Engines\Engine 抽象类。该抽象类包含自定义引擎必须实现的八个方法:

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 类中这些方法的实现可能会有所帮助。该类为学习如何在自定义引擎中实现这些方法提供了很好的起点。

注册引擎

编写自定义引擎后,可以使用 Scout 引擎管理器的 extend 方法将其注册到 Scout。Scout 引擎管理器可以从 Laravel 服务容器解析。应在 App\Providers\AppServiceProvider 类或应用使用的其他服务提供者的 boot 方法中调用 extend 方法:

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

/**
 * 启动所有应用服务。
 */
public function boot(): void
{
    resolve(EngineManager::class)->extend('mysql', function () {
        return new MySqlSearchEngine;
    });
}

注册引擎后,可以在应用的 config/scout.php 配置文件中将其指定为默认的 Scout driver:

'driver' => 'mysql',

本文章首发在 LearnKu.com 网站上。

本译文仅用于学习和交流目的,转载请务必注明文章译者、出处、和本文链接
我们的翻译工作遵照 CC 协议,如果我们的工作有侵犯到您的权益,请及时联系我们。

原文地址:https://learnku.com/docs/laravel/13.x/sc...

译文地址:https://learnku.com/docs/laravel/13.x/sc...

上一篇 下一篇
《L03 构架 API 服务器》
你将学到如 RESTFul 设计风格、PostMan 的使用、OAuth 流程,JWT 概念及使用 和 API 开发相关的进阶知识。
《L02 从零构建论坛系统》
以构建论坛项目 LaraBBS 为线索,展开对 Laravel 框架的全面学习。应用程序架构思路贴近 Laravel 框架的设计哲学。
贡献者:1
讨论数量: 0
发起讨论 只看当前版本


暂无话题~